bmtrap_2021

System Requirements

bmtrap is tested on the following environment:

• Ubuntu 18.04.3 LTS
• Python 3.7 or above
• 64GB RAM
• 4-core i7 CPU (faster with NVIDIA GPU)

Installation Guide

• Required packages: Phathom, Nuggt in a conda environment:

  • Phathom installation guide: here
  • Nuggt installation guide: here
  • Other required open-source packages are also described in requirements.txt

• Download the repository from Github:

  git clone https://github.com/chunglabmit/bmtrap_2021.git

• Install the required python packages:

  pip install -r requirements.txt

• Install trap-2021:

  pip install -e .

• Typical install time: ~10 minutes.

Cell & Co-positive Cell Detection

This section describes the pipeline of cell detection (tdTomato⁺), and co-positive cell (tdTomato⁺/cfos⁺) detection.

1. TdTomato⁺ cell Detection

• This step is done by using Phathom. Additionally, false positives can be reduced by running inference of a learning-based model.
• The list of coordinates is saved in Numpy format.

2. Cfos⁺ probability map generation

• Using Phathom, a combined map of curvature and intensity probability can be generated.
• The 3D map is generated in Zarr format.

3. Co-registration of tdTomato⁺ cells and cfos⁺ probability map

• With the outputs from step 1 and 2, co-positive (tdTomato⁺/cfos⁺) cells can be computed as using bmtrap:

usage: bmtrap [-h] [-st SRC_TIFPATH] -sz SRC_ZARRPATH -sc SRC_CC
              [-dt DST_TIFPATH] -dz DST_ZARRPATH -dp DST_PROBPATH -sp
              SAVE_PATH -thr THRESHOLD [-dbg]

bmtrap -sz data/toy/CFC-5R/561nm_tdTomato_zarr -sc data/toy/CFC-5R/tdTomato_prediction_TRAP-20200705-130651_pos_toy.npy -dz data/toy/CFC-5R/642nm_cFOS_zarr -dp data/toy/CFC-5R/642nm_cFOS_probs_zarr -thr 0.5 -sp data/toy/CFC-5R -dbg

Expected Output:

[---------- BaseParams() Variables and their values (BEGIN) ----------]
[ debug ]	: True
[ dst_probpath ]	: data/toy/CFC-5R/642nm_cFOS_probs_zarr
[ dst_tifpath ]	: None
[ dst_zarrpath ]	: data/toy/CFC-5R/642nm_cFOS_zarr
[ save_path ]	: data/toy/CFC-5R
[ src_cc ]	: data/toy/CFC-5R/tdTomato_prediction_TRAP-20200705-130651_pos_toy.npy
[ src_tifpath ]	: None
[ src_zarrpath ]	: data/toy/CFC-5R/561nm_tdTomato_zarr
[ threshold ]	: 0.5
[ viz ]	: False
[---------- BaseParams() Variables and their values (END) ----------]
loading data...
==== DATA ====
	src vol shape:  (40, 10556, 5732)
	dst vol shape:  (40, 10556, 5732)
	dst probMap shape:  (40, 10556, 5732)
	len(src_cc):  7896
finding co-positive cells..
CoPos: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████| 40/40 [02:29<00:00,  3.73s/it]

• An example of running with toy dataset can be found in notebook/copos_detection.ipynb.

4. Cell Density Computation

• Density of the co-positive (tdTomato⁺/cfos⁺) cells can be computed if the brain images are aligned with ATLAS.

• Requirement:

  • Output json file generated by Step 3. (e.g. CoPosCC_ccPos_thr_0.50.json)
  • ATLAS alignment files. (Refer to Nuggt page for more details.)
    • ATLAS Annotation TIFF (e.g. autofluorescence_25_half_sagittal_whole.tif)
    • ATLAS region information (e.g. AllBrainRegions.csv)
    • Re-scaled alignments (e.g. rescaled_alignment.json)

• Count the co-positive cells per region and per level using count-points-in-region (Nuggt):

    count-points-in-region --points [JSON] --alignment [RESCALED_JSON] --reference-segmentation [ATLAS_TIFF] --brain-regions-csv [ATLAS_REGION_CSV] --output [OUTPUT_CSV] --level [LEVEL]
  

  • In this paper, we use level=[1...7].
  • Refer script/count_copos.sh for computing the co-positive cell density.

       bash ./script/count_copos.sh [DATA_PATH]   

  • Refer script/count.sh for computing tdTomato⁺ cell density.

5. Density File Format Conversion and Merging

• Use notebook/convert_alignment_format.ipynb to convert the density files into the same format used for the paper.

• Finally, both density files of tdTomato⁺ and tdTomato⁺/cfos⁺ can be merged using notebook/merge_density_files.ipynb.

• The merged .csv files are used for the final statistical reports in the paper.

Data

• data/toy contains a toy dataset:
  • data/toy/CFC-5R contains 40 z-slices of CFC_5R dataset (Z=[960,1000]). It can be used to test-run the co-positive cell detection.

Authors

bmTrap is maintained by members of the Kwanghun Chung Lab at MIT.

• Primary contact: Minyoung Kim (minykim@mit.edu)

License

• This project is covered under the MIT License.