nispace.helpers.get_binary_cluster_map

nispace.helpers.get_binary_cluster_map(corrected_result, cluster_stat='size', alpha=0.05, map_key=None)[source]

Extract a binary (0/1) cluster mask from a NiMARE FWE-corrected MetaResult.

NiMARE’s cluster-corrected logp maps (e.g. logp_desc-size_level-cluster_corr-FWE_method-montecarlo) store a cluster-level -log10(p_FWE) value at every voxel that survived the voxel-level CDT, including non-significant clusters. Voxels in non-significant clusters have 0 < logp < -log10(alpha). This function binarizes correctly by thresholding at logp >= -log10(alpha).

Pass the returned image as y= to NiSpace and use null_maps_from_nimare() with the same corrected_result, cluster_stat, and alpha to generate matching binary null maps for permutation testing.

Parameters:

  • corrected_result (nimare.results.MetaResult) – Result of FWECorrector.transform(result).

  • cluster_stat ({"size", "mass"}, optional) – Which cluster-corrected map to binarize. "size" (default) uses logp_desc-size_level-cluster_corr-*; "mass" uses logp_desc-mass_level-cluster_corr-*. Must match the cluster_stat passed to null_maps_from_nimare().

  • alpha (float, optional) – FWE significance threshold. Voxels with logp >= -log10(alpha) are kept. Default: 0.05. Must match the alpha passed to null_maps_from_nimare().

  • map_key (str or None, optional) – Override: explicit key in corrected_result.maps to binarize, bypassing the cluster_stat search. Pass when NiMARE uses a non-standard naming scheme.

Returns:

Binary NIfTI image (float32, values 0 or 1) in NiMARE’s native space (MNI152NLin6Asym at 2 mm).

Return type:

nibabel.Nifti1Image

Examples

>>> fwe = FWECorrector(method="montecarlo", voxel_thresh=0.001, n_iters=1000)
>>> corrected = fwe.transform(result)
>>> binary_img = get_binary_cluster_map(corrected, alpha=0.05)
>>> nsp = NiSpace(x=ref_maps, y=binary_img, y_labels=["pain_cluster"],
...               parcellation="Schaefer200")
>>> nsp.fit(); nsp.colocalize()
>>> null_maps = null_maps_from_nimare(
...     result, "Schaefer200", corrector=fwe, alpha=0.05,
...     map_label="pain_cluster", observed_map=binary_img,
... )
>>> nsp.permute("maps", maps_which="Y", maps_nulls=null_maps)