unravel.cluster_stats.fdr module#

Use cstats_fdr (f) from UNRAVEL to perform FDR correction on a 1 - p value map to define clusters.

Inputs:

  • p value map (e.g., *`vox_p_`*`stat`*.nii.gz from vstats)

Outputs saved in the output directory:

  • FDR-adjusted 1-p value map (1 - q value defines the threshold for cluster maps)

  • Cluster information CSV

  • Reversed cluster index image (output_dir/input_name_rev_cluster_index.nii.gz)

  • min_cluster_size_in_voxels.txt

  • p_value_threshold.txt

  • 1-p_value_threshold.txt

Note

  • The q value does not influence the FDR-adjusted 1-p value map, but it does determine the threshold for cluster maps.

  • Cluster IDs are reversed in the cluster index image so that the largest cluster is 1, the second largest is 2, etc.

  • For bilateral data processed with a hemispheric mask, next run cstats_mirror_indices to mirror the cluster indices to the other hemisphere.

  • For unilateral data or bilateral data processed with a whole brain mask, the cluster indices are ready for validation with cstats_validation.

Making directional cluster indices from non-directional p value maps output from ANOVAs:

  • Provide the average immunostaining intensity images for each group being contrasted (img_avg)

  • The –output needs to have <group1>_v_<group2> in the name

  • _v_ will be replaced with _gt_ or _lt_ based on the effect direction

  • The cluster index will be split accoding to the effect directions

  • cstats_fdr -i vox_p_fstat1.nii.gz -mas mask.nii.gz -q 0.05 -a1 group1_avg.nii.gz -a2 group2_avg.nii.gz -o stats_info_g1_v_g2 -v

Next commands:

  • cstats_mirror_indices to mirror the cluster indices to the other hemisphere (if bilateral data processed with a hemispheric mask).

  • cstats_validation to validate the cluster indices (if unilateral data or bilateral data processed with a whole brain mask).

Usage#

cstats_fdr -i path/vox_p_tstat1.nii.gz -mas path/mask.nii.gz -q 0.05 0.01 0.001 [-ms 100] [-o output_dir] [-a1 path/avg_img1.nii.gz] [-a2 path/avg_img2.nii.gz] [-th 10] [-v]

unravel.cluster_stats.fdr.parse_args()[source]#
unravel.cluster_stats.fdr.fdr(input_path, fdr_path, mask_path, q_value)[source]#

Perform FDR correction on the input p value map using a mask.

Parameters:

  • input_path (-) – the path to the p value map

  • fdr_path (-) – the path to the output directory

  • mask_path (-) – the path to the mask

  • q_value (-) – the q value for FDR correction

Saves in the fdr_path:

  • FDR-adjusted 1-p value map (1 - q value defines the threshold)

Returns:

the path to the FDR-adjusted p value map - probability_threshold (float): the probability threshold for the FDR correction

Return type:

  • adjusted_pval_output_path (str)

unravel.cluster_stats.fdr.cluster_index(adj_p_val_img_path, min_size, threshold, output_index)[source]#
unravel.cluster_stats.fdr.reverse_clusters(cluster_index_img, output, data_type, cluster_index_nii)[source]#

Reverse the cluster IDs in a cluster index image (ndarray). Return the reversed cluster index ndarray.

unravel.cluster_stats.fdr.split_clusters_based_on_effect(rev_cluster_index_img, avg_img1, avg_img2, output, max_cluster_id, data_type, cluster_index_nii)[source]#
unravel.cluster_stats.fdr.process_fdr_and_clusters(input, mask, q, min_size, avg_img1, avg_img2, output=None)[source]#

Process FDR correction and cluster index generation for a given q value.

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