mesc-io 0.1.0__tar.gz

mesc_io-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the mesc-io authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mesc_io-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: mesc-io
+Version: 0.1.0
+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)
+
+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
+
+Not on PyPI yet. From the repository:
+
+```
+pip install "mesc-io @ git+https://github.com/LynnYuSmith/mesc-io"
+pip install "mesc-io[tiff,imagej] @ git+https://github.com/LynnYuSmith/mesc-io"   # + 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.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

mesc_io-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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)
+
+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
+
+Not on PyPI yet. From the repository:
+
+```
+pip install "mesc-io @ git+https://github.com/LynnYuSmith/mesc-io"
+pip install "mesc-io[tiff,imagej] @ git+https://github.com/LynnYuSmith/mesc-io"   # + 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.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

mesc_io-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mesc-io"
+version = "0.1.0"
+description = "Read Femtonics .mesc two-photon recordings, in the units the native reader shows"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Lynn Smith" }]
+keywords = ["mesc", "femtonics", "two-photon", "calcium-imaging", "microscopy", "hdf5"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = ["h5py>=3.6", "numpy>=1.21"]
+
+[project.urls]
+Homepage = "https://github.com/LynnYuSmith/mesc-io"
+Repository = "https://github.com/LynnYuSmith/mesc-io"
+Changelog = "https://github.com/LynnYuSmith/mesc-io/blob/main/CHANGELOG.md"
+Issues = "https://github.com/LynnYuSmith/mesc-io/issues"
+
+[project.optional-dependencies]
+tiff = ["tifffile>=2021.11"]
+imagej = ["roifile>=2022.9"]
+register = ["suite2p>=0.14,<1.0"]   # 1.x changed compute_reference/register_frames; validated on 0.14.x
+dev = ["pytest>=7", "roifile>=2022.9"]
+
+[project.scripts]
+mesc-io = "mesc_io.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The viewer's page ships inside the package. Without this it is missing from the wheel and
+# `mesc-io view` fails at the first request with a file-not-found — on someone else's machine,
+# not on the one it was built on.
+[tool.setuptools.package-data]
+mesc_io = ["viewer.html"]

mesc_io-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mesc_io-0.1.0/src/mesc_io/__init__.py

@@ -0,0 +1,8 @@
+"""Read Femtonics `.mesc` two-photon recordings, in the units the native reader shows."""
+from .errors import MescIOError
+from .reader import Channel, MescError, MescFile, Unit
+from .values import ConversionError, from_reader_units, to_reader_units
+
+__version__ = "0.1.0"
+__all__ = ["MescFile", "Unit", "Channel", "MescError", "MescIOError",
+           "to_reader_units", "from_reader_units", "ConversionError", "__version__"]

mesc_io-0.1.0/src/mesc_io/__main__.py

@@ -0,0 +1,214 @@
+"""`mesc-io` on the command line: look inside a .mesc, get frames out, put frames back."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .errors import MescIOError
+from .reader import MescFile
+
+
+def _as_json(payload) -> int:
+    import json
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+def _info(args) -> int:
+    with MescFile(args.file) as f:
+        units = f.units()
+        if args.json:
+            return _as_json([{"unit": u.path, "frames": u.n_frames,
+                              "height": u.height, "width": u.width, "dtype": u.dtype,
+                              "frame_rate_hz": u.frame_rate_hz,
+                              "duration_s": u.duration_s,
+                              "pixel_size_um": u.pixel_size_um,
+                              "comment": u.comment,
+                              "channels": [{"name": c.name, "offset": c.offset,
+                                            "scale": c.scale} for c in u.channels]}
+                             for u in units])
+        print(f"{Path(args.file).name}: {len(units)} unit(s)")
+        print(f"{'unit':<18}{'frames':>8}{'size':>12}{'rate':>11}{'pixel':>11}  comment")
+        for u in units:
+            rate = f"{u.frame_rate_hz:.3f} Hz" if u.frame_rate_hz else "unknown"
+            px = f"{u.pixel_size_um:.4f} um" if u.pixel_size_um else "unknown"
+            print(f"  {u.path:<16}{u.n_frames:>8}{f'{u.height}x{u.width}':>12}"
+                  f"{rate:>11}{px:>11}  {u.comment[:44]}")
+    return 0
+
+
+def _check(args) -> int:
+    from .check import check
+    rep = check(args.file)
+    if args.json:
+        return _as_json({"file": rep.path, "units": rep.n_units, "ok": rep.ok,
+                         "findings": [{"level": f.level, "code": f.code,
+                                       "message": f.message, "units": list(f.units)}
+                                      for f in rep.findings]})
+    print(rep)
+    if rep.ok:
+        print("  nothing that would mislead an analysis")
+    return 0
+
+
+def _export(args) -> int:
+    from . import export as _ex
+    with MescFile(args.file) as f:
+        out = Path(args.out)
+        writer = _ex.to_tiff if out.suffix.lower() in (".tif", ".tiff") else _ex.to_hdf5
+        written = writer(f, args.unit, out, channel=args.channel,
+                         reader_units=not args.stored_units)
+        print(f"  {written}  ({'stored' if args.stored_units else 'reader'} units)")
+    return 0
+
+
+def _writeback(args) -> int:
+    from .frames_io import load_frames
+    from .writeback import write_frames
+
+    frames, in_file = load_frames(args.frames, dataset=args.dataset)
+    if args.reader_units:
+        units = True
+    elif args.stored_units:
+        units = False
+    elif in_file is not None:
+        units = in_file
+        print(f"  {Path(args.frames).name} says its values are in "
+              f"{'reader' if units else 'stored'} units")
+    else:
+        print("  the frames do not say which units they are in — pass --reader-units or "
+              "--stored-units. Getting this wrong writes a file that looks right and is not.",
+              file=sys.stderr)
+        return 1
+
+    report = write_frames(args.source, args.out, {args.unit: {f"Channel_{args.channel}": frames}},
+                          reader_units=units, tag=None if args.no_tag else args.tag,
+                          tolerance=args.tolerance)
+    for w in report["warnings"]:
+        print(f"  note: {w}")
+    for what, delta in report["agreement"].items():
+        print(f"  {what}: agrees with the frames it replaced to {delta:+.0f} counts")
+    print(f"  {report['out']}")
+    return 0
+
+
+def _view(args) -> int:
+    from .viewer import serve
+
+    serve(args.source, port=args.port, open_browser=not args.no_browser,
+          rois_path=args.rois)
+    return 0
+
+
+def _register(args) -> int:
+    from .registration import register_file
+
+    def _say(path, info):
+        print(f"  {path}: {info['n_frames']} frames, {info['n_channels']} channel(s), "
+              f"{info['leading_flat_frames']} flat at the front, "
+              f"shift |y|<={abs(info['y_shift']).max()} |x|<={abs(info['x_shift']).max()} px")
+
+    rep = register_file(args.source, args.out, units=args.units or None, channel=args.channel,
+                        reference_from=args.reference_from, nonrigid=args.nonrigid,
+                        block_size=args.block_size, max_shift=args.max_shift,
+                        max_shift_nr=args.max_shift_nr,
+                        tag=None if args.no_tag else args.tag, progress=_say)
+    print(f"  reference from {rep['reference_from']}"
+          f"{' (non-rigid)' if rep['nonrigid'] else ''}")
+    print(f"  {rep['out']}")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="mesc-io", description=__doc__)
+    ap.add_argument("--version", action="version", version=f"mesc-io {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("info", help="list the units in a .mesc and what they say about themselves")
+    p.add_argument("file")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.set_defaults(func=_info)
+
+    p = sub.add_parser("check", help="report what in a .mesc disagrees with itself")
+    p.add_argument("file")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.set_defaults(func=_check)
+
+    p = sub.add_parser("export", help="write one unit to .h5 or .tif (by the output's suffix)")
+    p.add_argument("file")
+    p.add_argument("unit", help="MUnit_0, or MSession_0/MUnit_0")
+    p.add_argument("out")
+    p.add_argument("--channel", type=int, default=0)
+    p.add_argument("--stored-units", action="store_true",
+                   help="write the file's own integers instead of the values the reader shows")
+    p.set_defaults(func=_export)
+
+    p = sub.add_parser("writeback",
+                       help="put processed frames back into a copy of a .mesc")
+    p.add_argument("source", help="the original .mesc — it is copied, never modified")
+    p.add_argument("out", help="the copy to write")
+    p.add_argument("unit", help="MUnit_0, or MSession_0/MUnit_0")
+    p.add_argument("frames", help=".h5 or .tif holding the processed frames")
+    p.add_argument("--channel", type=int, default=0)
+    p.add_argument("--dataset", default=None,
+                   help="which dataset in the .h5 (only needed if there is more than one)")
+    g = p.add_mutually_exclusive_group()
+    g.add_argument("--reader-units", action="store_true",
+                   help="the frames hold the values the reader displays")
+    g.add_argument("--stored-units", action="store_true",
+                   help="the frames hold the file's own integers")
+    p.add_argument("--tag", default="_MC",
+                   help="appended to the written unit's comment (default: _MC)")
+    p.add_argument("--no-tag", action="store_true", help="do not mark the written unit")
+    p.add_argument("--tolerance", type=float, default=60.0,
+                   help="how far, in stored counts, the new frames may differ from the ones "
+                        "they replace before the write is refused (default: 60)")
+    p.set_defaults(func=_writeback)
+
+    p = sub.add_parser("view",
+                       help="open the recording in a browser: the movie, the file's own "
+                            "numbers, and traces of regions you draw")
+    p.add_argument("source")
+    p.add_argument("--port", type=int, default=8020)
+    p.add_argument("--no-browser", action="store_true",
+                   help="do not open a browser; print the address and wait")
+    p.add_argument("--rois", default=None,
+                   help="where the drawn regions are kept (default: beside the CWD, never "
+                        "beside the raw file — raw data is not ours to add files to)")
+    p.set_defaults(func=_view)
+
+    p = sub.add_parser("register",
+                       help="motion-correct units against one shared reference (needs Suite2p)")
+    p.add_argument("source")
+    p.add_argument("out")
+    p.add_argument("--units", nargs="*", default=None,
+                   help="which units; all of them by default. Name them when the file holds "
+                        "more than one field — one reference across two fields is meaningless")
+    p.add_argument("--channel", type=int, default=0,
+                   help="the channel registration is computed on; the others take its shifts")
+    p.add_argument("--reference-from", default=None,
+                   help="anchor unit (default: the first one), so the reference is the state "
+                        "the session started in rather than an average over it")
+    p.add_argument("--nonrigid", action="store_true",
+                   help="also correct a smooth position-dependent warp")
+    p.add_argument("--block-size", type=int, default=128)
+    p.add_argument("--max-shift", type=float, default=0.1,
+                   help="rigid cap, as a fraction of the frame (default: 0.1)")
+    p.add_argument("--max-shift-nr", type=float, default=5.0,
+                   help="non-rigid cap in px; keep it small (default: 5)")
+    p.add_argument("--tag", default="_MC")
+    p.add_argument("--no-tag", action="store_true")
+    p.set_defaults(func=_register)
+
+    args = ap.parse_args(argv)
+    try:
+        return args.func(args)
+    except (MescIOError, FileNotFoundError, KeyError, ImportError, MemoryError) as exc:
+        print(f"  {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mesc_io-0.1.0/src/mesc_io/check.py

@@ -0,0 +1,143 @@
+"""Look a `.mesc` over before you trust it.
+
+A file can be perfectly readable and still not be what you assume. These are the
+disagreements worth knowing about before an analysis is built on top of one — each is
+something a file has actually done, not a hypothetical:
+
+* **units recorded at different frame rates.** Normal in a session where the field or the
+  zoom changed, and ruinous if you take one rate for the whole file. A z-stack saved
+  alongside the recordings reports a frame period that is not a frame rate at all.
+* **units at different pixel sizes.** The zoom was changed between recordings, so distances
+  in one unit are not distances in another.
+* **conversion attributes missing.** Then the values you read are the stored integers and the
+  package has nothing to convert them with — it says so rather than assuming a common offset.
+* **channels with different conversions across units**, which means a per-file constant is
+  the wrong model for that file.
+* **empty or single-frame units**, which are usually a snapshot or an aborted recording and
+  will surprise anything that expects a movie.
+
+`check` reports; it never repairs. What is a problem depends on what you are doing, so the
+severities are advisory and the report names the units so you can look.
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+from .reader import MescFile
+
+__all__ = ["check", "Report", "Finding"]
+
+
+@dataclass(frozen=True)
+class Finding:
+    level: str          # "note" | "warn"
+    code: str
+    message: str
+    units: tuple = ()
+
+    def __str__(self) -> str:
+        where = f"  [{', '.join(self.units[:6])}{'…' if len(self.units) > 6 else ''}]" if self.units else ""
+        return f"{self.level:>4}: {self.message}{where}"
+
+
+@dataclass
+class Report:
+    path: str
+    n_units: int
+    findings: List[Finding] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not any(f.level == "warn" for f in self.findings)
+
+    def __str__(self) -> str:
+        head = f"{self.path}: {self.n_units} unit(s), {len(self.findings)} finding(s)"
+        return "\n".join([head] + [str(f) for f in self.findings])
+
+
+def _group(values: Dict[str, object]) -> Dict[object, List[str]]:
+    out = defaultdict(list)
+    for unit, v in values.items():
+        out[v].append(unit)
+    return dict(out)
+
+
+def check(path) -> Report:
+    """Read a `.mesc`'s metadata and report what disagrees with what."""
+    with MescFile(path) as f:
+        units = f.units()
+        rep = Report(path=str(f.path.name), n_units=len(units))
+
+        rates = {u.path: (round(u.frame_rate_hz, 3) if u.frame_rate_hz else None) for u in units}
+        missing = [u for u, r in rates.items() if r is None]
+        if missing:
+            rep.findings.append(Finding(
+                "warn", "no-frame-rate",
+                f"{len(missing)} unit(s) do not state a frame rate", tuple(missing)))
+        present = {u: r for u, r in rates.items() if r is not None}
+        by_rate = _group(present)
+        if len(by_rate) > 1:
+            common = Counter(present.values()).most_common(1)[0][0]
+            odd = tuple(u for u, r in present.items() if r != common)
+            rep.findings.append(Finding(
+                "warn", "mixed-frame-rates",
+                f"{len(by_rate)} different frame rates in one file "
+                f"({', '.join(f'{r:g} Hz x{len(v)}' for r, v in sorted(by_rate.items()))}) — "
+                f"use each unit's own rate, never one for the file", odd))
+
+        sizes = {u.path: u.pixel_size_um for u in units if u.pixel_size_um}
+        by_size = _group(sizes)
+        if len(by_size) > 1:
+            rep.findings.append(Finding(
+                "warn", "mixed-pixel-sizes",
+                f"{len(by_size)} different pixel sizes "
+                f"({', '.join(f'{s:.4f} um x{len(v)}' for s, v in sorted(by_size.items()))}) — "
+                "distances are not comparable across these units", ()))
+        if len(sizes) < len(units):
+            rep.findings.append(Finding(
+                "note", "no-pixel-size",
+                f"{len(units) - len(sizes)} unit(s) do not state a pixel size",
+                tuple(u.path for u in units if not u.pixel_size_um)))
+
+        shapes = _group({u.path: (u.height, u.width) for u in units})
+        if len(shapes) > 1:
+            rep.findings.append(Finding(
+                "note", "mixed-frame-shapes",
+                f"{len(shapes)} different frame shapes "
+                f"({', '.join(f'{h}x{w}' for h, w in sorted(shapes))})", ()))
+
+        thin = tuple(u.path for u in units if u.n_frames <= 1)
+        if thin:
+            rep.findings.append(Finding(
+                "note", "not-a-movie",
+                f"{len(thin)} unit(s) hold one frame or none — a snapshot or an aborted "
+                "recording", thin))
+
+        no_conv, per_channel = [], defaultdict(dict)
+        for u in units:
+            for c in u.channels:
+                per_channel[c.name][u.path] = (c.offset, c.scale)
+                if c.offset == 0.0 and c.scale == 1.0:
+                    no_conv.append(f"{u.path}/{c.name}")
+        if no_conv:
+            rep.findings.append(Finding(
+                "warn", "no-conversion",
+                f"{len(no_conv)} channel(s) carry no conversion attributes — their values "
+                "cannot be put in reader units and come back as stored", tuple(no_conv)))
+        for name, per_unit in sorted(per_channel.items()):
+            distinct = set(per_unit.values())
+            if len(distinct) > 1:
+                rep.findings.append(Finding(
+                    "warn", "mixed-conversion",
+                    f"{name} does not use one conversion across the file "
+                    f"({len(distinct)} different) — convert per unit, never per file", ()))
+
+        counts = Counter(len(u.channels) for u in units)
+        if len(counts) > 1:
+            rep.findings.append(Finding(
+                "note", "mixed-channel-counts",
+                f"units carry different channel counts "
+                f"({', '.join(f'{n} ch x{k}' for n, k in sorted(counts.items()))})", ()))
+    return rep