nimare.meta.cbma.ale.ALE

class ALE(kernel_transformer=<class 'nimare.meta.kernel.ALEKernel'>, null_method='approximate', n_iters=10000, n_cores=1, **kwargs)[source]

Bases: nimare.meta.cbma.base.CBMAEstimator

Activation likelihood estimation.

Parameters

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

  • null_method ({“approximate”, “montecarlo”}, optional) – Method by which to determine uncorrected p-values. “approximate” is faster, but slightly less accurate. “montecarlo” can be much slower, and is only slightly more accurate.

  • n_iters (int, optional) – Number of iterations to use to define the null distribution. This is only used if null_method=="montecarlo". Default is 10000.

  • n_cores (int, optional) – Number of cores to use for parallelization. This is only used if null_method=="montecarlo". If <=0, defaults to using all available cores. Default is 1.

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

Variables

  • ~ALE.masker –

  • ~ALE.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.

  • ~ALE.null_distributions_ (dict or numpy.ndarray) – Null distributions for ALE and any multiple-comparisons correction methods. Entries are added to this attribute if and when the corresponding method is fit.

Notes

The ALE algorithm was originally developed in [1]_, then updated in [2]_ and [3]_.

The ALE algorithm is also implemented as part of the GingerALE app provided by the BrainMap organization (https://www.brainmap.org/ale/).

Available correction methods: ALE.correct_fwe_montecarlo()

References

1

Turkeltaub, Peter E., et al. “Meta-analysis of the functional neuroanatomy of single-word reading: method and validation.” Neuroimage 16.3 (2002): 765-780.

2

Turkeltaub, Peter E., et al. “Minimizing within‐experiment and within‐group effects in activation likelihood estimation meta‐analyses.” Human brain mapping 33.1 (2012): 1-13.

3

Eickhoff, Simon B., et al. “Activation likelihood estimation meta-analysis revisited.” Neuroimage 59.3 (2012): 2349-2361.

compute_summarystat(data)[source]

Compute summary statistics from data.

The actual summary statistic varies across Estimators. For ALE and SCALE, the values are known as ALE values. For (M)KDA, they are “OF” scores.

Parameters

data (array, pandas.DataFrame, or list of img_like) – Data from which to estimate summary statistics. The data can be: (1) a 1d contrast-len or 2d contrast-by-voxel array of MA values, (2) a DataFrame containing coordinates to produce MA values, or (3) a list of imgs containing MA values.

Returns

stat_values (1d array) – Summary statistic values. One value per voxel.

correct_fwe_montecarlo(result, voxel_thresh=0.001, n_iters=10000, n_cores=1, vfwe_only=False)[source]

Perform FWE correction using the max-value permutation method.

Only call this method from within a Corrector.

Changed in version 0.0.11:

  • Rename *_level-cluster maps to *_desc-size_level-cluster.

  • Add new *_desc-mass_level-cluster maps that use cluster mass-based inference.

Parameters

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

  • voxel_thresh (float, optional) – Cluster-defining p-value threshold. Default is 0.001.

  • n_iters (int, optional) – Number of iterations to build the voxel-level, cluster-size, and cluster-mass FWE null distributions. Default is 10000.

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

  • vfwe_only (bool, optional) – If True, only calculate the voxel-level FWE-corrected maps. Voxel-level correction can be performed very quickly if the Estimator’s null_method was “montecarlo”. If this is set to True and the original null method was not montecarlo, an exception will be raised. Default is False.

Returns

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

  • logp_desc-size_level-cluster: Cluster-level FWE-corrected -log10(p) map based on cluster size. This was previously simply called “logp_level-cluster”. This array is not generated if vfwe_only is True.

  • logp_desc-mass_level-cluster: Cluster-level FWE-corrected -log10(p) map based on cluster mass. According to [1]_ and [2]_, cluster mass-based inference is more powerful than cluster size. This array is not generated if vfwe_only is True.

  • logp_level-voxel: Voxel-level FWE-corrected -log10(p) map. Voxel-level correction is generally more conservative than cluster-level correction, so it is only recommended for very large meta-analyses (i.e., hundreds of studies), per [3]_.

Notes

If vfwe_only is False, this method adds three new keys to the null_distributions_ attribute:

  • values_level-voxel_corr-fwe_method-montecarlo: The maximum summary statistic value from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-size_level-cluster_corr-fwe_method-montecarlo: The maximum cluster size from each Monte Carlo iteration. An array of shape (n_iters,).

  • values_desc-mass_level-cluster_corr-fwe_method-montecarlo: The maximum cluster mass from each Monte Carlo iteration. An array of shape (n_iters,).

See also

nimare.correct.FWECorrector

The Corrector from which to call this method.

References

1

Bullmore, E. T., Suckling, J., Overmeyer, S., Rabe-Hesketh, S., Taylor, E., & Brammer, M. J. (1999). Global, voxel, and cluster tests, by theory and permutation, for a difference between two groups of structural MR images of the brain. IEEE transactions on medical imaging, 18(1), 32-42. doi: 10.1109/42.750253

2

Zhang, H., Nichols, T. E., & Johnson, T. D. (2009). Cluster mass inference via random field theory. Neuroimage, 44(1), 51-61. doi: 10.1016/j.neuroimage.2008.08.017

3

Eickhoff, S. B., Nichols, T. E., Laird, A. R., Hoffstaedter, F., Amunts, K., Fox, P. T., … & Eickhoff, C. R. (2016). Behavior, sensitivity, and power of activation likelihood estimation characterized by massive empirical simulation. Neuroimage, 137, 70-85. doi: 10.1016/j.neuroimage.2016.04.072

Examples

>>> meta = MKDADensity()
>>> result = meta.fit(dset)
>>> corrector = FWECorrector(method='montecarlo', voxel_thresh=0.01,
                             n_iters=5, n_cores=1)
>>> cresult = corrector.transform(result)
fit(dataset, drop_invalid=True)[source]

Fit Estimator to Dataset.

Parameters

  • dataset (Dataset) – Dataset object to analyze.

  • drop_invalid (bool, optional) – Whether to automatically ignore any studies without the required data or not. Default is False.

Returns

MetaResult – Results of Estimator fitting.

Variables

~Estimator.fit.inputs_ (dict) – Inputs used in _fit.

Notes

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)[source]

Get parameters for this estimator.

Parameters

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

Returns

params (dict) – Parameter names mapped to their values.

classmethod load(filename, compressed=True)[source]

Load a pickled class instance from file.

Parameters

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

  • compressed (bool, optional) – 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 (class object) – Loaded class object.

save(filename, compress=True)[source]

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)[source]

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.

Returns

self