nimare.meta.ibma.Stouffers

class Stouffers(use_sample_size=False, normalize_contrast_weights=False, two_sided=True, **kwargs)

Bases: IBMAEstimator

A t-test on z-statistic images.

Requires z-statistic images.

This method is described in Stouffer et al.[1].

Changed in version 0.3.0:

• New parameter: two_sided, controls the type of test to be performed. In addition,

  the default is now set to True (two-sided), which differs from previous versions where only one-sided tests were performed.

• Add correction for multiple contrasts within a study.

• New parameter: normalize_contrast_weights to normalized the weights by the

  number of contrasts in each study.

Changed in version 0.2.1:

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

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

• use_sample_size (bool, optional) – Whether to use sample sizes for weights (i.e., “weighted Stouffer’s”) or not, as described in Zaykin[2]. Default is False.

• normalize_contrast_weights (bool, optional) – Whether to use number of contrast per study to normalized the weights or not. 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.

Notes

Requires z images and optionally the sample size metadata field.

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

“z”	Z-statistic map from one-sample test.
“p”	P-value map from one-sample test.
“dof”	Degrees of freedom map from one-sample test.

Warning

Masking approaches which average across voxels (e.g., NiftiLabelsMaskers) will result in invalid results. It cannot be used with these types of maskers.

By default, all image-based meta-analysis estimators adopt an aggressive masking strategy, in which any voxels with a value of zero in any of the input maps will be removed from the analysis. Setting aggressive_mask=False will instead run tha analysis in bags of voxels that have a valid value across the same studies.

References

[1]

Samuel A Stouffer, Edward A Suchman, Leland C DeVinney, Shirley A Star, and Robin M Williams Jr. The american soldier: adjustment during army life.(studies in social psychology in world war ii), vol. 1. Studies in social psychology in World War II, 1949.

[2]

Dmitri V Zaykin. Optimally weighted z-test is a powerful method for combining probabilities in meta-analysis. Journal of evolutionary biology, 24(8):1836–1841, 2011. URL: https://doi.org/10.1111/j.1420-9101.2011.02297.x, doi:10.1111/j.1420-9101.2011.02297.x.

See also

pymare.estimators.StoufferCombinationTest

The PyMARE estimator called by this class.

Methods

fit(dataset[, drop_invalid])	Fit Estimator to Dataset.
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.

fit(dataset, drop_invalid=True)

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:

Results of Estimator fitting.

Return type:

MetaResult

Variables:

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)

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