Skip to content

Home

Jump to bottom
Bo Hu edited this page Apr 12, 2024 · 17 revisions

Welcome to the neuRoi wiki!

Create an experiment

To analyze the data recorded from an experiment, we will first create an NrModel instance containing all necessary metadata of the experiment.

rawDataDir = '/directory/to/raw/data/';
rawFileList = {'trial01.tif', 'trial02.tif', 'trial03.tif'};
resultDir = '/directory/to/save/results/';
expInfo.name = 'example-experiment';
expInfo.frameRate = 30;
expInfo.nPlane = 4;

myexp = NrModel('rawDataDir',rawDataDir,...
                'rawFileList',rawFileList,...
                'resultDir',resultDir,...
                'expInfo',expInfo);
  • rawDataDir is the directory that contains the raw image files.
  • rawFileList is the list of raw image filenames. Each image file corresponds to a trial. Note that these should be realative paths with respect to rawDataDir, instead of the abosolute ones.
  • resultDir is the directory where the analysis results will be stored.
  • expInfo is a structure containing metadata of the experiment. The required fields are:
    • name is the name of the experiment
    • frameRate is the frame rate (frames/second) of the image files. For multiplane imaging withe setup A, this should be the total frame rate for all planes. The frame rate for each plane will be frameRate/nPlane
    • nPlane is the total number of planes imaged in each trial. For single-plane imaging, nPlane is 1. For multiplane imaging with setupA, this should be the same as the number of planes in fastZ configuration in ScanimageB.

Pre-processing

There are several options to pre-process the image files before creating ROIs. These include

  • Scan pattern subtraction
  • Rigid motion correction within a trial
  • Subsampling
  • Compute anatomy
  • Rigid motion correction between trials To pre-process the trials, we can call the function NrModel.processRawData() with the corresponding parameters specified.

Scan pattern subtraction

For a resonance scanning setup, e.g. setupA, it is recommended to subtract the pattern caused by the scanner. The parameters for scan pattern subtraction are

subtractScan % If true, do scan pattern subtraction
noSignalWindow % An 2-element array specifying the range of frames used to compute
% the scan pattern. This range should ideally contain no signals from the imaged
% sample and should have the photomultiplier (PMT) not yet switched on.
% For example setting noSignalWindow to [1, 20], it will take the range from
% the 1st frame to the 20th frame for computing the template in each trial.
% For a multiplane experiment, we need to divide this range by nPlane. For example
% for 4-plane imaging, the no-signal frame range is 1 to 20 for all planes.
% Then the noSignalWindow should be specified as [1, 20/4], since each plane
% only has 5 no-signal frames.

Rigid motion correction within a trial

When the biological sample is not stable during a trial, it is sometimes necessary to correct the motion of sample frame by frame. In neuRoi there is an option to do motion correction by registering each frame to a template frame and translate each frame in x and y accordingly.

Whether to perform motion correction within trial is controlled by the following parameter.

motionCorr % If true, do motion correction whithin each trial

Note that this currently only works for single-plane trials, multi-plane is not yet implemented.

Subsampling

Subsample binParam.trialOption = struct('process',true,'noSignalWindow',[1 4]); scan pattern subtraction

binParam.shrinkFactors = [1, 1, 2]; binParam.depth = 8; % uint8 or uint16 integer depth for the resulting binned image

Compute anatomy

Rigid motion correction between trials

        addParameter(pa,'computeAnatomy',true);

Save experiment

Folder structure of an experiment

  • Raw data folder

  • Result folder experiment_.mat anatomy

alignment df_rgb response_map roi stardist_mask time_trace

Pre-processing

Subtract scan pattern

Motion correction within a trial

Subsample Save experiment

Draw ROIs manually

Open an experiment

  • Open a trial open a trial by double click on the trial name in the neuRoi main GUI.

  • maps anatomy dF/F map maximum dF/F map local correlation map import additional maps

  • Switching between maps To switch between maps, press 'q', 'w', 'e', each key corresponds to a map in tab 1, 2 or 3. You can also switch between maps by clicking the buttons with 1, 2, 3 etc. above the map.

  • Add ROI: Press 'f'. Cursor enters drawing mode. Draw the ROI by pressing and dragging the mouse, upon release a new ROI will be generated with an integer id of max (ROI-ids of current plane)+1. If the ROI contains only 1 or less pixel, which can be generated by accidentally finished ROI, the ROI will not be added. To exit drawing mode without adding a ROI, press Esc to cancel

  • move ROI: Select a ROI by clicking on it. Press 'v'. ROI changes color. Move the ROI by draging the ROI patch. Double click on the moved ROI to confirm or press Esc to cancel move.

  • redraw ROI: Select a ROI by clicking on it. Press 'x'. ROI disappear and the cursor enters drawing mode. Redraw the ROI. Press Enter to confirm or press Esc to cancel redraw.

  • Delete ROI: Select a ROI by clicking or select several ROIs by pressing Shift key while selecting. Press 'd' or 'delete' to delete the ROIs.

  • Toggle display of ROIs: Press 'r' to toggle display of ROIs on and off.

  • Zoom Press '=' or '2' to zoom in. Press '-' or '1' to zoom out. Press Ctrl+1 to reset the zoom level

  • Load ROIs To load previously saved ROIs to the current trial, go to File > Load ROIs and select the ROI .mat file to load.

A window will pop up asking whether you would like to merge the ROIs with the currently drawn ROIs, or delete the ROIs and replace with the ROIs from the file.

Note that if you choose 'merge', the ROI IDs of the newly loaded file will change in order to preserve the uniqueness of the ROI IDs in the trial.

  • Save ROIs To save the ROIs in the current trial, go to File > Save ROIs. Select a file path and click 'save'.

  • Import ROIs from mask

Assign ROI to groups

  • Add a ROI group To add a ROI group, press the '+' button on top of the ROI group list and then type in the name of the group. Click 'OK', a ROI group will be created.
  • Rename a ROI group Select the ROI group in the ROI group list, press 'Ctrl+o', type in the new name of the ROI group, click 'OK'.
  • Assign ROIs to a group Select the ROI group to be assigned to in the ROI group list. Click on the ROI map, press 'b', then draw a region overlay by dragging the mouse. The ROIs that intersects with the overlay will be selected.

Then press 'n' to assign the selected ROIs to the current ROI group.

If you accidentally pressed 'f' instead of 'b' and ended up drawing a big ROI, you could press 'Ctrl+z' to restore the previous state.

Compatibility with StarDist

Generating Groundtruth for training StarDist export maps export masks

Generating StarDist predictions

Since StarDist can make predictions based on RGB images, we make use of the three RGB channels to contain information of the anatomy, dF/F and local correlation maps.

To generate such an RGB image for a trial, first open the trial by double-clicking the trial entry. Then make sure the required maps in this trial are computed. This can be done either by setting myexp.mapsAfterLoading = {'response', 'responseMax', 'localCorrelation'}; or by clicking the add map buttons manually.

trial = myexp.getCurrentTrial();
rgbDir = myexp.getDefaultDir('df_rgb');
if ~exist(rgbDir, 'dir')
    mkdir(rgbDir);
end
rgbSubdir = myexp.appendPlaneDir(rgbDir, myexp.planeNum);
if ~exist(rgbSubdir, 'dir')
    mkdir(rgbSubdir)
end
mapTypeList = {'anatomy','response','localCorrelation'};
mapDataList = trial.getMapDataList(mapTypeList);
fileName = sprintf('merged_%s.tif',trial.fileBaseName);
filePath = fullfile(rgbSubdir,fileName);
imwrite(mapDataList,filePath);

Next, we will use the RGB image as input to the trained StarDist Model to generate prediction of neurons. To do this, we need to run stardist_pred/predict_mergedRGB.py in a python environment where StarDist is properly installed.

This is currently not implemented directly in neuRoi in MATLAB, but the following code can print the command to run python with corresponding input parameters.

maskDir = myexp.getDefaultDir('stardist_mask')
if ~exist(maskDir,'dir')
    mkdir(maskDir)
end
maskSubdir = myexp.appendPlaneDir(rgbDir, myexp.planeNum);
if ~exist(maskSubdir,'dir')
    mkdir(maskSubdir)
end
stardistCmd = sprintf('python predict_mergedRGB.py %s %s',...
                      rgbSubdir, maskSubdir)
disp(stardistCmd)

Import StarDist prediction as ROIs

After generating the ROI mask with StarDist, we can import it into neuRoi and modify the ROIs manually. To import the ROIs, open the trial by double-clicking the corresponding trial name. In the trial window, click File menu > Import ROIs from mask. The choose the TIF file of the mask image, click Okay. The ROIs should be imported into the current trial.

After modifying the ROIs, click File menu > Save ROis, to save the ROIs in the neuRoi format.

Trial stack

For an experiment with multiple trials, if the sample has deformation across trials, it is necessary to morph the ROI map to each trial, to correct for the deformation.

Select trials for processing

Although an experiment contains many trials, we may need to select a subset of trials for processing. For this purpose, we can use the selectedFileIdx property of NrModel. Note that currently selecting trials is only possible programmatically. A GUI button for this will be introduced in the future version.

For example, the following code will allow us process only trial01 and trial03, instead of all 3 trials in the experiment.

% Creating an experiment
rawFileList = {'trial01.tif', 'trial02.tif', 'trial03.tif'};
expInfo = struct('frameRate', 30, 'nPlane', 1);
myexp = NrModel('rawDataDir', '/path/to/raw_data/',...
'rawFileList', rawFileList,...
'resultDir', '/path/to/result/',...
'expInfo', expInfo);

% Select trials
% The numbers in the list correspond to the indices of
% the selected trials in myexp.rawFileList
myexp.selectedFileIdx = [1, 2];

If myexp.selectedFileIdx is not set, by default all trials are selected.

The selection of trials will apply for getting a trial stack and extract time traces.

Notes for setup A users For setup A users who does the odor stimulation experiment, there is a function in neuRoi that helps to sort the trials according to odor conditions. We can then based on the sorted table of trials, decide which trials to keep for further analysis.

%% Get trial table
% This step is to sort the raw data files according to odor conditions
myexp.arrangeTrialTable();
disp(myexp.trialTable)
%% Remove the trials that you do not want to include in further analysis
% Note that this step only removes the trials in the trial table.
% It does not affect the rawFileList of the experiment
removeIdx = [11, 12];

if length(removeIdx)
    myexp.removeTrialFromTable(removeIdx);
    myexp.trialTable.trialNum = [];
    myexp.trialTable = batch.addTrialNum(myexp.trialTable);
end
disp(myexp.trialTable)

%% After having a trial table with all trials we want to keep,
% select the corresponding trials in the experiment
myexp.selectedFileIdx = myexp.trialTable.fileIdx;

Rigid alignment of Trials

TODO rigid alignment without Bunwarpj

Important If you are using the Bunwarpj feature to deform ROIs across trials, the rigid alignment will be performed automatically. It is recommended to not do rigid alignment outside Bunwarpj, or at least set myexp.alignTrials = false to avoid both shifting the trial movie and transforming the ROIs.

This confusing issue will be improved in the future version.

Transforming ROIs across trials (Bunwarpj)

Under many experimental conditions, the brain sample has non-linear deformation across trials. Hence it is necessary to transform the ROIs according to the deformations across each trials.

The Bunwarpj feature make use of the bUnwarpJ for computing the transformations based on anatomy images of trials. Therefore, we need to have Fiji and bUnwarpJ installed.

Then we need to set the paths in neuRoi that points to the bUnwarpJ plugin. To do this, open neuRoi/+Buwnarpj/getImageJPaths.m and modify the imagejPaths variable according to the location where Fiji and bUnwarpJ is installed.

Before starting the Bunwarpj feature, we may want to select only a subset of trials to compute the transformation. To do this, please refer to [Select trials for processing](#### Select trials for processing).

Now we can start the Bunwarpj feature. First, go to the Non-rigid inter trial registration panel in neuRoi main GUI. In the text box, type in the transformation name. This is the name of the subfolder where the computed transformation is stored. Next, select the reference trial in the drop down menu. This will the template trial that other trials are aligned to. If the contrast of the anatomy images is not good, you could choose contrast enhancement method, CLAHE or Histogram equalization to enhance the contrast before computing the transformation.

Then click "Calculate Bunwarpj". NeuRoi will start to compute the transformations.

TODO apply transformation before inspection

After the computation finishes, select the transformation name in the drop down menu and click "Inspect tirals". A trial stack GUI will pop up and we could inspect and edit the ROIs in the stack of trials.

Editing ROIs in the trial stack

add ROIs to an individual trial

add ROIs to the stack with transformation

move ROIs in an individual trial

delete ROIs in an individual trial

delete ROIs in the stack

Extracting time traces

Then run extract_time_trace.m to draw ROIs manually and extract time traces.

Customizing for experiment setups

Overview

User Manual

Documentation For Developers

Clone this wiki locally