mesofield 0.3.2b0__py3-none-any.whl

docs/_static/custom.css

@@ -0,0 +1,40 @@
+/* Wordmark font: Exo 2 — clean, slightly futuristic, pairs well with PyData. */
+@import url("https://fonts.googleapis.com/css2?family=Exo+2:wght@400;500;600;700&display=swap");
+
+/* PyData renders the brand as: .navbar-brand > img.logo__image + p.title */
+.navbar-brand {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    text-decoration: none;
+}
+
+/* Override pydata's higher-specificity rule on the logo image. */
+.bd-header .navbar-brand img.logo__image,
+.navbar-brand img.logo__image,
+.navbar-brand-box img.logo__image {
+    height: 1.4rem !important;
+    max-height: 1.4rem !important;
+    width: auto !important;
+    object-fit: contain;
+}
+
+/* Stop the README's banner image from being stretched to content width.
+   pydata applies width:100% to images by default; cap to natural size. */
+.bd-content img {
+    max-width: 100%;
+    width: auto;
+    height: auto;
+    object-fit: contain;
+}
+
+.navbar-brand p,
+.navbar-brand .title {
+    font-family: "Exo 2", system-ui, sans-serif;
+    font-weight: 500;
+    font-size: 1.5rem;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    margin: 0;
+    line-height: 1;
+}

docs/api/index.md

@@ -0,0 +1,70 @@
+# API Reference
+
+Mesofield is organised into a small set of subpackages. Each one is documented below; start with the package you're working in.
+
+::::{grid} 1 2 2 2
+:gutter: 2
+
+:::{grid-item-card} `base` & `protocols`
+:link: mesofield.base
+:link-type: doc
+
+The `Procedure` orchestrator and the device protocols every hardware adapter implements.
+:::
+
+:::{grid-item-card} `config` & `signals`
+:link: mesofield.config
+:link-type: doc
+
+The `ExperimentConfig` registry and the lightweight psygnal-based event bus.
+:::
+
+:::{grid-item-card} `hardware` & `engines`
+:link: mesofield.hardware
+:link-type: doc
+
+`HardwareManager` lifecycle and the MicroManager MDA engine integrations.
+:::
+
+:::{grid-item-card} `devices`
+:link: mesofield.devices
+:link-type: doc
+
+Concrete hardware adapters: cameras, DAQs, encoders, treadmills, PsychoPy.
+:::
+
+:::{grid-item-card} `data` & `datakit`
+:link: mesofield.data
+:link-type: doc
+
+Writers, batch managers, and the post-acquisition data exploration toolkit.
+:::
+
+:::{grid-item-card} `gui`
+:link: mesofield.gui
+:link-type: doc
+
+The PyQt6 widgets and controllers that make up the desktop app.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+mesofield.base
+mesofield.config
+mesofield.protocols
+mesofield.signals
+mesofield.hardware
+mesofield.engines
+mesofield.devices
+mesofield.data
+mesofield.datakit
+mesofield.processing
+mesofield.processors
+mesofield.scaffold
+mesofield.gui
+mesofield.utils
+```

docs/conf.py

@@ -0,0 +1,200 @@
+"""Sphinx configuration for the Mesofield docs."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+# -- Project information ------------------------------------------------------
+
+project = "Mesofield"
+author = "Jacob Gronemeyer"
+copyright = "2026, Sipe Laboratory, Penn State"
+
+try:
+    from mesofield._version import version as _version
+except Exception:
+    _version = "0.0.0"
+release = _version
+version = ".".join(_version.split(".")[:2])
+
+# -- General configuration ----------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "api/mesofield.rst"]
+
+# -- Autodoc ------------------------------------------------------------------
+
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "member-order": "bysource",
+    "exclude-members": "__weakref__,__init_subclass__,__subclasshook__",
+}
+
+
+def _skip_foreign_members(app, what, name, obj, skip, options):
+    """Hide classes/functions that live outside the ``mesofield`` package.
+
+    Re-exports like ``from psygnal import Signal`` would otherwise pull in
+    upstream docstrings (often markdown-formatted) and render them poorly.
+    """
+    if skip:
+        return skip
+    module = getattr(obj, "__module__", None)
+    if module and not module.startswith("mesofield"):
+        return True
+    return None
+autodoc_typehints = "description"
+autodoc_class_signature = "separated"
+autodoc_preserve_defaults = True
+
+# Mock platform-specific imports so the autodoc build can run anywhere.
+autodoc_mock_imports = [
+    "pywin32",
+    "win32",
+    "win32com",
+    "winreg",
+]
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+# -- Napoleon (Google-style docstrings) ---------------------------------------
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# -- MyST ---------------------------------------------------------------------
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "tasklist",
+    "attrs_inline",
+    "smartquotes",
+    "substitution",
+]
+myst_heading_anchors = 3
+
+# -- Intersphinx --------------------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+}
+
+# -- HTML output --------------------------------------------------------------
+
+html_theme = "pydata_sphinx_theme"
+html_title = "Mesofield"
+html_static_path = ["_static"]
+html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.png"
+html_css_files = ["custom.css"]
+html_theme_options = {
+    "logo": {
+        "text": "MESOFIELD",
+        "image_light": "_static/logo.png",
+        "image_dark": "_static/logo.png",
+    },
+    "github_url": "https://github.com/Gronemeyer/mesofield",
+    "use_edit_page_button": True,
+    "show_prev_next": False,
+    "navbar_align": "left",
+    "header_links_before_dropdown": 6,
+    "icon_links": [],
+    "pygment_light_style": "tango",
+    "pygment_dark_style": "monokai",
+}
+html_context = {
+    "github_user": "Gronemeyer",
+    "github_repo": "mesofield",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+
+# -- sphinx-apidoc ------------------------------------------------------------
+
+def _run_apidoc(_app) -> None:
+    """Generate one .rst per package/module under mesofield/ before build."""
+    from sphinx.ext import apidoc
+
+    out_dir = Path(__file__).parent / "api"
+    src_dir = ROOT / "mesofield"
+    excludes = [
+        str(src_dir / "_version.py"),
+        str(src_dir / "__main__.py"),
+        str(src_dir / "datakit" / "_version.py"),
+        str(src_dir / "datakit" / "__main__.py"),
+        str(src_dir / "datakit" / "_utils"),
+    ]
+    apidoc.main(
+        [
+            "--force",
+            "--separate",
+            "--module-first",
+            "--no-toc",
+            "--maxdepth",
+            "1",
+            "--output-dir",
+            str(out_dir),
+            str(src_dir),
+            *excludes,
+        ]
+    )
+
+    # Post-process apidoc output:
+    #   1. Strip the hardcoded ``:undoc-members:`` so undocumented members do
+    #      not flood the rendered pages.
+    #   2. Rewrite the page title from ``mesofield.devices.base module`` to
+    #      just ``base`` so the sidebar shows leaf names.
+    for rst in out_dir.glob("mesofield*.rst"):
+        lines = rst.read_text().splitlines()
+        if (
+            len(lines) >= 2
+            and lines[1]
+            and set(lines[1]) <= {"="}
+            and len(lines[1]) == len(lines[0])
+        ):
+            title = lines[0]
+            # Strip the "module"/"package" suffix and pick the last dotted part.
+            for suffix in (" module", " package"):
+                if title.endswith(suffix):
+                    title = title[: -len(suffix)]
+                    break
+            leaf = title.rsplit(".", 1)[-1] or title
+            lines[0] = leaf
+            lines[1] = "=" * len(leaf)
+        cleaned = [line for line in lines if line.strip() != ":undoc-members:"]
+        rst.write_text("\n".join(cleaned) + "\n")
+
+
+def setup(app) -> None:
+    app.connect("builder-inited", _run_apidoc)
+    app.connect("autodoc-skip-member", _skip_foreign_members)

docs/developer_guide.md

@@ -0,0 +1,303 @@
+# Developer Guide
+
+This guide is for **developers extending mesofield** — writing custom
+device adapters, subclassing `Procedure`, building frame processors, or
+contributing to the framework itself. If you're just running
+acquisitions, see the [User Guide](user_guide.md) instead.
+
+## Architecture in one diagram
+
+```
+experiment.json
+     │
+     ▼
+ExperimentConfig ─── HardwareManager ─── Devices (BaseDevice subclasses)
+     │                     │                       │
+     │                     │                       ├── DataProducer.signals.data ──┐
+     │                     │                       │                               ▼
+     │                     └── DataManager ◀───── Queues ─────── DataSaver ───--- disk
+     │
+     ▼
+Procedure (orchestrates lifecycle, emits signals, owns the run)
+     │
+     ▼
+MainWindow (Qt GUI; binds widgets to procedure.events)
+```
+
+The four backbone classes are:
+
+| Class | Module | Owns |
+|-------|--------|------|
+| `Procedure` | [`mesofield.base`](api/generated/mesofield.base) | Run lifecycle (initialize → arm → start → finish), hooks, manifest |
+| `ExperimentConfig` | [`mesofield.config`](api/generated/mesofield.config) | Parameter registry + JSON I/O + BIDS paths |
+| `HardwareManager` | [`mesofield.hardware`](api/generated/mesofield.hardware) | YAML-driven device factory + lifecycle |
+| `DataManager` | [`mesofield.data`](api/generated/mesofield.data) | Per-run data queues, notes, timestamps, manifest writes |
+
+## Procedure lifecycle
+
+```
+1. initialize_hardware       — bring devices up (one-time)
+2. prerun                    — subclass hook (default: no-op)
+3. hardware.arm_all          — per-run prep on every device
+4. connect primary.signals.finished -> _cleanup_procedure
+5. on_started                — subclass hook
+6. hardware.start_all
+7. on_finished               — subclass hook (after primary fires finished)
+8. save_data + cleanup
+```
+
+Hooks `prerun`, `on_started`, `on_finished` are no-ops on `Procedure`
+itself. Override them in your subclass under
+`experiments/<name>/procedure.py`.
+
+```python
+from mesofield.base import Procedure
+
+
+class MyProcedure(Procedure):
+    def prerun(self):
+        self.logger.info(f"Subject {self.config.subject}, "
+                         f"duration {self.config.duration}s")
+
+    def on_started(self):
+        # called after every device has started
+        pass
+
+    def on_finished(self):
+        # called after the primary camera signals finished
+        self.logger.info("Run complete; manifest will be written next")
+```
+
+`load_procedure_from_config` is the discovery hook called by the CLI; it
+reads the optional `procedure_file` and `procedure_class` fields from
+`experiment.json` and instantiates your subclass.
+
+## Procedure signals (`procedure.events`)
+
+`Procedure.events` is a [`ProcedureSignals`](api/generated/mesofield.base)
+`QObject` exposing four `pyqtSignal`s:
+
+| Signal | Payload | Fires when |
+|--------|---------|-----------|
+| `procedure_started` | — | After all devices have started |
+| `hardware_initialized` | `bool` (success) | After `initialize_hardware` |
+| `procedure_finished` | — | After cleanup completes successfully |
+| `procedure_error` | `str` (message) | On any uncaught run-time error |
+| `data_saved` | — | After `save_data` completes |
+
+Connect from a Qt widget or from another device:
+
+```python
+procedure.events.procedure_started.connect(self.lock_form)
+procedure.events.procedure_finished.connect(self.unlock_form)
+procedure.events.procedure_error.connect(self.show_error_dialog)
+```
+
+## Custom hardware devices
+
+A hardware device is any class that satisfies the
+[`HardwareDevice`](api/generated/mesofield.protocols) protocol. The
+easiest path is to subclass one of the base classes:
+
+| Base | Use when |
+|------|----------|
+| `BaseDevice` | Generic device with no streaming data |
+| `BaseDataProducer` | Streaming source (timeseries / counts) with a buffer |
+| `BaseSerialDevice` | Streaming source whose transport is a serial port |
+| `BaseCamera` | Anything that produces frames + writes a writer file |
+
+### Minimal example — a serial sensor
+
+```python
+from mesofield import DeviceRegistry
+from mesofield.devices.base import BaseSerialDevice
+
+
+@DeviceRegistry.register("thermal")
+class ThermalSensor(BaseSerialDevice):
+    """One-byte-per-sample thermal probe over serial."""
+
+    file_type = "csv"
+    bids_type = "beh"
+    data_type = "thermal"
+
+    def parse_line(self, line: bytes):
+        """Parse one serial frame.
+
+        Returns:
+            ``(payload, timestamp_or_None)`` — the payload is whatever
+            you want fanned out on ``self.signals.data``; pass ``None``
+            for the timestamp to let the framework stamp it.
+        """
+        return float(line), None
+```
+
+Then in `hardware.yaml`:
+
+```yaml
+thermal:
+  type: thermal
+  port: /dev/ttyUSB1
+  baudrate: 115200
+  output:
+    suffix: thermal
+    file_type: csv
+    bids_type: beh
+```
+
+`@DeviceRegistry.register("thermal")` is what binds the YAML `type:`
+string to the class. The decorator also stamps `registry_key` onto the
+class so any instance can report its YAML type for hardware export.
+
+### Camera-shaped devices
+
+For anything that produces frames, subclass
+[`BaseCamera`](api/generated/mesofield.devices.base_camera) — it
+defaults to OME-TIFF output via `CustomWriter`, exposes a `snap()` /
+`start_live()` / `stop_live()` contract for the GUI preview, and
+plumbs frame metadata into the manifest. The
+[`MMCamera`](api/generated/mesofield.devices.cameras) and
+[`OpenCVCamera`](api/generated/mesofield.devices.cameras) classes
+are the two concrete implementations to read for reference.
+
+## Threading models
+
+Devices can use any concurrency model that respects the lifecycle:
+
+```python
+# Qt-thread device (camera, GUI-driven serial)
+from PyQt6.QtCore import QThread
+from mesofield.protocols import HardwareDevice
+
+class QtDevice(QThread):
+    device_type = "qt_device"
+    device_id   = "qdev"
+    def run(self): ...     # Qt thread loop
+
+
+# Python threading device
+from mesofield.protocols import ThreadedHardwareDevice
+
+class ThreadedDevice(ThreadedHardwareDevice):
+    device_type = "thread_device"
+    device_id   = "tdev"
+    def _run(self): ...    # standard daemon thread
+
+
+# asyncio device
+from mesofield.protocols import AsyncioHardwareDevice
+
+class AsyncDevice(AsyncioHardwareDevice):
+    device_type = "async_device"
+    device_id   = "adev"
+    async def _run(self): ...
+```
+
+Pick whichever fits your hardware best — the framework only cares about
+the protocol, not the concurrency model.
+
+## Frame processors
+
+For per-frame compute (mean intensity, ROI tracking, anything that
+turns an ndarray into a scalar), use the `@processor` decorator on a
+`Procedure` method:
+
+```python
+from mesofield.base import Procedure, processor
+
+
+class MyProcedure(Procedure):
+    @processor(camera="meso", plot=True, label="Frame mean", y_range=(0, 65535))
+    def frame_mean(self, img, idx, ts):
+        return float(img.mean())
+```
+
+The framework wraps the function in a
+[`FrameProcessor`](api/generated/mesofield.processors), attaches it to
+the camera whose `device_id` matches `"meso"`, registers it with
+`DataManager`, and (when `plot=True`) adds a live
+[`SerialWidget`](api/generated/mesofield.gui.speedplotter) to the GUI.
+
+Recognised `plot_kwargs`: `label`, `value_label`, `value_units`,
+`y_range`, `value_scale`, `max_points`.
+
+## Scaffolding a new experiment
+
+The CLI scaffold drops a fill-out template:
+
+```bash
+mesofield new my-experiment --rig my-rig
+cd my-experiment
+```
+
+You get:
+
+```
+my-experiment/
+    README.md
+    experiment.json      # subjects, duration, DisplayKeys
+    hardware.yaml        # copied from the selected rig
+    procedure.py         # your Procedure subclass
+    devices/
+        __init__.py
+        thermal_example.py  # annotated custom-device template
+```
+
+`--rig` selects from `mesofield rig list`. Use `--hardware path/to/file`
+to use an explicit YAML; omit both to enter an interactive picker.
+
+## Rig store
+
+A `hardware.yaml` is rig-specific (COM ports, camera ids, MM `.cfg`
+paths). Each machine keeps a small store of named canonical configs in
+the OS config directory:
+
+```bash
+mesofield rig new my-rig             # writes a fill-out template
+mesofield rig list                   # show registered rigs
+mesofield rig add my-rig file.yaml   # adopt an existing yaml
+```
+
+The store lives at the platform-default config location (resolved by
+`platformdirs`); `mesofield rig where` prints the path.
+
+## Logging
+
+Use the project logger inside your code:
+
+```python
+from mesofield.utils._logger import get_logger
+
+logger = get_logger(__name__)
+logger.info("...")
+```
+
+Every device and processor should use a `__name__`-scoped logger so the
+file traces are easy to grep.
+
+## Where to look for examples
+
+- [`mesofield/devices/mocks.py`](api/generated/mesofield.devices.mocks)
+  — mock serial encoder + mock camera. Read these first; they're the
+  simplest concrete implementations of every base class.
+- [`mesofield/devices/cameras.py`](api/generated/mesofield.devices.cameras)
+  — `MMCamera` (Micro-Manager backend) and `OpenCVCamera` (capture
+  thread + MP4 writer). The two shapes most custom cameras start from.
+- [`mesofield/scaffold/experiment.py`](api/generated/mesofield.scaffold)
+  — what the `mesofield new` CLI emits. Reading the templates is a
+  shortcut to understanding the expected file shape.
+- [`mesofield/processors/frame_mean.py`](api/generated/mesofield.processors)
+  — three-line frame processor. The minimum viable processor.
+
+## Retrofitting legacy sessions
+
+Sessions acquired before manifests landed can be retrofitted:
+
+```bash
+mesofield process retrofit-manifest /path/to/experiment
+```
+
+This walks the BIDS tree, reads `timestamps.csv` / `configuration.csv`,
+and synthesises an `AcquisitionManifest` per session. Calibration
+constants aren't recoverable (they weren't written), but everything
+else round-trips and downstream tools become happy again.

docs/index.md

@@ -0,0 +1,25 @@
+```{include} ../README.md
+```
+
+```{toctree}
+:caption: Get started
+:hidden:
+
+Home <self>
+tutorial
+```
+
+```{toctree}
+:caption: Guides
+:hidden:
+
+user_guide
+developer_guide
+```
+
+```{toctree}
+:caption: Reference
+:hidden:
+
+api/index
+```

docs/tutorial.md

@@ -0,0 +1,4 @@
+# Tutorial
+
+```{include} ../TUTORIAL.md
+```