HNCcorr algorithm for neuron identification in Calcium Imaging datasets.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
subroutines
.gitignore
HNCcorr.m
LICENSE.md
README.md
analyzeCells.m
generateH5File.m
main.m

README.md

This Matlab version is a preliminary implementation of the HNCcorr algorithm for cell identification in calcium-imaging as described in Spaen, Hochbaum, and Asín-Achá. "HNCcorr: A Novel Combinatorial Approach for Cell Identification in Calcium-Imaging Movies." arXiv preprint arXiv:1703.01999 (2017). This code was developed for 2D calcium-imaging datasets. A Python version (that also supports 3D datasets) is under active development.

This code is for non-commercial use only (see license).

Prerequisites

  1. Download and install the jsonlab toolbox for Matlab.
  2. Download and install a C-compiler for Matlab to compile mex-files.
  3. Confirm that the imagesci toolbox is installed (for generating h5-files).
  4. Install the neurofinder package for Python with pip install neurofinder to compare the output of HNCcorr with reference segmentations.

Setup

  1. In your working directory, create empty folders HNCcorrResults and H5files. Your working directory should look
  2. Depending on your OS, copy rtifc.mexw64 or rtifc.mexa64 from the folder <matlab root>/<version>/toolbox/matlabimagesci/private to your working directory. Here, <matlab root> is the installation directory of Matlab and <version> is the installed Matlab version (e.g. R2017a).
  3. Your working directory should now have the following structure:
$ ls
analyzeCells.m
generateH5File.m
H5files
HNCcorrResults
HNCcorr.m
LICENSE.md
main.m
README.md
subroutines

How to run

There are three main scripts/functions:

  1. generateH5File.m: Preprocesses a set of tiff files and stores the data as an h5-file in the folder H5files. The h5-file serves as the input for main.m.
  2. main.m: This script defines the hyper parameters for HNCcorr, runs the algorithm, and saves the result in HNCcorrResults.
  3. analyzeCells.m: Provides a crude graphical interface to analyze the output of HNCcorr.

The scripts should be ran in this order. Hyper parameters (see below for description) should be adjusted in the scripts themselves.

Hyper parameters

This section provides an overview of the hyper parameters. Default values or recommended values are specified when appropriate. Parameters that most strongly affect performance are (in order of importance): avgSize, maxSize, posSeedsWidth, binSize, perc, minSize.

generateH5file.m

  • fileNameBase: A base filename for HNCcorr's intermediate/output files.
  • rawdata_dir: Directory with tiff files. Each tiff file should contain a single frame. It is assumed that the files are named image00001.tiff, image00002.tiff, etc.
  • dataSize=[<width> <height>]: Dimensions of the dataset in pixels.
  • nFiles: Number of frames/files.
  • chunkSize=31: Chunk size for data storage in .h5 files. Parameter does not affect the output of HNCcorr.
  • binSize=10: The frames in the h5 file are averages of binSize frames of the original movie. 10-frame averages were effective for the Neurofinder benchmark datasets.

main.m

Setup parameters:

  • fileNameBase: A base filename for HNCcorr's intermediate/output files.
  • dataFileName: Path to the pre-processed .h5 file (see generateH5file.m).
  • dataSize=[<width> <height>]: Dimensions of the dataset in pixels.
  • nFrames: Number of frames in the .h5 file.
  • jsonFile='': Path to reference segmentations used for evaluation of HNCcorr's segmentations. If no reference is available, set as empty string ''.
  • windowSize=31: Width/height in pixels of the window that is used for segmentation. Odd number is required. Window should be sufficiently large to capture a single cell. Rule-of-thumb: Set windowSize equal to 1.5-2x the diameter of a cell.

Seed selection parameters:

  • posSeedsWidth=2: Size of the square used as a seed for the cell. Use 0 for 1x1 pixel, 1 for 3x3 pixels and 2 for 5x5 pixels. Different parameter values may be preferred some datasets.
  • perc=0.4: Percentage of seeds (ranked by expected quality) to test. Determines the trade-off between running time and quality. More seeds is not always better, due to false positives.

Oracle parameters (dataset specific):

  • avgSize: Average (estimated) number of pixels for a cell in the dataset.
  • minSize=40: Smallest (estimated) number of pixels for a cell in the dataset.
  • maxSize: Largest (estimated) number of pixels for a cell in the dataset.

analyzeCells.m

  • filename: Path for the .mat output file generated by HNCcorr.