simsh5 0.3.0

Reader and analysis recipes for open SIMS-H5 (tof-sims-sparse-hdf5) TOF-SIMS data

simsh5

Reader and analysis recipes for open SIMS-H5 (tof-sims-sparse-hdf5) TOF-SIMS data. Small and dependency-light — a SIMS-H5 archive is self-contained, so reading it needs only numpy + h5py (plus hdf5plugin for the compression filters).

The file format is defined in open_tof_sims_format; this library implements the §10 analyst recipes behind a small API.

Install

pip install simsh5                # core reader (numpy + h5py + hdf5plugin)
pip install "simsh5[notebook]"    # + matplotlib/Jupyter for examples/

Usage

import simsh5

arc = simsh5.open_archive("scan.h5")     # or use as a context manager
print(arc.acquisition_mode, arc.polarity, arc.row_shape)

img  = simsh5.total_ion_image(arc)            # total counts; (ny, nx), or stitched mosaic
mz, intensity = simsh5.total_spectrum(arc)    # summed spectrum
fe   = simsh5.ion_image(arc, 55.0, 57.0)      # ion image for an m/z window
mz_p, counts_p = simsh5.spectrum_at_pixel(arc, 0)
arc.close()

For depth_profile archives, simsh5.depth_profile(arc) returns (sputter_time_s, counts_per_cycle).

For mosaic archives, total_ion_image / ion_image stitch the tiles onto the stage grid using /mosaic/tile_index_xy, returning a (gy*ny, gx*nx) panorama (e.g. a 6×6 grid of 256×256 tiles → (1536, 1536)) rather than (ny, nx).

Images use a lower-left origin (PHI convention: row 0 is the bottom row), so display them with plt.imshow(img, origin="lower"). Both image recipes accept bin_factor=N to sum non-overlapping N×N pixel blocks (2→1, 4→1, …; must divide the image dimensions) for coarser, higher-SNR images.

What it handles for you

• Sparse CSR-on-mass-axis decoding (mass_bin / indptr / pixel_id / count).
• count > 255 exceptions patched back in.
• Absent @mass_bin_width_ps → treated as lossless (1).
• Per-mode geometry: image_2d / depth_profile collapse to (ny, nx); mosaic tiles are stitched onto the stage grid → (gy*ny, gx*nx) (lower-left origin).
• Optional bin_factor pixel binning on total_ion_image / ion_image.
• Quadratic m/z calibration (tof_ps_to_mz / mz_to_tof_ps).

Development

pip install -e ".[dev]"
ruff check . && mypy && pytest

Tests run against any tests/fixtures/*.h5 archive (an image_2d sample and a synthetic mosaic are bundled).

License

MIT — see LICENSE.