Imaging data
Calcium imaging enters a project in two parts:
- Cell segmentation (Cellpose): which pixels belong to which cell, and which cell is which project neuron. Required for holographic stimulation.
- Traces: fluorescence per cell, extracted from raw TIFFs or imported from Suite2p output, added as trace (and spike) data.
Patch-clamp recordings are covered in Patch-clamp data.
Cell segmentation
Open File → Cell segmentation, or drop a TIFF or PNG on the Cell segmentation tab. A dropped file opens the same dialog with the file waiting: choose the model and Adjust brightness first as below, then click Segment file.
Segment an image: choose a Model (cpsam, cpsam_v2, cpdino,
cpdino-vitb; cpsam_v2 is more sensitive on low-SNR fields) and click
Select file for segmentation… with a mean-fluorescence TIFF or a PNG.
Results are saved next to the image with the model in the name
(fov_cpsam_seg.npy, fov_cpsam_cp_masks.png), so other models' results and
a Cellpose GUI fov_seg.npy are kept. Adjust brightness first lets you set
brightness/contrast before segmenting; Cellpose then segments the adjusted
image.
Or load existing files: an image (PNG/TIF) and a segmentation (.npy,
including Cellpose _seg.npy, or .csv). Open Cellpose and Open Fiji
launch the external tools.
Neuron ID mapping
Mapping strategy decides which Cellpose cell is which input neuron:
| Strategy | Mapping |
|---|---|
| Linear | Input neuron 0 is the cell with Cellpose ID equal to the offset, then upward; lower IDs wrap to the end. |
| Custom | Type pairs input:cellpose (e.g. 1:12,2:3), or tick Assign by clicking cells and click cells in order (unclicked cells get the remaining IDs in Cellpose order). |
| Custom with areas of interest | A square and/or circle, each preferential or exclusion. Cells in preferential areas get the lowest IDs, cells in exclusion areas the highest, each tier in Cellpose-ID order. |
Input IDs are 0-based: 0 is the first input row. The SysCon2 export and the
readout use the same IDs, so 1:12 always stimulates and records cell 12 as
input row 1.
Area shapes can be set in pixels or percent, and dragged and resized in the viewer; the mapping updates as they move. Under Linear the shapes are shown and kept but do not change the mapping.
The segmentation is saved in the project. Delete Cellpose Data removes it.
Raw calcium imaging TIFFs
File → Import data → Output → Calcium Imaging (raw .tif) extracts traces from one or more 2-photon TIFF stacks in the background.
- Add TIFF… the stack(s) and tick the ones to import.
- Pick Cellpose masks: those loaded in the project (with mapping), a
_seg.npyfile, or Suite2p auto-detection (set Cell diameter). - Set the parameters and click Run pipeline.
The file list is saved with the project: when the dialog opens again, files added before are listed (unticked; files that no longer exist are dropped), so another one can be imported without browsing for it. Clear list empties it.
Several ticked files are, by default, separate recordings: each runs
through the pipeline in turn (never two at once) with the same settings and
becomes its own data group, named after the file (rec1, rec1 (2) if the
name is taken; Simulation is reserved and :: becomes _), with its movie
in the Imaging tab. The progress window names
the file being processed. One summary at the end lists the imported files and
the failed ones with the reason; a failed file does not stop the others.
Stop after this file lets the running file finish and imports what is
done; pressing it again (Abort this file too) also stops the running file.
One Undo removes the whole batch, data groups and movies; Redo adds it back.
Undoing a single-file import likewise removes its movie too.
The same Cellpose masks, input array and Imaging started at apply to every file, so the files must show the same field of view (frame size) and start at the same time on the input array. With Suite2p auto-detection the ROIs are found per file, and the first imported file's ROIs become the project's cell segmentation.
Choose Parts of one recording instead for a recording split over several
files (e.g. ScanImage's _00001, _00002, … parts): they are joined, in list
order, into one data group.
Raw stacks over ~1 GB crash Cellpose. Segment a projection instead: Open
Fiji, Image → Stacks → Z Project… (Max for sparse, Mean for dense
activity), save it, segment it with Open Cellpose, then load the
_seg.npy. The pipeline still runs on the full stack.
| Parameter | Default | Notes |
|---|---|---|
| Pipeline | Suite2p | Or Simply average from ROI. |
| Frame rate (fs) | 30 Hz | Per channel. |
| # channels | 2 | 1 when ROI average is chosen. |
| Functional channel | 1 | |
| Indicator tau | 0.5 s | jGCaMP8m. |
| Neuropil coefficient | 0.7 | |
| Spike threshold | 0.02 | Suite2p. |
Simply average from ROI streams the stack, so long recordings (15 min at 512×512, about 14 GB) need not fit in memory. Options:
- Neuropil correction: subtracts coefficient × an annulus of the 350 nearest pixels more than 2 px from any cell.
- Compute ΔF/F and deconvolve spikes: ΔF/F against Suite2p's sliding maximin baseline (30 s) of the raw fluorescence; OASIS spikes counted above Spike threshold (ΔF/F) (default 0.1).
- Stimulation artefact suppression: replaces frames lit by an input array's stimulation with the mean of the neighbouring clean frames. Imaging started at is the first frame's time on that array's axis (0 if both started together, positive if imaging started later). It is on by default only when an input array looks like pulsed light stimulation, and that array is preselected. Electrophysiology inputs (units A, pA, nA, V, mV, ...; e.g. an imported patch-clamp wave) and inputs non-zero in more than 90% of their samples are not preselected: every frame they overlap would be replaced, flattening that stretch of the traces. The import message reports how many frames were replaced.
Precomputed traces
File → Import data → Output → Calcium Imaging (Suite2p outputs): choose
the output folder (with F.npy, Fneu.npy, spks.npy, stat.npy), or pick
files under Individual File Selection (.npy or .csv).
- Traces are
F − 0.7·Fneu(whenFneuis present), normalised to 0-1 per neuron. - Spikes come from
spks.npy, kept above Spike threshold (default 0.02). - Max neurons to import defaults to 2; Sample rate to 30 Hz.
- Rows are mapped to input neurons through the Cellpose mapping when one is loaded.
Imaging tab
- Channels / Show: for interleaved multi-channel movies, set the channel count and pick the channel to play; All frames plays every frame. The TIFF pipeline presets both. ScanImage recordings use Functional channel in the ScanImage tab instead.
- Moved files: projects store only the movie path. If it is missing, click Locate file…; other parts of a split movie are found in the same folder. Save the project to keep the new path.
- Save imaging data…: choose frames (counted from 1; Current frame and All frames buttons), then Original frames (TIFF substack) or With stimulation marks (TIFF or GIF), which marks stimulated cells with a red "x" on a fixed grey scale.
GPU acceleration
Cellpose and Suite2p run on PyTorch and are far faster on an NVIDIA (CUDA) or Apple Silicon (MPS) GPU. Intel integrated graphics are not supported. Check:
A +cpu version or False means a CPU-only build (the Cellpose GPU option is
greyed out). Install a GPU build:
This is required on Windows, where the default wheel is CPU-only. A later
uv sync can revert it; set UV_TORCH_BACKEND=auto to avoid that. In a conda
environment use
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
(pick the cuXXX matching your driver). Without a supported GPU, segment on
another machine and import the _seg.npy.