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.

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

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.

Motion correction

mesc-io register recording.mesc recording_MC.mesc          # one reference per unit
mesc-io preset save soma --block-size 128 --max-shift-nr 5 # name a set of settings
mesc-io register recording.mesc out.mesc --preset soma     # use it; a flag still wins

Needs pip install "mesc-io[register]". The defaults are the calcium-imaging pipeline's own correction; z-stacks and units too short to register are skipped and said so. Groups, presets, where they are kept and how to share them: docs/registration.md.

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. A z-stack is shown in slices and microns, with a max projection, a 3D view you can turn (MIP, semi-transparent, or coloured by depth) and XYZ orthogonal views through one crosshair. Layout and decisions: 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.