Updated defaults to use CCFv3 (30 um) with the iDISCO/LSFM template (we warped it to CCF space and refined alignment)

Author: daniel-rijsketic

README.md

@@ -36,7 +36,7 @@
 If you have any questions, suggestions, or are interested in collaborations and contributions, please reach out to us. 
 
 ### Developers
-* **Daniel Ryskamp Rijsketic** (lead developer and maintainer) - [danrijs@stanford.edu](mailto:danrijs@stanford.edu)
+* **Daniel Ryskamp Rijsketic** (developer and maintainer) - [danrijs@stanford.edu](mailto:danrijs@stanford.edu)
 * **Austen Casey** (developer) - [abcasey@stanford.edu](mailto:abcasey@stanford.edu)
 * **MetaCell** (UNRAVEL visualizer developers) - [info@metacell.us](mailto:info@metacell.us)
 * **Boris Heifets** (PI) - [bheifets@stanford.edu](mailto:bheifets@stanford.edu)
@@ -59,7 +59,7 @@ If you have any questions, suggestions, or are interested in collaborations and
 * [pandas](https://pandas.pydata.org/)
 * [cc3d](https://pypi.org/project/connected-components-3d/)
 * Registration and warping workflows were inspired by [MIRACL](https://miracl.readthedocs.io/en/latest/)
-* We adapted [LSFM/iDISCO+ atlases](https://pubmed.ncbi.nlm.nih.gov/33063286/) from [Gubra](https://www.gubra.dk/cro-services/3d-imaging/)
+* We warped this [LSFM/iDISCO+ average template brain](https://pubmed.ncbi.nlm.nih.gov/33063286/) to Allen brain atlas space (CCFv3) and refined alignment. 
 
 ### Support is welcome for
 * Analysis of new datasets

_other/drafts/check_reg_fsleyes.py

@@ -11,7 +11,7 @@
 def parse_args():
     parser = argparse.ArgumentParser(description='Prepares and displays medical images in fsleyes for analysis.', formatter_class=SuppressMetavar)
     parser.add_argument('-fri', '--fixed_reg_in', help='Pattern for fixed image from registration. Default: *autofl_50um_masked_fixed_reg_input.nii.gz', default="*autofl_50um_masked_fixed_reg_input.nii.gz", action=SM)
-    parser.add_argument('-wa', '--warped_atlas', help='Pattern for the warped atlas image from registration. Default: *gubra_ano_combined_25um_in_tissue_space.nii.gz', default="*gubra_ano_combined_25um_in_tissue_space.nii.gz", action=SM)
+    parser.add_argument('-wa', '--warped_atlas', help='Pattern for the warped atlas image from registration. Default: *atlas_CCFv3_2020_30um_in_tissue_space.nii.gz', default="*atlas_CCFv3_2020_30um_in_tissue_space.nii.gz", action=SM)
     parser.epilog = """Usage: check_reg_fsleyes.py"""
     return parser.parse_args()
 

_other/drafts/fsleyes.py

@@ -12,7 +12,7 @@ def parse_args():
     parser.add_argument('-i', '--inputs', help='List of .nii.gz files to view or if empty all .nii.gz files in the current directory.', nargs='*', default=None)
     parser.add_argument('-min', '--display_range_min', help='Minimum display range value.', default=0, type=float)
     parser.add_argument('-max', '--display_range_max', help='Maximum display range value.', required=True, type=float)
-    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: /usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz)', default='/usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz', action=SM)
+    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: atlas/atlas_CCFv3_2020_30um.nii.gz)', default='atlas/atlas_CCFv3_2020_30um.nii.gz', action=SM)
     return parser.parse_args()
 
 def main():

_other/fsleyes_luts/path_to_place_random.lut_for_Allen_coloring_of_atlas_labels.txt

@@ -4,4 +4,4 @@ Replace the original random look up table (LUT) text file with one containing re
 Location of LUTs for fsleyes: 
 /home/user/.config/fsleyes/luts/random.lut
 
-Launch fsleyes, load atlas gubra_ano_combined_25um.nii.gz, and change 3D/4D volume to Label image to apply LUT (random.lut is applied by default).
+Launch fsleyes, load atlas atlas_CCFv3_2020_30um.nii.gz, and change 3D/4D volume to Label image to apply LUT (random.lut is applied by default).

unravel/cluster_stats/brain_model.py

@@ -3,20 +3,17 @@
 """
 Use ``cluster_brain_model`` from UNRAVEL to prep .nii.gz and RGBA .txt for vizualization in dsi_studio.
 
-Usage with CCFv3:
------------------
-    cluster_brain_model -i input.nii.gz -sa path/atlas_CCFv3_2020_30um_split.nii.gz -m -v 
-
-Usage with gubra atlas:
------------------------
-    cluster_brain_model -i input.nii.gz -sa path/gubra_ano_split_25um.nii.gz -m -ax 0 -s 2 -v -csv regional_summary.csv
+Usage:
+------
+    cluster_brain_model -i input.nii.gz -sa atlas/atlas_CCFv3_2020_30um_split.nii.gz -m -v 
 
 Outputs: 
     - img_WB.nii.gz (bilateral version of cluster index w/ ABA colors)
     - rgba.txt (RGBA values for each region in the cluster index)
 
 Note: 
     - The input image will be binarized and multiplied by the split atlas to apply region IDs.
+    - Split means the left hemisphere region IDs are increased by 20000.
     - regional_summary_CCFv3-2020.csv is in UNRAVEL/unravel/core/csvs/
     - It has columns: Region_ID, ID_Path, Region, Abbr, General_Region, R, G, B
     - Alternatively, use regional_summary.csv or provide a custom CSV with the same columns.
@@ -43,7 +40,7 @@ def parse_args():
     parser.add_argument('-m', '--mirror', help='Mirror the image in the x-axis for a bilateral representation. Default: False', action='store_true', default=False)
     parser.add_argument('-ax', '--axis', help='Axis to flip the image along if mirroing. Default: 2', default=2, type=int, action=SM)
     parser.add_argument('-s', '--shift', help='Number of voxels to shift content after flipping. Default: 0', default=0, type=int, action=SM)
-    parser.add_argument('-sa', '--split_atlas', help='path/gubra_ano_split_25um.nii.gz. Default: gubra_ano_split_25um.nii.gz', default='gubra_ano_split_25um.nii.gz', action=SM)
+    parser.add_argument('-sa', '--split_atlas', help='path/split_atlas.nii.gz. Default: atlas/atlas_CCFv3_2020_30um_split.nii.gz', default='atlas/atlas_CCFv3_2020_30um_split.nii.gz', action=SM)
     parser.add_argument('-csv', '--csv_path', help='CSV name or path/name.csv. Default: regional_summary_CCFv3-2020.csv', default='regional_summary_CCFv3-2020.csv', action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False)
     parser.epilog = __doc__

unravel/cluster_stats/cluster_summary.ini

@@ -9,16 +9,16 @@ alternate = two-sided  # two-sided, greater, less (for t-test)
 
 [index]
 valid_clusters_dir = _valid_clusters
-atlas = /usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz  # path/atlas.nii.gz with symmetric labels
+atlas = atlas/atlas_CCFv3_2020_30um.nii.gz  # path/atlas.nii.gz with symmetric labels
 output_rgb_lut = True  # Output sunburst_RGBs.csv if True (for Allen brain atlas coloring w/ Flourish)
 sunburst_csv_path = sunburst_IDPath_Abbrv_CCFv3-2020.csv  # or sunburst_IDPath_Abbrv.csv in UNRAVEL/unravel/core/csvs/ (or path to a custom csv)
 info_csv_path = CCFv3-2020_info.csv  # or CCFv3_info.csv in UNRAVEL/unravel/core/csvs/ (or path to a custom csv)
 
 [brain]
 mirror = True  # Mirror the image in the x-axis for a bilateral representation (set as false if a whole brain mask was used for ``vstats`` instead of a hemisphere mask)
-axis = 0  # Axis to flip the image along
-shift = 2  # Number of voxels to shift content after flipping (accounts for asymmetry in the gubra atlas)
-split_atlas = /usr/local/unravel/atlases/gubra/gubra_ano_split_25um.nii.gz  # path/atlas.nii.gz (left label IDs increased by 20000)
+axis = 2  # Axis to flip the image along
+shift = 0  # Number of voxels to shift content after flipping (use if there is an asymmetry)
+split_atlas = atlas/atlas_CCFv3_2020_30um_split.nii.gz  # path/atlas.nii.gz (left label IDs increased by 20000)
 csv_path = regional_summary_CCFv3-2020.csv  # or regional_summary.csv in UNRAVEL/unravel/core/csvs/ (or path to a custom csv)
 
 [table]

unravel/cluster_stats/index.py

@@ -36,7 +36,7 @@ def parse_args():
     parser.add_argument('-ci', '--cluster_idx', help='Path to the reverse cluster index NIfTI file.', required=True, action=SM)
     parser.add_argument('-ids', '--valid_cluster_ids', help='Space-separated list of valid cluster IDs.', nargs='+', type=int, required=True, action=SM)
     parser.add_argument('-vcd', '--valid_clusters_dir', help='path/name_of_the_output_directory. Default: valid_clusters', default='_valid_clusters', action=SM)
-    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: path/gubra_ano_combined_25um.nii.gz)', default='/usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz', action=SM)
+    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: atlas/atlas_CCFv3_2020_30um.nii.gz)', default='atlas/atlas_CCFv3_2020_30um.nii.gz', action=SM)
     parser.add_argument('-rgb', '--output_rgb_lut', help='Output sunburst_RGBs.csv if flag provided (for Allen brain atlas coloring)', action='store_true')
     parser.add_argument('-scsv', '--sunburst_csv', help='CSV name or path/name.csv. Default: sunburst_IDPath_Abbrv_CCFv3-2020.csv', default='sunburst_IDPath_Abbrv_CCFv3-2020.csv', action=SM)
     parser.add_argument('-in', '--info', help='CSV name or path/name.csv. Default: CCFv3-2020_info.csv', default='CCFv3-2020_info.csv', action=SM)

unravel/cluster_stats/sunburst.py

@@ -44,7 +44,7 @@
 def parse_args():
     parser = argparse.ArgumentParser(description='Generate a sunburst plot of regional volumes that cluster comprise across the ABA hierarchy', formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input', help='path/rev_cluster_index.nii.gz (e.g., with valid clusters)', required=True, action=SM)
-    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: path/gubra_ano_combined_25um.nii.gz)', default='/usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz', action=SM)
+    parser.add_argument('-a', '--atlas', help='path/atlas.nii.gz (Default: atlas/atlas_CCFv3_2020_30um.nii.gz)', default='atlas/atlas_CCFv3_2020_30um.nii.gz', action=SM)
     parser.add_argument('-rgb', '--output_rgb_lut', help='Output sunburst_RGBs.csv if flag provided (for Allen brain atlas coloring)', action='store_true')
     parser.add_argument('-scsv', '--sunburst_csv_path', help='CSV name or path/name.csv. Default: sunburst_IDPath_Abbrv_CCFv3-2020.csv', default='sunburst_IDPath_Abbrv_CCFv3-2020.csv', action=SM)
     parser.add_argument('-icsv', '--info_csv_path', help='CSV name or path/name.csv. Default: CCFv3-2020_info.csv', default='CCFv3-2020_info.csv', action=SM)

unravel/docs/guide.md

@@ -869,14 +869,12 @@ rstats_summary --groups Saline MDMA Meth -d 10000 -hemi r
 │   ├── sample03
 │   └── sample04
 ├── atlas
-│   ├── gubra_ano_25um_bin.nii.gz  # bin indicates that this has been binarized (background = 0; foreground = 1)
-│   ├── gubra_ano_combined_25um.nii.gz  # Each atlas region has a unique intensity/ID
-│   ├── gubra_ano_split_25um.nii.gz  # Intensities in the left hemisphere are increased by 20,000
-│   ├── gubra_mask_25um_wo_ventricles_root_fibers_LH.nii.gz  # Left hemisphere mask that excludes ventricles, undefined regions (root), and fiber tracts
-│   ├── gubra_mask_25um_wo_ventricles_root_fibers_RH.nii.gz
-│   └── gubra_template_25um.nii.gz  # Average template brain that is aligned with the atlas
+│   ├── atlas_CCFv3_2020_30um.nii.gz  # Each atlas region has a unique intensity/ID
+│   ├── atlas_CCFv3_2020_30um_split.nii.gz  # Intensities in the left hemisphere are increased by 20,000
+│   ├── average_template_CCFv3_30um.nii.gz  # Average template brain that is aligned with the atlas
+│   └── mask_CCFv3_2020_30um_RH_wo_root_ventricles_fibers_OB.nii.gz  # Right hemisphere mask that excludes undefined regions (root), ventricles, and fiber tracts
 ├── reg_results
-├── ilastik_brain_mask
+├── brain_mask
 │   ├── brain_mask.ilp  # Ilastik project trained with the pixel classification workflow to segment the brain in resampled autofluo images
 │   ├── sample01_slice_0000.tif
 │   ├── sample01_slice_0005.tif

unravel/env_var.sh

@@ -1,22 +1,22 @@
 #!/bin/bash
 
 # Alias for sourcing this script added to .bashrc and .zshrc: 
-# alias exp=". /path/anes_env_gubra.sh"
+# alias exp=". /path/env_var.sh"
 
 # Set environment variables for the current terminal session when this script is sourced
 export EXP="exp_name"
 export BASE="/path/to/your/experiment"
 export DIRS="$BASE/Control/ $BASE/Treatment/"
 export PATTERN="sample??"
 export LOOP=$(echo "for d in Control Treatment ; do cd \$BASE/\$d ; for s in $PATTERN; do <commands> ; done ; done")
-export XY="3.5232063182059137"
+export XY="3.5232063182059137" # XY voxel size in microns
 export Z="5.0"
 export SAMPLE_KEY="$BASE/sample_key.csv"
-export BRAIN_MASK_ILP="$BASE/ilastik_brain_mask/brain_mask.ilp"
-export ATLAS="$BASE/atlas/gubra_ano_combined_25um.nii.gz"
-export SPLIT="$BASE/atlas/gubra_ano_split_25um.nii.gz"
-export TEMPLATE="$BASE/atlas/gubra_template_25um.nii.gz"
-export MASK="$BASE/atlas/gubra_mask_25um_wo_ventricles_root_fibers_RH.nii.gz"
+export BRAIN_MASK_ILP="$BASE/brain_mask/brain_mask.ilp"
+export ATLAS="$BASE/atlas/atlas_CCFv3_2020_30um.nii.gz"
+export SPLIT="$BASE/atlas/atlas_CCFv3_2020_30um_split.nii.gz"
+export TEMPLATE="$BASE/atlas/average_template_CCFv3_30um.nii.gz"
+export MASK="$BASE/atlas/mask_CCFv3_2020_30um_RH_wo_root_ventricles_fibers_OB.nii.gz"
 
 echo "These environment variables have been set for the current session:" 
 echo "EXP: $EXP"
@@ -27,8 +27,8 @@ echo "LOOP: $LOOP"
 echo "XY: $XY"
 echo "Z: $Z"
 echo 'SAMPLE_KEY: $BASE/sample_key.csv'
-echo 'BRAIN_MASK_ILP: $BASE/ilastik_brain_mask/brain_mask.ilp'
-echo 'ATLAS: $BASE/atlas/gubra_ano_combined_25um.nii.gz'
-echo 'SPLIT: $BASE/atlas/gubra_ano_split_25um.nii.gz'
-echo 'TEMPLATE: $BASE/atlas/gubra_template_25um.nii.gz'
-echo 'MASK: $BASE/atlas/gubra_mask_25um_wo_ventricles_root_fibers_RH.nii.gz'
+echo 'BRAIN_MASK_ILP: $BASE/brain_mask/brain_mask.ilp'
+echo 'ATLAS: $BASE/atlas/atlas_CCFv3_2020_30um.nii.gz'
+echo 'SPLIT: $BASE/atlas/atlas_CCFv3_2020_30um_split.nii.gz'
+echo 'TEMPLATE: $BASE/atlas/average_template_CCFv3_30um.nii.gz'
+echo 'MASK: $BASE/atlas/mask_CCFv3_2020_30um_RH_wo_root_ventricles_fibers_OB.nii.gz'

unravel/register/affine_initializer.py

@@ -5,13 +5,13 @@
 
 Usage:
 ------
-    reg_affine_initializer -f reg_outputs/autofl_50um_masked_fixed_reg_input.nii.gz -m /usr/local/unravel/atlases/gubra/gubra_template_25um.nii.gz -o reg_outputs/ANTsPy_init_tform.nii.gz -t 10
+    reg_affine_initializer -f reg_outputs/autofl_50um_masked_fixed_reg_input.nii.gz -m atlas/average_template_CCFv3_30um.nii.gz -o reg_outputs/ANTsPy_init_tform.nii.gz -t 10
 
 Python usage:
 -------------
 >>> import subprocess
 >>> import os
->>> command = ['python', 'reg_affine_initializer', '-f', 'reg_outputs/autofl_50um_masked_fixed_reg_input.nii.gz', '-m', '/usr/local/unravel/atlases/gubra/gubra_template_25um.nii.gz', '-o', 'reg_outputs/ANTsPy_init_tform.nii.gz', '-t', '10' ]
+>>> command = ['python', 'reg_affine_initializer', '-f', 'reg_outputs/autofl_50um_masked_fixed_reg_input.nii.gz', '-m', 'atlas/average_template_CCFv3_30um.nii.gz', '-o', 'reg_outputs/ANTsPy_init_tform.nii.gz', '-t', '10' ]
 >>> with open(os.devnull, 'w') as devnull:
 >>>    subprocess.run(command, stderr=devnull)
 """

unravel/register/reg.py

@@ -70,7 +70,7 @@ def parse_args():
     parser.add_argument('-bc', '--bias_correct', help='Perform N4 bias field correction. Default: False', action='store_true', default=False)
     parser.add_argument('-sm', '--smooth', help='Sigma value for smoothing the fixed image. Default: 0 for no smoothing. Use 0.4 for autofl', default=0, type=float, action=SM)
     parser.add_argument('-ort', '--ort_code', help='3 letter orientation code of fixed image if not set in fixed_img (e.g., RAS)', action=SM)
-    parser.add_argument('-m2', '--moving_img2', help='path/atlas.nii.gz (outputs <reg_outputs>/<atlas>_in_tissue_space.nii.gz for checking reg; Default: /usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz)', default='/usr/local/unravel/atlases/gubra/gubra_ano_combined_25um.nii.gz', action=SM)
+    parser.add_argument('-m2', '--moving_img2', help='path/atlas.nii.gz (outputs <reg_outputs>/<atlas>_in_tissue_space.nii.gz for checking reg; Default: atlas/atlas_CCFv3_2020_30um.nii.gz)', default='atlas/atlas_CCFv3_2020_30um.nii.gz', action=SM)
     parser.add_argument('-inp', '--interpol', help='Interpolation method for warping -m2 to padded fixed img space (nearestNeighbor, multiLabel [default], linear, bSpline)', default="multiLabel", action=SM)
     parser.add_argument('-it', '--init_time', help='Time in seconds allowed for ``reg_affine_initializer`` to run. Default: 30' , default='30', type=str, action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity.', action='store_true', default=False)

unravel/register/reg_check.py

@@ -28,7 +28,7 @@ def parse_args():
     parser.add_argument('-td', '--target_dir', help='path/target_output_dir name for aggregating outputs from all samples (cwd if omitted).', default=None, action=SM)
     parser.add_argument('-ro', '--reg_outputs', help="Name of folder w/ outputs from ``reg``. Default: reg_outputs", default="reg_outputs", action=SM)
     parser.add_argument('-fri', '--fixed_reg_in', help='Fixed image from registration ``reg``. Default: autofl_50um_masked_fixed_reg_input.nii.gz', default="autofl_50um_masked_fixed_reg_input.nii.gz", action=SM)
-    parser.add_argument('-wa', '--warped_atlas', help='Warped atlas image from ``reg``. Default: gubra_ano_combined_25um_in_tissue_space.nii.gz', default="gubra_ano_combined_25um_in_tissue_space.nii.gz", action=SM)
+    parser.add_argument('-wa', '--warped_atlas', help='Warped atlas image from ``reg``. Default: atlas_CCFv3_2020_30um_in_tissue_space.nii.gz', default="atlas_CCFv3_2020_30um_in_tissue_space.nii.gz", action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity.', action='store_true', default=False)
     parser.epilog = __doc__
     return parser.parse_args()

unravel/segment/copy_tifs.py

@@ -5,7 +5,7 @@
 
 Usage to prep for ``seg_brain_mask``:
 -------------------------------------
-    seg_copy_tifs -i reg_inputs/autofl_50um_tifs -s 0000 0005 0050 -o ilastik_brain_mask
+    seg_copy_tifs -i reg_inputs/autofl_50um_tifs -s 0000 0005 0050 -o brain_mask
 
 Usage to prep for ``seg_ilastik`` to segment full resolution immunofluorescence images:
 ---------------------------------------------------------------------------------------
@@ -31,7 +31,7 @@ def parse_args():
     parser.add_argument('-p', '--pattern', help='Pattern for sample?? dirs. Use cwd if no matches.', default='sample??', action=SM)
     parser.add_argument('-d', '--dirs', help='List of sample?? dir names or paths to dirs to process', nargs='*', default=None, action=SM)
     parser.add_argument('-i', '--input', help='reg_inputs/autofl_50um_tifs (from ``reg_prep``) or name of directory with raw tifs', default=None, action=SM)
-    parser.add_argument('-o', '--output', help='path/dir to copy TIF files. (e.g., ilastik_brain_mask or ilastik_segmentation)', required=True, action=SM)
+    parser.add_argument('-o', '--output', help='path/dir to copy TIF files. (e.g., brain_mask or ilastik_segmentation)', required=True, action=SM)
     parser.add_argument('-s', '--slices', help='List of slice numbers to copy (4 digits each; space separated)', nargs='*', type=str, default=[])
     parser.add_argument('-v', '--verbose', help='Increase verbosity.', action='store_true', default=False)
     parser.epilog = __doc__

unravel/utilities/aggregate_files_from_sample_dirs.py

@@ -6,11 +6,11 @@
 
 Usage for when sample?? is already in the name of files being copied:
 ---------------------------------------------------------------------
-    utils_agg_files -i atlas_space/sample??_FOS_rb4_gubra_space_z_LRavg.nii.gz -e $DIRS -v
+    utils_agg_files -i atlas_space/sample??_cfos_rb4_30um_CCF_space_z_LRavg.nii.gz -e $DIRS -v
 
 Usage to prepend sample?? to the name of files being copied:
 ------------------------------------------------------------
-    utils_agg_files -i atlas_space/FOS_rb4_gubra_space_z_LRavg.nii.gz -e $DIRS -v -a
+    utils_agg_files -i atlas_space/cfos_rb4_30um_CCF_space_z_LRavg.nii.gz -e $DIRS -v -a
 """
 
 import argparse