nimare.meta.ibma.WeightedLeastSquares

class WeightedLeastSquares(tau2=0, **kwargs)

Bases: _PyMARERegressionEstimator

Weighted least-squares meta-regression.

Changed in version 0.21.0:

• New parameters: groupby, weight_scheme and rho.

• The dof map now reports Satterthwaite degrees of freedom for the CR2 standard errors. It is floating point rather than int32, and varies by voxel.

Changed in version 0.2.1:

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

Changed in version 0.0.12:

• Add “se” to outputs.

Changed in version 0.0.8:

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

Added in version 0.0.4.

Provides the weighted least-squares estimate of the fixed effects given known/assumed between-study variance tau^2. When tau^2 = 0 (default), the model is the standard inverse-weighted fixed-effects meta-regression.

This method was described in Brockwell and Gordon[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.

• weight_scheme ({'rescale', 'individual', 'collapse'}, optional) – How images within a group are weighted, passed to PyMARE. 'rescale' (the default) divides each image’s weight by its group size, so a group’s total weight does not grow with the number of maps it contributed – the correlated-effects model of Hedges et al.[2], weighted as in Fisher and Tipton[3]. 'individual' leaves the weights alone; 'collapse' fits one row per group. Group labels also switch the standard errors to CR2 and the reference to a t distribution with Satterthwaite degrees of freedom [4].

• rho (float, optional) – Assumed within-group correlation, in [0, 1]. Enters only through tau^2, to which results are weakly sensitive. Default is 0.8, matching robumeta. Ignored when weight_scheme='individual'. Together the two choose a working model in the sense of Pustejovsky and Tipton[5]: cluster-robust standard errors stay valid if it is wrong, so the choice costs precision rather than validity.

• tau2 (float or 1D numpy.ndarray, optional) – Assumed/known value of tau^2. Must be >= 0. Default is 0.

Notes

Requires beta and varcope images.

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.
“est”	Fixed effects estimate for intercept test.
“se”	Standard error of fixed effects estimate.
“dof”	Degrees of freedom map from one-sample test.

Warning

Cluster-robust inference is asymptotic in the number of groups, not images. PyMARE warns at 10 or fewer groups, where robust variance estimation is anti-conservative [2], and when the Satterthwaite degrees of freedom fall below about 4 [4]. Both are common for small meta-analyses.

Masking approaches which average across voxels (e.g., NiftiLabelsMaskers) will likely result in biased results. The extent of this bias is currently unknown.

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]

Sarah E Brockwell and Ian R Gordon. A comparison of statistical methods for meta-analysis. Statistics in medicine, 20(6):825–840, 2001. URL: https://doi.org/10.1002/sim.650, doi:10.1002/sim.650.

[2] (1,2)

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.

[3]

Zachary Fisher and Elizabeth Tipton. Robumeta: an r-package for robust variance estimation in meta-analysis. arXiv preprint arXiv:1503.02220, 2015. URL: https://doi.org/10.48550/arXiv.1503.02220, doi:10.48550/arXiv.1503.02220.

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

[5]

James E Pustejovsky and Elizabeth Tipton. Meta-analysis with robust variance estimation: expanding the range of working models. Prevention Science, 23(3):425–438, 2022. URL: https://doi.org/10.1007/s11121-021-01246-3, doi:10.1007/s11121-021-01246-3.

See also

pymare.estimators.WeightedLeastSquares

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