diff --git a/demos/notebooks/demo_pipeline.ipynb b/demos/notebooks/demo_pipeline.ipynb index 7122980f1..0cd7dd538 100644 --- a/demos/notebooks/demo_pipeline.ipynb +++ b/demos/notebooks/demo_pipeline.ipynb @@ -7,7 +7,7 @@ "# CNMF demo pipeline: Intro\n", "A full pipeline for the analysis of a two-photon calcium imaging dataset using the CaImAn software package. It demonstrates how to use Caiman for the following analysis steps:\n", "\n", - "![full workflow cartoon](../../docs/img/full_cnmf_workflow.jpg)\n", + "![Full CNMF Workflow](https://raw.githubusercontent.com/flatironinstitute/CaImAn/main/docs/img/full_cnmf_workflow.jpg)\n", "\n", "1) Apply the nonrigid motion correction (NoRMCorre) algorithm for motion correction.\n", "2) Apply the constrained nonnegative matrix factorization (CNMF) source separation algorithm to extract initial estimates of neuronal spatial footprints and calcium traces. \n", @@ -197,9 +197,9 @@ "

Displaying large files

\n", "Loading a movie with cm.load() pulls the data into memory, which is not always feasible. When working with your own data, you might need to adapt the above code when working with extremely large files. Caiman provides tools to handle this use case. One, you can just load some of your data into a movie object using the `subindices` argument to the `load()` function. For example, if you just want to load the first 500 frames of a movie, you can send it subindices=np.arange(0,500). \n", "\n", - "If you don't want to truncate your movie, there is a play_movie() function that behaves just like movie.play(), but it doesn't load the movie into memory. Rather, it takes the filename as an argument and loads frames from disk as they are shown. If you want to use it, just import using from caiman.base.movies import play_movie and read the documentation. We don't use it for this demo because the demo movie is small, and we do some calculations on the loaded movie array. \n", + "

If you don't want to truncate your movie, there is a play_movie() function that behaves just like movie.play(), but it doesn't load the movie into memory. Rather, it takes the filename as an argument and loads frames from disk as they are shown. If you want to use it, just import using from caiman.base.movies import play_movie and read the documentation. We don't use it for this demo because the demo movie is small, and we do some calculations on the loaded movie array.

\n", "\n", - "Another option for viewing very large movies is to use the fastplotlib library, which leverages the GPU to provide interactive visualization within Jupyter notebooks (we discuss this more below).\n", + "

Another option for viewing very large movies is to use the fastplotlib library, which leverages the GPU to provide interactive visualization within Jupyter notebooks (we discuss this more below).

\n", "" ] }, @@ -448,9 +448,9 @@ "

Optimizing performance

\n", "If you hit memory issues later, there are a few things you can do. First, you may want to lower the number of processors you are using. Each processor uses more RAM, and on a workstation with many processors, you can sometimes get better performance by reducing num_processors_to_use.The best way to determine the optimal number is by trial and error. When you set num_processors_to_use variable to None, it defaults to one less than the total number of CPU cores available (the reason we don't automatically set it to the total number of cores is because in practice this typically leads to worse performance).\n", "\n", - "Second, if your system has less than 32GB of RAM, and things are running slowly or you are running out of memory, then get more RAM. While you can sometimes get away with less, we recommend a *bare minimum* level of 16GB of RAM, but more is better. 32GB RAM is acceptable, 64GB or more is best. Obviously, this will depend on the size of your data sets. \n", + "

Second, if your system has less than 32GB of RAM, and things are running slowly or you are running out of memory, then get more RAM. While you can sometimes get away with less, we recommend a *bare minimum* level of 16GB of RAM, but more is better. 32GB RAM is acceptable, 64GB or more is best. Obviously, this will depend on the size of your data sets.

\n", "\n", - "Third, if none of your memory optimizations work, you may just have too much data for offline CNMF. For this case, we also provide an online version of CNMF (OnACID), which uses a small number of frames to initialize the spatial and temporal components, and iteratively updates them with new data. This uses much less memory than the offline approach. The demo notebook for OnACID is found in demo_OnACID_mesoscope.ipynb. See the Caiman paper for more discussion.\n", + "

Third, if none of your memory optimizations work, you may just have too much data for offline CNMF. For this case, we also provide an online version of CNMF (OnACID), which uses a small number of frames to initialize the spatial and temporal components, and iteratively updates them with new data. This uses much less memory than the offline approach. The demo notebook for OnACID is found in demo_OnACID_mesoscope.ipynb. See the Caiman paper for more discussion.

\n", "" ] }, @@ -461,7 +461,7 @@ "## Motion Correction\n", "The first substantive step in our analysis pipeline is to remove motion artifacts from the original movie:\n", "\n", - "\"motion\n", + "\"motion\n", "\n", "It is *very* important to get rid of motion artifacts, as the subsequent CNMF source separation algorithm assumes that each pixel represents the same region of space\n", "\n", @@ -658,7 +658,7 @@ "\n", "Everything is now set up for running CNMF. This algorithm simultaneously extracts the *spatial footprint* and corresponding *calcium trace* for each component. \n", "\n", - "![cnmf patch flow image](../../docs/img/cnmf_workflow.jpg)\n", + "![cnmf patch flow image](https://raw.githubusercontent.com/flatironinstitute/CaImAn/main/docs/img/cnmf_workflow.jpg)\n", "\n", "It also performs *deconvolution*, providing an estimate of the spike count that generated the calcium signal in the movie. " ] @@ -669,7 +669,7 @@ "source": [ "The algorithm is parallelized as illustrated here:\n", "\n", - "\"cnmf\n", + "\"cnmf\n", "\n", "1) The movie field of view is split into overlapping patches.\n", "2) These patches are processed in parallel by the CNMF algorithm. The degree of parallelization depends on your available computing power: if you have just one CPU then the patches will be processed sequentially. \n", @@ -919,7 +919,7 @@ "

More on Estimates

\n", "The estimates object contains a great deal of information. The attributes are discussed in more detail in the documentation, but you might also find exploring the source code helpful. For instance, while most users initially care about the extracted calcium signals C and spatial footprints A, the background model is also very important. The background model is included in the estimate in fields b and f (which correspond to the spatial and temporal components of the low-rank background model, respectively). We discuss the background model more below.\n", "\n", - "Also, we realize that attribute names like A are not very informative or Pythonic. These names are rooted in mathematical conventions from the original papers in the literature.\n", + "

We realize that attribute names like A are not very informative or Pythonic. These names are rooted in mathematical conventions from the original papers in the literature.

\n", "" ] }, @@ -930,7 +930,7 @@ "# Component Evaluation\n", "As already mentioned, the initial estimates produced by CNMF contains many spurious components. Our next step is to do some some quality control, cutting out the bad estimates to arrive at our final set of estimates:\n", "\n", - "![component evaluation image](../../docs/img/evaluation_workflow.jpg)" + "![component evaluation image](https://raw.githubusercontent.com/flatironinstitute/CaImAn/main/docs/img/evaluation_workflow.jpg)" ] }, { @@ -945,7 +945,7 @@ "\n", "The first two criteria are illustrated schematically here (see also Figure 2 of the Caiman paper):\n", "\n", - "![component evaluation image](../../docs/img/component_evaluation.jpg)" + "![component evaluation image](https://raw.githubusercontent.com/flatironinstitute/CaImAn/main/docs/img/component_evaluation.jpg)" ] }, { @@ -1008,7 +1008,7 @@ "In practice, SNR is the most important evaluation factor. The spatial correlation factors are less important. In particular, the CNN for spatial evaluation may be inaccurate if your neural components are not \"canonically\" shaped somata. \n", "\n", "\n", - "You may have noticed from the description above, that when running evaluate_components() the three evaluation thresholds are appied inclusively: if a component is above any of the thresholds, it will pass muster. This was found in practice to be reasonable (e.g., a low SNR component that is very strongly neuronally shaped tends to not be an accident: it is just a very low SNR neuron). However, there is a second set of absolute threshold parameters set for each criterion. If a component is below this absolute threshold for any of the evaluation parameters, it will be discarded: these are the SNR_lowest, rval_lowest, and cnn_lowest, respectively. \n", + "

When running evaluate_components() the three evaluation thresholds are appied inclusively: if a component is above any of the thresholds, it will pass muster. This was found in practice to be reasonable (e.g., a low SNR component that is very strongly neuronally shaped tends to not be an accident: it is just a very low SNR neuron). However, there is a second set of absolute threshold parameters set for each criterion. If a component is below this absolute threshold for any of the evaluation parameters, it will be discarded: these are the SNR_lowest, rval_lowest, and cnn_lowest, respectively.

\n", "" ] }, @@ -1206,13 +1206,13 @@ "metadata": {}, "source": [ "## Extract $\\Delta F/F$ values\n", - "So far our calcium traces are in arbitrary units. It is common to report the calcium fluorescence relative to some baseline value $F_0$:\n", + "So far our calcium traces are in arbitrary units. It is more common to report the calcium fluorescence relative to some baseline value $F_0$:\n", "\n", "$$\n", "\\Delta F/F = (F(t)-F_0)/F_0\n", "$$\n", "\n", - "Traditionally, the baseline value was calculated during some initial period of queiscience (e.g., in the visual system, when the animal was sitting in the dark). However, it is problematic to make any assumptions about a \"quiet\" baseline period, so researchers have started to use a moving percentile for $F_0$. This is also what Caiman does.\n", + "Traditionally, the baseline value was calculated during some initial period of queiscience (e.g., in the visual system, when the animal was sitting in the dark). However, it is problematic to make any assumptions about a \"quiet\" baseline period, so researchers have started to use a moving average to calculate $F_0$. This is also what Caiman does.\n", "\n", "More specifically, in Caiman the baseline is a running percentile calculated over a `frames_window` moving window. You can calculate $\\Delta F/F$ using raw traces or the denoised traces in C (this is toggled using the `use_residuals` argument):" ] @@ -1245,7 +1245,7 @@ "source": [ "
\n", "

More on $\\Delta F/F$

\n", - "The above discussion of dff leaves out some details about it is actually calculated in Caiman. Behind the scenes, Caiman projects the background activity (see the discussion on the background model below) to the spatial footprint of the neuron and adds a moving percentile of this projected trace to the denominator. This acts as an empirical fudge factor that can keep results from getting too large when very low values for $F_0$ are in the denominator (especially when using denoised traces). Users may prefer to use the more traditional equation directly. Thanks to Peter Rupprecht for a helpful discussion of this topic. \n", + "The above discussion of dff leaves out some details about it is actually calculated in Caiman. Behind the scenes, Caiman projects the background activity to the spatial footprint of the neuron and adds a moving percentile of this projected trace to the denominator (see the discussion on the background model below). This acts as an empirical fudge factor that can keep results from getting too large when very low values for $F_0$ are in the denominator (especially when using denoised traces). Users may prefer to use the more traditional equation directly. Thanks to Peter Rupprecht for a helpful discussion of this topic. \n", "
" ] }, diff --git a/demos/notebooks/demo_pipeline_cnmfE.ipynb b/demos/notebooks/demo_pipeline_cnmfE.ipynb index 90a1958f6..ebb3e3289 100644 --- a/demos/notebooks/demo_pipeline_cnmfE.ipynb +++ b/demos/notebooks/demo_pipeline_cnmfE.ipynb @@ -7,9 +7,9 @@ "# CNMF-E demo pipeline: Intro \n", "This notebook demonstrates how to use Caiman for processing 1p microendoscopic data. It shows how to use Caiman for the following steps:\n", "\n", - "![workflow diagram](../../docs/img/full_cnmfe_workflow.jpg)\n", + "![workflow diagram](https://raw.githubusercontent.com/flatironinstitute/CaImAn/main/docs/img/full_cnmfe_workflow.jpg)\n", "\n", - "1. Apply the nonrigid motion correction (NoRMCorre) algorithm for motion correction.\n", + "1. Apply the nonrigid motion correction (NoRMCorre) algorithm for motion correction to the original movie.\n", "2. Apply the constrained nonnegative matrix factorization endoscopic (CNMF-E) source separation algorithm to extract an initial estimate of neuronal spatial footprint and calcium traces.\n", "3. Apply quality control metrics to evaluate the initial estimates to narrow them down to a final set of estimates.\n", "\n", @@ -410,7 +410,7 @@ "

CNMF-E: The Ring Model

\n", " Background activity is very ill-behaved with 1p recordings: it often fluctuates locally and is much larger in magnitude than the neural signals we want to extract. In other words, the large-scale background model used for CNMF is not sufficient for most 1p data. Hence, Pengcheng Zhou and others came up with a localized model of background activity for CNMFE: the background at each pixel is represented as the weighted sum of activity from a circle (or ring) of pixels a certain distance from that pixel. The distance of this ring from the reference pixel is set by the ring_size_factor parameter. This more complex pixel-by-pixel background model explains why CNMFE is computationally more expensive than CNMF, and also why it works better to mop up large-scale localized background noise in 1p data. \n", " \n", - "When you set gnb in the CNMF model (usually to 1 or 2), you are setting the number of global background components. The fact that you can get away with so few is testament to how well-behaved the background activity is in 2p recordings. When we set gnb to 0 in Caiman, this is a flag telling Caiman's back end to switch to the more complicated ring model of the background activity. \n", + "

When you set gnb in the CNMF model (usually to 1 or 2), you are setting the number of global background components. The fact that you can get away with so few is testament to how well-behaved the background activity is in 2p recordings. When we set gnb to 0 in Caiman, this is a flag telling Caiman's back end to switch to the more complicated ring model of the background activity.

\n", "\n", "For more details on CNMFE you can see the original paper and the Caiman paper. \n", "" @@ -475,7 +475,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", + "\n", "Using `nb_inspect_correlation_pnr()`, you can inspect the correlation and PNR images to find threshold values for these quantities: `min_corr` and `min_pnr`. You can adjust the range of values displayed in the two subplots below by choosing the Y-box select tool (third button from the left -- highlighted in yellow in the accompanying image to the right) and selecting the desired region in the histograms on the right hand side of each image. You can also use the pan button (first button on the left) to zoom/adjust the axis limits in the histogram to make it easier to see the limits." ] }, @@ -527,10 +527,10 @@ "source": [ "
\n", "

CNMFE initialization: More on correlation and peak-to-noise-ratio

\n", - " \n", + " \n", "How are correlation and peak-to-noise ratio actually calculated? First Caiman convolves the motion corrected movie with a mean-centered Gaussian (example to the right). The sigma of the Gaussian is gSig, and mean centering is turned on by setting center_psf to True. This mean centering creates a Gaussian with a positive peak in the middle of width approximately gSig/2, surrounded by a negative trench, and a ledge of zeros around the outer edges. This crucial preprocessing filter serves to highlight neuronal peaks and smooth away low-frequency background activity.\n", "\n", - "The function correlation_pnr() applies this mean-centered Gaussian to each frame of the motion corrected movie and returns the correlation image of that movie, as well as the peak-to-noise-ratio (PNR). The correlation image is the correlation of each pixel with its neighbors. The PNR is the ratio of the maximum magnitude at a pixel to the noise value at that pixel (it is a fast and rough measure of signal-to-noise). As mentioned above, both of these values tend to be higher in pixels that contain neurons. The CNMFE initialization procedure is to set a threshold for both quantities, take their product, and use the peaks in this product map to find seed pixels for initialization of the CNMFE source separation algorithm.\n", + "

The function correlation_pnr() applies this mean-centered Gaussian to each frame of the motion corrected movie and returns the correlation image of that movie, as well as the peak-to-noise-ratio (PNR). The correlation image is the correlation of each pixel with its neighbors. The PNR is the ratio of the maximum magnitude at a pixel to the noise value at that pixel (it is a fast and rough measure of signal-to-noise). As mentioned above, both of these values tend to be higher in pixels that contain neurons. The CNMFE initialization procedure is to set a threshold for both quantities, take their product, and use the peaks in this product map to find seed pixels for initialization of the CNMFE source separation algorithm.

\n", "\n", "More details on the initialization procedure used here can be found in the CNMFE paper, or by exploring the code. \n", "
"