Open-source projects – hardware, software, training curricula – have changed science and enabled significant advances across multiple disciplines. Neuroscience, in particular, has benefited tremendously from the open-source movement. Numerous open-source projects have emerged (White et al., 2019; Freeman, 2015), including various types of behavioral apparatus facilitating the design of novel experiments (Buccino et al., 2018; Frie and Khokhar, 2019; Lopes et al., 2015; Nguyen et al., 2016; Matikainen-Ankney et al., 2021), computational tools enabling the analysis of large-scale datasets (Kabra et al., 2013; Mathis et al., 2018; van den Boom et al., 2017; Zhou et al., 2018; Lu et al., 2018; Mukamel et al., 2009; Jun et al., 2017; Klibisz et al., 2017; Giovannucci et al., 2019; Sheintuch et al., 2017; Pennington et al., 2019; Friedrich et al., 2017; Giovannucci et al., 2017; Jewell and Witten, 2018), and recording devices allowing access to large populations of neurons in the brain (Aharoni et al., 2019; Owen and Kreitzer, 2019; Siegle et al., 2017; Solari et al., 2018; Barbera et al., 2019; Jacob et al., 2018; Liberti et al., 2017; de Groot et al., 2020; Skocek et al., 2018; Scott et al., 2018). Miniature microscopy has been an area of particular importance for the open-source movement in neuroscience. To increase the usability, accessibility, and transparency of this remarkable technology originally developed by Schnitzer and colleagues (Ghosh et al., 2011; Ziv et al., 2013), a number of labs innovated on top of the original versions with open-source versions (Barbera et al., 2019; Jacob et al., 2018; Liberti et al., 2017; de Groot et al., 2020; Skocek et al., 2018; Scott et al., 2018). The UCLA Miniscope project, a user-friendly miniature head-mounted microscope for in vivo calcium imaging in freely behaving animals, is one such project that has been accessible to a large number of users (Aharoni et al., 2019; Cai et al., 2016; Shuman et al., 2020; Aharoni and Hoogland, 2019).

With the increasing popularity of miniature microscopes, there is a growing need for analysis pipelines that can reliably extract neuronal activities from recording data. To address this need, numerous algorithms have been developed and made available to the neuroscience community. The principal component analysis or independent component analysis (PCA-ICA)-based approach (Mukamel et al., 2009) and region of interest (ROI)-based approach (Cai et al., 2016) were among the earliest algorithms that reliably detected the locations of neurons and extract their overall activities across pixels. However, one of the limitations of these approaches is that activities from cells that are spatially overlapping cannot be demixed. A subsequent constrained non-negative matrix factorization (CNMF) approach was shown to reliably extract neuronal activity from both two-photon and single-photon calcium imaging data (Pnevmatikakis et al., 2016), and demix the activities of overlapping cells. The CNMF algorithm models the video as a product of a ‘spatial’ matrix containing detected neuronal footprints (locations of cells) and a ‘temporal’ matrix containing the temporal calcium traces of each detected cell. This approach is particularly effective at addressing crosstalk between neurons, which is of particular concern in single-photon imaging, where the fluorescence from overlapping or nearby cells contaminates each other. Moreover, by deconvolving calcium traces, the CNMF algorithm enables a closer exploration of the underlying activity of interest, action potentials (Friedrich et al., 2017; Vogelstein et al., 2010). Originally developed for two-photon data, the CNMF algorithm did not include an explicit model of the out-of-focus fluorescence that is often present in single-photon miniature microscope recordings. This issue was addressed via the CNMF-E algorithm (Zhou et al., 2018), where a ring model is used as a background term to account for out-of-focus fluorescence. Later, an open-source Python pipeline for calcium imaging analysis, CaImAn, was published, which included both the CNMF and CNMF-E algorithms, as well as many other functionalities (Giovannucci et al., 2019). The latest development in analysis pipelines for in vivo miniature microscope data is MIN1PIPE (Lu et al., 2018), where a morphological operation is used to remove background fluorescence during preprocessing of the data, and a seed-based approach is used for initialization of the CNMF algorithm. Other approaches have also been used to extract signals from calcium imaging data, including an online approach (Giovannucci et al., 2017), $\mathcal{l}0$ -penalization approach to infer spikes (Jun et al., 2017; Jewell and Witten, 2018), robust modeling of noise (Inan et al., 2021), and source detection using neural networks (Klibisz et al., 2017).

The open sharing of the algorithms necessary for the computation of neural activity has been exceptionally important for the field. However, implementation of these tools can be complex as many algorithms have numerous free parameters (those that must be set by the user) that can influence the outcomes, without clear guidance on how these parameters should be set or to what extent they affect results. Moreover, there is a lack of ground-truth data for in vivo miniature microscope imaging, making it hard to validate algorithms and/or parameters. Together, these obstacles make it challenging for neuroscience labs to adopt the analysis pipelines since it is difficult for researchers to adjust parameters to fit their data or to trust the output of the pipeline for downstream analysis. Thus, the next challenge in open-source analysis pipelines for calcium imaging is to make the analysis tools more user-friendly and underlying algorithms more accessible to neuroscience researchers so that they can more easily understand the pipeline and interpret the results.

To increase the accessibility of the mathematical algorithms, transparency into how altering parameters alters the data output, and usability for researchers with limited computational resources and experience, we developed Minian (miniscope analysis), an open-source analysis pipeline for single-photon calcium imaging data inspired by previously published algorithms. We based Minian on the CNMF algorithm (Giovannucci et al., 2019; Pnevmatikakis et al., 2016), but also leverage methods from other pipelines, including those originally published by Cai et al., 2016 and MIN1PIPE (Lu et al., 2018). To enhance compatibility with different types of hardware, especially laptops or personal desktop computers, we implemented an approach that supports parallel and out-of-core computation (i.e., computation on data that are too large to fit a computer’s memory). We then developed interactive visualizations for every step in Minian and integrated these steps into annotated Jupyter Notebooks as an interface for the pipeline. We have included detailed notes and discussions on how to adjust the parameters from within the notebook and have included all free parameters in the code for additional flexibility. The interactive visualizations will help users to intuitively understand and visually inspect the effect of each parameter, which we hope will facilitate more usability, transparency, and reliability in calcium imaging analysis.

Minian contributes to three key aspects of calcium image data analysis:

1. Visualization. For each step in the pipeline, Minian provides visualizations of inputs and results. Thus, users can proceed step-by-step with an understanding of how the data are transformed and processed. In addition, all visualizations are interactive and support simultaneous visualization of the results obtained with different parameters. This feature provides users with knowledge about the corresponding outcome for each parameter value and allows the users to choose the outcome that fits best with their expectation. Hence, the visualizations also facilitate parameter exploration for each step, which is especially valuable when analyzing data from heterogeneous origins that may vary by brain region, cell type, species, and the extent of viral transfection.

2. Memory demand. One of the most significant barriers in adopting calcium imaging pipelines is the memory demand of algorithms. The recorded imaging data usually take up tens of gigabytes of space when converted to floating-point datatypes and often cannot fit into the RAM of standard computers without spatially and/or temporally downsampling. CaImAn (Giovannucci et al., 2019) addresses this issue by splitting the data into overlapping patches of pixels, processing each patch independently, and merging the results together. This enables out-of-core computation since at any given time only subsets of data are needed and loaded into memory. In Minian, we extend this concept further by flexibly splitting the data either spatially (split into patches of pixels) or temporally (split into chunks of frames). In this way, we avoid the need to merge the results based on overlapping parts. The result is a pipeline that supports out-of-core computation at each step, which gives nearly constant memory demand with respect to input data size. Minian can process more than 20 min of recording (approximately 12.6 GB of raw data) with 8 GB of memory, which makes Minian suitable to be deployed on modern personal laptops.

3. Accessibility. Minian is an open-source Python package. In addition to the codebase, Minian distributes several Jupyter Notebooks that integrate explanatory text with code and interactive visualizations of results. For each step in the notebook, detailed instructions, as well as intuition about the underlying mathematical formulation, are provided, along with code, which can be directly executed from within the notebook. Upon running a piece of code within the notebook, visualizations appear directly below. In this way, the notebooks serve as a complement to traditional API documentations of each function. In addition, users can easily rearrange and modify the pipeline notebook to suit their needs without diving into the codebase and modifying the underlying functions. The notebooks distributed by Minian can simultaneously function as a user guide, template, and production tool. We believe the inclusion of these notebooks, in combination with Minian’s other unique features, can increase understanding of the underlying functioning of the algorithms and greatly improve the accessibility of miniature microscopy analysis pipelines.

This article is organized as follows. Since Minian’s major contribution is usability and accessibility, we first present the detailed steps in the analysis pipeline in ‘Materials and methods’. Following a step-by-step description of the algorithms Minian adapted from existing works, we present novel visualizations of the results, as well as how users can utilize these visualizations. In ‘Results’, we benchmark Minian across two brain regions and show that spatial footprints and the temporal activity of cells can be reliably extracted. We also show that the cells extracted by Minian in hippocampal CA1 exhibit stable spatial firing properties consistent with the existing literature.

Minian comprises five major stages, as shown in Figure 1. Raw videos are first passed into a preprocessing stage. During preprocessing, the background caused by vignetting (in which the central portion of the field of view is brighter) is corrected by subtracting a minimum projection of the movie across time. Sensor noise, evident as granular specks, is then corrected with a median filter. Finally, background fluorescence is corrected by the morphological process introduced in MIN1PIPE (Lu et al., 2018). The preprocessed video is then motion-corrected with a standard template-matching algorithm based on cross-correlation between each frame and a reference frame (Brunelli, 2009). The motion-corrected and preprocessed video then serves as the input to initialization and CNMF algorithms. The seed-based initialization procedure looks for local maxima in max projections of different subsets of frames and then generates an over-complete set of seeds, which are candidate pixels for detected neurons. Because this process is likely to produce many false positives, seeds are then further refined based on various metrics, including the amplitude of temporal fluctuations and the signal-to-noise ratio of temporal signals. The seeds are transformed into an initial estimation of cells’ spatial footprints based on the correlation of neighboring pixels with each seed pixel, and the initial temporal traces are in turn estimated based on the weighted temporal signal of spatial footprints. Finally, the processed video, initial spatial matrix, and temporal matrix are fed into the CNMF algorithm. The CNMF algorithm first refines the spatial footprints of the cells (spatial update). The algorithm then denoises the temporal traces of each cell while simultaneously deconvolving the calcium trace into estimated ‘spikes’ (temporal update). CNMF spatial and temporal updates are performed iteratively and can be repeated until a satisfactory result is reached through visual inspection. Typically, this takes two cycles of spatial, followed by temporal, updates. Minian also includes a demo dataset that allows the user to run and test the pipeline comprised of the pre-made Jupyter Notebook immediately after installation.

Figure 1

Download asset Open asset

The first section in the pipeline includes house-keeping scripts to import packages and functions, defining parameters, and setting up parallel computation and visualization. Most notably, the distributed cluster that carries out all computations in Minian are set up in this section. By default, the cluster runs locally with multicore CPUs; however, it can be easily scaled up to run on distributed computers. The computation in Minian is optimized such that in most cases the memory demand for each process/core can be as low as 2 GB. However, in some cases depending on the hardware, the state of operating system and data locality, Minian might need more than 2 GB per process to run. If a memory error (KilledWorker) is encountered, it is common for users to increase the memory limit of the distributed cluster to get around the error. Regardless of the exact memory limit per process, the total memory usage of Minian roughly scales linearly with the number of parallel processes. The number of parallel processes and memory usage of Minian is completely limited and managed by the cluster configuration, allowing users to easily change them to suit their needs.

The CNMF algorithm can sometimes misclassify a single cell as multiple cells. To counteract this phenomenon, we implement a step to merge cells based on their proximity and temporal activity. All cells with spatial footprints sharing at least one pixel are considered candidates for merging, and the pairwise correlation of their temporal activity is computed. Users can then specify a threshold where cell pairs with activity correlations above the threshold are merged. Merging is done by taking the sum of the respective spatial footprints and the mean of all of the temporal traces for all cells to be merged. Since this is only a simple way to correct for the number of estimated cells and does not fit numerically with what the model CNMF assumes, merging is only done between iterations of CNMF, but not at the end.

Minian provides an interactive visualization to help the users manually inspect the quality of putative cells and potentially merge or drop cells. At any given time, the visualization shows spatial temporal activities (Figure 14, top row, middle panel) and temporal dynamics of a selected subset of cells (Figure 14, bottom row ). The spatial temporal activities are shown side-by-side with the spatial footprints of all cells and the preprocessed movie (input to CNMF algorithm) at a given frame (Figure 14, top row). The field of view is synchronized across the three images on the top, so that the users can easily zoom in and compare the estimated spatial footprints of cells to the input data. The spatial temporal images in the middle show the product of spatial footprints and calcium dynamics, which represent the model estimated image of a subset of cells at a given frame. This spatial temporal product is calculated on-the-fly and synchronized with the frame indicators on the temporal dynamic plots. In this way, users can easily pick times of interest (e.g., when a cell has a calcium event) and validate whether the estimated spatial temporal activities match the input data. Lastly, this interactive visualization allows the user to either drop false-positive cells or merge multiple cells together via drop-down menus. The result of manual curation is saved as an array with a label for each unit indicating whether a cell should be discarded or how several cells should be merged. In this way, only the new label is saved and no data is modified, allowing the user to repeat or correct the manual curation process if needed.

Figure 14

Download asset Open asset

After completing the analysis of individual recording sessions, users can register cells across sessions. While more complex approaches are proposed in other pipelines (Giovannucci et al., 2019; Sheintuch et al., 2017), here, our intention is simplicity. To account for shifts in the field of view from one session to the next, we first align the field of view from each session based upon a summary frame. Users can either choose a max projection of each preprocessed and motion-corrected video, or a summed projection of the spatial footprints of all cells. Users can also choose which session should be used as the template for registration, to which every other session should be aligned. We use a standard cross-correlation based on a template-matching algorithm to estimate the translational shifts for each session relative to the template and then correct for this shift. The weighted centroid of each cell’s spatial footprint is then calculated and pairwise centroid distances are used to cross-register cells. A distance threshold (maximum pixel distance) is set. Users should choose this threshold carefully to reflect the maximum expected displacement of cells across sessions after registration. We found that a threshold of five pixels works well. Finally, a pair of cells must be the closest cells to each other in order to be considered the same cell across sessions.

To extend this method to more than two sessions, we first cross-register all possible session pairs. We then take the union of all these pairwise results and transitively extend the cross-registration across more than two sessions. At the same time, we discard all matches that result in conflicts. For example, if cell A in the first session is matched with cell B in the second session, and cell B is in turn matched with cell C in the third session, but cells A and C are not matched when directly registering the first and third sessions, all of these matches are discarded and all three cells are treated as individual cells. We recognize that this approach might be overly conservative. However, we believe that this strategy provides an easy-to-interpret result that does not require users to make decisions about whether to accept cell pairs that could conflict across sessions.

To save computation time, we implement a moving window where centroid distances are only calculated for cell pairs within these windows. Users should set the size of windows to be much larger than the expected size of cells.

Minian has been tested using OSX, Linux, and Windows operating systems. Additionally, although we routinely use Minian on specialized analysis computers, the pipeline works on personal laptops for many common length (~30 min) miniature microscope experiments. Specifications of all of the computers that have been tested can be found in Tested hardware specifications. We anticipate that any computer with at least 16 GB of memory will be capable of processing at least 20 min of recording data, although increased memory and CPU power will speed up processing. Moreover, due to the read-write processes involved in out-of-core computation, we recommend that the videos to be processed are held locally at the time of analysis, preferably on a solid-state drive. The relatively slow speed of transfer via Ethernet cables, Wi-Fi, or USB cables to external drives will severely impair analysis times.

Minian is built on top of project Jupyter (Kluyver et al., 2016) and depends heavily on packages provided by the open-source community, including NumPy (Harris et al., 2020), SciPy (Virtanen et al., 2020), xarray (Hoyer and Hamman, 2017), HoloViews (Rudiger et al., 2020), Bokeh (Bokeh Development Team, 2020), OpenCV (Bradski, 2020), and Dask (Dask Team, 2016). A complete list of direct dependencies for Minian can be found in ‘List of dependencies.’ Of note, the provided install instructions handle the installation of all dependencies.

We first validated Minian with simulated datasets. We synthesized different datasets with varying number of cells and signal levels based on existing works (Zhou et al., 2018; Lu et al., 2018). The simulated datasets contain local background fluctuations, noise, and motions similar to experimental datasets (see ‘Generation of simulated datasets’ for details). The field of view contains 512 × 512 pixels and 20,000 frames, corresponding to roughly 10 min of recording at 30 fps. We processed the data with both Minian and CaImAn. For Minian, we utilized the visualization described here to optimize the parameters. For CaImAn, we used the same parameters as Minian whenever the implementations were equivalent. Otherwise, we followed the suggested parameters and tweaked them based on the knowledge of simulated ground truth.

To compare the results objectively, we first matched the resulting putative cells from the output of Minian or CaImAn to the simulated ground truth (see ‘Matching neurons for validation’ for details). We then calculated three metrics to measure the quality of output: F1 score, spatial footprints correlation, and temporal dynamics correlation. The F1 score is defined as the harmonic mean of precision (proportion of detected neurons that are true) and recall (proportion of ground-truth neurons that has been detected). Hence, the F1 score measures the overall accuracy of neuron detection. For each detected neuron that has been matched to ground truth, we compute Pearson correlation between the estimated and ground-truth spatial footprint, as well as the Pearson correlation between the estimated calcium dynamic and the ground-truth calcium dynamic. We then take the median correlation across all the matched neurons to measure the overall quality of estimated spatial footprints and temporal dynamics.

As shown in Figure 15, both Minian and CaImAn achieve similar and near-perfect levels (>0.95) of F1 score across all conditions. Similarly, the spatial footprints remain nearly perfect (>0.95) for both pipelines across all conditions. At the lowest signal level (0.2), both pipelines suffer from decreased correlation of temporal dynamics. This is likely due to noise and background contaminating the true signal. Overall, these results show that the Minian and CaImAn pipelines perform similarly well in terms of output accuracy on simulated datasets.

Figure 15

Download asset Open asset

Figure 15—source data 1

Raw validation performance with simulated data.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig15-data1-v2.csv

Download elife-70661-fig15-data1-v2.csv

Additionally, we want to validate the deconvolved signal from Minian output since this is usually the most important output for downstream analysis. Our ground-truth spikes are simulated as binary signals. However, in reality calcium activity often reflects the integration of several spikes, and the deconvolved signals from Minian output are real-valued. Because of this, we downsampled both the ground-truth spikes and deconvolved signals by five times, and then calculated Pearson correlation for all matched cells. The resulting correlation is summarized in Figure 16A. Our results indicate that the deconvolved output from Minian is highly similar to ground-truth spikes when signal level is high, and the correlation asymptote and approach 1 when signal level is higher than 1. The lower correlation corresponding to low signal level is likely due to the background and noise contamination being stronger than signal. In line with this idea, the detected ‘spikes’ from the deconvolved signals closely match those from ground truth, as shown by the example traces in Figure 16B. The main difference between the two traces is the amplitude of the deconvolved signals, which is prone to be influenced by local background and noise. Overall, these results suggest that Minian can produce deconvolved signals that are faithful to ground truth and suitable for downstream analysis.

Figure 16

Download asset Open asset

Figure 16—source data 1

Raw correlations between Minian deconvolved traces and simulated ground truth.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig16-data1-v2.csv

Download elife-70661-fig16-data1-v2.csv

Figure 16—source data 2

Raw example traces from Minian and simulated ground truth.

File names indicate signal level and source of trace.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig16-data2-v2.zip

Download elife-70661-fig16-data2-v2.zip

We next validated Minian with experimental datasets. The data was collected from hippocampal CA1 regions in animals performing a spatial navigation task. Six animals with different density of cells were included in the validation dataset. The recordings are collected with 608 × 608 pixels at 30 fps and last 20 min (~36,000 frames). Due to difficulties in obtaining ground truth for experimental data, we choose to validate Minian with CaImAn, which has been established as one of the most accurate existing pipelines. To evaluate the results objectively, we matched resulting ROIs from Minian with those from CaImAn using the same approach as in ‘Validation with simulated datasets.’ We then calculated correlation of spatial footprints and temporal activity between matched ROIs from the two pipelines. Across the six datasets, the mean F1 score is 0.73 (sem ± 0.03). The mean spatial footprints correlation is 0.84 (sem ± 0.02), and the mean temporal activity correlation is 0.86 (sem ± 0.02). An example field of view and temporal activity from matched ROIs is shown in Figure 17. Our results indicate that most of the ROIs detected by Minian and CaImAn correspond to the same population of putative cells, and the resulting spatial footprints and temporal activity are nearly identical. These cells tend to cluster near the center of the field of view, which usually has better signal-to-noise ratio. However, the cells near the edge of the field of view usually have low intensity and spatial consistency due to the optical property of GRIN lens. As a consequence, Minian and CaImAn might detect different populations of cells near the border of field of view due to differences in preprocessing and initialization between the two pipelines. We have chosen to use the same set of parameters across all datasets so that the results are easier to interpret, hence the parameters we used were relatively conservative. In practice, the users can further fine-tune the parameters for each recording so that Minian would be able to capture all the low signal cells in the field of view. Overall, these results suggest that the output of Minian is highly similar to CaImAn when analyzing experimental datasets.

Figure 17

Download asset Open asset

Figure 17—source data 1

Raw spatial footprint values shown in the overlay plot.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig17-data1-v2.zip

Download elife-70661-fig17-data1-v2.zip

Figure 17—source data 2

Raw example traces from Minian and Caiman.

File names indicate cell id and source of trace.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig17-data2-v2.zip

Download elife-70661-fig17-data2-v2.zip

To see how the performance of Minian scales with different input data size, we synthesized datasets with varying number of cells and number of frames (recording length). The field of view contains 512 × 512 pixels (same as those used in validation of accuracy), and the signal level was held constant at 1 to make sure both Minian and CaImAn can detect roughly equal number of neurons during the pipeline. To this end, we tracked two metrics of performance: the total running time of the pipeline and the peak memory usage during running. The running time was obtained by querying operating system time during the pipeline. The memory usage was tracked with an independent process that queries memory usage of the pipeline from the operating system on a 0.5 s interval. Both pipelines were set to utilize four parallel processes during the run across all conditions. All benchmarking are carried out on a custom-built Linux machine (model ‘Carbon’ under Tested hardware specifications).

As shown in Figure 18, the run time of both Minian and CaImAn scales linearly as a function of input recording length. The exact running times vary depending on the number of cells as well as whether visualization is included in the processing, but in general the running time is similar across both pipelines. On the other hand, the peak memory usage of CaImAn scales linearly with recording length when the number of parallel processes was set to be constant. At the same time, the peak memory usage of Minian stays mostly constant across increasing number of frames. This is likely due to the flexible chunking implementation of Minian (see ‘Parallel and out-of-core computation with Dask’), where Minian was able to break down computations into chunks in both spatial and temporal dimensions depending on which way is more efficient. In contrast, CaImAn only splits data into different spatial chunks (patches), resulting in a linear scaling of memory usage with recording length for each chunk-wise computation. Additionally, we run Minian and CaImAn with different number of parallel processes on the simulated dataset with 28,000 frames and 500 cells. As expected, with more parallel processes the performance improves and the run time decreases but at the same time the total peak memory usage increases. The tradeoff between run time and peak memory usage is shown in Figure 19. In conclusion, these results show that in practice Minian is able to perform as fast as CaImAn, while maintaining near constant memory usage regardless of input data size. This allows the users to process much longer recordings with limited RAM resources.

Figure 18

Download asset Open asset

Figure 18—source data 1

Raw memory usage and running time with different datasets for both pipelines.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig18-data1-v2.csv

Download elife-70661-fig18-data1-v2.csv

Figure 19

Download asset Open asset

Figure 19—source data 1

Raw memory usage and running time with different parallel processes for both pipelines.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig19-data1-v2.csv

Download elife-70661-fig19-data1-v2.csv

In addition to direct validation of the output for single session, we wanted to validate the scientific significance of the spike signal, as well as the quality of the cross-session registration, and ensure that Minian is capable of generating meaningful results consistent with the existing literature. We leveraged the extensively documented properties of place cells in rodent hippocampal CA1 (O’Keefe and Dostrovsky, 1971). Place cells have been shown to have consistent place fields across at least 2 days (Ziv et al., 2013; Thompson and Best, 1990) with only a minority of detected cells undergoing place field remapping. Here, we looked at place field stability across two linear track sessions (Figure 20A). Briefly, animals were trained to run back and forth on a 2 m linear track while wearing a Miniscope to obtain water rewards available at either end (Shuman et al., 2020). The time gap between each session was 2 days. We record calcium activity in dorsal CA1 region with a FOV of 480 × 752 pixels collected at 30 fps. Each recording session lasts 15 min (~27,000 frames). Calcium imaging data were analyzed with Minian, while the location of animals was extracted with an open-source behavioral analysis pipeline ezTrack (Pennington et al., 2019). The resulting calcium dynamics and animal behavior were aligned with the timestamps recorded by Miniscope data acquisition software (http://miniscope.org/index.php/Main_Page). We used the spike signal for our downstream analysis. To calculate average spatial activity rate, we binned the 2-m-long track into 100 spatial bins. In addition, we separated the epochs when the animals are running in opposite directions, resulting in a total of 200 spatial bins. We then smoothed both the binned activity rate and animal’s occupancy with a Gaussian kernel with a standard deviation of 5 cm. We classified place cells based on three criteria: spatial information criterion, stability criterion, and place field size criterion (Shuman et al., 2020). (See ‘Classification of place cells’ for more detail.) Finally, we analyzed cells that are cross-registered by Minian and are classified as place cells in both sessions. We then calculated the Pearson correlation for the average spatial firing rate for each cross-registered cell. We found that, on average, place cells have a correlation of ~0.6, which is consistent with the existing literature (Shuman et al., 2020).

Figure 20

Download asset Open asset

Figure 20—source data 1

Raw correlation of spatial firing pattern with different shifts in field of view.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig20-data1-v2.csv

Download elife-70661-fig20-data1-v2.csv

Figure 20—source data 2

Raw spatial firing activity for the two sessions shown.

https://cdn.elifesciences.org/articles/70661/elife-70661-fig20-data2-v2.zip

Download elife-70661-fig20-data2-v2.zip

Next, we validated the cross-session registration to verify that the correct cells were being matched across days. We translated the spatial footprints of the second session in both directions up to 50 pixels and registered the cells with the shifted spatial footprints. We then carried out the same analysis with the registration results from shifted spatial footprints. We found that the average correlations between spatial firing patterns have higher values when the shifts are close to zero (Figure 20B).

In conclusion, Minian can reliably process in vivo calcium imaging data and produce results that are in agreement with the known properties of rodent CA1. Minian can thus help neuroscience labs easily implement and select the best parameters for their calcium analysis pipeline by providing detailed instructions and visualizations.

Neuroscience has benefited tremendously from open-source projects, ranging from do-it-yourself hardware (White et al., 2019) to sophisticated algorithms (Freeman, 2015). Open-source projects are impactful because they make cutting-edge technologies available to neuroscience labs with limited resources, as well as opening the door for innovation on top of previously established methods. We believe that openly sharing knowledge and tools is just the first step. Making knowledge accessible even to nonexperts should be one of the ultimate goals of open-source projects.

With the increasing popularity of miniaturized microscopes (Aharoni and Hoogland, 2019), there has been significant interest in analysis pipelines that can reliably extract neural activities from the data. Numerous algorithms have been developed to solve this problem (Zhou et al., 2018; Mukamel et al., 2009; Klibisz et al., 2017; Friedrich et al., 2017; Giovannucci et al., 2017; Pnevmatikakis et al., 2016), and many of them are implemented as open-source packages that can function as a one-stop pipeline (Lu et al., 2018; Jun et al., 2017; Giovannucci et al., 2019). However, one of the biggest obstacles for neuroscience labs in adopting analysis pipelines is the difficulty in understanding the exact operation of the algorithms, leading to two notable challenges: first, researchers face difficulties adjusting the parameters when the data they have collected are out of the expected scope of the pipeline’s default parameters. Second, even after neural activity data is obtained, it is hard for researchers to be sure that they have chosen the best approaches and parameters for their dataset. Indeed, it has been found that depending on the features of the data and the metric used, more sophisticated algorithms do not always outperform simpler algorithms (Pachitariu et al., 2018), making it even harder for researchers to interpret the results obtained from some analysis pipelines. Researchers therefore often have to outsource data analysis to experts with strong computational backgrounds or simply trust the output of the algorithms being used. Minian was created to address these challenges. By providing not only detailed documentation of all functions, but also by providing rich interactive visualizations, Minian helps researchers to develop an intuitive understanding of the operations of algorithms without expertise in mathematics or computer science. These insights help researchers choose the best parameters, as well as to become more confident in their interpretation of results. Furthermore, transparency regarding the underlying algorithms enables researchers to develop in-house modifications of the pipeline, which is a common practice in neuroscience labs. We believe that Minian will contribute to the open science community by making the analysis of calcium imaging data more accessible and understandable to neuroscience labs.

Although Minian provides users with insights into the parameter tuning process across different brain regions, these insights are achieved mainly through visual inspection. However, the performance of an analysis pipeline should be measured objectively. While calcium imaging has been validated with electrophysiology under ex vivo settings (Chen et al., 2013), ground-truth data for single-photon in vivo calcium imaging are lacking, making objective evaluation of the algorithms difficult. Therefore, here we have provided only indirect validations of the pipeline by recapitulating well-established biological findings.

As described earlier, an alternative strategy to thresholding fluorescence intensity during seeds initialization is to explicitly model the distribution of fluorescence fluctuations of all candidate seeds and select those with relatively higher fluctuation. Here, we describe this process and the rationale. Since the seeds are generated from local maxima, they include noise from relatively empty regions with no actual cells. The seeds from these regions usually have low fluctuations in fluorescence across time and can be classified as spurious. To identify these cases, we compute a range of fluctuation for each seed (range of min-max across time) and model these ranges with a Gaussian mixture model of two components. The fluctuations from ‘noise’ seeds compose a Gaussian distribution with low fluctuation, while seeds from actual cells assume a higher degree of fluctuation and form another Gaussian distribution with a higher mean. Any seed whose fluctuations belong to the lower Gaussian distribution is discarded in this step. To compute the range of fluctuation for each seed, we compute the difference between the 99.9 and 0.1 percentile of all fluorescence values across time, which is less biased by outliers than the actual maximum and minimum values.

Normally, this step is parameter-free. In rare cases, there are regions containing noise while other regions are almost completely dark. Thus, seeds from these two regions will form two peaks in the distribution of what the user would consider ‘bad seeds,’ and a Gaussian mixture model with two components will no longer be valid. In such cases, users can tweak the number of components (number of modeled Gaussian distributions), as well as the number of components to be considered as composed of real signal. However, because the two noise distributions are likely to overlap to some degree, using two components will likely suffice. The distribution of fluctuations, Gaussian mixture model fit, and resulting seeds are visualized, enabling the user to judge the appropriateness and accuracy of this step. It should be noted that in practice we have found this process to depend heavily on the relative proportion of the ‘good’ and ‘bad’ seeds and can easily result in a significant amount of false negatives if the proportion of the ‘bad’ seed is too low. This makes the Gaussian mixture model approach less stable and in general less preferable to simple thresholding unless a good threshold of fluorescence intensity cannot be easily determined.

We use a pipeline modified from (Zhou et al., 2018) and (Lu et al., 2018) to generate simulated data for validation and benchmarking of Minian. Specifically, we generate a 512 × 512 pixels field of view with varying number of frames and neurons. The neurons are simulated as spherical 2-D Gaussian. The center of neurons is drawn uniformly from the whole field of view, and the Gaussian widths ${\sigma }_x$ and ${\sigma }_y$ for each neuron are drawn from ${\displaystyle \mathcal{N}(15,5^2)}$, with a minimum value of 3. Spikes are simulated from a Bernoulli process with a 0.01 probability of spiking per frame. Calcium dynamics are simulated by convolving the spikes with a temporal kernel $g\left(t\right)=exp(-t/{\tau }_d)-exp(-t/{\tau }_r)$, with rise time ${\tau }_r=5$ frames and decay time ${\tau }_d=60$ frames. We simulate the spatial footprints of backgrounds as spherical 2-D Gaussian distributed uniformly across field of view. In total, 300 independent background terms are used for all simulations. The Gaussian widths are drawn from ${\displaystyle \mathcal{N}(900,{50}^2)}$. The temporal dynamics of backgrounds are simulated from a constrained Gaussian random walk process with steps drawn from ${\displaystyle \mathcal{N}(0,2^2)}$, then clipped to be non-negative and Gaussian smoothed temporally with a variance of 60 frames. We also simulate motion of the field of view as 2-D translations. The translational shift in each direction is simulated from a constrained Gaussian random walk process with steps drawn from ${\displaystyle \mathcal{N}(-0.2d,1)}$, where $d$ is the current amount of shift. Lastly, we add a ${\displaystyle \mathcal{N}(0,{0.1}^2)}$ Gaussian noise to the entire simulated data. The activity of neurons is multiplied by a scalar before combining with the background activity and noise. We call this scalar ‘signal level.’

To validate the accuracy of Minian output, we simulate data with different signal level and number of cells. The signal levels we use are 0.2, 0.4, 0.6, 1.0, 1.4, and 1.8. The number of cells we use is 100, 300, and 500. On the other hand, to benchmark the performance of Minian, we simulate data with different number of frames and cells. The number of frames varies from 4000 to 28,000 with a step size of 8000. The number of cells we use is 100, 300, and 500.

To compute different metrics of the accuracy of Minian output, we first need to match the putative neurons from Minian output with neurons from ground truth. To obtain this mapping, we first compute the max projection of spatial footprints across all neurons. We then register the max projection of putative spatial footprints to the max projection of ground-truth spatial footprints by estimating a translational shift between the two max projection images. After correcting for translational shifts, we compute the center of mass for all neurons, from which we obtain an N × M pairwise distance matrix, where N and M are number of neurons detected by Minian and number of ground-truth neurons, respectively. We then calculate an optimal mapping by solving the linear assignment problem of minimizing the total cost (distance) of a particular cell mapping. Lastly, we threshold the resulting mapping by discarding any matched cell that has a distance larger than 15 pixels.

We use the spatially binned averaged ‘firing’ rate calculated from spike signals to classify whether each cell is a place cell. A place cell must simultaneously satisfy three criteria: spatial information criterion, stability criterion, and place field size criterion. To determine whether a cell has significant spatial information or stability, we obtain a null distribution of the measurements (spatial information and stability) with a bootstrap strategy, where we roll the timing of activity by a random amount for each cell 1000 times. The observed spatial information or stability is defined as significant if it exceeds the 95th percentile of its null distribution (p<0.05). For the spatial information criterion, we use the joint information between ‘firing’ rate and an animal’s location measured in bits per ‘spike.’ For the stability criterion, we calculate the Fisher’s z-transformation of the Pearson correlation coefficient between spatial ‘firing’ patterns across different trials within a recording session. A trial is defined as the time that the animal runs from one end of the linear track to the other and returns to the starting location. We calculate the z-transformed correlation between the odd number of trials and the even number of trials, as well as between the first half of the trials and the second half of the trials. We then average these two measures of correlations and use that as the measure of stability for a cell. Lastly, for the place field size criterion, we define the place field of each cell as the longest contiguous spatial bin where the averaged ‘firing’ rate exceeded the 95th percentile of all averaged firing rate bins. A cell must have a place field larger than 4 cm (i.e., two spatial bins) to pass the place field size criterion.

Adult male C57/BL6J mice from Jackson Laboratories were used for all testing. Animals were housed in a temperature, humidity, and light-controlled vivarium down the hall from the experimental testing rooms with lights on at 7 am and off at 7 pm. Water was restricted to maintain a body weight of 85–90%. Water deprivation consisted of allotting the animal ~1 ml of water per day, including water obtained during testing. Water not obtained during testing was given after the testing period. Animals were acclimated to handling for 5–7 days prior to training/testing. All experiments were performed in accordance with relevant guidelines and regulations approved by the Institutional Animal Care and Use Committee of Icahn School of Medicine at Mount Sinai (reference # IACUC-2017-0361, protocol # 17-1994).

The hardware specifications of computers that have effectively run Minian are summarized in the following table.

The funders had no role in study design, data collection and interpretation, or the decision to submit the work for publication.

We thank Eftychios A Pnevmatikakis, Andrea Giovannucci, and Liam Paninski for establishing the theoretical foundation and providing helpful insights for the pipeline. We thank Pat Gunn for helping with benchmarking with CaImAn pipeline. We thank Taylor Francisco and Denisse Morales-Rodriguez for helping with data analysis and revision. We thank MetaCell (Stephen Larson, Giovanni Idili, Zoran Sinnema, Dan Knudsen, and Paolo Bazzigaluppi) for contributing to the documentation and continuous integration of the pipeline. We thank Stellate Communications for assistance with the preparation of this manuscript. We thank Brandon Wei, Mimi La-Vu, and Christopher Lee for contributing to the dataset used in Minian development and testing. The authors acknowledge support from the following funding sources: WM is supported by NIH F32AG067640. KR is supported by NIH BRAIN Initiative (R01EB028166), James S. McDonnell Foundation’s Understanding Human Cognition Scholar Award (220020466), NSF Award (NSF1926800 and NSF2046583), Simons Foundation (891834) and Alfred P. Sloan Foundation (FG-2019-12027). TS is supported by CURE Epilepsy Taking Flight Award, American Epilepsy Society Junior investigator Award, R03 NS111493, R21 DA049568, and R01 NS116357. DA is supported by NIH U01NS094286-01, and NSF Award (NSF1700408 Neurotech Hub). DJC is supported by NIH DP2MH122399, R01 MH120162, One Mind Otsuka Rising Star Award, McKnight Memory and Cognitive Disorders Award, Klingenstein-Simons Fellowship Award in Neuroscience, Mount Sinai Distinguished Scholar Award, Brain Research Foundation Award, and NARSAD Young Investigator Award.

All experiments were performed in accordance with relevant guidelines and regulations approved by the Institutional Animal Care and Use Committee of Icahn School of Medicine at Mount Sinai (Reference #: IACUC-2017-0361, Protocol #: 17-1994).

1. Preprint posted: May 4, 2021 (view preprint)
2. Received: May 25, 2021
3. Accepted: May 31, 2022
4. Accepted Manuscript published: June 1, 2022 (version 1)
5. Version of Record published: June 17, 2022 (version 2)

© 2022, Dong et al.

This article is distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use and redistribution provided that the original author and source are credited.