Effect sizes

Calculation of effect sizes and sampling variances, see the user guide.

escalc

escalc(
    measure: str | None = None,
    ai: ArrayLike | str | None = None,
    bi: ArrayLike | str | None = None,
    ci: ArrayLike | str | None = None,
    di: ArrayLike | str | None = None,
    n1i: ArrayLike | str | None = None,
    n2i: ArrayLike | str | None = None,
    x1i: ArrayLike | str | None = None,
    x2i: ArrayLike | str | None = None,
    t1i: ArrayLike | str | None = None,
    t2i: ArrayLike | str | None = None,
    m1i: ArrayLike | str | None = None,
    m2i: ArrayLike | str | None = None,
    sd1i: ArrayLike | str | None = None,
    sd2i: ArrayLike | str | None = None,
    xi: ArrayLike | str | None = None,
    mi: ArrayLike | str | None = None,
    ri: ArrayLike | str | None = None,
    ti: ArrayLike | str | None = None,
    fi: ArrayLike | str | None = None,
    pi: ArrayLike | str | None = None,
    sdi: ArrayLike | str | None = None,
    r2i: ArrayLike | str | None = None,
    mini: ArrayLike | str | None = None,
    maxi: ArrayLike | str | None = None,
    ni: ArrayLike | str | None = None,
    yi: ArrayLike | str | None = None,
    vi: ArrayLike | str | None = None,
    sei: ArrayLike | str | None = None,
    *,
    data: DataFrame | Mapping[str, ArrayLike] | None = None,
    slab: ArrayLike | str | None = None,
    flip: ArrayLike | str | None = None,
    subset: ArrayLike | str | None = None,
    include: ArrayLike | str | None = None,
    add: float | None = None,
    to: Literal['all', 'only0', 'if0all', 'none'] = 'only0',
    drop00: bool = False,
    vtype: str | Sequence[str] = 'LS',
    correct: bool | str = True,
    cutoff: float | None = None,
    var_names: Sequence[str] = ('yi', 'vi'),
    add_measure: bool = False,
    append: bool = True,
    replace: bool = True,
    digits: int | Sequence[int] | None = None,
    onlyo1: bool = False,
    addyi: bool = True,
    addvi: bool = True,
) -> DataFrame

Calculate effect sizes yi and sampling variances vi (metafor's escalc).

The metafor reference (last section) lists the measures, the arguments each one needs and the vtype options. add defaults to 1/2, except for the measures where metafor uses 0 (AS, PHI, ZPHI, RTET, ZTET, IRSD, PAS, PFT, IRS, IRFT).

Parameters:

Name	Type	Description	Default
measure	str | None	Effect size or outcome measure to compute, a metafor code such as 'SMD', 'OR', 'RR', 'ZCOR' or 'PR'; see the metafor reference (last section) for the full list. Which of the data arguments below are needed depends on the measure. None (with yi) means 'GEN'.	None
ai	ArrayLike | str | None	2x2 table frequencies (upper left cell).	None
bi	ArrayLike | str | None	2x2 table frequencies (upper right cell).	None
ci	ArrayLike | str | None	2x2 table frequencies (lower left cell).	None
di	ArrayLike | str | None	2x2 table frequencies (lower right cell).	None
n1i	ArrayLike | str | None	Group sizes or row totals (first group or row).	None
n2i	ArrayLike | str | None	Group sizes or row totals (second group or row).	None
x1i	ArrayLike | str | None	Number of events (first group).	None
x2i	ArrayLike | str | None	Number of events (second group).	None
t1i	ArrayLike | str | None	Total person-times (first group).	None
t2i	ArrayLike | str | None	Total person-times (second group).	None
m1i	ArrayLike | str | None	Means (first group or time point).	None
m2i	ArrayLike | str | None	Means (second group or time point).	None
sd1i	ArrayLike | str | None	Standard deviations (first group or time point).	None
sd2i	ArrayLike | str | None	Standard deviations (second group or time point).	None
xi	ArrayLike | str | None	Frequencies of the event of interest.	None
mi	ArrayLike | str | None	Frequencies of the complement of the event of interest, or the group means.	None
ri	ArrayLike | str | None	Raw correlation coefficients.	None
ti	ArrayLike | str | None	Total person-times or t-test statistics.	None
fi	ArrayLike | str | None	F-test statistics.	None
pi	ArrayLike | str | None	(Signed) p-values.	None
sdi	ArrayLike | str | None	Standard deviations.	None
r2i	ArrayLike | str | None	R^2 values.	None
mini	ArrayLike | str | None	Minimum values.	None
maxi	ArrayLike | str | None	Maximum values.	None
ni	ArrayLike | str | None	Sample or group sizes.	None
yi	ArrayLike | str | None	Effect size estimates, for measure='GEN' (used as they are, with vi or sei).	None
vi	ArrayLike | str | None	Sampling variances matching yi.	None
sei	ArrayLike | str | None	Standard errors matching yi; vi is their square. Ignored when vi is given.	None
data	DataFrame | Mapping[str, ArrayLike] | None	Data frame (or mapping of columns) holding the variables named in the data arguments. Each of the arguments above is then an array or the name of a column of data.	None
slab	ArrayLike | str | None	Study labels, as a sequence or a column name. Stored in attrs['slab'].	None
flip	ArrayLike | str | None	Flip the sign of the estimates: a boolean (or a boolean per study), or a numeric multiplier (one per study), or the name of a column of data. The sampling variances are multiplied by the square of the multiplier.	None
subset	ArrayLike | str | None	Studies to keep in the returned frame: a boolean array, 0-based indices or an expression string evaluated on data.	None
include	ArrayLike | str | None	Studies for which the measure is computed (the others get missing values), given like subset.	None
add	float | None	Non-negative amount to add to zero cells, counts or frequencies. Default 0.5 (0 for the measures listed above).	None
to	Literal['all', 'only0', 'if0all', 'none']	When add is added: 'only0' (to the table of a study with a zero cell, the default), 'all', 'if0all' (to all tables when any has a zero cell) or 'none'.	'only0'
drop00	bool	Drop studies with no cases or events (or only cases) in both groups from the calculations (set their values to missing). Used for the 2x2 table measures and 'IRR', 'IRD' and 'IRSD' only.	False
vtype	str | Sequence[str]	Type of sampling variance: one of 'UB', 'LS' (the default), 'LS2', 'LS3', 'HO', 'ST', 'CS', 'AV', 'AV2', 'AVHO', 'H0', 'H0a', 'H0b' or 'MAX'. The valid options depend on the measure; a sequence gives one type per study.	'LS'
correct	bool | str	Apply the bias correction to the estimates (default True), for the measures that have one ('SMD', 'SMD1', 'SMDH', 'SMD1H', 'ROM', 'VR', 'CVR', 'SMN', 'SDLN', 'CVLN', 'SMCC', 'SMCR', 'SMCRH', 'SMCRP', 'SMCRPH', 'ROMC' and 'CVRC'); it has no effect on the others. For the measures built on cmicalc ('SMD', 'SMD1', 'SMDH', 'SMD1H', 'SMN', 'SMCC', 'SMCR', 'SMCRH', 'SMCRP', 'SMCRPH') it may also be 'exact' (the same as True) or 'approx'; ROM, VR, CVR, SDLN, CVLN, ROMC and CVRC need a bool.	True
cutoff	float | None	Absolute value above which a computed estimate is flagged with a warning. The default is 2 for 'SMD', 'SMDH', 'SMD1' and 'SMD1H' and no check for the other measures; NaN switches the check off. A given set of estimates is flagged once per session.	None
var_names	Sequence[str]	Names of the estimate and sampling variance columns of the result (('yi', 'vi'); a third name with add_measure).	('yi', 'vi')
add_measure	bool	Add a column recording the measure computed (named 'measure' unless var_names has a third entry).	False
append	bool	Return data with the new columns appended (True, the default) or only the new columns.	True
replace	bool	Replace existing yi/vi values in data (True, the default) or only their missing values. Needs append=True.	True
digits	int | Sequence[int] | None	Number of decimals used when the frame is printed (stored in attrs['digits']; None uses the digits option, 4 by default). The stored values are not rounded.	None
onlyo1	bool	For the 2x2 table measures: add is added to the ai and ci cells only, not to bi and di. The same option as metafor's ... argument.	False
addyi	bool	True (the default) computes yi from the counts after add and to have been applied, False from the unadjusted counts (zero cells then give missing values for ratios). Used by 'RR', 'OR' (and 'OR2D', 'OR2DN', 'OR2DL', 'MPORM'), 'RD', 'IRR', 'IRD', 'IRSD', 'PR', 'PLN', 'PLO', 'IR', 'IRLN' and 'IRS'; the other measures ignore it. The same option as metafor's ... argument.	True
addvi	bool	The same for the sampling variances vi, for the same measures.	True

Returns:

Type	Description
DataFrame	The columns var_names (yi and vi), appended to data when it is given and append=True, else a frame with those columns only. attrs['measure'], attrs['slab'], attrs['ni'], attrs['digits'], attrs['yi_names'] and attrs['vi_names'] carry metafor's attributes, so the frame can be passed to rma_uni.

Raises:

Type	Description
InputError	an argument or the data is invalid.
ArgumentError	an argument has the wrong type or is not accepted.
NotSupportedError	the requested combination is not implemented.
InternalError	an internal invariant does not hold.

Metafor reference

escalc

summary_escalc

summary_escalc(
    object: DataFrame,
    out_names: Sequence[str] = (
        'sei',
        'zi',
        'pval',
        'ci.lb',
        'ci.ub',
    ),
    var_names: Sequence[str] | None = None,
    H0: ArrayLike = 0,
    append: bool = True,
    replace: bool = True,
    level: float = 95,
    olim: Sequence[float] | None = None,
    digits: int | Sequence[int] | None = None,
    transf: Callable[..., Any] | None = None,
    **kwargs: Any,
) -> DataFrame

Add standard errors, test statistics, p-values and confidence intervals to the output of escalc.

Mirrors metafor's summary.escalc. With yi and vi the effect sizes and sampling variances, it computes sei = sqrt(vi), zi = (yi - H0) / sei, the two-sided p-value pval and the Wald-type interval yi -/+ z_crit * sei. With transf, yi and the bounds are transformed (the bounds are put in increasing order) and vi, sei, zi and pval are dropped.

Parameters:

Name	Type	Description	Default
object	DataFrame	data frame returned by escalc (or a frame with the effect sizes and sampling variances as columns).	required
out_names	Sequence[str]	names of the five new columns, in the order standard error, test statistic, p-value, lower and upper bound (default 'sei', 'zi', 'pval', 'ci.lb', 'ci.ub').	('sei', 'zi', 'pval', 'ci.lb', 'ci.ub')
var_names	Sequence[str] | None	names of the columns with the effect sizes and the sampling variances (two names). Default None: taken from the attributes of object, else 'yi' and 'vi'.	None
H0	ArrayLike	value of the effect under the null hypothesis for zi and pval, a scalar or one value per row (default 0).	0
append	bool	whether the new columns are appended to object (default True); otherwise only the effect sizes (and sampling variances) and the new columns are returned.	True
replace	bool	whether existing columns with the names in out_names are replaced (default True); if False only their missing values are filled in.	True
level	float	confidence level in percent, between 0 and 100 (default 95).	95
olim	Sequence[float] | None	(lower, upper) limits to which yi and the bounds are clipped; zi and pval are based on the unclipped values. Default None: no clipping.	None
digits	int | Sequence[int] | None	number of decimals used when the frame is printed; stored in attrs['digits']. Default None: the digits of object.	None
transf	Callable[..., Any] | None	function applied to the effect sizes and the bounds, for example metafopy.transf.ilogit. Default None.	None
**kwargs	Any	additional arguments passed on to transf.	{}

Returns:

Type	Description
DataFrame	A data frame with the columns of object and the new columns named by out_names (or yi, vi, and the new columns when
DataFrame	append=False). The escalc attributes (measure, slab, ni, ...) are kept, except when transf is given: the result then
DataFrame	does not carry measure, slab, ni and the row labels. With transf and append=False, only yi and the two bounds are returned.

Raises:

Type	Description
InputError	out_names or var_names or olim has the wrong length, a column is not found, level is outside 0 to 100, or transf does not return a single value for each value.

Metafor reference

print.escalc

cmicalc

cmicalc(
    mi: ArrayLike, method: bool | str = 'exact'
) -> NDArray[float64]

Small-sample bias correction factor for standardized mean differences.

Mirrors metafor's cmicalc. The factor c(m) of Hedges (1981, doi:10.3102/10769986006002107) multiplies a standardized mean difference to remove its small-sample bias. escalc uses it for the measures SMD, SMD1, SMDH, SMD1H, SMN, SMCC, SMCR, SMCRH, SMCRP and SMCRPH, passing its argument correct as method.

Parameters:

Name	Type	Description	Default
mi	ArrayLike	degrees of freedom m (for example n1i + n2i - 2), scalar or array-like.	required
method	bool | str	'exact' | 'approx' | True | False. 'exact' (or True, the default) uses the gamma-function form, 'approx' the approximation 1 - 3/(4m - 1), and False applies no correction (a factor of 1). Strings can be abbreviated; an empty string or None raises.	'exact'

Returns:

Type	Description
NDArray[float64]	Array of the factors c(m) with the shape of mi; with 'exact' or 'approx', NaN where m <= 1 (or mi is missing).

Raises:

Type	Description
InputError	method is None, or a string that is not an abbreviation of 'exact' or 'approx'.

Metafor reference

cmicalc

cbind_escalc

cbind_escalc(
    *args: DataFrame | Series, **columns: Any
) -> DataFrame

Combine data frames and further columns side by side and keep the escalc attributes.

Mirrors metafor's cbind() for escalc objects. The names of the effect size, sampling variance, standard error, test statistic, p-value and confidence interval columns of all frames are collected (those of later frames first, as in R), digits is that of the last frame, and measure, slab and ni come from the first frame that has them. Column names are not made unique.

Parameters:

Name	Type	Description	Default
*args	DataFrame | Series	data frames (usually from escalc or summary_escalc) or named Series, all with the same number of rows.	()
**columns	Any	further columns, named by the keyword; a vector becomes one column and a data frame has its columns prefixed with name. (unless it has just one column).	{}

Returns:

Type	Description
DataFrame	The combined data frame, with the columns of all arguments in order and the index of the first.

Raises:

Type	Description
InputError	nothing is given, or the arguments have different numbers of rows.
ArgumentError	an argument is neither a data frame nor a named Series.

rbind_escalc

rbind_escalc(*args: DataFrame) -> DataFrame

Stack data frames on top of each other and keep the escalc attributes.

Mirrors metafor's rbind() for escalc objects. The columns are matched by name and the attributes of the first frame (measure, digits, the names of the effect size columns, ...) are kept. ni is the concatenation of the sample sizes of all frames (missing if one has none) and slab the concatenation of the study labels made unique as metafor does (repeats get .1, .2, ...), or missing if one frame has none.

Parameters:

Name	Type	Description	Default
*args	DataFrame	the data frames to stack, usually from escalc; they must have the same columns.	()

Returns:

Type	Description
DataFrame	The stacked data frame. If all frames have the default index, a fresh 0-based index is made, else the row names are made unique.

Raises:

Type	Description
InputError	nothing is given, or the numbers or names of the columns differ.
ArgumentError	an argument is not a data frame.