One recording in a freely-moving experiment using MINI2P system usually includes one or multiple MINI2P calcium imaging files (tiff stack) generated by ScanImage and one or multiple animal tracking videos generated by tracking camera recording software, such as AnimalTracker or Pylon. Becuase the MINI2P imaging and tracking video recording in our system is hardware-level synchronized, the synchronization data is not required.
In order to implement quantitative analysis for real neuroscience studies, individual cells' anatomical and activity information, and animal behavior including trajectory, speed, and head direction need to be extracted from the raw imaging tiff files and tracking videos, respectively.
First of all, we use Suite2P to do cell segmentation, signal extraction, and signal deconvolution from raw calcium imaging tiff stack, and DeepLabCut to extra animal`s body parts, like ears, body center, tail base, and etc., from raw animal tracking video. Still, the output of Suite2P and DeepLabCut can not be directly used for biology analysis until a more meaningful, highly extracted and integrated, and easy-to-understand data format is generated. And a powerful data visualization tool for non-programming-expert to easily present and investigate these data before going into a more complex analysis is also required. NATEX.mlapp was developed for these purposes. It has four major functions:
- Process Suite2P output: take the output from Suite2P, calculate dF/F, significant transients, and SNR, clear up the deconvolved signal, detect repeated cells in multiplane imaging data, and finally package the processing information and save processed neuron activity data.
- Process DeepLabcut output: Take the output from DeepLabCut, calculate head/body position, speed, direction using user-selected tracking models, combine or split multiple recording sessions, and finally package the processing information and save processed tracking data.
- Integration: combine the processed neuron activity data and tracking data with a user-defined alignment strategy, package the combination information, and save the combined data.
- Data Visualization: provide multiple useful functions to view the neuronal activity (dF/F, significant transients, or deconvolved signal), different types of anatomical cell map, MINI2P imaging projection, animal trajectory derived by head or body (coded by position, speed, direction), the spatial tuning plots ( calcium event/position plot, activity map, calcium event/direction/position plot, directional tuning), etc. The simplified data-flow chart and NATEX major functions are shown below:
NATEX.mlapp is highly modularized so you can input, process, view, output, and reload (processed) neuronal activity data, tracking data, or combined data independently.
The Python version of NATEX will be published in the first KISN International MINI2P workshop in 2022.
The app was written with Matlab 2020a, but should work with any newer version. It uses the Statistics and Machine Learning Toolbox, the DSP System Toolbox and the Curve Fitting Toolbox, which need to be installed before running the applications.
There are two ways to install the application.
First way is to install the raw codes which gives you the right to modify the function:
Download or clone the whole repository in a local folder. Open Matlab, press "set path” on home toolstrip, then press “add with subfolders...", navagate to the location of \MINI2P_toolbox\MINI2P_toolbox\AnLysis, press "select folder", and finally, "save" the current path.
Second way is to install the app into the Matlab toolboxes which makes the most convinient way to call it. But you can not see or change the codes:
In order to read out and save the ScanImage tiff header (the function "Save SI Information"), you need to install ScanImage on the same computer too. The free version will work well. Follow their instruction for installation.
All recordings belong to one experiment should be put in one "data folder". An experiment can include multiple sessions and in each session, the raw data usually includes one tiff-stack file from MINI2P recording (output from ScanImage) and one tracking video (.AVI). For analyzing neuronal activity data, you should first run Suite2P analysis on your raw tiff files. Suite2P will automatically combine all tiff files in the "data folder" together to extract the cell signal and generate a single output folder called "suite2p". Folder "suite2p" is the only thing NATEX.mlapp needs to process the neuronal activity data. Therefore, do not change the name of this folder after it is generated by Suite2P. In addition, important to make sure that the option "save_mat" is 1 and the option "combined" is 1 when you run the Suite2P analysis. If you want to also extract and output the ScanImage tiff header (when the function "Save SI Information" is enabled), keep the raw tiff files in the "data folder" too. For analyzing tracking data, you will first run DeepLabCut (or other method or software) to extract the body part position. DeepLabCut will generate one set of results for each video (or session). NATEX.mlapp only looked for and takes the CSV files that include all body-part tracking results to do the tracking analysis. In other words, as soon as you can generate CSV files with the same format as DeepLabCut, they can be read by NATEX.mlapp for analysis. The number of sessions is decided by the number of tracking files (.csv) the user selects.
NATEX is coded with high modularity which means the neuronal activity analysis and tracking analysis are quite independent. Therefore, it does not require all kinds of input to run specific analyses. For example, if you select the analysis type as " Only MINI2P ", you only need to have the Suite2P output folder. And if you select " Only tracking ", you only need the body-part CSV files. This is useful for some pilot experiments such as head-fixed test recordings or pure behavior studies in which, tracking video or MINI2P imaging files is not applicable, respectively.
In total, NATEX will generate five output files. NeuronActivityMatrix.mat and NeuronInformation.mat are generated if the analysis type is "Only MINI2P" "MINI2P+tracking" or "Complete pipeline". TrackingResultMatrix.mat is generated if the analysis type is "Only Tracking ", "MINI2P+tracking" or "Complete pipeline". NAT.mat and ExperimentInformation.mat are generated if the analysis type is "Complete pipeline", or manually execute the function "generate NAT!". All these files are saved in the same data folder.
NeuronActivityMatrix.mat is generated after the neuronal activity analysis part in analysis type "Only MINI2P" "MINI2P+tracking" or "Complete pipeline" is finished. It included several cell-by-cell signal traces described in detail below:
NeuronInformation.mat is also generated after the neuronal activity analysis part in analysis type "Only MINI2P" "MINI2P+tracking" or "Complete pipeline" is finished. It included cell footprints, SNR, event counting, processing parameters, and all other useful analysis information other than the signal traces that are saved in NeuronActivityMatrix.mat already. Described in detail below:
TrackingResultMatrix.mat is generated after the tracking analysis part in analysis type "Only Tracking ", "MINI2P+tracking" or "Complete pipeline" is finished. It included the head (or body if selected) position, direction and speed information, tracking processing parameters,and all other useful analysis information. This is the only output in tracking analysis part. Described in detail below:
NAT.mat is generated after the neuronal activity data and tracking data combination part in analysis type "Complete pipeline", or manually executed function "generate NAT!" is finished. It is a matrix that combines cell-by-cell neuronal activity data and animal tracking data.Described in detail below:
ExperimentInformation.mat is also generated after after the neuronal activity data and tracking data combination part in analysis type "Complete pipeline", or manually executed function "generate NAT!" is finished. Most of the information saved here are copied from NeuronInformation.mat and TrackingResultMatrix.mat. But it also includes the neuronal activity data and tracking data combination and alignment information that is unique here. Described in detail below:
There are 11 permanent panels on GUI and a pop-up will appear when a certain preview button is pressed (described in detail below). Currently, all options and parameters will be saved in output data files (.mats) and updated automatically when processed data is loaded in. In the future version, NATEX will allow the user to save and load in analysis options and parameters without specific processed data.
In this panel, user selects the desired analysis type and the data folder. In the future version, user can also save and load in analysis options and parameters in this panel.
- "Analysis type": a drop-down allows users to select analysis type.
- "Select data folder and DLC output": when press this button, a folder-selecting dialog box appears for the user to select the data folder. if the analysis type is "Only Tracking ", "MINI2P+tracking" or "Complete pipeline", a second dialog box appears after the data folder is selected, for the user to select tacking CSV files. Users should select "all" csv files that they want to analyze and combine with neuronal activity data.
In this panel, user controls the start and abort of the analysis.
- "Run analysis!": start the analysis based on user-selected analysis type.
- "Abort analysis": manually abort the analysis. Attention! You may get some incomplete results or output when aborting the analysis. Errors may also appear if you use other functions after aborting an analysis. Therefore, always run the analysis again after you abort the last analysis.
- "Close all figures": all pop-ups will be closed.
In this panel, user needs to decide several options for processing and analyzing the neuronal activity data. The reason and reference for these parameters can be found in the original paper (Zong, et.al, 2021).
- "Moving window": The time window to calculate the local standard deviation of the raw fluorescence. This local standard deviation is then used to compute the baseline fluorescence (F-zero). See ΔF/F calculation for details. Default: 30s.
- "Transient lasting": the temporal lasting threshold for a transient to be called a "significant transient". See Significant transient calculation for details. It depends on the calcium indicator dynamics and the signal quality. Default: 0.75s for GCaMP6s transgenic mice.
- "Lowpass filter": the cut-off frequency of a low-pass filter applied on cell signal (ΔF/F) for calculating the cross-correlation between cells. It is not applied to the output data or any downstream analysis. Default: 2Hz.
- "Neuropil correction": neuropil coefficient, the definition is the same as neucoeff in Suite2P. Default: 0.7.
- "Transient extent": a safe margin added on both sides of a significant transient so it can fully cover the deconvolved events. Default: 0.4s.
- "Cell distance threshold": the distance threshold (unit: pixel) for two cells to be identified as the same cell in different planes. Default: 10 pixels.
- "Cell cross-correlation threshold": the cross-correlation threshold (unit: a.u.) for two cells to be identified as the same cell in different planes. Default: 0.5.
- "Cell overlap ratio threshold": the overlap ratio threshold (unit: a.u.) for two cells to be identified as the same cell in different planes. Default: 0.75.
This panel is for selecting a subgroup of cells to show in pop-ups such as activity traces, cell footprints, and spatial tuning plots. NATEX supports two modes of defining selected cells:
- "Range": give the total number of cells ("cells to check") and the "start cell". For example, "cells to check"=5 and "start cell"=4 aims to show cells with ID: 4,5,6,7, and 8.
- "Arbitrary": directly input the cell ID. The separator can be comma(","), semicolon (";"),blank(" "), or tab (" "), and should be consistent. Do not put any separator at the end. For example: 1,2,3
Note: NATEX only inputs and processes ROIs extracted and classified "cells" in Suite2P. Therefore, the cell ID used here is not the same cell ID used in Suite2P. The Suite2P cell ID of each cell can be found in the file NeuronInformation.mat and is also shown on the cell map if the option "show cell ID" is selected.
This panel is for viewing the neuronal activity processing analysis result. Read-only results:
- "X pixel" and "Y pixel": frame size of the 2P imaging.
- "channels": number of imaging channels.
- "planes": number of imaging planes.
- "Frame rate": sampling rate (per frame).
- "Volume rate": "Frame rate"/"planes".
- "Total volumes": the number of stacks in the recording. If the recording is a single plane recording, this number is equal to the total number of frames. If the recording is a multi-plane recording, this number is equal to the total number of frames deciding the number of planes.
- “Total cells": number of cells classified as "cells" in Suite2P.
- "Repeated cells": cells that are identified as repeated recorded in multiple planes. For instance, if cell 1 in plane 1, cell 2 in plane 2, and cell 3 in plane 3 are identified as the same cell, and cell 2 has the highest SNR, then cell 1 and cell 3 are the repeated cells so that "Repeated cells" will add 2.
Show activity traces:
This panel is used to define the parameters used for the tracking analysis.
- "Session combined?": tick this if the raw tiff files (ScanImage output) are blocks of the same session. If the individual tiffs in the base folder represent different session leave box unticked.
- "Tracking synched with MINI2P?": Tick this box if the tracking tiffs are synchronised with the scanImage output; meaning that the first frame of the tracking occurred at the same time as the the first frame of the calcium imaging.
- "Track body": tick this box if the deep lab cut model used analysed body position and you want to track the body of the animal in addition to the head (it is possible to get an accurate occupancy trace by only track the head position of the animal).
- "Tracking frame rate": exact frame rate used to record the animal's behaviour.
- "Speed smooth":
- "Center x (pixel)" and Center y (pixel): the x and y pixel in the tracking tiffs corresponding to the centre of each image (also found in MetaData.csv if using custom LabView GUI)
- "Resolution (cm/pixel)": the resolution of the tracking images, in cm/pixel, used to calculate speed/distance etc.
- "Head tracking fashion": M1-M3 denotes the method used to calculate the head position/the way it is reported in the DLC output. M1 uses tracking of two points at equal distance from a centre point that is then used as the head position (e.g. left and right ear), where head direction is extrapolated as perpendicular from the line connecting the right and left point. M2 calculates head position as the centre of two parallel points anterior and posterior of the head position (e.g. nose and back of head), head direction is considered as the continued direction through these two points (ahead of the anterior point). M3 uses only one point to calculate head position and therefore does not have an accurate frame by frame head direction. The CSV column for each point in each of the methods denotes the actual column the x and y position of said point can be found in the DLC .csv output.
- "Body tracking fashion": M1-M2 specifies the method used to calculate body position. M1 uses two points on one line (e.g. head and tail base), whose anterior extension denotes the body direction. M2 uses a single position to track body position, body direction is therefore not applicable. The CSV column for each point in each of the methods denotes the actual column the x and y position of said point can be found in the DLC .csv output.
This panel is used to input the options for the tracking and combine tuning maps.
- "Angle bin (degree)": angular bins (in degrees) used for the tuning maps.
- "Angle smoothing (degree)": degree(s) used for angular smoothing of tuning maps.
- "Plot range min (cm)":
- "Plot range max (cm)":
- "Min time (s)":
- "Spatial bin (cm)":
- "Spatial smoothing (cm)":
- "Speed threshold max (cm/s)":
- "Speed threshold min (cm/s)":
- "Show part": drop down menu to choose which body part to use for the tracking - head or body (often head gives the best tracking result).
- "Tracking and tuning colormap": drop down menu to choose the colormap of the tracking maps used in next panel. Code can be manually be updated to incorporate whichever colormap the user chooses.
This panel allows you to quickly look at the tracking data in terms of trajectory/direction/speed etc.
- "Total sessions": read only result, shows the total amount of sessions found in the base folder.
- "Show session": drop down menu to decide which of the total number of sessions (as seen above) that will be plotted in this panel.
- "Refresh": refreshing the panel. Read only results:
- "Total frames": total number of frames for the individual session (not total amount if more than one session).
- "Total time": total time for individual session in seconds.
- "Total distance (cm)": total distance covered by the animal the specified session.
- "Mean speed (cm/s)": average speed of the animal the specified session.
- "90th speed (cm/s)": 90th percentile of speed that session.
- "Show trajectory": button that shows the trajectory of the animal based on the inputs in this and "Tracking and combined plots options" panel.
- "Show direction plot": button to open a figure showing the radial map of the head/body direction based on parameters set in panel input.