unravel.cluster_stats.validation module#

Use cstats_validation (cv) from UNRAVEL to warp a cluster index from atlas space to tissue space, crop clusters, apply a segmentation mask, and quantify validation metrics (e.g., cell density, label density, and mean intensity) in each cluster (and optionally in atlas subregions within each cluster).

Prereqs:

  • Create cluster maps using clusters or cstats_fdr (note, the cluster index is reversed so that the largest cluster is 1)

  • Optional: cstats_fdr_range to determine the q value thresholds yielding significant clusters

  • cstats_mirror_indices to recursively mirror the cluster indices to the other hemisphere (if bilateral data was combined and processed w/ a hemispheric mask).

  • seg_ilastik to generate a segmentation mask in tissue space (e.g., to label c-Fos+ cells)

Inputs:

  • path/rev_cluster_index.nii.gz to warp from atlas space (rev = reverse, i.e., cluster IDs are from large to small)

  • rel_path/seg_img.nii.gz. 1st glob match processed

Outputs:

  • ./sample??/clusters/<cluster_index_dir>/outer_bounds.txt

  • ./sample??/clusters/<cluster_index_dir>/<args.metric>_data.csv

  • cluster_index_dir = Path(args.moving_img).name w/o “_rev_cluster_index” and “.nii.gz”

Note

  • For -s, if a dir name is provided, the command will load ./sample??/seg_dir/sample??_seg_dir.nii.gz.

  • If a relative path is provided, the command will load the image at the specified path.

Next steps:

  • cstats_summary_config: Copy the cluster_summary.ini file to the current working directory for editing and use with cstats_summary.

  • cstats_summary: Aggregate and analyze cluster validation data from cstats_validation.

Usage:#

cstats_validation -m <path/rev_cluster_index_to_warp_from_atlas_space.nii.gz> -s <rel_path/seg_img.nii.gz> [-me cell_density | label_density | mean_in_cluster | mean_in_seg_in_cluster] [-o <rel_path/output.csv>] [-c all or list of clusters (e.g., 1 3 4)] [-n <rel_path/native_image.zarr or .nii.gz>] [-fri <fixed_reg_input_for_reg>] [-inp nearestNeighbor or multiLabel] [-ro <reg_outputs_dir>] [-r <reg_res_in_microns>] [-md <metadata.txt>] [-zo <zoom_order>] [-pad <pad_percent_from_reg>] [-at <rel_path/native_atlas_in_tissue_space.nii.gz>] [-csv CCFv3-2020_info.csv] [-cc <connected_component_connectivity>] [-mi] [-d list of paths] [-p sample??] [-v]

unravel.cluster_stats.validation.parse_args()[source]#
unravel.cluster_stats.validation.crop_outer_space(native_cluster_index, output_path)[source]#

Crop outer space around all clusters and save bounding box to .txt file (outer_bounds.txt) Return cropped native_cluster_index, outer_xmin, outer_xmax, outer_ymin, outer_ymax, outer_zmin, outer_zmax

unravel.cluster_stats.validation.cluster_bbox(cluster_ID, native_cluster_index_cropped)[source]#

Get bounding box for the current cluster. Return cluster_ID, xmin, xmax, ymin, ymax, zmin, zmax.

unravel.cluster_stats.validation.cluster_bbox_parallel(native_cluster_index_cropped, clusters)[source]#

Get bounding boxes for each cluster in parallel. Return list of results.

unravel.cluster_stats.validation.count_cells(seg_in_cluster, connectivity=6)[source]#

Count cells (objects) in each cluster using connected-components-3d Return the number of cells in the cluster.

unravel.cluster_stats.validation.load_ccfv3_lookup(info_csv_path, region_id_col='lowered_ID')[source]#

Load region lookup from a built-in or user-provided CCFv3 info CSV.

Parameters:

  • info_csv_path (str or Path) – Path to a custom info CSV, or one of the built-in names: CCFv3-2017_info.csv or CCFv3-2020_info.csv.

  • region_id_col (str, optional) – Column to use as the region-ID key. Default: lowered_ID. Common options include lowered_ID and structure_ID.

Returns:

Mapping from region ID to a dictionary with abbreviation and region_name values.

Return type:

dict

unravel.cluster_stats.validation.metric_in_cluster(cluster_data, native_cluster_index_cropped, seg_cropped, xy_res, z_res, connectivity=6, metric='cell_density', intensity_cropped=None)[source]#

Measure a validation metric in the current cluster.

Supported metrics:

  • cell_density

  • label_density

  • mean_in_cluster

  • mean_in_seg_in_cluster

Returns:

cluster_ID, primary_value, cluster_volume_in_cubic_mm, metric_value, xmin, xmax, ymin, ymax, zmin, zmax

unravel.cluster_stats.validation.metric_in_cluster_parallel(cluster_bbox_results, native_cluster_index_cropped, seg_cropped, xy_res, z_res, connectivity=6, metric='cell_density', intensity_cropped=None)[source]#

Measure a validation metric in each cluster in parallel. Return list of results.

unravel.cluster_stats.validation.metric_in_subregions_of_cluster(cluster_data, native_cluster_index_cropped, atlas_cropped, seg_cropped, xy_res, z_res, connectivity=6, metric='cell_density', intensity_cropped=None, region_lookup=None)[source]#

Measure a metric in each atlas subregion within the current cluster.

Returns:

list of dicts, one row per (cluster_ID, region_ID)

unravel.cluster_stats.validation.metric_in_subregions_of_cluster_parallel(cluster_bbox_results, native_cluster_index_cropped, atlas_cropped, seg_cropped, xy_res, z_res, connectivity=6, metric='cell_density', intensity_cropped=None, region_lookup=None)[source]#

Measure a metric in atlas subregions within each cluster, in parallel.

unravel.cluster_stats.validation.main()[source]#