multi-recording-configuration

name	multi-recording-configuration
description	Complete reference for multi-recording pipeline configuration parameters, prerequisites, and MCP configuration tools. Documents all 7 configuration sections, parameter meanings, default values, prerequisites from single-recording processing, and available MCP tools for generating, modifying, and validating configurations and discovering candidates. Use when configuring multi-recording processing or when the user asks about multi-recording configuration parameters.
user-invocable	true

Multi-recording configuration reference

Complete parameter reference for the multi-recording (cross-recording) cindra ROI tracking pipeline.

---

Scope

Covers:

• All 7 configuration sections and their parameters for the MultiRecordingConfiguration dataclass
• Default values, types, and descriptions for every parameter
• Prerequisites from single-recording processing
• Pipeline-set parameters
• MCP tools for configuration generation, modification, validation, and recording discovery
• Registration and tracking tuning guidance
• Configuration compliance verification

Does not cover:

• Output data formats and file references (see /multi-recording-results)
• Processing workflow, batch operations, or status monitoring (see /multi-recording-processing)
• Single-recording configuration (see /single-recording-configuration)

---

Agent requirements

You MUST use the cindra MCP tools for all configuration operations. Do not hand-edit configuration files or import cindra Python functions directly when an MCP tool exists for the task. If MCP tools are not available, invoke /cindra-mcp-environment-setup to diagnose and resolve connectivity issues.

---

Available tools

These tools are registered on the cindra-mcp server. Tool parameters and return values are self-documented via MCP introspection.

Tool	Purpose
generate_config_file_tool	Generates a default configuration YAML for the specified pipeline type
discover_recordings_tool	Discovers single and multi-recording candidates under a root directory
resolve_dataset_name_tool	Constructs qualified dataset names from base name + specifier
read_config_file_tool	Reads any YAML file as a raw dictionary (supports legacy and non-cindra)
validate_config_file_tool	Validates a cindra config against schema, reports errors and non-defaults
set_config_values_tool	Writes new values into an existing configuration file, atomically

set_config_values_tool is the only supported way to change a parameter of an existing file. It addresses each parameter by the section.parameter dotted path validate_config_file_tool reports under non_default_parameters, resolves every entry before applying any of them so a rejected entry writes nothing, and re-validates what it wrote. Supply each value in the form the YAML carries it, so a path is a string, an enumeration is its raw value, and a tuple is a list. Gate on the returned valid flag rather than on success, and never call it against a configuration whose jobs are executing, because the pipeline reads configuration from disk when it dispatches a job.

discover_recordings_tool returns candidate objects rather than bare paths. Each multi_recording_candidates entry maps recording_root to the session-level root and output_root to the parent of the cindra/ directory holding the discovered combined_metadata.npz. Read candidate["output_root"] for the output_roots of resolve_dataset_name_tool and prepare_multi_recording_batch_tool.

---

Configuration overview

The multi-recording pipeline uses MultiRecordingConfiguration, a dataclass with 7 nested sections. This pipeline tracks ROIs across multiple recordings and extracts consistent fluorescence traces using consensus template masks.

All parameters are specified in the MultiRecordingConfiguration YAML file. The pipeline loads the fully resolved configuration directly from the file without any runtime overrides.

CPU worker allocation lives outside the configuration file. The discovery and extraction stages each receive their worker count as an invocation argument, supplied by the cindra run options -dw/--discover-workers and -ew/--extract-workers, or by execute_processing_jobs_tool and execute_full_pipeline_tool at dispatch time.

---

Prerequisites from single-recording processing

Before multi-recording processing, all recordings must have completed single-recording processing through all four phases (binarization, registration, processing, combination). The multi-recording pipeline locates single-recording output by recursively searching each output root for a combined_metadata.npz file, and it rejects an output root holding more than one. The parent directory of this file becomes the cindra root for that recording.

Required single-recording outputs per recording:

File	Used for
combined_metadata.npz	Recording discovery, frame dimensions, binary paths
roi_masks.npz	Loading ROI spatial data for selected ROIs
roi_statistics.npz	ROI filtering by size and shape
cell_classification.npy	ROI filtering by classifier probability
detection_data/*.npy	Reference images for diffeomorphic registration
channel_1_data.bin	Fluorescence extraction from registered binary data

No special single-recording configuration is required. The pipeline always generates combined output and preserves registered binary files by default.

Extraction opens each recording's plane binaries as one combined view whose frame count is that of the recording's shortest plane. Binarization gives every plane of the recording the same frame count, so that view spans the recording's full frame range.

---

Pipeline-set parameters

These parameters are set automatically by the pipeline and should not be manually configured:

Parameter	Set by	Value
recording_io.recording_directories	CLI/MCP	List of output roots (output_roots or -rp)
recording_io.dataset_name	MCP	The qualified dataset name the prepare tool takes
runtime.display_progress_bars	CLI/MCP	Whether to show progress bars

The on-disk field keeps the name recording_directories while the MCP argument that fills it is output_roots. Both name one concept, a completed single-recording run's output root, the parent of that recording's cindra/ directory.

---

Section 1: runtime

Runtime behavior settings shared with the single-recording pipeline.

Parameter	Type	Default	Description
display_progress_bars	bool	False	Show progress bars. Batch tools force this False.

cindra run displays progress bars by default and writes its choice into this field before dispatching, so the flag that suppresses them is -np/--no-progress. The batch MCP tools write False into every per-dataset configuration they create, because concurrent jobs sharing a terminal interleave their bars.

Worker allocation reaches the discovery and extraction stages as an invocation argument, as described in the Configuration overview section. Omitting a worker option applies the measured default of 2 workers for discovery and 16 for extraction, published as DISCOVERY_WORKERS and EXTRACTION_WORKERS in cindra.orchestration. Setting a worker option to -1 requests every available core.

---

Section 2: recording_io

Controls input recording paths, output dataset naming, and ROI selection caching. The pipeline receives a list of recording directories (populated by the MCP batch tool) and natural-sorts them to determine the main recording. Each recording stores its own multi-recording output under its own cindra/multi_recording/{dataset_name}/ directory. The main (first natural-sorted) recording additionally holds the shared resolved configuration and the processing tracker. ROI selection results are cached per dataset so that re-running the pipeline skips selection unless repeat_selection is enabled.

Parameter	Type	Default	Description
recording_directories	tuple[Path]	()	Set by batch tool. Absolute paths to recording roots. Natural-sorted, first = main recording.
dataset_name	str	""	REQUIRED. Unique identifier for this dataset. Used for output folder: multi_recording/{dataset_name}/.
repeat_selection	bool	False	Re-run ROI selection even if existing selections are found.

Important notes on recording_io

• recording_directories is populated by the MCP batch tool from its output_roots argument, or by cindra run -rp/--recording-path. Both take completed single-recording output roots.
• dataset_name reaches the resolved per-dataset copy through prepare_multi_recording_batch_tool, as the Configuration lifecycle section states.
• When repeat_selection is True, ROI selection is re-run using current criteria even if selections already exist. This allows updated single-recording results or modified selection criteria to be integrated.

---

Section 3: roi_selection

Filters single-recording ROIs before cross-recording tracking. Each recording's detected ROIs are filtered by classifier probability, spatial size, and distance from MROI region borders. Only ROIs passing all criteria enter the tracking pipeline. This pre-filtering controls the quality/quantity tradeoff for the tracked population.

Parameter	Type	Default	Description
probability_threshold	float	0.85	Min classifier probability from single-recording. Lower = keep more ROIs.
maximum_size	int	1000	Max ROI size (pixels). ROIs larger are excluded.
mroi_region_margin	int	30	Min distance (pixels) from ROI centroid to MROI region border.
probability_threshold_channel_2	float / None	None	Channel 2 probability threshold. None = use channel 1 value.
maximum_size_channel_2	int / None	None	Channel 2 max size. None = use channel 1 value.
mroi_region_margin_channel_2	int / None	None	Channel 2 MROI margin. None = use channel 1 value.

Channel 2 parameters default to None, which causes the pipeline to fall back to the corresponding channel 1 value. Set these independently when channel 2 ROIs have different classification or size characteristics.

Tuning guidance

• More tracked ROIs: Lower probability_threshold (0.7-0.8) to include lower-confidence ROIs from single-recording detection. This feeds more candidates into tracking but may include noisier ROIs.
• Fewer false positives: Raise probability_threshold (0.9+) to only track high-confidence cells.
• Large ROIs excluded: Increase maximum_size (1500-2000) if legitimate cells exceed the default limit.
• MROI edge artifacts: Increase mroi_region_margin (40-60) to exclude more ROIs near region borders where registration distortion is highest. The parameter applies to MROI recordings, which are the only ones for which region borders are computed.
• After re-running single-recording processing: Set repeat_selection=True to re-apply selection criteria against updated single-recording results, then set back to False.

---

Section 4: diffeomorphic_registration

Aligns recordings to a common coordinate space using groupwise diffeomorphic Demons registration. At each scale level of a coarse-to-fine pyramid, symmetric Demons forces are computed from every recording to all others and averaged, producing a displacement field that is regularized via cubic B-spline fitting with injectivity constraints to guarantee invertibility. Deformations are composed across scales to produce smooth, invertible forward and inverse maps per recording. Forward maps warp ROI masks into the shared space for tracking. Inverse maps transform tracked template masks back to each recording's native space for signal extraction.

Parameter	Type	Default	Description
image_type	str	"enhanced_mean"	Reference image type: "mean", "enhanced_mean", or "maximum_projection".
grid_sampling_factor	float	1.0	B-spline grid refinement per scale. 0-1. Lower = finer grid at coarse scales.
final_grid_sampling	float	16.0	Knot spacing (pixels) at the finest scale. Lower = supports smaller images.
scale_sampling	int	30	Iterations per scale level. 20-30 typical. Higher = better but slower.
speed_factor	float	3.0	Deformation strength. Most important tuning parameter. 1-5 typical.
repeat_registration	bool	False	Re-run registration, and the tracking and projection steps depending on it.

Tuning guidance

• Minimal drift (stable chronic windows): Lower speed_factor (1.5) and scale_sampling (20) for faster convergence when tissue displacement between recordings is small.
• Moderate drift (typical use case): Default speed_factor (3.0) and scale_sampling (30) work well for most longitudinal imaging preparations.
• Significant drift (challenging cases): Increase speed_factor (4.5) and scale_sampling (40) to allow larger deformations and more iterations per scale level.
• Different reference image: Change image_type to "mean" if enhanced mean images introduce artifacts, or "maximum_projection" for sparse labeling where bright pixels are more informative.
• Finer spatial control: Lower grid_sampling_factor (0.5-0.8) to use a denser B-spline grid at coarse scales, improving accuracy for spatially complex deformations at the cost of speed.
• Small reference images: Lower final_grid_sampling (8.0) when registration reports a knot grid too small to freeze its edges. The finest scale level needs the reference images to span more than twice this spacing along both dimensions, so a 32 pixel field of view fails at the 16.0 default.

---

Section 5: roi_tracking

Clusters ROI masks across registered recordings to identify cells tracked over time. After forward-deforming all single-recording masks into the shared coordinate space, the field of view is partitioned into spatial bins with overlap margins. Within each bin, ROI pairs from different recordings within maximum_distance are compared by Jaccard distance and grouped via hierarchical clustering. For each cluster passing mask_prevalence, a consensus template mask is built by retaining only pixels present in at least pixel_prevalence percent of member masks. Templates with fewer than minimum_size non-overlapping pixels are discarded. Final templates are inverse-deformed back to each recording's native coordinates for fluorescence extraction.

Parameter	Type	Default	Description
threshold	float	0.75	Jaccard distance threshold for clustering. Lower = stricter matching.
mask_prevalence	int	50	Min % of recordings that must contain the ROI. Higher = more reliable.
pixel_prevalence	int	50	Min % of a cluster's member masks a pixel must appear in.
step_sizes	tuple[int, int]	(200, 200)	Spatial bin size [h, w] in pixels. Both must be equal.
bin_size	int	50	Overlap margin (pixels) between adjacent bins for border ROI clustering.
maximum_distance	int	20	Max centroid distance (pixels) between masks to consider same ROI.
minimum_size	int	25	Min non-overlapping pixels for ROI-template assignment.

Tuning guidance

• Strict tracking (fewer, highly reliable ROIs): Lower threshold (0.65) for stricter Jaccard matching, raise mask_prevalence (70) and pixel_prevalence (60) to require more cross-recording consistency, and decrease maximum_distance (15) to tighten centroid proximity.
• Lenient tracking (more ROIs, some less reliable): Raise threshold (0.85) for more permissive matching, lower mask_prevalence (30) and pixel_prevalence (40) to accept ROIs present in fewer recordings, and increase maximum_distance (25) to tolerate larger centroid shifts.
• Small ROIs lost: Lower minimum_size (15-20) to retain templates with fewer non-overlapping pixels.
• Dense labeling: Tune threshold (0.65-0.70) and maximum_distance (15) to keep crowded neighbours from merging, and raise mask_prevalence and pixel_prevalence to demand more cross-recording agreement. step_sizes and bin_size govern peak memory and per-bin overhead rather than clustering accuracy, so leave them at their defaults unless memory is the constraint.

---

Section 6: signal_extraction

Fluorescence extraction from tracked ROIs. Shared with the single-recording pipeline.

Parameter	Type	Default	Description
extract_neuropil	bool	True	Extract neuropil activity. False = assume zero neuropil.
allow_overlap	bool	False	Include overlapping pixels in signal extraction.
minimum_neuropil_pixels	int	350	Min neuropil region size (pixels).
inner_neuropil_border_radius	int	2	Pixels between cell and neuropil region.
cell_probability_percentile	int	50	Percentile threshold for cell vs neuropil pixel classification.
classification_threshold	float	0.5	Min classifier confidence for labeling ROI as a cell.
batch_size	int	500	Frames per extraction batch.
colocalization_threshold	float	0.65	Threshold for cross-channel ROI colocalization.

The multi-recording pipeline always uses allow_overlap=True internally regardless of the configured value, since multi-recording template masks are spatially distinct by construction. No reclassification is performed because tracked ROIs are already known cells, so classification_threshold is not used during multi-recording extraction.

Tuning guidance

See /single-recording-configuration Section 8 for full tuning guidance. The same recommendations apply here, except for the two parameters the paragraph above overrides.

---

Section 7: spike_deconvolution

Spike inference from multi-recording fluorescence traces. Shared with the single-recording pipeline.

Parameter	Type	Default	Description
extract_spikes	bool	True	Deconvolve spikes from fluorescence.
neuropil_coefficient	float	0.7	Neuropil scaling before subtraction.
baseline_method	str	"maximin"	Baseline method: "maximin", "constant", or "constant_percentile".
baseline_window	float	60.0	Sliding window (seconds) for maximin baseline.
baseline_sigma	float	10.0	Gaussian sigma (frames) for baseline computation.
baseline_percentile	float	8.0	Percentile for constant_percentile baseline.

Tuning guidance

See /single-recording-configuration Section 9 for full tuning guidance. The same recommendations apply here.

---

User-configurable vs auto-set parameters

Parameters users should consider

Parameter	When to change
roi_selection.probability_threshold	Different quality/quantity tradeoff
roi_selection.mroi_region_margin	MROI (multi-region) imaging mode
diffeomorphic_registration.speed_factor	Different amounts of tissue drift
roi_tracking.mask_prevalence	Different recording-to-recording consistency needs

Parameters typically left at default

• diffeomorphic_registration.image_type, grid_sampling_factor, final_grid_sampling, scale_sampling
• roi_tracking.step_sizes, bin_size, minimum_size
• All signal_extraction parameters
• All spike_deconvolution parameters

---

Configuration file format

Minimal configuration (required fields only)

pipeline_type: multi-recording

recording_io:
  dataset_name: "animal_A_learning_task"

The pipeline_type: multi-recording discriminator must be present at the top level of every multi-recording configuration file. generate_config_file_tool writes it automatically, and both validate_config_file_tool and cindra run reject a file that omits it. The examples below show only the sections being customized and assume the discriminator is already present.

Typical configuration

recording_io:
  dataset_name: "animal_A_learning_task"

roi_selection:
  probability_threshold: 0.85
  maximum_size: 1000

diffeomorphic_registration:
  speed_factor: 3.0

roi_tracking:
  threshold: 0.75
  mask_prevalence: 50

Full configuration with MROI region filtering

runtime:
  display_progress_bars: false

recording_io:
  dataset_name: "animal_A_vr_navigation"

roi_selection:
  probability_threshold: 0.85
  maximum_size: 1000
  mroi_region_margin: 30

diffeomorphic_registration:
  image_type: "enhanced_mean"
  grid_sampling_factor: 1.0
  final_grid_sampling: 16.0
  scale_sampling: 30
  speed_factor: 3.0

roi_tracking:
  threshold: 0.75
  mask_prevalence: 50
  pixel_prevalence: 50
  step_sizes: [200, 200]
  bin_size: 50
  maximum_distance: 20
  minimum_size: 25

The signal_extraction and spike_deconvolution sections take the same keys and defaults their tables above list, and both are left at those defaults in the common case.

---

Configuration lifecycle

1. Template configs: De-novo configurations generated via generate_config_file_tool or manually created. Templates can live anywhere (e.g., /Data/CA1_GCaMP6f_MD.yaml) and are reusable across datasets. Templates are never modified by the pipeline. One template can serve multiple datasets that share the same processing parameters (only dataset_name differs, and this is handled by the batch tool).

2. Resolved copies: When prepare_multi_recording_batch_tool runs, it loads the template and applies runtime-specific overrides (recording_io.dataset_name lowercased to a filesystem-safe key, recording_io.recording_directories natural-sorted from the supplied output_roots, and runtime.display_progress_bars=False). It then saves the resolved copy as multi_recording_configuration.yaml inside the main recording's dataset output directory (cindra/multi_recording/{dataset_name}/). The resolved copy stays immutable after the prepare step, because execute_processing_jobs_tool resolves the worker allocation at dispatch time and passes it to each job as an invocation argument. These resolved copies are what the pipeline actually executes against.

   A second preparation of a dataset whose tracker already exists never rewrites the resolved copy, so the dataset keeps running against the output roots it was first prepared with. The prepare tool reports that disagreement under path_conflicts, naming the stored value, the passed value, and the directory to remove to prepare it again.

Do NOT create per-dataset configuration files manually. Pass a single template path to the batch tool and let it handle per-dataset fine-tuning automatically. Change a parameter of a resolved copy or of a template with set_config_values_tool rather than by hand.

---

Configuration workflow

1. Discover candidates using discover_recordings_tool to find recordings with completed single-recording output (read candidate["output_root"] from each multi_recording_candidates entry).
2. Verify prerequisites: Confirm all discovered recordings have completed single-recording processing (all four phases). If any recording is incomplete, invoke /single-recording-processing (or /acquisition-data-preparation if raw data is not yet prepared) to complete the prerequisite chain before continuing.
3. Generate a template configuration using generate_config_file_tool with pipeline_type="multi-recording". Save it at a user-chosen location (e.g., /Data/CA1_GCaMP6f_MD.yaml). Alternatively, use read_config_file_tool to inspect an existing or legacy configuration for conversion.
4. Set dataset_name: Use resolve_dataset_name_tool to construct a qualified name from a shared base name and a batch-specific specifier derived from the group's output_roots. This is the only required user parameter. The tool is a pure string computation that writes no file, so the name reaches a configuration one of two ways. Passing it as a dataset's dataset_name to prepare_multi_recording_batch_tool is the normal path, which the Configuration lifecycle section covers. To set the field on the template itself, call set_config_values_tool with {"recording_io.dataset_name": "<qualified name>"}. A template validates with any non-empty, filesystem-safe string, because the prepare tool overwrites it per dataset.
5. Review and tune registration and tracking parameters based on expected tissue drift, writing every change with set_config_values_tool.
6. Validate the configuration using validate_config_file_tool to check for errors, warnings, and non-default parameters.
7. Configuration complete: The validated template file is ready for use. This skill does not start processing. If invoked standalone, the configuration is ready. To run it, proceed to /multi-recording-processing. If invoked from another skill, return control to the caller.

---

Related skills

Skill	Relationship
/cindra-pipeline	Overview: end-to-end phases, handoffs, and the single-vs-multi entry point
/cindra-mcp-environment-setup	Prerequisite: MCP server must be connected for configuration tools
/cli-reference	Reference: cindra configure and the cindra run worker options
/acquisition-data-preparation	Upstream: invoke if raw data is not yet prepared for the prerequisite chain
/single-recording-processing	Prerequisite: single-recording processing must complete first
/single-recording-results	Prerequisite: single-recording outputs required as multi-recording input
/single-recording-configuration	Companion configuration reference for the single-recording pipeline
/multi-recording-processing	Next step: processing workflow that consumes this configuration
/multi-recording-results	Output data format reference for evaluating processing results
/visualization	Downstream: launch viewers to inspect multi-recording results after processing

---

Verification checklist

You MUST verify configuration files against this checklist before starting multi-recording processing. Use validate_config_file_tool for automated validation of YAML structure, parameter constraints, and pipeline-set parameter detection.

Multi-Recording Configuration Compliance:
- [ ] cindra MCP server is connected (if not, invoke `/cindra-mcp-environment-setup`)
- [ ] `validate_config_file_tool` reports no errors (run this first)
- [ ] Every parameter change was written with `set_config_values_tool`, whose `valid` flag reported true
- [ ] `recording_io.dataset_name` is set to a unique, non-empty string (prepare overwrites it with the qualified name)
- [ ] `roi_selection.probability_threshold` is appropriate for the dataset (0.85 default)
- [ ] `diffeomorphic_registration.speed_factor` matches expected tissue drift (1-5 range)
- [ ] `roi_tracking.mask_prevalence` is set appropriately for the number of recordings
- [ ] Channel 2 roi_selection parameters are set if channel 2 ROIs have different characteristics
- [ ] Review any warnings from `validate_config_file_tool` (pipeline-set parameters, unusual ranges)