nimare.meta.cbma.mkda.MKDAChi2

class MKDAChi2(kernel_transformer=<class 'nimare.meta.kernel.MKDAKernel'>, prior=0.5, fwe_null_method='label-permutation', memory=Memory(location=None), memory_level=0, **kwargs)

Bases: PairwiseCBMAEstimator

Multilevel kernel density analysis- Chi-square analysis.

The MKDA chi-square method was originally introduced in Wager et al.[1].

Changed in version 0.2.1:

• Make prior parameter default to None, which controls if posterior probabilities

  pFgA, pAgF_prior and pFgA_prior are calculated. This is useful because probability maps are difficult to interpret and for speeding up the algorithm.

• Rename consistency to uniformity and specificity to association to match Neurosynth’s terminology

• New parameters: memory and memory_level for memory caching.

Changed in version 0.0.12:

• Use a 4D sparse array for modeled activation maps.

Changed in version 0.0.8:

• [REF] Use saved MA maps, when available.

Parameters:

• kernel_transformer (KernelTransformer, optional) – Kernel with which to convolve coordinates from dataset. Default is MKDAKernel.

• prior (float, default=0.5) – Uniform prior probability of each feature being active in a map in the absence of evidence from the map. Default: 0.5

• memory (instance of joblib.Memory, str, or pathlib.Path) – Used to cache the output of a function. By default, no caching is done. If a str is given, it is the path to the caching directory.

• memory_level (int, default=0) – Rough estimator of the amount of memory used by caching. Higher value means more memory for caching. Zero means no caching.

• **kwargs – Keyword arguments. Arguments for the kernel_transformer can be assigned here, with the prefix ‘kernel__’ in the variable name.

Variables:

• masker (NiftiMasker or similar) – Masker object.

• inputs (dict) – Inputs to the Estimator. For CBMA estimators, there is only one key: coordinates. This is an edited version of the dataset’s coordinates DataFrame.

• null_distributions (dict of numpy.ndarray) –

  Null distributions for any multiple-comparisons correction methods.

  Important

  MKDAChi2 does not retain uncorrected summary-statistic-to-p null distributions, since the summary statistic in this case is the chi-squared value, which has an established null distribution.

  Entries are added to this attribute if and when the corresponding method is applied.

  If correct_fwe_montecarlo() is applied:

  • values_desc-pAgF_level-voxel_corr-fwe_method-montecarlo: The maximum chi-squared value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-pAgFsize_level-cluster_corr-fwe_method-montecarlo: The maximum cluster size value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-pAgFmass_level-cluster_corr-fwe_method-montecarlo: The maximum cluster mass value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-pFgA_level-voxel_corr-fwe_method-montecarlo: The maximum chi-squared value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-pFgAsize_level-cluster_corr-fwe_method-montecarlo: The maximum cluster size value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-pFgAmass_level-cluster_corr-fwe_method-montecarlo: The maximum cluster mass value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

Notes

The MKDA Chi-square algorithm was originally implemented as part of the Neurosynth Python library (https://github.com/neurosynth/neurosynth).

Available correction methods: MKDAChi2.correct_fwe_montecarlo(), MKDAChi2.correct_fdr_indep().

References

[1]

Tor D Wager, Martin Lindquist, and Lauren Kaplan. Meta-analysis of functional neuroimaging data: current and future directions. Social cognitive and affective neuroscience, 2(2):150–158, 2007. URL: https://doi.org/10.1093/scan/nsm015, doi:10.1093/scan/nsm015.

Methods

correct_fdr_indep(result[, alpha])	Perform FDR correction using the Benjamini-Hochberg method.
correct_fwe_montecarlo(result[, ...])	Perform FWE correction using the max-value permutation method.
fit(dataset1, dataset2[, drop_invalid, ...])	Fit Estimator to two collections.
get_params([deep])	Get parameters for this estimator.
load(filename[, compressed])	Load a pickled class instance from file.
save(filename[, compress])	Pickle the class instance to the provided file.
set_params(**params)	Set the parameters of this estimator.

correct_fdr_indep(result, alpha=0.05)

Perform FDR correction using the Benjamini-Hochberg method.

Only call this method from within a Corrector.

Changed in version 0.0.12: Renamed from correct_fdr_bh to correct_fdr_indep.

Parameters:

• result (MetaResult) – Result object from a KDA meta-analysis.

• alpha (float, optional) – Alpha. Default is 0.05.

Returns:

maps – Dictionary of 1D arrays corresponding to masked maps generated by the correction procedure. The following arrays are generated by this method: ‘z_desc-uniformity_level-voxel’ and ‘z_desc-association_level-voxel’.

Return type:

dict

See also

nimare.correct.FDRCorrector

The Corrector from which to call this method.

Examples

>>> meta = MKDAChi2()
>>> result = meta.fit(dset)
>>> corrector = FDRCorrector(method='indep', alpha=0.05)
>>> cresult = corrector.transform(result)

correct_fwe_montecarlo(result, voxel_thresh=0.001, n_iters=1000, n_cores=1)

Perform FWE correction using the max-value permutation method.

Only call this method from within a Corrector.

Changed in version 0.0.13: Change cluster neighborhood from faces+edges to faces, to match Nilearn.

Changed in version 0.0.12: Include cluster level-corrected results in Monte Carlo null method.

Parameters:

• result (MetaResult) – Result object from a KDA meta-analysis.

• voxel_thresh (float, default=0.001) – Voxel-level threshold. Default is 0.001.

• n_iters (int, default=1000) – Number of iterations to build the vFWE null distribution. Default is 1000.

• n_cores (int, default=1) – Number of cores to use for parallelization. If <=0, defaults to using all available cores. Default is 1.

Returns:

maps – Dictionary of 1D arrays corresponding to masked maps generated by the correction procedure. The following arrays are generated by this method:

• p_desc-uniformity_level-voxel: Voxel-level FWE-corrected p-values from the uniformity/forward inference analysis.

• z_desc-uniformity_level-voxel: Voxel-level FWE-corrected z-values from the uniformity/forward inference analysis.

• logp_desc-uniformity_level-voxel: Voxel-level FWE-corrected -log10 p-values from the uniformity/forward inference analysis.

• p_desc-uniformityMass_level-cluster: Cluster-level FWE-corrected p-values from the uniformity/forward inference analysis, using cluster mass.

• z_desc-uniformityMass_level-cluster: Cluster-level FWE-corrected z-values from the uniformity/forward inference analysis, using cluster mass.

• logp_desc-uniformityMass_level-cluster: Cluster-level FWE-corrected -log10 p-values from the uniformity/forward inference analysis, using cluster mass.

• p_desc-uniformitySize_level-cluster: Cluster-level FWE-corrected p-values from the uniformity/forward inference analysis, using cluster size.

• z_desc-uniformitySize_level-cluster: Cluster-level FWE-corrected z-values from the uniformity/forward inference analysis, using cluster size.

• logp_desc-uniformitySize_level-cluster: Cluster-level FWE-corrected -log10 p-values from the uniformity/forward inference analysis, using cluster size.

• p_desc-association_level-voxel: Voxel-level FWE-corrected p-values from the association/reverse inference analysis.

• z_desc-association_level-voxel: Voxel-level FWE-corrected z-values from the association/reverse inference analysis.

• logp_desc-association_level-voxel: Voxel-level FWE-corrected -log10 p-values from the association/reverse inference analysis.

• p_desc-associationMass_level-cluster: Cluster-level FWE-corrected p-values from the association/reverse inference analysis, using cluster mass.

• z_desc-associationMass_level-cluster: Cluster-level FWE-corrected z-values from the association/reverse inference analysis, using cluster mass.

• logp_desc-associationMass_level-cluster: Cluster-level FWE-corrected -log10 p-values from the association/reverse inference analysis, using cluster mass.

• p_desc-associationSize_level-cluster: Cluster-level FWE-corrected p-values from the association/reverse inference analysis, using cluster size.

• z_desc-associationSize_level-cluster: Cluster-level FWE-corrected z-values from the association/reverse inference analysis, using cluster size.

• logp_desc-associationSize_level-cluster: Cluster-level FWE-corrected -log10 p-values from the association/reverse inference analysis, using cluster size.

Return type:

dict

Notes

This method adds six new keys to the null_distributions_ attribute:

• values_desc-pAgF_level-voxel_corr-fwe_method-montecarlo: The maximum chi-squared value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

• values_desc-pAgFsize_level-cluster_corr-fwe_method-montecarlo: The maximum cluster size value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

• values_desc-pAgFmass_level-cluster_corr-fwe_method-montecarlo: The maximum cluster mass value from the p(A|F) one-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

• values_desc-pFgA_level-voxel_corr-fwe_method-montecarlo: The maximum chi-squared value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

• values_desc-pFgAsize_level-cluster_corr-fwe_method-montecarlo: The maximum cluster size value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

• values_desc-pFgAmass_level-cluster_corr-fwe_method-montecarlo: The maximum cluster mass value from the p(F|A) two-way chi-squared test from each Monte Carlo iteration. An array of shape (n_iters,).

See also

nimare.correct.FWECorrector

The Corrector from which to call this method.

Examples

>>> meta = MKDAChi2()
>>> result = meta.fit(dset)
>>> corrector = FWECorrector(method='montecarlo', n_iters=5, n_cores=1)
>>> cresult = corrector.transform(result)

fit(dataset1, dataset2, drop_invalid=True, ma_maps1=None, ma_maps2=None, inference_map1=None, inference_map2=None)

Fit Estimator to two collections.

Parameters:

• dataset1/dataset2 (Studyset or Dataset) – Collection objects to analyze.

• ma_maps1/ma_maps2 (scipy sparse matrix or sparse array, optional) – Precomputed study-wise MA maps aligned to dataset1 and dataset2, respectively. When provided, the estimator will reuse these maps instead of recomputing them from coordinates. These are typically 2D study-by-masked-voxel sparse matrices.

• inference_map1/inference_map2 (array_like or Niimg-like, optional) – Optional directional inference maps aligned to the common masked voxel space. Positive pairwise effects are only evaluated where inference_map1 > 0, and negative pairwise effects are only evaluated where inference_map2 > 0.

Returns:

• MetaResult – Results of Estimator fitting.

• .. warning:: – Support for Dataset inputs is deprecated and will be removed in a future release. Prefer Studyset.

• The fit method is a light wrapper that runs input validation and

• preprocessing before fitting the actual model. Estimators’ individual

• ”fitting” methods are implemented as _fit, although users should

• call fit.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

classmethod load(filename, compressed=True)

Load a pickled class instance from file.

Parameters:

• filename (str) – Name of file containing object.

• compressed (bool, default=True) – If True, the file is assumed to be compressed and gzip will be used to load it. Otherwise, it will assume that the file is not compressed. Default = True.

Returns:

obj – Loaded class object.

Return type:

class object

save(filename, compress=True)

Pickle the class instance to the provided file.

Parameters:

• filename (str) – File to which object will be saved.

• compress (bool, optional) – If True, the file will be compressed with gzip. Otherwise, the uncompressed version will be saved. Default = True.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Return type:

self