CNMF-E¶

This tool uses 2.0 compute credits per hour.

The CNMF-E algorithm attempts to automatically identify the spatial location of cells in the input movie and their associated activity.

Inputs¶

Parameter	Required?	Default	Description
Input Movie Files	True	N/A	path to the input isxd movie files
Cell Diameter	True	7	Average cell diameter of a representative cell in pixels
Minimum Correlation	True	0.8	Minimum correlation of a pixel with its immediate neighbors when searching for new cell centers
Minimum Peak-to-Noise Ratio	True	10	Minimum peak-to-noise ratio of a pixel when searching for new cell centers.
Background Spatial Subsampling	True	2	Spatial downsampling factor to use when estimating the background activity
Ring Size Factor	True	1.4	Multiple of the average cell diameter to use for computing the radius of the ring model used for estimating the background activity
Gaussian Kernel Size	True	0	Width in pixels of the Gaussian kernel used for spatial filtering of the movie before cell initialization (automatically estimated when the value provided is smaller than 3)
Closing Kernel Size	True	0	Size in pixels of the morphological closing kernel used for removing small disconnected components and connecting small cracks within individual cell footprints (automatically estimated when the value provided is smaller than 3)
Merge Threshold	True	0.7	Temporal correlation threshold for merging cells that are spatially close
Processing Mode	True	parallel_patches	Processing mode for CNMF-E
Number of Threads	True	4	Number of threads to be used for running the CNMFe algorithm
Patch Size	True	80	Side length of an individual square patch within the field of view in pixels
Patch Overlap	True	20	Amount of overlap between adjacent patches in pixels
Output Unit Type	True	df_over_noise	Units of the output temporal traces

File Inputs¶

Source Parameter	File Type	File Format
Input Movie Files	miniscope_movie	isxd

Algorithm Description¶

CNMF-E stands for "Constrained Non-negative Matrix Factorization for endoscopic data". The CNMF algorithm was originally developed for two-photon data¹. The two-photon algorithm was modified with enhanced background subtraction routines to work in the one-photon setting². MATLAB CNMF_E was ported to Python in the CaImAn package, described in³.

CaImAn CNMF-E was ported to C++ for implementation into Inscopix Data Processing Software, improved for performance, and extended to offer greater processing control and transparency. The specific mathematics of the algorithm can be found in those papers, and is described at a high level in this section. The algorithm can be broken down into distinct and reusable processing modules:

Figure: Overview of the CNMFe algorithm.

Colors highlight repeated modules.

Determine patch coordinates¶

Based on the chosen mode, the field of view may be broken up into spatially distinct regions referred to as patches. This first step determines the boundaries of all such patches based on the specified patch size and patch overlap.

Create memory-mapped files¶

The next step is to convert one or more .isxd movie files into memory-mapped files, allowing efficient memory management and processing of files otherwise too large to fit in memory at once.

Noise estimation¶

The power spectrum of each pixel is computed by applying a fast Fourier transform to its temporal variation, and then averaged over the high-frequency range to estimate the noise level.

Cell initialization¶

In the next step, each frame of the movie is first high-pass filtered with a Gaussian filter of size equal to Gaussian filter width. The correlation and peak-to-noise ratio (PNR) images are computed from the filtered movie. The correlation image is an image where a particular pixel value is equal to the average correlation over time of that pixel with the 8 neighbor pixels that surround it. The PNR image is an image where a pixel value is equal to the maximum value over time divided by the estimated noise level. A search image is constructed by multiplying the correlation and PNR images. Here's an example from a striatal recording of what these images look like:

A good initialization is essential for good cell identification, and the Min pixel correlation and Min peak-to-noise ratio parameters are the primary parameters used in the initialization process. First, the correlation and PNR images are thresholded by the Min pixel correlation and Min peak-to-noise ratio parameters, and the search image is computed by multiplying the two thresholded images. In the figure above, the PNR and correlation images are shown before thresholding, the search image is shown after. The threshold parameters were Min pixel correlation=0.8 and Min peak-to-noise ratio=5.

After computing the search image, the highest valued pixel is selected as a seed pixel, and the seed pixel is considered to be a potential cell. A box around the seed pixel is constructed, roughly the size of the parameter Average cell diameter, and a basic footprint and trace extraction is performed. The cell footprint is subtracted from from the search image, and the process is repeated until no more seed pixels are found.

Background estimation¶

After CNMF-E obtains an initialization for the footprints and traces, it estimates the background, with the footprints and traces fixed. The background estimation uses a "ring model", in which the background at a pixel is estimated as a linear combination of activity for a ring around that pixel, with diameter equal to Ring size factor times the cell size as specified by Average cell diameter. Figure 5a from ⁴, reproduced here with permission, can provide some intuition about the background model:

This figure shows the raw data (left) being composed of a static background image ("const. baseline"), a time-varying background computed with the ring model ("Fluc. background"), the actual neural signal comprised of the footprints and traces, and then the residual, which is whatever is left.

Update the spatial footprints¶

The estimated background is subtracted from the movie, and the footprints are re-fit, using a constrained non-negative matrix factorization (CNMF) approach, with each footprint that resulted from the initialization step serving as the initial guess to the CNMF optimization. After a footprint is refined in this way, it is post-processed. The post-processing steps include smoothing with a median filter, morphological closing, and thresholding, followed by retaining only the largest connected component.

Update the temporal traces¶

In this step, the spatial footprints and background are fixed, and the traces for each cell are optimized in parallel. Each trace is denoised using a deconvolution algorithm as described in ⁵. The deconvolution is accomplished by modeling the generation of calcium traces from spikes using a simple exponential model. The following figure illustrates example traces with deconvolved spike events:

The algorithm implementation of ⁵ does not produce discrete unit-valued spikes as output; the spikes have an amplitude that ranges from zero to one. "True" spikes tend to have values that are closer to one than "noise" spikes. Spikes can be thresholded to produce events that appear to correspond better to increments in the calcium trace.

Cell merging¶

A merging algorithm is executed after each iteration of spatial/temporal fitting. The algorithm looks for cells that are spatially close and whose traces have high temporal correlations. Cells with a temporal correlation greater than the parameter Merging threshold are automatically merged throughout the process.

Extract raw temporal traces¶

The residual of each temporal trace is computed and added back to the denoised trace to obtain a raw version of the trace.

Merge results from all patches¶

In this step, the results of all independent patches are combined into a single set of spatial footprints and temporal traces. Duplicate cells that can arise when using a patch overlap greater than zero are removed by keeping cells only if their closest patch center matches the patch in which they were identified.

Scale spatial footprints and temporal traces¶

The spatial footprints are vectorized and normalized to have unit length. The corresponding temporal traces are then scaled based on the specified output units.

Cell filtering¶

The first line of defense against false positive cells is through setting the Min pixel correlation and Min peak-to-noise ratio parameters, which affect the initialization of footprints and traces. After initialization, cells can be filtered using the Automated Accept/Reject Cells tool.