Getting started

This page takes you from a blank machine to a saved analysis. It should take about ten minutes.

1. Install twopy

The examples use micromamba; any conda-compatible tool works.

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

Check that the package imported cleanly:

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

2. Tell twopy where your data lives

twopy reads a config.yml file from the directory you launch it from. Copy the example and edit the paths:

cp config.example.yml config.yml

The main keys you usually edit:

  • database_path — folder holding the lab SQLite database files.

  • data_paths — list of folders that contain microscope recording folders. twopy checks them in order; the first one that has the recording wins.

  • analysis_output — where saved analyses end up. Use source to write into each recording’s own twopy/ folder, or a folder path to mirror the recording tree under it.

  • analysis_caching — keep true for normal use. twopy converts and writes locally first, then publishes the saved files to analysis_output in the background.

config.yml is private to your machine and is never committed.

3. Launch the app

micromamba activate twopy
twopy

Or open a recording directly:

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

You can pass a raw microscope folder, an already-converted folder, or a recording_data.h5 file. If the recording has not been converted yet, twopy converts it first.

4. Open your first recording

The right side of napari has a tabbed dock called twopy. The first tab, Load, has three ways to pick a recording:

  • Search database — opens a side-by-side filter window (user, cell type, sensor, stimulus, date) over your lab database. See Loading recordings.

  • Load manually — pick one or more source folders, converted folders, or recording_data.h5 files.

  • Load CSV list — reopen a list you saved earlier with Save loaded list.

When the recording loads, napari shows the mean image, an optional aligned movie, and an editable rois Labels layer.

5. Draw an ROI and watch the response

  1. Click the rois layer in the layer list on the left.

  2. Pick a label number and use the paint tool to draw a cell.

  3. The top twopy responses dock updates as soon as your edit is committed.

If you want generated ROIs instead of hand-drawn ones, the ROIs tab can make a pixel grid, a micron grid, or a watershed segmentation from the mean image. See Drawing and generating ROIs.

6. Save the analysis

Switch to the Export tab and click Save ROIs + analysis. twopy writes:

  • rois.h5 — the ROI masks.

  • analysis_outputs.h5 — dF/F traces, grouped responses, QC scores, and your current processing settings.

  • response_heatmaps.h5 — movie-level response heatmaps.

  • exports/csvs/response_summary_trials.csv and response_summary_grouped.csv — flat per-trial and per-epoch tables.

With analysis_caching: true, the same files sync to analysis_output in the background. The Metadata tab shows whether the sync succeeded.

Where to go next