Metadata-Version: 2.4
Name: simsh5
Version: 0.1.0
Summary: Reader and analysis recipes for open SIMS-H5 (tof-sims-sparse-hdf5) TOF-SIMS data
Project-URL: Homepage, https://github.com/PhysicalElectronics/simsh5
Project-URL: Source, https://github.com/PhysicalElectronics/simsh5
Project-URL: Format spec, https://github.com/PhysicalElectronics/open_tof_sims_format
Author: ULVAC-PHI
License-Expression: MIT
License-File: LICENSE
Keywords: HDF5,SIMS,TOF-SIMS,hyperspectral,imaging,mass-spectrometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: h5py>=3.10
Requires-Dist: hdf5plugin>=4.1
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: ipywidgets>=8; extra == 'notebook'
Requires-Dist: matplotlib>=3.7; extra == 'notebook'
Requires-Dist: notebook>=7; extra == 'notebook'
Description-Content-Type: text/markdown

# 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`](https://github.com/PhysicalElectronics/open_tof_sims_format);
this library implements the §10 analyst recipes behind a small API.

## Install

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

## Usage

```python
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)            # (ny, nx) total counts
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)`.

### 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` / `mosaic`) collapsed to `(ny, nx)`.
- Quadratic m/z calibration (`tof_ps_to_mz` / `mz_to_tof_ps`).

## Development

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

Tests run against any `tests/fixtures/*.h5` archive (one small sample is included).

## License

MIT — see [`LICENSE`](LICENSE).
