nimare.meta.ibma.Fishers

class Fishers(two_sided=True, use_sample_size=False, **kwargs)

Bases: IBMAEstimator

An image-based meta-analytic test using t- or z-statistic images.

Changed in version 0.21.0:

• New parameter: groupby, identifying images contributed by the same participants.

• The dof map now counts independent groups rather than images.

Requires z-statistic images, but will be extended to work with t-statistic images as well.

This method is described in Fisher and others[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.

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 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 assign each study a total weighted-Fisher coefficient equal to its sample size. Repeated images divide that coefficient internally in PyMARE, so image multiplicity does not change the study’s total weight, and a group whose images report different sample sizes is weighted by their mean. Default is False, preserving ordinary Fisher/Brown inference.

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

When groupby finds a group holding more than one image, Fisher’s chi-squared reference is replaced by the scaled one of Brown[2], whose scale factor is estimated from the null correlation between the input maps [3].

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, 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]

Ronald Aylmer Fisher and others. Statistical methods for research workers. Statistical methods for research workers., 1946.

[2]

Morton B Brown. A method for combining non-independent, one-sided tests of significance. Biometrics, 31(4):987–992, 1975. URL: https://doi.org/10.2307/2529826, doi:10.2307/2529826.

[3]

James T Kost and Michael P McDermott. Combining dependent p-values. Statistics & Probability Letters, 60(2):183–190, 2002. URL: https://doi.org/10.1016/S0167-7152(02)00310-3, doi:10.1016/S0167-7152(02)00310-3.

See also

pymare.estimators.FisherCombinationTest

The PyMARE estimator called by this class.

Methods

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.

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