single-recording-results

name	single-recording-results
description	Complete reference for single-recording pipeline output data formats. Documents every file, directory, array shape, dtype, and NPZ key produced by the pipeline, plus verification checklists for output completeness. Use when evaluating single-recording processing results or when the user asks about single-recording output data.
user-invocable	true

Single-recording results data reference

Complete output data format documentation for the single-recording (within-recording) cindra processing pipeline.

---

Scope

Covers:

• Complete output data reference: every file, directory, array shape, dtype, and NPZ key produced by the pipeline
• Directory structure for combined and per-plane results
• Processing phase and file creation timeline
• Data type conventions and memory-mapping guidance
• Multi-recording compatibility requirements
• Output completeness verification

Does not cover:

• Configuration parameters (see /single-recording-configuration)
• Input data format, TIFF requirements, and acquisition parameters (see /acquisition-data-preparation)
• Processing workflow, batch operations, or status monitoring (see /single-recording-processing)
• Multi-recording output data formats (see /multi-recording-results)

---

Agent requirements

You MUST use the cindra MCP query and verification tools to inspect output data rather than reading output files directly when a tool exists for the task. If MCP tools are not available, invoke /cindra-mcp-environment-setup to diagnose and resolve connectivity issues.

---

Available tools

Use these cindra MCP tools to query and verify single-recording output data programmatically. Prefer these over manual file reads whenever possible.

Verification tool

Tool	Purpose
verify_single_recording_output_tool	Verifies completeness of all expected output files and NPZ keys

Query tools

Tool	Purpose
query_single_recording_metadata_tool	Queries recording dimensions, frame count, sampling rate, ROI/cell counts, and timing
query_detection_summary_tool	Queries detection image intensity statistics and estimated ROI diameter
query_registration_quality_tool	Queries per-plane registration offset summaries, correlations, bad frames, PC metrics
query_roi_statistics_tool	Queries per-ROI spatial statistics and classification with sorting and filtering
query_traces_tool	Queries fluorescence trace arrays for specific ROIs with optional downsampling

Recommended query order

1. query_single_recording_metadata_tool — understand recording properties and processing status
2. query_registration_quality_tool — assess motion correction quality per plane
3. query_detection_summary_tool — review detection image quality and ROI diameter
4. query_roi_statistics_tool — inspect ROI quality metrics and classification
5. query_traces_tool — examine fluorescence activity for specific ROIs

Query tool argument semantics

The recording_path argument for the verify and query tools must be the recording output directory, the parent of the cindra/ folder. This equals the recording_output_paths entries passed to and returned by the prepare tool when the output root differs from the raw-data root, not the raw-data path itself. The tools resolve the cindra/ subdirectory automatically.

The ROI indices accepted by query_traces_tool and query_roi_statistics_tool are 0-based positional row indices into the per-recording arrays, not a tracking identity. Out-of-range indices are silently dropped without an error, so a confidently "successful" empty result can mean a wrong index rather than missing data.

---

Output data reference

All results are saved under {output_path}/cindra/. The pipeline produces combined (multi-plane merged) data at the root level and per-plane data in numbered subdirectories. Channel 2 files are only present for two-channel recordings where both channels are functional.

Directory structure

cindra/
├── configuration.yaml                          # Saved pipeline configuration
├── acquisition_parameters.yaml                 # Saved acquisition metadata
├── combined_metadata.npz                       # Combined multi-plane metadata
├── detection_data/                             # Combined detection images
│   ├── mean_image.npy
│   ├── enhanced_mean_image.npy
│   ├── maximum_projection.npy
│   └── correlation_map.npy
├── roi_masks.npz                               # Combined ROI spatial data
├── roi_statistics.npz                          # Combined ROI shape statistics
├── cell_fluorescence.npy                       # Combined fluorescence traces
├── neuropil_fluorescence.npy
├── subtracted_fluorescence.npy
├── spikes.npy
├── cell_classification.npy
├── plane_0/                                    # Per-plane processing results
│   ├── runtime_data.yaml                       # Plane runtime metadata
│   ├── channel_1_data.bin                      # Registered binary data
│   ├── registration_data/                      # Registration arrays
│   │   ├── reference_image.npy
│   │   ├── bad_frames.npy
│   │   ├── rigid_y_offsets.npy
│   │   ├── rigid_x_offsets.npy
│   │   ├── rigid_correlations.npy
│   │   ├── nonrigid_y_offsets.npy
│   │   ├── nonrigid_x_offsets.npy
│   │   ├── nonrigid_correlations.npy
│   │   ├── principal_component_extreme_images.npy
│   │   ├── principal_component_projections.npy
│   │   └── principal_component_shift_metrics.npy
│   ├── detection_data/                         # Plane detection images
│   │   ├── mean_image.npy
│   │   ├── enhanced_mean_image.npy
│   │   ├── maximum_projection.npy
│   │   └── correlation_map.npy
│   ├── roi_masks.npz                           # Plane ROI spatial data
│   ├── roi_statistics.npz                      # Plane ROI shape statistics
│   ├── cell_fluorescence.npy
│   ├── neuropil_fluorescence.npy
│   ├── subtracted_fluorescence.npy
│   ├── spikes.npy
│   └── cell_classification.npy
├── plane_1/
└── ...

Processing phase and file creation timeline

Phase 1 — Binarize: Creates configuration.yaml, acquisition_parameters.yaml, per-plane channel_1_data.bin (and channel_2_data.bin if two-channel), and initial runtime_data.yaml per plane.

Phase 2 — Process (per-plane): Creates registration_data/, detection_data/, ROI .npz files, fluorescence .npy traces, and updates runtime_data.yaml with processing results and timing.

Phase 3 — Combine: Creates combined_metadata.npz, combined detection_data/, and combined ROI and trace files at the root level by merging all per-plane results.

---

Combined metadata

File: combined_metadata.npz

NPZ key	Dtype	Shape	Description
plane_count	uint8	(1,)	Number of planes combined
combined_height	uint32	(1,)	Height of combined field of view in pixels
combined_width	uint32	(1,)	Width of combined field of view in pixels
tau	float32	(1,)	Calcium indicator timescale in seconds
sampling_rate	float32	(1,)	Per-plane sampling rate in Hz
plane_heights	uint16	(N,)	Per-plane frame heights
plane_widths	uint16	(N,)	Per-plane frame widths
plane_y_offsets	int32	(N,)	Per-plane Y displacement for combined view
plane_x_offsets	int32	(N,)	Per-plane X displacement for combined view
registered_binary_paths	str	(N,)	Relative paths to channel 1 registered binaries
registered_binary_paths_channel_2	str	(N,)	Relative paths to channel 2 registered binaries (2-ch)

---

Detection images

Saved in detection_data/ subdirectories at both the combined root and per-plane levels. All files are .npy format, float32 dtype, with shape (height, width).

Channel 1 (always present):

File	Description
mean_image.npy	Temporal mean across all registered frames
enhanced_mean_image.npy	High-pass filtered mean for enhanced ROI visibility
maximum_projection.npy	Maximum intensity projection across all frames
correlation_map.npy	Pixel-wise correlation map for identifying active regions

Channel 2 (two-channel only, same shape and dtype):

File	Description
mean_image_channel_2.npy	Channel 2 temporal mean image
enhanced_mean_image_channel_2.npy	Channel 2 high-pass filtered mean
maximum_projection_channel_2.npy	Channel 2 maximum intensity projection
correlation_map_channel_2.npy	Channel 2 correlation map

---

ROI spatial data (roi_masks.npz)

Saved at both the combined root and per-plane levels. Uses the ROIMask serialization format.

NPZ key	Dtype	Shape	Description
pixel_counts	uint32	(num_rois,)	Number of pixels in each ROI
y_pixels	int32	(total_pixels,)	Y-coordinates of all ROI pixels (concatenated)
x_pixels	int32	(total_pixels,)	X-coordinates of all ROI pixels (concatenated)
pixel_weights	float32	(total_pixels,)	Spatial filter weights for each pixel
centroids	int32	(num_rois, 2)	ROI centroid coordinates (y, x)
radius	float32	(num_rois,)	Fitted ellipse radius per ROI
cluster_id	uint32	(num_rois,)	Multi-recording tracking cluster ID (0 = unclustered)
recording_count	uint16	(num_rois,)	Number of recordings ROI appears in
frame_width	uint32	(1,)	Frame width in pixels

To reconstruct per-ROI pixel arrays, split the concatenated y_pixels, x_pixels, and pixel_weights arrays using cumulative sums of pixel_counts.

Channel 2 data uses identical keys in roi_masks_channel_2.npz.

---

ROI shape statistics (roi_statistics.npz)

Saved at both the combined root and per-plane levels. Companion file to roi_masks.npz.

NPZ key	Dtype	Shape	Description
footprints	uint16	(num_rois,)	Spatial scale (hop size) used during detection
compactness	float32	(num_rois,)	Ratio of actual to expected mean radius (1.0=circular)
solidity	float32	(num_rois,)	Ratio of soma pixels to convex hull area
pixel_count	uint32	(num_rois,)	Total pixels in complete ROI
aspect_ratio	float32	(num_rois,)	Ellipse axis ratio indicating elongation
normalized_pixel_count	float32	(num_rois,)	Pixel count normalized by expected ROI size (soma)
skewness	float32	(num_rois,)	Fluorescence skewness (NaN if unavailable)
plane_index	int32	(num_rois,)	Imaging plane index for each ROI

Optional variable-length arrays (present only when the data exists):

NPZ key	Dtype	Description
soma_mask_counts	uint32	Per-ROI pixel count for soma masks
soma_mask	bool	Concatenated soma boolean masks
neuropil_mask_counts	uint32	Per-ROI pixel count for neuropil masks
neuropil_mask	int32	Concatenated raveled neuropil pixel indices
overlap_mask_counts	uint32	Per-ROI pixel count for overlap masks
overlap_mask	bool	Concatenated overlap boolean masks

Variable-length arrays use the same split-by-counts pattern as roi_masks.npz.

Channel 2 data uses identical keys in roi_statistics_channel_2.npz.

---

Fluorescence traces and classification

Saved at both the combined root and per-plane levels. All files are .npy format, float32 dtype.

Channel 1 (always present):

File	Shape	Description
cell_fluorescence.npy	(num_rois, frames)	Raw somatic fluorescence traces
neuropil_fluorescence.npy	(num_rois, frames)	Neuropil fluorescence traces
subtracted_fluorescence.npy	(num_rois, frames)	Neuropil-and-baseline-subtracted fluorescence
spikes.npy	(num_rois, frames)	Deconvolved spike estimates
cell_classification.npy	(num_rois, 2)	Column 0: is_cell label (1.0 or 0.0), column 1: classifier probability

If spike_deconvolution.extract_spikes is False, both subtracted_fluorescence.npy and spikes.npy are filled with zeroes. In that case query_traces_tool returns an all-zero trace with success=true rather than an error, so an all-zero spike or corrected trace can mean deconvolution was disabled rather than the absence of activity.

Channel 2 (two-channel only, same shapes):

File	Description
cell_fluorescence_channel_2.npy	Channel 2 raw somatic fluorescence
neuropil_fluorescence_channel_2.npy	Channel 2 neuropil fluorescence
subtracted_fluorescence_channel_2.npy	Channel 2 subtracted fluorescence
spikes_channel_2.npy	Channel 2 deconvolved spikes
cell_classification_channel_2.npy	Channel 2 classification results

Optional colocalization files (combined root and per-plane):

File	Shape	Description
cell_colocalization.npy	(num_rois, 2)	Channel-2 colocalization; columns depend on the extraction path
corrected_structural_mean_image.npy	(height, width)	Bleed-through-corrected structural channel mean

The cell_colocalization.npy column semantics depend on the extraction path. When one channel is structural, intensity-based colocalization runs (and also writes corrected_structural_mean_image.npy): column 0 is the is_colocalized label (1.0 or 0.0) and column 1 the probability. When both channels are functional, spatial colocalization runs instead: column 0 is the matched channel-2 ROI index (-1 if unmatched) and column 1 the overlap score. query_roi_statistics_tool surfaces this as a per-ROI colocalization pair plus top-level colocalization_mode and colocalization_columns.

The metadata tool's two_channels flag means channel 2 is present AND functional, not merely that the recording is dual-channel. A recording with a structural (non-functional) channel 2 reports two_channels=False yet still writes cell_colocalization.npy. Use the presence of cell_colocalization.npy (not two_channels) as the signal that channel-2 colocalization was computed.

---

Per-plane registration data

Saved in plane_N/registration_data/. All files are .npy format.

File	Dtype	Shape	Description
reference_image.npy	float32	(height, width)	Template image used for alignment
bad_frames.npy	bool	(num_frames,)	Frames flagged for excessive motion
rigid_y_offsets.npy	int32	(num_frames,)	Rigid registration Y displacement per frame
rigid_x_offsets.npy	int32	(num_frames,)	Rigid registration X displacement per frame
rigid_correlations.npy	float32	(num_frames,)	Phase correlation quality per frame
nonrigid_y_offsets.npy	float32	(num_frames, num_blocks)	Nonrigid Y displacement per block per frame
nonrigid_x_offsets.npy	float32	(num_frames, num_blocks)	Nonrigid X displacement per block per frame
nonrigid_correlations.npy	float32	(num_frames, num_blocks)	Nonrigid correlation quality per block per frame
principal_component_extreme_images.npy	float32	(2, num_components, height, width)	Mean images at PC extremes (0=low, 1=high)
principal_component_projections.npy	float32	(num_frames, num_components)	Frame projections onto principal components
principal_component_shift_metrics.npy	float32	(num_components, 3)	Columns: rigid magnitude, mean nonrigid shift, max nonrigid shift

---

Per-plane binary data

File	Format	Description
channel_1_data.bin	Contiguous int16	Motion-corrected frames: [frame0_row0_col0, frame0_row0_col1, ...]
channel_2_data.bin	Contiguous int16	Channel 2 motion-corrected frames (two-channel only)

Binary files store frames as contiguous int16 arrays. Each frame has height × width values. Read with np.memmap(path, dtype=np.int16, mode='r', shape=(frame_count, height, width)) using dimensions from runtime_data.yaml.

---

Per-plane runtime metadata (runtime_data.yaml)

A YAML file containing scalar metadata from all processing stages. Key sections:

Section	Key fields
io	frame_height, frame_width, frame_count, sampling_rate, plane_index
registration	valid_y_range, valid_x_range, bidirectional_phase_offset, bidirectional_phase_corrected, normalization_minimum, normalization_maximum
detection	roi_diameter, roi_diameter_channel_2, aspect_ratio
timing	binarization_time, registration_time, two_step_registration_time, registration_metrics_time, detection_time, extraction_time, classification_time, deconvolution_time, detection_time_channel_2, extraction_time_channel_2, classification_time_channel_2, deconvolution_time_channel_2, total_plane_time, date_processed, python_version, cindra_version

Array fields from registration, detection, and extraction are saved as separate .npy files (documented above) and set to None in the YAML.

---

Data type conventions

Category	Dtype	Examples
Pixel coordinates	int32	y_pixels, x_pixels, centroids, rigid offsets
Images and traces	float32	mean_image, fluorescence, spikes, correlations
Counts / dimensions	uint32	pixel_counts, frame_count, combined_height
Small counts	uint16	plane_heights, plane_widths, recording_count
Booleans	bool	bad_frames, soma_mask, overlap_mask
Plane indices	int32	plane_index
Plane counts	uint8	plane_count

Extraction trace, classification, and colocalization .npy files and all .npz archives are saved with allow_pickle=False; detection and registration .npy files use NumPy save defaults but contain only numeric arrays that load safely with allow_pickle=False. Arrays support memory-mapped loading via np.load(path, mmap_mode='r+') for efficient access to large datasets.

---

Multi-recording compatibility requirements

For recordings intended for multi-recording processing, single-recording processing must complete all three phases (binarize, process, combine); no special configuration is required. For the authoritative list of the single-recording outputs the multi-recording pipeline consumes, see /multi-recording-configuration (Prerequisites from single-recording processing).

---

Related skills

Skill	Relationship
/cindra-pipeline	Overview: end-to-end phases, handoffs, and the single-vs-multi entry point
/cindra-mcp-environment-setup	Prerequisite: cindra MCP server for query and verification tools
/acquisition-data-preparation	Upstream: input data, TIFF requirements, and acquisition parameters
/single-recording-configuration	Configuration parameter reference for the single-recording pipeline
/single-recording-processing	Processing workflow that produces this output
/multi-recording-results	Companion output data reference for the multi-recording pipeline
/multi-recording-configuration	Multi-recording configuration requires these outputs as prerequisites
/visualization	Launch viewers and query tools to visualize and inspect this output data

---

Verification checklist

Use verify_single_recording_output_tool to automate this verification. The tool checks all expected files and NPZ keys and returns a completeness verdict with any missing items listed. Fall back to the manual checklist below only if the MCP tool is unavailable. Replace N with the expected plane count from the acquisition parameters.

Single-Recording Output Completeness:
Root-level files:
- [ ] `configuration.yaml` exists
- [ ] `acquisition_parameters.yaml` exists
- [ ] `combined_metadata.npz` exists and contains `plane_count`, `combined_height`, `combined_width` keys

Combined detection images (cindra/detection_data/):
- [ ] `mean_image.npy` exists
- [ ] `enhanced_mean_image.npy` exists
- [ ] `maximum_projection.npy` exists
- [ ] `correlation_map.npy` exists
- [ ] Channel 2 variants exist if `main.two_channels` is True and both channels are functional

Combined extraction data (cindra/):
- [ ] `roi_masks.npz` exists and contains `pixel_counts`, `y_pixels`, `x_pixels`, `pixel_weights` keys
- [ ] `roi_statistics.npz` exists and contains `footprints`, `compactness`, `plane_index` keys
- [ ] `cell_fluorescence.npy` exists with shape (num_rois, num_frames)
- [ ] `neuropil_fluorescence.npy` exists with shape matching cell_fluorescence
- [ ] `subtracted_fluorescence.npy` exists with shape matching cell_fluorescence
- [ ] `spikes.npy` exists with shape matching cell_fluorescence (if spike_deconvolution.extract_spikes is True)
- [ ] `cell_classification.npy` exists with shape (num_rois, 2)
- [ ] Channel 2 trace and classification files exist if both channels are functional

Per-plane directories (cindra/plane_0/ through cindra/plane_{N-1}/):
- [ ] Each expected plane directory exists
- [ ] Each plane contains `runtime_data.yaml` with non-zero `io.frame_count` and `io.sampling_rate`
- [ ] Each plane contains `channel_1_data.bin` (registered binary)
- [ ] Each plane contains `channel_2_data.bin` if `main.two_channels` is True

Per-plane registration data (plane_N/registration_data/):
- [ ] `reference_image.npy` exists
- [ ] `bad_frames.npy` exists
- [ ] `rigid_y_offsets.npy` and `rigid_x_offsets.npy` exist
- [ ] `rigid_correlations.npy` exists
- [ ] Nonrigid arrays exist if nonrigid_registration.enabled is True
- [ ] PC metric arrays exist if registration.registration_metric_principal_components > 0

Per-plane detection and extraction data (plane_N/):
- [ ] `detection_data/` contains the four channel-1 images: `mean_image.npy`, `enhanced_mean_image.npy`,
      `maximum_projection.npy`, and `correlation_map.npy`
- [ ] `roi_masks.npz` and `roi_statistics.npz` exist
- [ ] Fluorescence trace .npy files exist with consistent shapes across all traces
- [ ] `cell_classification.npy` exists with shape (num_rois, 2)

Multi-recording readiness (if multi-recording processing is planned):
- [ ] `combined_metadata.npz` contains `registered_binary_paths` key
- [ ] All registered binary files referenced in `registered_binary_paths` exist on disk