nimare.meta.cbma.ale.ALESubtraction

class ALESubtraction(kernel_transformer=<class 'nimare.meta.kernel.ALEKernel'>, n_iters=5000, memory=Memory(location=None), memory_level=0, n_cores=1, **kwargs)

Bases: PairwiseCBMAEstimator

ALE subtraction analysis.

Changed in version 0.2.1:

• New parameters: memory and memory_level for memory caching.

Changed in version 0.0.12:

• Use memmapped array for null distribution and remove memory_limit parameter.

• Support parallelization and add progress bar.

• Add ALE-difference (stat) and -log10(p) (logp) maps to results.

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

Changed in version 0.0.8:

• [FIX] Assume non-symmetric null distribution.

Changed in version 0.0.7:

• [FIX] Assume a zero-centered and symmetric null distribution.

Parameters:

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

• n_iters (int, default=5000) – Default is 5000.

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

• n_cores (int, default=1) –

  Number of processes to use for meta-analysis. If -1, use all available cores. Default is 1.

  New in version 0.0.12.

• **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:

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

Notes

This method was originally developed in Laird et al.[1] and refined in Eickhoff et al.[2].

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

The voxel-wise null distributions used by this Estimator are very large, so they are not retained as Estimator attributes.

Warning

This implementation contains one key difference from the original version.

In the original version, group 1 > group 2 difference values are only evaluated for voxels significant in the group 1 meta-analysis, and group 2 > group 1 difference values are only evaluated for voxels significant in the group 2 meta-analysis.

In NiMARE’s implementation, the analysis is run in a two-sided manner for all voxels in the mask.

References

[1]

Angela R Laird, P Mickle Fox, Cathy J Price, David C Glahn, Angela M Uecker, Jack L Lancaster, Peter E Turkeltaub, Peter Kochunov, and Peter T Fox. Ale meta-analysis: controlling the false discovery rate and performing statistical contrasts. Human brain mapping, 25(1):155–164, 2005. URL: https://doi.org/10.1002/hbm.20136, doi:10.1002/hbm.20136.

[2]

Simon B Eickhoff, Danilo Bzdok, Angela R Laird, Florian Kurth, and Peter T Fox. Activation likelihood estimation meta-analysis revisited. Neuroimage, 59(3):2349–2361, 2012. URL: https://doi.org/10.1016/j.neuroimage.2011.09.017, doi:10.1016/j.neuroimage.2011.09.017.

Methods

correct_fwe_montecarlo()	Perform Monte Carlo-based FWE correction.
fit(dataset1, dataset2[, drop_invalid])	Fit Estimator to two Datasets.
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_fwe_montecarlo()

Perform Monte Carlo-based FWE correction.

Warning

This method is not implemented for this class.

fit(dataset1, dataset2, drop_invalid=True)

Fit Estimator to two Datasets.

Parameters:

dataset1/dataset2 (Dataset) – Dataset objects to analyze.

Returns:

Results of Estimator fitting.

Return type:

MetaResult

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)

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