Moved help guides for each script from argparse to the module-level d…

…ocstring and formated them for sphinx

unravel/cluster_stats/brain_model.py

@@ -1,5 +1,17 @@
 #!/usr/bin/env python3
 
+"""
+Prep .nii.gz and RGBA .txt for vizualization in dsi_studio.
+
+Usage:
+    brain_model.py -i input.csv -m -sa path/gubra_ano_split_25um.nii.gz -v
+
+The input image will be binarized and multiplied by the split atlas to apply region IDs.
+
+Outputs: 
+    img_WB.nii.gz (bilateral version of cluster index w/ ABA colors)
+"""
+
 import argparse
 import nibabel as nib
 import numpy as np
@@ -15,22 +27,14 @@
 
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='Prep .nii.gz and RGBA .txt for vizualization in dsi_studio', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input', help="path/img.nii.gz (e.g., valid cluster index)", required=True, action=SM)
     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. Default: 0', default=0, type=int, action=SM)
     parser.add_argument('-s', '--shift', help='Number of voxels to shift content after flipping. Default: 2', default=2, 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('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False)
-    parser.epilog = """Example usage: brain_model.py -i input.csv -m -sa path/gubra_ano_split_25um.nii.gz -v
-
-The input image will be binarized and multiplied by the split atlas to apply region IDs.
-
-Outputs: 
-img_WB.nii.gz (bilateral version of cluster index w/ ABA colors)
-
-"""
-
+    parser.epilog = __doc__
     return parser.parse_args()
 
 

unravel/cluster_stats/crop_clusters.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+"""
+Load image, load bounding box, crop cluster, and save as .nii.gz
+"""
+
 import argparse
 from rich.traceback import install
 from rich import print
@@ -12,7 +16,7 @@
 
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='Load image, crop cluster, and save as .nii.gz', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input', help='path/img.czi, path/img.nii.gz, or path/tif_dir', action=SM)
     parser.add_argument('-o', '--output', help='path/output_img.nii.gz', action=SM)
     parser.add_argument('-b', '--bbox', help='path/bbox.txt', action=SM)
@@ -21,6 +25,7 @@ def parse_args():
     parser.add_argument('-x', '--xy_res', help='xy resolution in um', type=float, action=SM)
     parser.add_argument('-z', '--z_res', help='z resolution in um', type=float, action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False)
+    parser.epilog = __doc__
     return parser.parse_args()
 
 def save_cropped_img(img_cropped, xy_res, z_res, args, cluster=None):

unravel/cluster_stats/effect_sizes/effect_sizes.py

@@ -1,5 +1,25 @@
 #!/usr/bin/env python3
 
+"""
+Calculates the effect size for a comparison between two groups for each cluster [or a valid cluster list]
+
+Usage:
+    effect_sizes.py -i densities.csv -c1 saline -c2 psilocybin
+
+-c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
+
+Outputs CSV w/ the effect size and CI for each cluster:
+    <input>_Hedges_g_<condition_1>_<condition_2>.csv
+
+If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
+    <input>_Hedges_g_<condition_1>_<condition_2>_valid_clusters.csv
+
+The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
+    Hedges' g = ((c2-c1)/spooled*corr_factor)
+    CI = Hedges' g +/- t * SE
+    0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large
+"""
+
 import argparse
 import os
 import pandas as pd
@@ -9,26 +29,12 @@
 from unravel.core.argparse_utils import SuppressMetavar, SM
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='''Calculates the effect size for a comparison between two groups for each cluster [or a valid cluster list]''', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input_csv', help='CSV with densities (Columns: Samples, Conditions, Cluster_1, Cluster_2, ...)', action=SM)
     parser.add_argument('-c1', '--condition_1', help='First condition of interest from csv (e.g., saline [data matching prefix pooled])', action=SM)
     parser.add_argument('-c2', '--condition_2', help='Second condition (e.g, psilocybin [data matching prefix pooled])', action=SM)
     parser.add_argument('-c', '--clusters', help='Space separated list of valid cluster IDs (default: process all clusters)', default=None, nargs='*', type=int, action=SM)
-    parser.epilog = """Example usage:    sex_effect_sizes_absolute.py -i densities.csv -c1 saline -c2 psilocybin
-
--c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
-
-Outputs CSV w/ the effect size and CI for each cluster:
-<input>_Hedges_g_<condition_1>_<condition_2>.csv
-
-If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
-<input>_Hedges_g_<condition_1>_<condition_2>_valid_clusters.csv
-
-The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
-
-Hedges' g = ((c2-c1)/spooled*corr_factor)
-CI = Hedges' g +/- t * SE
-0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large"""
+    parser.epilog = __doc__
     return parser.parse_args()
 
 
@@ -55,7 +61,7 @@ def condition_selector(df, condition, unique_conditions, condition_column='Condi
     else:
         raise ValueError(colored(f"Condition {condition} not recognized!", 'red'))
 
-# Calculate the effect size for each cluster and sex
+# Calculate the effect size for each cluster
 def hedges_g(df, condition_1, condition_2): 
 
     df = pd.read_csv(df)

unravel/cluster_stats/effect_sizes/effect_sizes_by_sex__absolute.py

@@ -1,5 +1,27 @@
 #!/usr/bin/env python3
 
+"""
+Calculates the effect size for a comparison between two groups for each cluster [or a valid cluster list]
+
+Enter M or F in the Sex column.
+    
+Usage:
+    effect_sizes_by_sex__absolution.py -i densities.csv -c1 saline -c2 psilocybin
+
+-c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
+
+Outputs CSV w/ the effect size and CI for each cluster:
+    <input>_Hedges_g_<condition_1>_<condition_2>.csv
+
+If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
+    <input>_Hedges_g_<condition_1>_<condition_2>_valid_clusters.csv
+
+The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
+    Hedges' g = ((c2-c1)/spooled*corr_factor)
+    CI = Hedges' g +/- t * SE
+    0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large
+"""
+
 import argparse
 import os
 import pandas as pd
@@ -9,28 +31,12 @@
 from unravel.core.argparse_utils import SuppressMetavar, SM
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='''Calculates the effect size for a comparison between two groups for each cluster [or a valid cluster list]''', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input_csv', help='CSV with densities (Columns: Samples, Sex, Conditions, Cluster_1, Cluster_2, ...)', action=SM)
     parser.add_argument('-c1', '--condition_1', help='First condition of interest from csv (e.g., saline [data matching prefix pooled])', action=SM)
     parser.add_argument('-c2', '--condition_2', help='Second condition (e.g, psilocybin [data matching prefix pooled])', action=SM)
     parser.add_argument('-c', '--clusters', help='Space separated list of valid cluster IDs (default: process all clusters)', default=None, nargs='*', type=int, action=SM)
-    parser.epilog = """Enter M or F in the Sex column.
-    
-Example usage:    effect_sizes_by_sex__absolution.py -i densities.csv -c1 saline -c2 psilocybin
-
--c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
-
-Outputs CSV w/ the effect size and CI for each cluster:
-<input>_Hedges_g_<condition_1>_<condition_2>.csv
-
-If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
-<input>_Hedges_g_<condition_1>_<condition_2>_valid_clusters.csv
-
-The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
-
-Hedges' g = ((c2-c1)/spooled*corr_factor)
-CI = Hedges' g +/- t * SE
-0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large"""
+    parser.epilog = __doc__
     return parser.parse_args()
 
 

unravel/cluster_stats/effect_sizes/effect_sizes_by_sex__relative.py

@@ -1,5 +1,27 @@
 #!/usr/bin/env python3
 
+"""
+Calculates the relative effect size for (comparing sexes) for a comparison between two groups for each cluster [or a valid cluster list]
+
+Enter M or F in the Sex column.
+    
+Usage:
+    effect_sizes_by_sex__relative.py -i densities.csv -c1 saline -c2 psilocybin
+
+-c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
+
+Outputs CSV w/ the relative effect size (F>M) and CI for each cluster:
+    <input>_Hedges_g_<condition_1>_<condition_2>_F_gt_M.csv
+
+If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
+    <input>_Hedges_g_<condition_1>_<condition_2>_F_gt_M_valid_clusters.csv
+
+The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
+    Hedges' g = ((c2-c1)/spooled*corr_factor)
+    CI = Hedges' g +/- t * SE
+    0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large
+"""
+
 import argparse
 import os
 import pandas as pd
@@ -9,28 +31,12 @@
 from unravel.core.argparse_utils import SuppressMetavar, SM
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='''Calculates the relative effect size for (comparing sexes) for a comparison between two groups for each cluster [or a valid cluster list]''', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     parser.add_argument('-i', '--input_csv', help='CSV with densities (Columns: Samples, Sex, Conditions, Cluster_1, Cluster_2, ...)', action=SM)
     parser.add_argument('-c1', '--condition_1', help='First condition of interest from csv (e.g., saline [data matching prefix pooled])', action=SM)
     parser.add_argument('-c2', '--condition_2', help='Second condition (e.g, psilocybin [data matching prefix pooled])', action=SM)
     parser.add_argument('-c', '--clusters', help='Space separated list of valid cluster IDs (default: process all clusters)', default=None, nargs='*', type=int, action=SM)
-    parser.epilog = """Enter M or F in the Sex column.
-    
-Example usage:    effect_sizes_by_sex__relative.py -i densities.csv -c1 saline -c2 psilocybin
-
--c1 and -c2 should match the condition name in the Conditions column of the input CSV or be a prefix of the condition name.
-
-Outputs CSV w/ the relative effect size (F>M) and CI for each cluster:
-<input>_Hedges_g_<condition_1>_<condition_2>_F_gt_M.csv
-
-If -c is used, outputs a CSV with the effect sizes and CI for valid clusters:
-<input>_Hedges_g_<condition_1>_<condition_2>_F_gt_M_valid_clusters.csv
-
-The effect size is calculated as the unbiased Hedge\'s g effect sizes (corrected for sample size): 
-
-Hedges' g = ((c2-c1)/spooled*corr_factor)
-CI = Hedges' g +/- t * SE
-0.2 - 0.5 = small effect; 0.5 - 0.8 = medium; 0.8+ = large"""
+    parser.epilog = __doc__
     return parser.parse_args()
 
 

unravel/cluster_stats/fdr.py

@@ -1,32 +1,10 @@
 #!/usr/bin/env python3
 
-import argparse
-import concurrent.futures
-import subprocess
-import numpy as np
-import nibabel as nib
-from concurrent.futures import ThreadPoolExecutor
-from pathlib import Path
-from rich import print
-from rich.traceback import install
-
-from unravel.core.argparse_utils import SM, SuppressMetavar
-from unravel.core.config import Configuration
-from unravel.core.utils import print_cmd_and_times, print_func_name_args_times
+"""
+Perform FDR correction on a p value map to define clusters
 
-
-def parse_args():
-    parser = argparse.ArgumentParser(description='Perform FDR correction on a p value map to define clusters', formatter_class=SuppressMetavar)
-    parser.add_argument('-i', '--input', help='path/p_value_map.nii.gz', required=True, action=SM)
-    parser.add_argument('-mas', '--mask', help='path/mask.nii.gz', required=True, action=SM)
-    parser.add_argument('-q', '--q_value', help='Space-separated list of FDR q values', required=True, nargs='*', type=float, action=SM)
-    parser.add_argument('-ms', '--min_size', help='Min cluster size in voxels. Default: 100', default=100, type=int, action=SM)
-    parser.add_argument('-o', '--output', help='Output directory. Default: input_name_q{args.q_value}"', default=None, action=SM)
-    parser.add_argument('-a1', '--avg_img1', help='path/averaged_immunofluo_group1.nii.gz for spliting the cluster index based on effect direction', action=SM)
-    parser.add_argument('-a2', '--avg_img2', help='path/averaged_immunofluo_group2.nii.gz for spliting the cluster index based on effect direction', action=SM)
-    parser.add_argument('-th', '--threads', help='Number of threads. Default: 10', default=10, type=int, action=SM)
-    parser.add_argument('-v', '--verbose', help='Increase verbosity', default=False, action='store_true')
-    parser.epilog = """Usage:    fdr.py -i path/vox_p_tstat1.nii.gz -mas path/mask.nii.gz -q 0.05
+Usage:
+    fdr.py -i path/vox_p_tstat1.nii.gz -mas path/mask.nii.gz -q 0.05
 
 Inputs: 
     - p value map (e.g., *vox_p_*stat*.nii.gz from vstats.py)    
@@ -52,6 +30,34 @@ def parse_args():
 
 For unilateral data or bilateral data processed with a whole brain mask, the cluster indices are ready for validation with validate_clusters.py.
 """
+
+import argparse
+import concurrent.futures
+import subprocess
+import numpy as np
+import nibabel as nib
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from rich import print
+from rich.traceback import install
+
+from unravel.core.argparse_utils import SM, SuppressMetavar
+from unravel.core.config import Configuration
+from unravel.core.utils import print_cmd_and_times, print_func_name_args_times
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
+    parser.add_argument('-i', '--input', help='path/p_value_map.nii.gz', required=True, action=SM)
+    parser.add_argument('-mas', '--mask', help='path/mask.nii.gz', required=True, action=SM)
+    parser.add_argument('-q', '--q_value', help='Space-separated list of FDR q values', required=True, nargs='*', type=float, action=SM)
+    parser.add_argument('-ms', '--min_size', help='Min cluster size in voxels. Default: 100', default=100, type=int, action=SM)
+    parser.add_argument('-o', '--output', help='Output directory. Default: input_name_q{args.q_value}"', default=None, action=SM)
+    parser.add_argument('-a1', '--avg_img1', help='path/averaged_immunofluo_group1.nii.gz for spliting the cluster index based on effect direction', action=SM)
+    parser.add_argument('-a2', '--avg_img2', help='path/averaged_immunofluo_group2.nii.gz for spliting the cluster index based on effect direction', action=SM)
+    parser.add_argument('-th', '--threads', help='Number of threads. Default: 10', default=10, type=int, action=SM)
+    parser.add_argument('-v', '--verbose', help='Increase verbosity', default=False, action='store_true')
+    parser.epilog = __doc__
     return parser.parse_args()
 
 # TODO: could add optional args like in vstats.py for running the fdr command. 

unravel/cluster_stats/fdr_range.py

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 
+"""
+Outputs a list of FDR q values that yeild clusters
+
+Usage: 
+    fdr_range.py -i path/vox_p_tstat1.nii.gz -mas path/mask.nii.gz -q 0.05 0.01 0.001
+
+Inputs: 
+    - p value map (e.g., *vox_p_*stat*.nii.gz from vstats.py)    
+"""
+
 import argparse
 import concurrent.futures
 import subprocess
@@ -11,19 +21,13 @@
 
 
 def parse_args():
-    parser = argparse.ArgumentParser(description='Outputs a list of FDR q values that yeild clusters', formatter_class=SuppressMetavar)
+    parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
     q_values_default = [0.00001, 0.00005, 0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.15, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95, 0.99, 0.999, 0.9999]
     parser.add_argument('-i', '--input', help='path/p_value_map.nii.gz', required=True, action=SM)
     parser.add_argument('-mas', '--mask', help='path/mask.nii.gz', required=True, action=SM)
     parser.add_argument('-q', '--q_values', help='Space-separated list of q values. If omitted, a default list is used.', nargs='*', default=q_values_default, type=float, action=SM)
     parser.add_argument('-th', '--threads', help='Number of threads. Default: 22', default=22, type=int, action=SM)
-    parser.epilog = """
-Usage: fdr_range.py -i path/vox_p_tstat1.nii.gz -mas path/mask.nii.gz -q 0.05 0.01 0.001
-
-Inputs: 
-    - p value map (e.g., *vox_p_*stat*.nii.gz from vstats.py)    
-
-"""
+    parser.epilog = __doc__
     return parser.parse_args()
 
 def smart_float_format(value, max_decimals=9):