Metadata-Version: 2.4
Name: mesc-io
Version: 0.3.1
Summary: Read Femtonics .mesc two-photon recordings, in the units the native reader shows
Author: Lynn Smith
License-Expression: MIT
Project-URL: Homepage, https://github.com/LynnYuSmith/mesc-io
Project-URL: Repository, https://github.com/LynnYuSmith/mesc-io
Project-URL: Changelog, https://github.com/LynnYuSmith/mesc-io/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/LynnYuSmith/mesc-io/issues
Keywords: mesc,femtonics,two-photon,calcium-imaging,microscopy,hdf5
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: h5py>=3.6
Requires-Dist: numpy>=1.21
Provides-Extra: tiff
Requires-Dist: tifffile>=2021.11; extra == "tiff"
Provides-Extra: imagej
Requires-Dist: roifile>=2022.9; extra == "imagej"
Provides-Extra: register
Requires-Dist: suite2p<1.0,>=0.14; extra == "register"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: roifile>=2022.9; extra == "dev"
Dynamic: license-file

# mesc-io

[![tests](https://github.com/LynnYuSmith/mesc-io/actions/workflows/tests.yml/badge.svg)](https://github.com/LynnYuSmith/mesc-io/actions/workflows/tests.yml) [![PyPI](https://img.shields.io/pypi/v/mesc-io)](https://pypi.org/project/mesc-io/)

Read Femtonics `.mesc` two-photon recordings in Python — the frames in the units the native
reader shows, every unit's metadata, an export, a write-back, and a viewer that draws ROIs and
computes their dF/F.

![the viewer on a synthetic recording: four spots, three of them blinking, their dF/F below](https://raw.githubusercontent.com/LynnYuSmith/mesc-io/main/docs/viewer.png)

## Install

```
pip install mesc-io
pip install "mesc-io[tiff,imagej]"     # + TIFF export, ImageJ ROI export
```

Needs Python 3.9 or newer, numpy and h5py; nothing else for reading and viewing. Motion
correction (`mesc-io register`) is an extra, `[register]`, and pulls in Suite2p 0.14.

## Python

```python
from mesc_io import MescFile

with MescFile("recording.mesc") as f:
    for u in f.units():
        print(u.path, u.shape, u.frame_rate_hz, u.pixel_size_um)

    frames = f.read("MUnit_0", channel=0)              # reader units, float64
    frames = f.read("MUnit_0", reader_units=False)     # the stored integers
    for block in f.iter_frames("MUnit_0", block=500):  # bigger than memory
        ...
```

`read` refuses over 4 GB by default (`max_gb=None` to override). A unit name that matches in
more than one session is refused, not resolved to the first; `MSession_1/MUnit_0` always works.

## Command line

```
mesc-io info      recording.mesc                            # units, rates, pixel sizes
mesc-io check     recording.mesc                            # what the file disagrees with itself about
mesc-io export    recording.mesc MUnit_0 u0.h5              # or u0.tif
mesc-io writeback recording.mesc out.mesc MUnit_0 u0.h5     # processed frames back in
mesc-io view      recording.mesc                            # the recording in a browser
```

`info` and `check` take `--json`.

### The viewer

`mesc-io view` opens the recording in a private browser window: units on the left with a
thumbnail each and the unit's own metadata (rate, pixel size, the stage position and the
position from the zero set on the rig); the image in
the middle — scrub it, average a window of N frames, zoom into a place by dragging a box;
ROIs on the right (spot, rectangle, polygon; drag to move, type a size); every ROI's time
course along the bottom, raw or dF/F by our pipeline's method (`mesc_io.dff`, numpy only,
held against the pipeline's functions in the tests), stacked or overlaid, zoomed by dragging a box. ROIs belong to the
unit they were drawn on and are saved as you go, beside the working directory, never beside
the raw file; so is the view itself, so reopening the file puts you back where you were.
Layout and decisions: [docs/viewer_design.md](docs/viewer_design.md).

To try it without a recording, make one:

```
python tools/make_synthetic.py            # writes synthetic_view.mesc: 3 units, 4 spots, 3 of them blinking
mesc-io view synthetic_view.mesc
```

## Development

```
pip install -e ".[tiff,dev]"
pytest
```

The package lives under `src/`, so tests run against the installed copy. CI runs the suite on
Python 3.9, 3.12 and 3.13 on Linux, macOS and Windows, plus one job with Suite2p for the
registration tests; the browser checks (`tests/*_real_chrome.js`) run in a real Chrome and are
not part of pytest.

## Acknowledgements

F. Kamari, for the idea. Claude Code, for the debugging.

## Licence

MIT — see [LICENSE](LICENSE).
