CaImAn Multi-Session Registration¶

This tool uses 0.5 compute credits per hour.

Overview¶

Multi-Session Registration (MSR, also referred to as Longitudinal Registration) is a fully automatic workflow for tracking cells across sessions spanning days, weeks or even months. The IDEAS CaImAn Multi-Session Registration tool is built around register_multisession(), the MSR algorithm implemented in CaImAn. On top of this core function, CaImAn Multi-Session Registration offers some additional features such as: 1) compatibility with .isxd cellsets and eventsets, 2) offering more control on how cellsets are aligned, and 3) providing more output data and visualizations to better understand and evaluate the MSR results.

CaImAn Multi-Session Registration requires two types of files as inputs for each session: one cellset and one template image (for example, a local correlation image or a maximum projection image). Optionally, one eventset per session can also be provided, to enable the convenient output of both registered cellsets and eventsets. These input files can be obtained through different processing tools available on IDEAS, such as Run suite2p pipeline, CaImAn Cell Extraction Workflow, or Project Movie, for example.

The MSR algorithm consists of two steps: first (optional), it aligns cell footprints across sessions using their corresponding template images; second, it solves the optimal assignment problem between aligned cells from the different sessions using the Hungarian algorithm.

Finally, CaImAn Multi-Session Registration outputs several files, each with their related metadata fields and preview figures. Along with a .h5 file containing the original CaImAn register_multisession()'s outputs, CaImAn Multi-Session Registration outputs two .csv files containing unique metrics for QC and validation purpose, and registered Inscopix .isxd cellsets and optional eventsets for seamless use with downstream analysis tools.

MSR on many sessions

When registering more than two sessions, MSR adopts an iterative approach: it starts by registering the two first sessions and yields a unified set of distinct cells (containing cells registered across both sessions, cells only present in the first session, and cells only present in the second session). Then, it continues by registering this unified cellset with the third session and yields a new unified cell set. It proceeds that way until reaching the last session.

Code¶

Package	Description
CaImAn fork	To enable working with Inscopix `.isxd` movies, we forked the official CaImAn repository (version `1.9.16`) and added the ability to directly read `.isxd` movies. We also surfaced several variables to enable computing QC metrics, presented in preview figures and outputted as two `.csv` files.
ideas-toolbox-caiman	This IDEAS tool is hosted in a Git repository. Modules and functions of this package integrate CaImAn functions into the IDEAS ecosystem.

CaImAn documentation¶

For more information and source code from official CaImAn sources, follow the links in the table below:

Link	Description
Official documentation	Provides a detailed list of settings (aka parameters) and much more useful information.
Git repository	Source code to dive into implementation details. Note that we currently use a fork of this repository, which has the added ability to read Inscopix `.isxd` files.
eLife 2019 paper	"CaImAn an open source tool for scalable calcium imaging data analysis". Manuscript by Andrea Giovannucci et al., introducing the CaImAn toolbox.

Input files¶

Source Parameter	File Type	File Format
Cellsets	caiman_data, caiman_data, cell_set	h5, hdf5, isxd
Template Images	image, image, miniscope_image	tif, tiff, isxd
(optional) Eventsets	neural_events	isxd

Obtaining input files

You can obtain input cellsets, eventsets and template images using different processing tools on IDEAS, such as:

Run suite2p pipeline for all input files
CaImAn Cell Extraction Workflow for all input files
Project Movie for template images

Parameters¶

Parameter	Required?	Default	Description
Cellsets	True	N/A	Cellsets containing the footprints for MSR computation, as well as the traces for outputting registered cellsets. [.h5/.hdf5, .isxd]
Template Images	True	N/A	Template images corresponding to the input cellsets. [.tif/.tiff, .isxd]
(optional) Eventsets	False	N/A	(optional) Eventsets containing the neural events for outputting registered eventsets. If Cellsets were provided as .h5/.hdf5, then they already contain Eventsets. [.isxd]
Align Template Images	False	True	[from CaImAn docs for `align_flag`] "Align the templates before matching." [bool]
Use Optical Flow	False	False	[from CaImAn docs for `use_opt_flow`] "Use dense optical flow to align templates." [bool]
Maximum x/y Shifts	False	10.0	[from CaImAn docs for `max_shifts`] "Max shifts in x and y." [int]
Footprint Binarization Threshold	False	0.0	[from CaImAn docs for `max_thr`] "Max threshold parameter before binarization." For each footprint, pixels below `max_thr` * footprint maximum amplitude will be set to 0. [float]
Maximum Footprint Centroid Distance	False	10.0	[from CaImAn docs for `max_dist`] "Max distance between centroids." Any pair of footprints with centroids more distant than `max_dist` will be discarded from potential matches. [float]
Maximum Footprint Disjunction	False	0.7	[from CaImAn docs for `thresh_cost`] "Maximum distance considered." Cost is defined as 1 - Jaccard Index (degree of overlap). Higher values of `thresh_cost` will thus relax overlap requirement for footprints to be considered a match. [float]
Cost Threshold for Enclosed Footprints	False	N/A	[from CaImAn docs for `enclosed_thr`] "If not None set distance to at most the specified value when ground truth is a subset of inferred." Effectively caps cost to 0.5 when one footprint is contained within another one. [None, float]
Use Cell Status	False	accepted	Cell status to use (either "accepted", "accepted & undecided", or "all").
Minimum Number of Registered Sessions	False	1	Minimum number of sessions an ROI must be registered across to be outputted in the registered cellsets (and optional eventsets). [int]
Footprint Thresholding Method	False	nrg	Method for thresholding footprint contours: either "nrg" to keep the pixels that contribute up to a specified fraction of the footprint energy, or "max" to set to 0 pixels that have value less than a fraction of the maximum footprint value.
Footprint Threshold	False	0.9	Threshold for footprint contours, in terms of either footprint energy or maximum value, depending of the chosen Footprint Thresholding Method. Set to a value between 0.0 and 1.0, for rawer or smoother footprints, respectively. [float]
Diverging Colormap	False	bwr	Name of the Matplotlib diverging colormap to be used in the template image alignment preview figure. [str]
Colormap	False	gray	Name of the Matplotlib colormap to be used in the template images in preview figures. [str]
Show Grid	False	True	Show grid on the template images of preview figures. [bool]
Ticks Step	False	100	Step for the x- and y-axis ticks. [int]
Number of Sample Cells	False	20	Number of sample cells to be plotted in the registered traces preview figure. [int]

Aligning templates through substantial x/y shifts

In our experience, using the fully nonrigid Optical Flow approach to align templates across sessions only works well for relatively small x/y shifts (< 10 pixels). To correct for bigger x/y shifts, we recommend using the implemented piecewise-rigid, NoRMCorre-like approach by keeping Use Optical Flow to False (default), and setting Maximum x/y Shifts to a higher value (e.g., 80 pixels).

Low registration yield despite visual matches

If the IDEAS CaImAn Multi-Session Registration tool only outputs few registered cells despite many more visual matches upon observing the preview figures, it might come from too stringent criteria for cells to be considered a match. You can try relaxing these criteria by increasing Maximum Footprint Centroid Distance and Maximum Footprint Disjunction. Indeed, a same cell can have footprints of slightly different shapes across sessions, due to variations in the cell extraction process, in its fluorescence level, or in the background activity, among other extrinsic and intrinsic factors. Such footprints could thus have centroids more distant than 10 pixels (default of Maximum Footprint Centroid Distance), and overlap less than 0.3 (in terms of Jaccard Index, or inversely be disjunct by more than a cost of 0.7). These two parameters can be tailored using the overlap and centroid distance histograms provided as a preview figure of the CaImAn MSR output .h5 file.

Output files¶

Format	Extension(s)	Notes
CaImAn MSR output	`.h5` file containing the regular `register_multisession()` outputs.	As listed in the CaImAn documentation.
Alignment QC Metrics	`.csv` file containing QC metrics for the alignment step of CaImAn MSR, such as pre- and post-alignment template image correlation coefficients, and average x/y shifts.	This file is key for investigating any issues at the alignment step.
CaImAn MSR Metrics	`.csv` file containing cell names in input cellsets, footprint centroid Euclidean distance, and footprint overlap metrics for all registered cells.	This file allows for further curation of the registered cellsets and eventsets, for example by rejecting all registered cells which aligned footprint centroids were distant from more than a given distance threshold.
*Registered Inscopix* cellsets**	As many `.isxd` cellset files as input cellsets, containing cells registered across sessions, with matching cell names.	Compatible with secondary analysis tools on IDEAS.
*Registered Inscopix* eventsets**	As many `.isxd` eventset files as input cellsets, only outputted if input cellsets were provided as `.h5` files or if optional input `.isxd` eventsets were provided, and containing neural events from cells registered across sessions, with matching cell names.	Compatible with secondary analysis tools on IDEAS.

Flexible outputs for different use cases

Registered Inscopix cellsets and eventsets can have flexible content to best match different use cases:

by setting Mininum Number of Registered Sessions to the total number of sessions provided as inputs, these output files will only contain cells that were registered across all sessions, which makes it straightforward to longitudinally compare neural activity in a same population of cells
by setting this same parameter to 1, the output registered cellsets and eventsets will contain neural activity for the union of all cells across all input cellsets, which is key to track activity of single cells that would be if active in some sessions and silent in other sessions

Each output file has metadata and previews attached to it. You can find below examples of these previews obtained from registering cells across two 2P mouse cortex cellsets recorded 5 days apart (internal data).

For CaImAn MSR output, you can explore 5 preview figures, illustrating various aspects of the MSR process:

*Registered cells on projection images.*

*Number of registered cells across sessions.*

*Fluorescence traces from registered cells.*

For Alignment QC Metrics, you can visualize pre- and post-alignment template image differences:

*Template images pre- and post-alignment.*

For CaImAn MSR Metrics, you can visualize histograms of footprint centroid distance and footprint overlap for all cell pairs for which these metrics were computed:

*Histograms of centroid distance and overlap for registered and non-registered cells.*

For Registered Inscopix cellsets and eventsets, you can visualize the usual footprint maps and sample fluorescence traces (cellsets), or summary figure of neural events (eventsets).

Modifying output figures

We provide a set of visualization parameters in the Analysis Table for controlling several graphical aspects of the preview figures (listed above; e.g., colormap, number of sample cells, etc), so you can get as close to presentation/publication-ready rendering as possible.

Next steps¶

The registered Inscopix cellsets and eventsets outputted by CaImAn Multi-Session Registration can be seamlessly used in the following secondary analysis tools on IDEAS:

FAQ¶

Question	Answer
Will this tool work on cellsets extracted using other workflows than CaImAn?	Absolutely! Beyond being compatible with cellsets extracted using the CaImAn Cell Extraction Workflow's `CaImAn Output` `.h5` file, it can process any Inscopix `.isxd` cellset and optional eventset. For example, it can be used on `.ixsd` cellsets outputted by the Run suite2p pipeline workflow.
Will this tool work on 2P data?	Yes, it is compatible with both 1P and 2P data. With this in mind, the exact imaging approach will likely warrant tuned parameters, such as, e.g., higher `Maximum x/y Shifts` for head-mounted 1P or 2P miniscopes (as opposed to tabletop microscopes), or more relaxed cell matching criteria for 2P footprints which are often less circular than 1P footprints.
How can I get the required template images?	You can use Run suite2p pipeline (from version `0.6.1`) or the CaImAn Cell Extraction Workflow (from version `1.3.0`) with `Save Template Image` set to `yes`. You can also apply Project Movie (from version `2.2.1`) on a motion-corrected movie.
What to do if my templates were not aligned properly?	Big x/y shifts between templates of distinct sessions happen with real-world data. If it does, simply use the piecewise-rigid NoRMCorre-like approach and set `Maximum x/y Shifts` to a higher value. See more details in the Parameters section above.
What to do if I have too few matches?	If template alignment went well but you only have a few cells matched across sessions, despite being able to eyeball more matches, simply relax the matching criteria by increasing `Maximum Footprint Centroid Distance` and `Maximum Footprint Disjunction`. See more details in the Parameters section above.