GIAnT-Python

GIAnT-Python is a Python package for processing glutamate imaging data, with advanced capabilities for SLAP2 recordings.

Currently, only SLAP2 Band Scan processing is implemented: BandSILo source extraction and Band Scan ROI annotation from pre-registered recordings. Additional functionality is available in GIAnT-MATLAB, and efforts are underway to port it into GIAnT-Python.

Requirements and scope

Provide an existing trial table, raw recordings with sidecars, reference TIFFs, alignment files, and the band registration lookup table. Python consumes these inputs; it does not organize or register recordings. Standard SILo, standalone deconvolution, trial-table writing, config-file loading, and checkpoint/resume are not supported.

Analysis trials come from the supplied table; Python does not split or merge them.

Installation

From the repository root, with Python 3.10 or later:

pip install -e .

Installation requires Git/network access for the slap2_utils dependency. Interactive ROI drawing uses OpenCV and tkinter; tkinter must be available in the Python installation. Headless extraction does not need a display.

For development setup and documentation builds, see CONTRIBUTING.md.

Run BandSILo

Use the actual trial-table filename, or pass a loaded TrialTable:

from giant_python import ExecutionOptions, extract_band_sources

summary = extract_band_sources(
    "path/to/trial_table.h5",
    execution=ExecutionOptions(max_workers=6, verbose=True),
)

Annotations are disabled by default. Use BandSiloParams for scientific settings, ExecutionOptions for workers/progress/trial limits, and AnnotationOptions for ROI inclusion and GUI policy. A chainable Pipeline is also available; see API and data conventions.

Paths matter: raw inputs come from the table's datadr; results are written under its savedr, in source_extraction/experiment_summary.h5. Copying the table does not change either directory. For explicit directory overrides and a fresh output location, use the staging example.

Manual ROIs

• Draw or load annotations with annotate_rois(table_or_filename) or Pipeline.annotate().
• Extract using existing ROIs with annotations=AnnotationOptions(enabled=True, interactive=False). Missing required annotations raise an error.
• The CLI provides giant annotate and giant extract, each taking a trial-table filename. For extraction with existing ROIs and no GUI, select --draw-user-rois --headless.

Annotations are stored beneath the table's savedr in annotations/annotations.h5.

Results and cautions

The returned ExperimentSummary is also saved to disk. Access imaging paths through summary.paths; each path contains sources, ROIs, visualizations, frame information, depths, and global fluorescence. Arrays are eager and may share storage. path_index is zero-based; disk groups start at Path1.

• Extraction saves least-squares dF_ls, convolution-constrained dF_denoised, and fitted events. Source activity uses channel zero; other channels and missing observations are NaN. Events are not automatically neuronal spikes, and smoother traces do not establish improved SNR.
• ROI Fsvd is written as NaN unless supplied explicitly; BandSILo does not compute it. Disabled or empty annotations produce zero-ROI datasets.
• Acquisition line indices are one-based; spatial coordinates are zero-based [z, y, x]. Saved offline shifts follow the MATLAB SILo alignment-displacement sign.
• Use a fresh output location for each analysis. Updating an existing summary preserves unrelated paths and existing root parameters/layout flags; writes are not atomic replacement or resume.

Reference

Documentation provenance.¹

• API, configuration, and staging
• Trace estimation, controls, and scientific caveats
• File formats, coordinates, and MATLAB interoperability
• Architecture and module ownership

Support

Occasional updates: no fixed update schedule. Community involvement through issues and pull requests is welcome.

Footnotes

1. Current documentation has been generated by large language models (LLMs) from human-verified code. ↩