ACE Workflow

AI-based Cartography of Ensembles (ACE) pipeline highlights:

  1. Cutting-edge vision transformer and CNN-based DL architectures trained on very large LSFM datasets (link to sample data and refer to example section) to map brain-wide neuronal activity.

  2. Optimized cluster-wise statistical analysis with a threshold-free enhancement approach to chart subpopulation-specific effects at the laminar and local level, without restricting the analysis to atlas-defined regions (link to sample data and refer to example section).

  3. Modules for providing DL model uncertainty estimates and fine-tuning.

  4. Interface with MIRACL registration to create study-specific atlases.

  5. Ability to account for covariates at the cluster level and map the connectivity between clusters of activations.

Main Inputs

Control and Treated directories, containing whole-brain 3D LSFM datasets for multiple subjects. OR A single directory containing a single subject’s whole-brain 3D LSFM dataset.

CLI

To get more information about the workflow and its required arguments use the following command on the cli:

$ miracl flow ace -h

The following information will be printed to the terminal:

usage: miracl flow ace [-s SINGLE_TIFF_DIR]
                       [-c CONTROL_BASE_DIR CONTROL_TIFF_DIR_EXAMPLE]
                       [-e EXPERIMENT_BASE_DIR EXPERIMENT_TIFF_DIR_EXAMPLE]
                       -sao SA_OUTPUT_FOLDER
                       -sam {unet,unetr,ensemble}
                       -sar X-res Y-res Z-res
                       [-sag SA_GPU_INDEX]
                       [-ctnd CTN_DOWN]
                       [-rcao RCA_ORIENT_CODE] [-rcav {10,25,50}]
                       [-rvad RVA_DOWNSAMPLE] [-rwcv {10,25,50}]
                       [--rerun-registration TRUE/FALSE]
                       [--rerun-segmentation TRUE/FALSE]
                       [--rerun-conversion TRUE/FALSE]

  1) Segments images with ACE
  2) Registers tissue cleared data (down-sampled nifti images) to Allen Reference mouse brain atlas
  3) Voxelizes high-resolution segmentation maps to downsample into Allen atlas resolution
  4) Warps voxelied segmentation maps from native space to Allen atlas
  5) Generates group-wise heatmaps of cell density using the average of voxelized and warped segmentation maps in each group
  6) Computes group-level statistics/correlation using cluster-wise analysis on voxelized and warped segmentation maps

Single or multi method arguments:
   -s SINGLE_TIFF_DIR, --single SINGLE_TIFF_DIR
                         path to single raw tif/tiff data folder
   -c CONTROL_BASE_DIR CONTROL_TIFF_DIR_EXAMPLE, --control CONTROL_BASE_DIR CONTROL_TIFF_DIR_EXAMPLE
                         FIRST: path to base control directory. SECOND: example
                         path to control subject tiff directory
   -e EXPERIMENT_BASE_DIR EXPERIMENT_TIFF_DIR_EXAMPLE, --experiment EXPERIMENT_BASE_DIR EXPERIMENT_TIFF_DIR_EXAMPLE
                         FIRST: path to base experiment directory. SECOND:
                         example path to experiment subject tiff directory

required arguments:
   -sao SA_OUTPUT_FOLDER, --sa_output_folder SA_OUTPUT_FOLDER
                         path to output file folder
   -sam {unet,unetr,ensemble}, --sa_model_type {unet,unetr,ensemble}
                         model architecture
   -sar X-res Y-res Z-res, --sa_resolution X-res Y-res Z-res
                         voxel size (type: float)

useful/important arguments:
   -sag SA_GPU_INDEX, --sa_gpu_index SA_GPU_INDEX
                         index of the GPU to use (type: int; default: 0)
   -ctnd CTN_DOWN, --ctn_down CTN_DOWN
                         Down-sample ratio for conversion (default: 5)
   -rcao RCA_ORIENT_CODE, --rca_orient_code RCA_ORIENT_CODE
                         to orient nifti from original orientation to
                         'standard/Allen' orientation, (default: ALS)
   -rcav {10,25,50}, --rca_voxel_size {10,25,50}
                         labels voxel size/Resolution in um (default: 10)
   -rvad RVA_DOWNSAMPLE, --rva_downsample RVA_DOWNSAMPLE
                         downsample ratio for voxelization, recommended: 5 <=
                         ratio <= 10
   -rwcv {10,25,50}, --rwc_voxel_size {10,25,50}
                         voxel size/Resolution in um for warping (default: 25)
   --rerun-registration TRUE/FALSE
                         Whether to rerun registration step of flow; TRUE =>
                         Force re-run (default: false)
   --rerun-segmentation TRUE/FALSE
                         Whether to rerun segmentation step of flow; TRUE =>
                         Force re-run (default: false)
   --rerun-conversion TRUE/FALSE
                         Whether to rerun conversion step of flow; TRUE =>
                         Force re-run (default: false)

--------------------------------------------------

Use -hv or --help_verbose flag for more verbose help

Note

There are a number of optional arguments including TFCE cluster-wise analysis parameters that can be provided to the respective function invoked by the workflow. These arguments have been ommitted here for readability but can be viewed by running miracl flow ace -hv.

Flag

Parameter

Type

Description

-s, --single

SINGLE_TIFF_DIR

str

path to single raw tif/tiff data folder

-c, --control

CONTROL_BASE_DIR, CONTROL_TIFF_DIR_EXAMPLE

(str, str)

FIRST: path to base control directory; SECOND: example path to control subject tiff directory

-e, --experiment

EXPERIMENT_BASE_DIR, EXPERIMENT_TIFF_DIR_EXAMPLE

(str, str)

FIRST: path to base experiment directory; SECOND: example path to experiment subject tiff directory

-sam, --sa_model_type

{unet,unetr,ensemble}

str

model architecture

-sao, --sa_output_folder

SA_OUTPUT_FOLDER

str

path to output file folder

-sar, --sa_resolution

X-res Y-res Z-res

(str, str, str)

Main outputs

clar_allen_reg # registration output / pre-liminary files
conv_final # conversion (tiff to nifti) output
reg_final  # main registration output
seg_final # segmentation output including model(s) outputs and uncertainty estimates
vox_final
warp_final
heatmap_final
cluster_final # cluster-wise analysis output including p_value and f_stats maps
corr_final # correlation analysis output including correlation maps and p_value maps

Executes:

seg/ace_interface.py
conv/miracl_conv_convertTIFFtoNII.py
reg/miracl_reg_clar-allen.sh
seg/miracl_seg_voxelize_parallel.py
reg/miracl_reg_warp_clar_data_to_allen.sh
stats/miracl_stats_heatmap_group.py
stats/miracl_stats_ace_interface.py

Example of running ACE flow on multiple subjects:

$ miracl flow ace \
   -c ./non_walking/ ./non_walking/Newton_HC1/cells/ \
   -e ./walking/ ./walking/Newton_UI1/cells/ \
   -sao ./output_dir \
   -sam unet \
   --overwrite

Jupyter notebook

An accompanying Jupyter notebook for this tutorial can be found here.