nispace.helpers.nimare_fwe_thresholds

nispace.helpers.nimare_fwe_thresholds(corrected_result, alpha=0.05, cluster_stat='size', voxel_thresh=0.001)[source]

Extract voxel z-threshold and cluster extent threshold from a NiMARE FWE-corrected result.

Reads corrected_result.estimator.null_distributions_ (populated during FWECorrector.transform()) to derive the FWE cluster extent threshold. The voxel-level CDT z-score is derived from voxel_thresh directly — NiMARE’s FWECorrector silently ignores any voxel_thresh passed to its constructor, so it must be provided explicitly here.

Parameters:

  • corrected_result (nimare.results.MetaResult) – The corrected MetaResult returned by FWECorrector.transform(result). The cluster-size null distributions are stored on its estimator (corrected_result.estimator.null_distributions_). Only method="montecarlo" is supported.

  • alpha (float, optional) – FWE significance level used to derive the cluster extent threshold from the null distribution. Default: 0.05.

  • cluster_stat ({"size", "mass"}, optional) – Which cluster-level null distribution to read. "size" (default) uses the max-cluster-voxel-count distribution; "mass" uses the max-cluster-z-sum distribution. Must match the statistic used to produce the observed cluster image. Default: "size".

  • voxel_thresh (float, optional) – Uncorrected voxel-level p-value for the cluster-defining threshold (CDT). Must match the threshold actually used during FWE correction. NiMARE’s default (and the default here) is 0.001 (z ≈ 3.09).

Returns:

  • voxel_thresh_z (float) – Z-score corresponding to voxel_thresh (scipy.stats.norm.isf(voxel_thresh)). E.g. voxel_thresh=0.001 → z ≈ 3.09.

  • min_cluster_extent (int or float or None) – FWE cluster extent threshold: the (1 - alpha) percentile of the max-cluster-stat null distribution. Voxel count (int) for cluster_stat="size"; z-score sum (float) for cluster_stat="mass". None if the relevant distribution is not found in corrected_result.estimator.null_distributions_.

Examples

>>> fwe = FWECorrector(method="montecarlo", n_iters=1000)
>>> corrected = fwe.transform(result)
>>> z_thresh, min_ext = nimare_fwe_thresholds(corrected, cluster_stat="size", voxel_thresh=0.001)
>>> binary_img = get_binary_cluster_map(corrected, cluster_stat="size")
>>> null_maps = null_maps_from_nimare(result, nsp._parc,
...                                   corrected_result=corrected, voxel_thresh=0.001)