Metadata-Version: 2.4
Name: twopy
Version: 0.2.1
Summary: Two-photon imaging analysis tool with a napari interface.
Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
License-Expression: MIT
Project-URL: Homepage, https://twopy.gumadeiras.com
Project-URL: Repository, https://github.com/gumadeiras/twopy
Requires-Python: <3.14,>=3.13
Description-Content-Type: text/markdown
Requires-Dist: h5py<4,>=3.16
Requires-Dist: matplotlib<4,>=3.10
Requires-Dist: napari[all]<0.8,>=0.7
Requires-Dist: numpy<3,>=2.3
Requires-Dist: pre-commit<5,>=4.6
Requires-Dist: qtpy<3,>=2.4
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: ruff>=0.15
Requires-Dist: scipy<2,>=1.17
Requires-Dist: tifffile<2027,>=2026.3
Requires-Dist: ty<0.1,>=0.0.34

# twopy

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

![twopy napari interface](https://raw.githubusercontent.com/gumadeiras/twopy/main/docs/assets/twopy-napari.png)

## 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 a standardized HDF5 format. The converted format includes 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 publishes 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.


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

Verify the install:

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

For a source checkout, copy `config.example.yml` to `config.yml` and edit the paths for your computer. `config.yml` stays local and is not tracked by git.

## Start

```sh
micromamba activate twopy
twopy
```

Open a source recording or converted recording directly:

```sh
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](https://twopy.gumadeiras.com)
- [Getting started](docs/getting_started.md): install, configure, launch, and save your first analysis.
- [GUI guide](docs/gui/index.md): one page per task — loading, ROIs, plots, custom workflows, group matching, saving.
- [Python API guide](docs/python_api.md): find recordings, convert data, extract traces, fit kernels, and open napari from scripts.
- [Writing custom workflows](docs/writing_custom_workflows.md): add your own analysis to the napari Custom tab.
- [Development guide](docs/development.md): source setup and local checks.
- [Input data spec](docs/input_data_spec.md): short recording folder contract.
- [Recording file reference](docs/recording_file_schema.md): detailed source and converted file schema.

## Check

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