User Guide

This guide is for experimenters — people running acquisitions on a configured rig. If you’re writing a new device class or subclassing Procedure, see the Developer Guide instead.

Overview

A mesofield experiment is described by up to two files:

File	Owns	Usually edited by	Required?
hardware.yaml	What devices exist on this rig and how to talk to them	Rig maintainer (one-time per machine)	Yes — the rig you launch
experiment.json	Subjects, sessions, protocol, duration	Experimenter (per study / per day)	Optional — load it, author it in the GUI, or script it

The hardware.yaml is all you need to launch. The mesofield CLI brings up the GUI and orchestrates the acquisition; experiment parameters can be loaded, authored in the Configuration Wizard, or supplied by a scripted Procedure.

Launching an acquisition

Point the CLI at your rig. The argument can be a hardware.yaml (rig only), an experiment.json (its adjacent hardware.yaml is auto-detected), a scripted procedure.py, or a directory containing them:

mesofield launch path/to/hardware.yaml       # rig only — author params in the GUI
mesofield launch path/to/experiment.json     # rig + params
python -m mesofield launch path/to/hardware.yaml   # module entry point, equivalent

This opens the main acquisition window with hardware initialised. When an experiment.json is supplied its parameters populate the form; otherwise use the Configuration Wizard to load or author one.

Experiment configuration (experiment.json)

{
    "Configuration": {
        "experimenter": "you",
        "protocol": "HFSA",
        "experiment_directory": "/where/mesofield/writes_outputs",
        "duration": 1000
    },
    "Subjects": {
        "STREHAB07": {
            "sex": "F",
            "session": "01",
            "task": "mesoscope"
        }
    },
    "DisplayKeys": [
        "subject",
        "session",
        "task",
        "experimenter",
        "protocol",
        "duration",
        "start_on_trigger",
        "led_pattern"
    ]
}

Field notes:

• experiment_directory and hardware_config_file are optional — both default to siblings of the JSON file’s parent directory.

• duration is in seconds. The MDA sequence builds duration × camera.fps frames.

• Subjects keys become BIDS sub-<key> directories under experiment_directory/data/. session and task become ses-<id> and task-<id>.

• DisplayKeys decides which fields appear in the editable form in the GUI. Edits persist back to experiment.json when the run completes (or via the Save button).

• Anything you add to the JSON outside of these reserved keys is preserved on save.

The acquisition window

The window has three regions:

1. Live Viewer (top-left) — per-camera snap / live / progress panels. The mesoscope view sits next to the pupil view by default.

2. Configuration form (top-right) — the DisplayKeys you declared, plus a subject selector, Record, Add Note, and dynamic hardware controls (LED test, NIDAQ pulse, etc.) for whatever your hardware.yaml requested.

3. Encoder / processor plots (bottom) — live traces of any frame processor with plot=True and any encoder / serial device with start_live_view enabled.

The Toggle Console action in the toolbar opens an embedded IPython shell with the live procedure bound — handy for inspecting state mid-run.

Notes during a run

Click Add Note at any time. Notes are timestamped and saved to data/sub-<id>/ses-<id>/notes.json when the run completes.

What ends up on disk

After a run, your experiment directory looks like:

<experiment_dir>/
    experiment.json               # updated with any DisplayKeys edits
    hardware.yaml
    data/
        sub-<id>/
            ses-<id>/
                manifest.json     # AcquisitionManifest — the contract
                notes.json
                <task>/
                    *_meso.ome.tiff
                    *_meso_frame_metadata.json
                    *_pupil.mp4
                    *_pupil_frame_metadata.json
                    *_wheel.csv

The manifest.json is a typed AcquisitionManifest (from mesokit-schema) describing every producer, its output path, its metadata sidecar, and any calibration constants. Downstream analysis tools read the manifest instead of globbing.

Embedded IPython console

Toolbar → Toggle Console. The kernel pre-binds:

• self — the main window (MainWindow)

• procedure — the active Procedure

• data — the mesofield.data package

Common one-liners:

procedure.config.items()                    # all configuration values
procedure.config.set("duration", 600)       # change the run length
procedure.hardware.cameras                  # list configured cameras
procedure.hardware.primary                  # the camera that drives MDA
procedure.events.procedure_started.connect(my_callback)

Logging

All application logs flow through one loguru logger and land in:

logs/mesofield.log

• Rotates daily at midnight.

• The console shows colourised logs at INFO; the file captures everything down to DEBUG.

• Uncaught exceptions are routed through the same hook so crashes leave a trail.

• Chatty third-party libraries (matplotlib, asyncio, traitlets) are pinned at WARNING or above.

To change the location or verbosity, see mesofield/utils/_logger.py.

System requirements

Mesofield is tested on Windows 10/11. For multi-camera acquisition with large files we recommend:

• ≥ 32 GB RAM

• 12th-gen Intel i7 or equivalent

• Fast local storage (NVMe SSD) for the experiment directory