Updated docstring/help

unravel/cluster_stats/group_bilateral_data.py

@@ -1,12 +1,13 @@
 #!/usr/bin/env python3
 
 """
-Organize bilateral csv outputs from validate_clusters.py
+Use ``cluster_group_data`` from UNRAVEL to organize bilateral csv outputs from ``cluster_validation``
 
-Run this script in the target_dir from org_data.py
+Run this script in the target_dir from ``cluster_org_data``
         
-Usage:
-    group_bilateral_data.py
+Usage
+-----
+    cluster_group_data
 
 It consolidates CSV files into pooled directories based on hemisphere.
 

unravel/cluster_stats/index.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python3
 
 """
-Create a cluster index with valid clusters from a given NIfTI image.
+Use ``cluster_index`` from UNRAVEL to create a cluster index with valid clusters from a given NIfTI image.
 
-Usage:
-    index.py -ci path/rev_cluster_index.nii.gz -a path/atlas.nii.gz -ids 1 2 3
+Usage
+-----
+    cluster_index -ci path/rev_cluster_index.nii.gz -a path/atlas.nii.gz -ids 1 2 3
     
 Outputs:
     - path/valid_clusters/rev_cluster_index_valid_clusters.nii.gz
-    - path/valid_clusters/cluster_*_sunburst.csv
+    - path/valid_clusters/cluster_<asterisk>_sunburst.csv
 """
 
 from pathlib import Path

unravel/cluster_stats/legend.py

@@ -1,16 +1,14 @@
 #!/usr/bin/env python3
 
 """
-Summarize volumes of the top x regions and collapsing them into parent regions until a criterion is met.
+Use ``cluster_legend`` from UNRAVEL to summarize regional abbreviations from <asterisk>_valid_clusters_table.xlsx files.
 
 Usage:
+------
     legend.py
 
-Prereqs:
-    valid_cluster_table.sh has been run and the resulting .xlsx files are in the working directory.
-
 Inputs:
-    <asterisk>_valid_clusters_table.xlsx files in the working directory
+    <asterisk>_valid_clusters_table.xlsx files in the working directory output from ``cluster_table``
 
 Outputs:
     legend.xlsx

unravel/cluster_stats/org_data.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 
 """
-Aggregates csv outputs from validate_clusters.py
+Use ``cluster_org_data`` from UNRAVEL to aggregate and organize csv outputs from ``cluster_validation``.
 
-Usage:
-    org_data.py -e <list of experiment directories> -cvd '*' -td <target_dir> -vd <path/vstats_dir> -v
+Usage
+-----
+    cluster_org_data -e <list of experiment directories> -cvd '<asterisk>' -td <target_dir> -vd <path/vstats_dir> -v
 """
 
 import argparse

unravel/cluster_stats/prism.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 
 """
-Organize cell_count|label_volume, cluster_volume, and <cell|label>_density data from cluster and sample and save as csv
+Use ``cluster_prism`` from UNRAVEL to organize cell_count|label_volume, cluster_volume, and <cell|label>_density data from cluster and sample and save as csv for plotting in Prism.
 
-Usage:
-    prism.py -ids 1 2 3
+Usage
+-----
+    cluster_prism -ids 1 2 3
         
 Inputs:
     <asterisk>.csv from cluster_org_data (in working dir)

unravel/cluster_stats/recursively_mirror_rev_cluster_indices.py

@@ -1,12 +1,13 @@
 #!/usr/bin/env python3
 
 """
-Recursively process img.nii.gz files, apply mirroring, and save new files.
+Use ``cluster_mirror_indices`` from UNRAVEL to recursively process img.nii.gz files, apply mirroring, and save new files.
 
-Usage:
-    recursively_mirror_rev_cluster_indices.py -m RH -v
+Usage
+-----
+    cluster_mirror_indices -m RH -v
     
-Use this script after fdr.py to mirror the cluster indices for the other side of the brain before running validate_clusters.py    
+Use this script after ``cluster_fdr`` to mirror the cluster indices for the other side of the brain before running ``cluster_validation``.  
 """
 
 import argparse

unravel/cluster_stats/stats.py

@@ -1,19 +1,21 @@
 #!/usr/bin/env python3
 
 """
-Validate clusters based on differences in cell/object or label density w/ t-tests.    
+Use ``cluster_stats`` from UNRAVEL to validate clusters based on differences in cell/object or label density w/ t-tests.    
 
-T-test usage:   
-    stats.py --groups <group1> <group2>
+T-test usage:  
+------------- 
+    cluster_stats --groups <group1> <group2>
 
 Tukey's test usage: 
-    stats.py --groups <group1> <group2> <group3> <group4> ...
+-------------------
+    cluster_stats --groups <group1> <group2> <group3> <group4> ...
 
 Input subdirs: 
     <asterisk> 
 
 Input files: 
-    <asterisk>_density_data.csv from validate_clusters.py (e.g., in each subdir named after the rev_cluster_index.nii.gz file)    
+    <asterisk>_density_data.csv from ``cluster_validation`` (e.g., in each subdir named after the rev_cluster_index.nii.gz file)    
 
 CSV naming conventions:
     - Condition: first word before '_' in the file name
@@ -31,15 +33,15 @@
 
 Examples:
     - Grouping data by condition prefixes: 
-        stats.py --groups psilocybin saline --condition_prefixes saline psilocybin
+        ``cluster_stats`` --groups psilocybin saline --condition_prefixes saline psilocybin
         - This will treat all 'psilocybin*' conditions as one group and all 'saline*' conditions as another
         - Since there will then effectively be two conditions in this case, they will be compared using a t-test
 
 Columns in the .csv files:
     sample, cluster_ID, <cell_count|label_volume>, cluster_volume, <cell_density|label_density>, ...
 
 Outputs:
-    - ./cluster_validation_summary.py and ./subdir/cluster_validation_info/
+    - ./_valid_clusters_stats/
 """
 
 import argparse
@@ -63,7 +65,7 @@ def parse_args():
     parser.add_argument('--groups', help='List of group prefixes. 2 groups --> t-test. >2 --> Tukey\'s tests (The first 2 groups reflect the main comparison for validation rates)',  nargs='+', required=True)
     parser.add_argument('-cp', '--condition_prefixes', help='Condition prefixes to group data (e.g., see info for examples)',  nargs='*', default=None, action=SM)
     parser.add_argument('-alt', "--alternate", help="Number of tails and direction ('two-sided' [default], 'less' [group1 < group2], or 'greater')", default='two-sided', action=SM)
-    parser.add_argument('-pvt', '--p_val_txt', help='Name of the file w/ the corrected p value thresh (e.g., from fdr.py). Default: p_value_threshold.txt', default='p_value_threshold.txt', action=SM)
+    parser.add_argument('-pvt', '--p_val_txt', help='Name of the file w/ the corrected p value thresh (e.g., from cluster_fdr). Default: p_value_threshold.txt', default='p_value_threshold.txt', action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False)
     parser.epilog = __doc__
     return parser.parse_args()
@@ -385,7 +387,7 @@ def main():
         with open(valid_cluster_IDs, 'w') as f:
             f.write(significant_cluster_ids_str)
 
-        # Save cluster validation info for valid_clusters_summary.py
+        # Save cluster validation info for ``cluster_summary`` 
         data_df = pd.DataFrame({
             'Direction': [f"{args.groups[0]} {effect_direction} {args.groups[1]}"],
             'FDR q': [fdr_q],

unravel/cluster_stats/stats_table.py

@@ -1,7 +1,11 @@
 #!/usr/bin/env python3
 
 """
-Recursively find and concatenate matching csvs (e.g., to summarize cluster validation info).
+Use stats_table.py from UNRAVEL to recursively find and concatenate matching CSVs (e.g., to summarize cluster validation info).
+
+Usage:
+------
+    stats_table -cp cluster_validation_info.csv -o cluster_validation_summary.csv
 """
 
 import argparse

unravel/cluster_stats/sunburst.py

@@ -1,14 +1,15 @@
 #!/usr/bin/env python3
 
 """
-Generate a sunburst plot of regional volumes that cluster comprise across the ABA hierarchy.
+Use ``cluster_sunburst`` from UNRAVEL to generate a sunburst plot of regional volumes across all levels of the ABA hierarchy.
 
 Usage:
-    sunburst.py -i path/rev_cluster_index.nii.gz -a path/atlas.nii.gz -v
+------ 
+    cluster_sunburst -i path/rev_cluster_index.nii.gz -a path/atlas.nii.gz -v
 
 Prereqs: 
-    - validate_clusters.py generates a rev_cluster_index.nii.gz (clusters of significant voxels) and validates them. 
-    - Optional: valid_cluster_index.py generates a rev_cluster_index.nii.gz w/ valid clusters.
+    - ``cluster_validation`` generates a rev_cluster_index.nii.gz (clusters of significant voxels) and validates them. 
+    - Optional: ``cluster_index`` generates a rev_cluster_index.nii.gz w/ valid clusters.
     
 Outputs:
     path/input_sunburst.csv and [input_path/sunburst_RGBs.csv]

unravel/cluster_stats/table.py

@@ -1,13 +1,14 @@
 #!/usr/bin/env python3
 
 """
-Summarize volumes of the top x regions and collapsing them into parent regions until a criterion is met.
+Use ``cluster_table`` from UNRAVEL to summarize volumes of the top x regions and collapsing them into parent regions until a criterion is met.
 
 Usage:
-    table.py
+------
+    cluster_table
 
 Prereqs:
-    valid_cluster_index.sh has been run. Run this script from the valid_clusters dir. <asterisk>cluster_info.txt in working dir.
+    ``cluster_index`` has been run. Run this script from the valid_clusters dir. <asterisk>cluster_info.txt in working dir.
 
 Sorting by hierarchy and volume:
 --------------------------------
@@ -43,7 +44,7 @@
 
 def parse_args():
     parser = argparse.ArgumentParser(formatter_class=SuppressMetavar)
-    parser.add_argument('-vcd', '--val_clusters_dir', help='Path to the valid_clusters dir output from index.py (else cwd)', action=SM)
+    parser.add_argument('-vcd', '--val_clusters_dir', help='Path to the valid_clusters dir output from unravel.cluster_stats.index (else cwd)', action=SM)
     parser.add_argument('-t', '--top_regions', help='Number of top regions to output. Default: 4', default=4, type=int, action=SM)
     parser.add_argument('-pv', '--percent_vol', help='Percentage of the total volume the top regions must comprise [after collapsing]. Default: 0.8', default=0.8, type=float, action=SM)
     parser.add_argument('-v', '--verbose', help='Increase verbosity. Default: False', action='store_true', default=False)

unravel/cluster_stats/valid_clusters_summary.py

@@ -1,26 +1,28 @@
 #!/usr/bin/env python3
 
 """ 
-Aggregates and analyzes cluster validation data from cluster_validation
+Use ``cluster_summary`` from UNRAVEL to aggregate and analyze cluster validation data from ``cluster_validation``.
 
-Usage if running directly after cluster_validation:
+Usage if running directly after ``cluster_validation``:
+-------------------------------------------------------
     cluster_summary -c <path/config.ini> -e <exp dir paths> -cvd '*' -vd <path/vstats_dir> -sk <path/sample_key.csv> --groups <group1> <group2> -v
 
-Usage if running after cluster_validation and cluster_org_data:
+Usage if running after ``cluster_validation`` and ``cluster_org_data``:
+-----------------------------------------------------------------------
     cluster_summary -c <path/config.ini> -sk <path/sample_key.csv> --groups <group1> <group2> -v
 
 The current working directory should not have other directories when running this script for the first time. Directories from cluster_org_data are ok though.
 
 Runs commands in this order:
-    - cluster_org_data
-    - cluster_group_data
-    - utils_prepend
-    - cluster_stats
-    - cluster_index
-    - cluster_brain_model
-    - cluster_table
-    - cluster_prism
-    - cluster_legend
+    - ``cluster_org_data``
+    - ``cluster_group_data``
+    - ``utils_prepend``
+    - ``cluster_stats``
+    - ``cluster_index``
+    - ``cluster_brain_model``
+    - ``cluster_table``
+    - ``cluster_prism``
+    - ``cluster_legend``
 
 The sample_key.csv file should have the following format:
     dir_name,condition

unravel/cluster_stats/validate_clusters.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 
 """
-Warps cluster index from atlas space to tissue space, crops clusters, applies segmentation mask, and quantifies cell/label densities
+Use ``cluster_validation`` from UNRAVEL to warp a cluster index from atlas space to tissue space, crop clusters, apply a segmentation mask, and quantify cell/label densities.
 
 Usage:
-    validate_clusters.py -e <experiment paths> -m <path/rev_cluster_index_to_warp_from_atlas_space.nii.gz> -s cfos_seg_ilastik_1 -v
+------
+    cluster_validation -e <experiment paths> -m <path/rev_cluster_index_to_warp_from_atlas_space.nii.gz> -s cfos_seg_ilastik_1 -v
 
 cluster_index_dir = Path(args.moving_img).name w/o "_rev_cluster_index" and ".nii.gz"
 
@@ -15,8 +16,8 @@
 For -s, if a dir name is provided, the script will load ./sample??/seg_dir/sample??_seg_dir.nii.gz. 
 If a relative path is provided, the script will load the image at the specified path.
 
-Next script:
-    valid_clusters_summary.py
+Next command:
+    ``cluster_summary``
 """
 
 
@@ -54,9 +55,9 @@ def parse_args():
 
     # Optional to_native() args
     parser.add_argument('-n', '--native_idx', help='Load/save native cluster index from/to rel_path/native_image.zarr (fast) or rel_path/native_image.nii.gz if provided', default=None, action=SM)
-    parser.add_argument('-fri', '--fixed_reg_in', help='Fixed input for registration (reg.py). Default: autofl_50um_masked_fixed_reg_input.nii.gz', default="autofl_50um_masked_fixed_reg_input.nii.gz", action=SM)    
+    parser.add_argument('-fri', '--fixed_reg_in', help='Fixed input for registration (unravel.register.reg). Default: autofl_50um_masked_fixed_reg_input.nii.gz', default="autofl_50um_masked_fixed_reg_input.nii.gz", action=SM)    
     parser.add_argument('-inp', '--interpol', help='Interpolator for ants.apply_transforms (nearestNeighbor [default], multiLabel [slow])', default="nearestNeighbor", action=SM)
-    parser.add_argument('-ro', '--reg_outputs', help="Name of folder w/ outputs from reg.py (e.g., transforms). Default: reg_outputs", default="reg_outputs", action=SM)
+    parser.add_argument('-ro', '--reg_outputs', help="Name of folder w/ outputs from unravel.register.reg (e.g., transforms). Default: reg_outputs", default="reg_outputs", action=SM)
     parser.add_argument('-r', '--reg_res', help='Resolution of registration inputs in microns. Default: 50', default='50',type=int, action=SM)
     parser.add_argument('-md', '--metadata', help='path/metadata.txt. Default: parameters/metadata.txt', default="parameters/metadata.txt", action=SM)
     parser.add_argument('-zo', '--zoom_order', help='SciPy zoom order for scaling to full res. Default: 0 (nearest-neighbor)', default='0',type=int, action=SM)
@@ -71,6 +72,7 @@ def parse_args():
 
 # TODO: QC. Aggregate .csv results for all samples if args.exp_dirs, script to load image subset.
 # TODO: Make config file for defaults or a command_generator.py script
+# TODO: Consider adding an option to quantify mean IF intensity in each cluster in segmented voxels. Also make a script for mean IF intensity in clusters in atlas space. 
 
 @print_func_name_args_times()
 def crop_outer_space(native_cluster_index, output_path):
@@ -243,7 +245,7 @@ def main():
             metadata_path = resolve_path(sample_path, args.metadata)
             xy_res, z_res, _, _, _ = load_image_metadata_from_txt(metadata_path)
             if xy_res is None or z_res is None: 
-                print("    [red bold]./sample??/parameters/metadata.txt missing. cd to sample?? dir and run: metadata.py")
+                print("    [red bold]./sample??/parameters/metadata.txt missing. cd to sample?? dir and run: io_metadata")
 
             # Get bounding boxes for each cluster in parallel
             cluster_bbox_data = cluster_bbox_parallel(native_cluster_index_cropped, clusters)

unravel/docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: bc3038a92de0faa6aa8c52ea42068d9d
+config: 1c245b62cc5739cdba715e510b31e42d
 tags: 645f666f9bcd5a90fca523b33c5a78b7

unravel/docs/_build/html/_modules/index.html

@@ -49,6 +49,21 @@
     <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
     <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
     <script>mermaid.initialize({startOnLoad:true});</script>
+    <script src="https://unpkg.com/d3/dist/d3.min.js"></script>
+    <script>
+            window.addEventListener("load", function () {
+              var svgs = d3.selectAll(".mermaid svg");
+              svgs.each(function() {
+                var svg = d3.select(this);
+                svg.html("<g>" + svg.html() + "</g>");
+                var inner = svg.select("g");
+                var zoom = d3.zoom().on("zoom", function(event) {
+                  inner.attr("transform", event.transform);
+                });
+                svg.call(zoom);
+              });
+            });
+            </script>
     <script>DOCUMENTATION_OPTIONS.pagename = '_modules/index';</script>
     <link rel="icon" href="../_static/favicon.png"/>
     <link rel="index" title="Index" href="../genindex.html" />

unravel/docs/_build/html/_modules/unravel/cluster_stats/brain_model.html

@@ -49,6 +49,21 @@
     <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
     <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
     <script>mermaid.initialize({startOnLoad:true});</script>
+    <script src="https://unpkg.com/d3/dist/d3.min.js"></script>
+    <script>
+            window.addEventListener("load", function () {
+              var svgs = d3.selectAll(".mermaid svg");
+              svgs.each(function() {
+                var svg = d3.select(this);
+                svg.html("<g>" + svg.html() + "</g>");
+                var inner = svg.select("g");
+                var zoom = d3.zoom().on("zoom", function(event) {
+                  inner.attr("transform", event.transform);
+                });
+                svg.call(zoom);
+              });
+            });
+            </script>
     <script>DOCUMENTATION_OPTIONS.pagename = '_modules/unravel/cluster_stats/brain_model';</script>
     <link rel="icon" href="../../../_static/favicon.png"/>
     <link rel="index" title="Index" href="../../../genindex.html" />

unravel/docs/_build/html/_modules/unravel/cluster_stats/crop_clusters.html

@@ -49,6 +49,21 @@
     <script>var togglebuttonSelector = '.toggle, .admonition.dropdown';</script>
     <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
     <script>mermaid.initialize({startOnLoad:true});</script>
+    <script src="https://unpkg.com/d3/dist/d3.min.js"></script>
+    <script>
+            window.addEventListener("load", function () {
+              var svgs = d3.selectAll(".mermaid svg");
+              svgs.each(function() {
+                var svg = d3.select(this);
+                svg.html("<g>" + svg.html() + "</g>");
+                var inner = svg.select("g");
+                var zoom = d3.zoom().on("zoom", function(event) {
+                  inner.attr("transform", event.transform);
+                });
+                svg.call(zoom);
+              });
+            });
+            </script>
     <script>DOCUMENTATION_OPTIONS.pagename = '_modules/unravel/cluster_stats/crop_clusters';</script>
     <link rel="icon" href="../../../_static/favicon.png"/>
     <link rel="index" title="Index" href="../../../genindex.html" />