nimare.meta.ibma.PermutedOLS

class PermutedOLS(two_sided=True, use_sample_size=False, n_jobs=1, random_state=42, **kwargs)

Bases: IBMAEstimator

An analysis with permuted ordinary least squares (OLS).

Changed in version 0.21.0:

• New parameters: groupby and use_sample_size.

• The statistic is computed over one contribution per group, referred to Satterthwaite degrees of freedom rather than a count of images.

• Nilearn’s permuted_ols() is no longer called, so exchangeability blocks work on every supported Nilearn version. The t map is unchanged.

Changed in version 0.2.1:

• New parameter: aggressive_mask, to control whether to use an aggressive mask.

Changed in version 0.0.12:

• Use beta maps instead of z maps.

Changed in version 0.0.8:

• [FIX] Remove single-dimensional entries of each array of returns (dict).

Added in version 0.0.4.

This approach is described in Freedman and Lane[1].

Parameters:

• aggressive_mask (bool, optional) – Voxels with a value of zero of NaN in any of the input maps will be removed from the analysis. If False, all voxels are included by running a separate analysis on bags of voxels that belong that have a valid value across the same studies. Default is False.

• groupby (None, str, array-like, or False, optional) – How to identify images that share participants and are therefore dependent. None (the default) groups by study_id. A str names a metadata field to group by instead, for a paper contributing independent samples (e.g. patients and controls). An array supplies one label per image. False treats every image as independent, which inflates significance whenever that is untrue. Default is None.

• use_sample_size (bool, optional) – Whether to weight each group’s contribution by its sample size. When False (the default), every group is weighted equally and the statistic is the ordinary one-sample t over group means. Default is False.

• two_sided (bool, optional) – If True, performs an unsigned t-test. Both positive and negative effects are considered; the null hypothesis is that the effect is zero. If False, only positive effects are considered as relevant. The null hypothesis is that the effect is zero or negative. Default is True.

• random_state (int or None, optional) – Seed for the sign-flip null. Default is 42.

Notes

Requires beta images, and sample_sizes metadata when use_sample_size=True.

Each group contributes the mean of its available images, so a study that uploaded fifty maps carries the same weight as one that uploaded a single map. Groups are sign-flipped as whole exchangeability blocks [2]. Equal weights reduce the statistic to the ordinary one-sample t over group means; sample-size weights make it the intercept-only CR2 statistic of Hedges et al.[3], referred to Satterthwaite degrees of freedom [4].

fit() produces a MetaResult object with the following maps:

“t”	T-statistic map from one-sample test.
“z”	Z-statistic map from one-sample test.
“dof”	Degrees of freedom map from one-sample test.

Available correction methods: PermutedOLS.correct_fwe_montecarlo()

Warning

With use_sample_size=True the degrees of freedom are Satterthwaite rather than a group count, and one dominant study can drag them well below it. PyMARE warns below about 4 [4].

By default, image-based meta-analysis estimators run the analysis in bags of voxels, where each bag holds the voxels that have a valid value across the same studies. A voxel is therefore only dropped from the studies that are missing it. Setting aggressive_mask=True instead removes any voxel with a value of zero or NaN in any input map from the analysis entirely. Either way, a bag whose valid images all belong to one group is skipped – one group cannot support the inference – and its voxels come back as NaN.

References

[1]

David Freedman and David Lane. A nonstochastic interpretation of reported significance levels. Journal of Business & Economic Statistics, 1(4):292–298, 1983.

[2]

Anderson M. Winkler, Gerard R. Ridgway, Matthew A. Webster, Stephen M. Smith, and Thomas E. Nichols. Permutation inference for the general linear model. NeuroImage, 92:381–397, 2014. doi:10.1016/j.neuroimage.2014.01.060.

[3]

Larry V Hedges, Elizabeth Tipton, and Matthew C Johnson. Robust variance estimation in meta-regression with dependent effect size estimates. Research Synthesis Methods, 1(1):39–65, 2010. URL: https://doi.org/10.1002/jrsm.5, doi:10.1002/jrsm.5.

[4] (1,2)

Elizabeth Tipton. Small sample adjustments for robust variance estimation with meta-regression. Psychological Methods, 20(3):375–393, 2015. URL: https://doi.org/10.1037/met0000011, doi:10.1037/met0000011.

See also

nilearn.mass_univariate.permuted_ols

The Nilearn function this implementation is derived from, and which it reproduces for the ungrouped, unweighted case.

Methods

correct_fwe_montecarlo(result[, n_iters, ...])	Perform FWE correction using the max-value permutation method.
fit(dataset[, drop_invalid])	Fit Estimator to a collection.
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(result, n_iters=5000, n_cores=1)

Perform FWE correction using the max-value permutation method.

Changed in version 0.21.0: One sign-flip null is now shared across every liberal-mask bag, so the max-statistic distribution describes the whole brain rather than one bag of it. The maximum is taken over z rather than t, so that bags backed by different numbers of images are on a common scale.

Added in version 0.0.4.

Only call this method from within a Corrector.

Parameters:

• result (MetaResult) – Result object from an image-based meta-analysis.

• n_iters (int, default=5000) – The number of iterations to run in estimating the null distribution. Default is 5000.

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

Returns:

images – Dictionary of 1D arrays corresponding to masked images generated by the correction procedure. The following arrays are generated by this method: ‘p_level-voxel’, ‘z_level-voxel’, ‘logp_level-voxel’.

Return type:

dict

See also

nimare.correct.FWECorrector

The Corrector from which to call this method.

Examples

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

fit(dataset, drop_invalid=True)

Fit Estimator to a collection.

Parameters:

• dataset (Studyset or Dataset) – Collection object to analyze.

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

Returns:

Result of Estimator fitting. Subclasses may return a MetaResult subclass.

Return type:

MetaResult

Variables:

• inputs (dict) – Inputs used in _fit.

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

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

• individual (preprocessing before fitting the actual model. Estimators')

• should ("fitting" methods are implemented as _fit, although users)

• fit. (call)

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