nimare.meta.cbma.weights.StudyWeights

class StudyWeights(source='sample_size', transform='sqrt', reduce='mean', inference_field=None, fixed_effects_discount=0.75, fixed_effects_labels=('fixed', 'ffx', 'fixed-effects', 'fixed effects', 'fe'), on_missing='raise')

Bases: NiMAREBase

Relative weights for the contrasts entering a meta-analysis.

Added in version 0.22.0.

Implements the weighting scheme of Wager et al.[1], in which each study contrast map is weighted by the square root of its sample size and contrasts analysed with a fixed-effects study-level model are discounted:

The weights this object returns are relative. The Estimator rescales them over the contrasts actually being analysed, which is what makes leave-one-out analyses renormalise correctly.

Parameters:

• source ({“sample_size”, “uniform”}, dict, or array-like, default=”sample_size”) – Where the per-contrast quantity comes from. "sample_size" reads the collection’s sample_sizes (or sample_size) metadata. A dict maps study ID to a weight; an array-like gives one weight per study in the order the Estimator collected them. Explicit values bypass transform and reduce, so they are the route for the “other study quality measures” of Wager et al.[1].

• transform ({"sqrt", "linear", "none"}, default="sqrt") – Function applied to the sample size. "sqrt" is the published method. "linear" weights by sample size directly and is not what Wager et al.[1] describes.

• reduce ({"mean", "sum", "min", "max"}, default="mean") – How to collapse a contrast’s sample_sizes list to one number. NiMARE’s converters write one entry per contrast, so this rarely matters; "mean" matches what the ALE kernel does with the same field.

• inference_field (str or None, default=None) – Metadata field naming each contrast’s study-level inference model. Contrasts whose value matches fixed_effects_labels are multiplied by fixed_effects_discount. With no field, no contrast is discounted – NiMARE has no fixed/random convention to infer from, and guessing wrong biases every voxel.

• fixed_effects_discount (float, default=0.75) – The applied to fixed-effects contrasts. Wager et al.[1] uses 0.75, which is a convention rather than an estimate.

• fixed_effects_labels (tuple of str, optional) – Values of inference_field that mark a fixed-effects model. Matched case-insensitively after stripping whitespace.

• on_missing ({"raise", "impute"}, default="raise") – What to do with contrasts whose weight is missing, zero or negative. "raise" refuses, because a silently substituted weight is invisible in the output map. "impute" instead replaces them with the mean of the valid weights and warns, which is what the CANlab MATLAB implementation does; it keeps the weighted and unweighted analyses over the same study set, at the cost of weighting some contrasts by a number that is not theirs.

References

[1] (1,2,3,4)

Tor D Wager, Martin A Lindquist, Thomas E Nichols, Hedy Kober, and Jared X Van Snellenberg. Evaluating the consistency and specificity of neuroimaging data using meta-analysis. NeuroImage, 45(1 Suppl):S210–S221, 2009. URL: https://doi.org/10.1016/j.neuroimage.2008.10.061, doi:10.1016/j.neuroimage.2008.10.061.

Methods

get_params([deep])	Get parameters for this estimator.
load(filename[, compressed])	Load a pickled class instance from file.
raw_weights(dataset, ids)	Return one unnormalised, strictly positive weight per study ID.
save(filename[, compress])	Pickle the class instance to the provided file.
set_params(**params)	Set the parameters of this estimator.

Properties

n_fixed_effects_	Number of contrasts the last call to raw_weights discounted.
n_imputed_	Number of contrasts the last call to raw_weights imputed a weight for.

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

n_fixed_effects_

Number of contrasts the last call to raw_weights discounted. Read by the Estimator when it writes the methods description.

n_imputed_

Number of contrasts the last call to raw_weights imputed a weight for.

raw_weights(dataset, ids)

Return one unnormalised, strictly positive weight per study ID.

Parameters:

• dataset (Studyset or Dataset) – Collection the Estimator is fitting.

• ids (array-like of str) – Study IDs to weight.

Returns:

Weights indexed by study ID. The Estimator rescales these.

Return type:

pandas.Series

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