aimez · public

magatfairy

MAGAT Analyzer experiments live as MATLAB objects that Python analysis cannot read, and magatfairy writes those objects to HDF5 so a lab can keep the vendor MATLAB stack while later workflows operate on the same tracks. The recording walks the repository tree so a lab can see MAGAT Analyzer layout and convert scripts beside a working HDF5 export.

Same cut on YouTube: youtu.be/QQuX2w2Lz34

Lab constraint use case

This page is a working case of agentic integration under research-lab constraints because MATLAB Engine stays required and MAGAT classes ship bundled at matlab/core, while locked-down machines call python -m cli.magatfairy and spatial assays convert with --stim-type spatial --no-bin when FID bins are absent. wavves keeps those convert flags and engine constraints on disk so a fresh agent thread hydrates the lab record from files.

Working export from that path: A27h_Chrimson_spatial_demo.h5 (24 tracks, 10 001 frames, spatial / no-FID).

Install

Clone the repo, then install Python deps and the MATLAB Engine bridge. A venv is optional and recommended. Bundled MAGAT classes at matlab/core are used by default.

git clone https://github.com/GilRaitses/magatfairy.git
cd magatfairy
python -m venv .venv
source .venv/bin/activate
python src/install/install.py
pip install -e .
magatfairy --help

On a managed machine that blocks PATH changes, call the module directly.

python -m cli.magatfairy --help
python -m cli.magatfairy convert auto /path/to/data --stim-type spatial --no-bin

Convert

Point the CLI at a genotype root, a single ESET folder with matfiles/, or one .mat experiment. Auto-detect is the usual entry. Spatial / odor stacks skip the FID .bin requirement.

magatfairy convert auto /path/to/eset --stim-type spatial --no-bin
magatfairy convert batch --root-dir /path/to/data --output-dir ./exports

H5 files land in the chosen output directory (default exports/). Each file carries tracks with derived quantities, global quantities, experiment time index and camera calibration when present.

Read the H5 in Python

Use smoothed location at derived_quantities/sloc (cm). Track-level ETI is the preferred time source.

import h5py

with h5py.File("A27h_Chrimson_spatial_demo.h5", "r") as f:
    keys = list(f["tracks"].keys())
    sloc = f[f"tracks/{keys[0]}/derived_quantities/sloc"][:]
    eti = f[f"tracks/{keys[0]}/derived_quantities/eti"][:]

Field mapping for MATLAB paths to H5 groups lives in docs/field-mapping.md.

Requirements

Python 3.8+ and MATLAB with MATLAB Engine for Python. If Engine install fails, install it from matlabroot/extern/engines/python. Override bundled MAGAT classes with MAGAT_CODEBASE or magatfairy config set magat_codebase /path/to/codebase when a lab keeps a fuller Analyzer tree.

magatfairy systemfairy
magatfairy config show

Source: github.com/GilRaitses/magatfairy. wavves control surface: wavves.aimez.ai