twopy

Two-photon imaging analysis tool for the Clark Lab output format.

Getting Started

twopy lets you open two-photon recordings, draw ROIs, plot responses in real time, process and analyze them, and save them.

When you first load a recording, twopy converts it to HDF5 files that it owns. Those files include the aligned movie, mean image, stimulus tables, photodiode signals, and recording metadata. Analysis and the GUI both work from the converted files, so the original source files remain separate from twopy's outputs. By default, converted recordings and interactive analysis outputs are cached locally under ~/.cache/twopy/recordings for speed; saving ROIs and analysis copies the changed output files back to the configured analysis_output location in the background.

Install

Examples use micromamba, but any conda-compatible environment manager should work.

micromamba create -n twopy -c conda-forge python=3.13 pip -y
micromamba run -n twopy python -m pip install twopy

Verify the install:

micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'

Create the config template in your user folder:

twopy config setup

twopy prints the config path it wrote. On macOS and Linux the default is ~/.config/twopy/config.yml; on Windows it is under %APPDATA%\twopy\config.yml. Edit that file with your database, data, and output paths before launching twopy. If you launch twopy before a config exists, twopy creates the same template, prints the path, and stops so you can edit it.

Validate the active config and show its path and file contents:

twopy config

Start

micromamba activate twopy
twopy

twopy validates the config before opening napari. It does not require lab data folders or network drives to be mounted at launch.

Open a source recording or converted recording directly:

twopy /path/to/source/recording
twopy /path/to/recording_data.h5

Basic GUI flow:

1. Search the database or load a recording manually.
2. Draw or edit ROIs in the rois Labels layer.
3. Update response plots from the current ROIs.
4. Click Save ROIs + analysis in Export when the plots look right.

When a source recording has not been converted yet, twopy converts it first. Converted data includes the aligned movie, mean image, stimulus tables, photodiode signals, and recording metadata.

Docs

• Full documentation
• Getting started: install, configure, launch, and save your first analysis.
• GUI guide: one page per task — loading, ROIs, plots, custom workflows, group matching, saving.
• Python API guide: find recordings, convert data, extract traces, fit kernels, and open napari from scripts.
• Writing custom workflows: add your own analysis to the napari Custom tab.
• Development guide: source setup and local checks.
• Input data spec: short recording folder contract.
• Recording file reference: detailed source and converted file schema.

Check

micromamba run -n twopy pre-commit run --all-files