Seeding CaImAn with a manual mask and using a structural channel for motion correction

This notebook aims to show how to use CaImAn for the following two use cases:

• How to perform motion correction on a structural (red) channel and apply the inferred shifts to the functional channel (green).
• How to use manual binary masks to seed the CNMF algorithm, including an approach for automatic segmentation of a structural channel.

This notebook will only focus on these points while building upon CaImAn's demo pipeline. For a general demonstration of CaImAn's pipeline, please refer to the general pipeline demo notebook.

Note that using information from a structural channel does not guarantee improved performance in terms of motion correction and cell identification. Structural channels might give poorer motion correction results depending on the SNR, and might express a different set of neurons compared to the functional channel.

Dataset courtesy of Tolias lab (Baylor College of Medicine)

Select file(s) from structural channel to be motion corrected

The download_demo function will download the specific file for you and return the complete path to the file which will be stored in your caiman_data directory. If you adapt this demo for your data make sure to pass the complete path to your file(s). Remember to pass the fnames variable as a list.

Setup motion correction object

Start a cluster and perform motion correction

Now apply shifts to functional channel

We can use the motion correction object that has stored the shifts from the structural channel and apply the method apply_shifts_movie to the functional channel. Moreover, we can automatically store the file in memory mapped format. In this case we have a single file so we can save it directly in order 'C'. If you have multiple files, then its recommended to save them in order 'F' and then reload them and save in order 'C' for efficient downstream processing. See demo_pipeline notebook for more details.

Segmentation and Seeded CNMF

We can use the registered structural channel to seed the CNMF algorithm. For example the mean image of the structural channel already shows a lot of neurons:

Segmentation of the mean image

CaImAn has an openCV based function for segmenting images like that. You specify the parameter gSig which corresponds to an approximation of the radius of the average neuron. The output of this function is a binary matrix with dimensions # of pixels x # of components that can then be used to seed the CNMF algorithm. Each column of the matrix represents the mask of an individual component.

Now run CaImAn batch (CNMF) seeded with the set of the binary masks

To use seeded initialization we pass the set of binary masks in the variable Ain when constructing the CNMF object.

The two main parameter changes for the seeded compared to the standard CNMF run are rf = None (since the component detection is substituted by the mask and is not run in patches anymore) and only_init = False (since the initialization is already being done and deconvolution is necessary). The other parameters can be carried over from the standard pipeline.

Additionally, the expected half size of neurons in pixels gSig is very important to be close to the data. ROI detection and separation of the mask as well as CNN evaluation are greatly influenced by gSig.

For a general explanation of the parameters see the general notebook.

Load the memory mapped file

Restart the cluster to clean up some memory

Now construct the object and fit

Note how the matrix of masks is passed in the object.

Plot contours against the correlation image

From the contour plot above we see that neurons with active spots in the correlation image have been selected by the algorithm. However, there is also a lot of other components with no clear mark in the correlation image. This could corresponds to neurons that are inactive during the experiment or are simply not expressed in the correlation image. These components tend to have non-spiking traces as shown below.

Component filtering

We can apply our quality tests to filter out these components. Components are evaluated by the same critera:

• the shape of each component must be correlated with the data at the corresponding location within the FOV
• a minimum peak SNR is required over the length of a transient
• each shape passes a CNN based classifier

For the seeded CNMF, this is necessary to eliminate falsely marked ROIs, especially when ROI selection is performed on structural or mean-intensity images.

Experience showed that the CNN classifier might not perform well on manually selected spatial components. If a lot of high-SNR components are rejected, try running the estimation without the CNN ('use_cnn':False).

Comparison with (unseeded) CaImAn batch

Select only high quality components and compare two approaches

This updates the estimates object by only keeping the components indexed by idx_components. Components from idx_components_bad are removed. This makes indexing the estimates object as seen in the cells above unnecessary and non-effective. Rejected components can be recovered with the restore_discarded_components() function, as long as select_components() has not been called with save_discarded_components=False.

The set of accepted components is largely the same in both cases. We can quantify this comparison by using the register_ROIs function to register the components against each other. Before doing that, the spatial footprints need also to be thresholded to remove any faint tails.

Seeding CaImAn online algorithm

The same procedure can also be followed for the CaImAn online algorithm. Seeding can be done by passing the binary mask in the estimates.A field of the OnACID object and then calling the fit method:

cnm_on = cnmf.online_cnmf.OnACID(params=opts)
cnm_on.estimates.A = Ain
cnm_on.fit_online()

Some info on creating your own binary seeding mask

To run a seeded CNMF, we have to provide the algorithm with directions on where it has to look for neurons. This can be done by creating a binary mask with the same dimensions as the movie, which marks possible neuron locations with True or 1.

To manually determine neuron locations, a template on which to find neurons has to be created. This template can be constructed with two different methods:

1. Structural channel and average intensity: If your recording incorporates a calcium-independent structural channel, it can be used to extract locations of neurons by averaging the intensity of each pixel over time. This method can also be applied to the calcium-dependent channel itself. The averaging greatly reduces noise, but any temporal component is eliminated, and it is impossible to tell whether a neuron was active or inactive during the recording. Thus, many neurons selected through this technique will be false positives, which should be filtered out during the component evaluation.
2. Local correlations: The arguably more accurate template can be the local correlation image of the calcium-dependent signal. Here, each pixel's value is not determined by it's intensity, but by its intensity correlation to its neighbors. Thus, groups of pixels that change intensity together will be brighter. This method incorporates the temporal component of the signal and accentuates firing structures like neurons and dendrites. Features visible in the local correlation image are likely functional units (such as neurons), which is what we are ultimately interested in. The number of false positives should be lower than in method 1, as structual features visible in mean-intensity images are greatly reduced. Additionally, it reduces the donut shape of some somata, making neuron detection easier.

A binary seeding mask from this template can be created automatically or manually:

1. Automatic: The CaImAn function extract_binary_masks_from_structural_channel() does basically what it says. It extracts binary masks from a movie or an image with the Adaptive Gaussian Thresholding algorithm provided by the OpenCV library. If the function is provided a movie, it applies the thresholding on the average intensity image of this movie.
2. Manual: Raw movies, average intensity images or local correlation images can be loaded into Fiji to manually select ROIs. Average intensity images can be created from a raw movie with through Image → Stacks → Z Project.... Manually creating a binary mask in Fiji is described in the next cell.

This notebook demonstrates the seeding with a mask manually created from a local correlations image. The automatic method is displayed, but commented out to avoid confusion.

Now that we have our local correlation image, we can manually select ROIs with Fiji. For this, open the image in Fiji/ImageJ and draw the outline of a potential neuron with the Freehand selections tool. Then, add the current selection to the ROI manager with t (Mac and Windows). Please note that for proper ROI detection, make sure that features cut off at the edge have a ROI that touches the edge as well.

Neurons in the imaged tissue can lie in different depths, thus their ROIs and calcium signals can overlap. The best solution to account for this is to create one mask for each component. ROIs can be saved as binary masks through Edit → Selection → Create mask. Fiji's macro function can help to automatically save individual ROIs as binary images. This preserves original neuron shapes and potential overlaps. CaImAn recognizes pixels that are shared by multiple components and takes this into account when extracting the calcium signal from these regions. It is thus recommended to retain overlapping ROIs when seeding the CNMF.

Alternatively, individual selections can be combined in Fiji and exported together. Then, overlapping ROIs will be separated afterwards with a watershed algorithm (see below).

Extracting spatial components from binary masks

The CNMF object stores spatial components in a sparse column format (csc_matrix) with n rows (number of pixels of the flattened image) and m columns (number of components). Thus, single ROIs have to be extracted and transformed into individual binary masks.

Loading separate masks for each component (recommended)

If each component ROI has been saved in its own mask, they can be loaded and transformed into the csc_matrix format individually. This method is recommended, as it retains the original shapes of neurons, and the algorithm takes pixels shared across multiple components into account during signal extraction.

In this demo it is assumed that individual binary .png masks are stored in one directory.

Loading one mask that includes all components (not recommended)

If the masks for all components have been saved in one file, some more processing is required to separate ROIs for each component. Since now overlapping components result in fused ROIs, they have to be separated with a watershed algorithm before being passed into the csc_matrix. This is not recommended because information of which pixels are shared by multiple components is lost, which leads to contamination of the signal from one component to the other at shared pixels. Furthermore, the additional processing step decreases the precision due to imperfect ROI separation.

If you have separate masks and do not need this step, skip the next cells until Perform seeded CNMF.

Identify individual features

To run the watershed algorithm, we have to label each individual component. To separate overlapping features, a distance matrix can be calculated, where pixels get a value representing their distance to the nearest edge. This creates local maxima in the center of features which are not overlapping with nearby features. To account for irregularly shaped cells that would create more than one local maximum, the expected cell diameter gSig_seed is used to threshold local maxima, merging local maxima that are closer together than the cell radius.

Separate components with watershed algorithm

Now that we have the location of separated features, but we still have to apply this separation to the original mask to preserve its shape as much as possible. For this we label the local maxima individually to prepare them for the watershed algorithm. Some irregularly shaped cells will have multiple maxima, even after the thresholding done in the previous step. We should thus remove very small features. These cleaned-up labels can then be used to apply watershed to the original image. Now the watershed algorithm knows where the individual components are and calculates smooth boundaries between them.

Bring labels into sparse column format that CNMF can use

Now we have each component marked with a different label, even if their ROIs are overlapping or merged. We can use this matrix to bring it into the sparse column format that the CNMF uses to store spatial components. Each of the labelled features will be extracted separately and used as the spatial component for this neuron.