Publication bias

Tests and methods for publication bias and small-study effects, see Publication bias.

regtest

Regression test for funnel plot asymmetry (metafor's regtest).

Sterne & Egger (2005), doi:10.1002/0470870168.ch6 -- the test adds the standard error (or another measure of precision) as a predictor to the meta-analytic model. See https://wviechtb.github.io/metafor/reference/regtest.html.

RegtestResult dataclass

RegtestResult(
    model: str,
    predictor: str,
    zval: float,
    pval: float,
    ddf: int | None,
    method: str,
    digits: int,
    ret_fit: bool,
    fit: RMAResult | None,
    est: float | None,
    ci_lb: float | None,
    ci_ub: float | None,
)

Bases: HtmlRepr

Result of regtest.

Attributes:

Name	Type	Description
model	str	'rma' or 'lm', the regression model used.
predictor	str	the predictor that was used ('sei', 'vi', 'ni', 'ninv', 'sqrtni' or 'sqrtninv').
zval	float	test statistic for the coefficient of the predictor. It is referred to a t-distribution with ddf degrees of freedom when ddf is not None (always for model='lm'), else to the standard normal distribution.
pval	float	p-value of that test.
ddf	int | None	degrees of freedom of the t-test (model='lm': the number of studies minus the number of coefficients; model='rma': tests 't', 'knha' and 'adhoc'), or None for a z-test.
method	str	tau^2 estimator of the regression model. For model='lm' no tau^2 is estimated and this is only the label of the estimator of x (or the method that was given).
digits	int	number of decimals used when printing.
ret_fit	bool	whether the printed summary shows the fitted model.
fit	RMAResult | None	the fitted regression model (RMAResult for model='rma'), or None.
est	float | None	the 'limit estimate': the intercept of the model, its estimate at zero of the predictor. It is defined (not None) only when the predictor is 'sei', 'vi', 'ninv' or 'sqrtninv' and the model has no moderators besides the intercept.
ci_lb	float | None	lower bound of the confidence interval of est (None when est is None).
ci_ub	float | None	upper bound of the confidence interval of est (None when est is None).

dfs property

dfs: int | None

Degrees of freedom of the test (alias of ddf); None for a z-test.

summary

summary(
    digits: int | None = None, ret_fit: bool | None = None
) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None
ret_fit	bool | None	whether to show the fitted regression model. Default None: the value stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

regtest

regtest(
    x: RMAResult | FixedBinaryResult | ArrayLike | str,
    vi: ArrayLike | str | None = None,
    *,
    sei: ArrayLike | str | None = None,
    ni: ArrayLike | str | None = None,
    subset: ArrayLike | None = None,
    data: DataFrame | None = None,
    model: Literal['lm', 'rma'] = 'rma',
    predictor: Literal[
        'sei', 'vi', 'ni', 'ninv', 'sqrtni', 'sqrtninv'
    ] = 'sei',
    ret_fit: bool = False,
    digits: int | None = None,
    level: float | None = None,
    method: str | None = None,
    test: str | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> RegtestResult

Regression test for funnel plot asymmetry (Egger's test and extensions).

Mirrors metafor's regtest. The effect sizes are regressed on a measure of their precision (the standard error by default) and the test for the coefficient of that predictor is the test for asymmetry (Egger et al., 1997, doi:10.1136/bmj.315.7109.629). With a fitted model that has moderators, the predictor is added to the model. The intercept of the model with sei, vi, ninv or sqrtninv as the predictor is the 'limit estimate' of the effect (the estimate under infinite precision), see RegtestResult.

Parameters:

Name	Type	Description	Default
x	RMAResult | FixedBinaryResult | ArrayLike | str	a fitted model (rma_uni result, or a fixed-effects rma_mh / rma_peto result with model='lm'; model='rma' raises for the latter two, as in metafor), or the observed effect sizes (array-like, or the name of a column of data).	required
vi	ArrayLike | str | None	sampling variances of a vector x (array-like or column name of data); ignored with a warning when x is a model.	None
sei	ArrayLike | str | None	standard errors, used when vi is not given.	None
ni	ArrayLike | str | None	sample sizes (array-like or column name of data), needed for the predictors based on ni. For a model it must have the length of the original data set and defaults to the sample sizes stored in the model. For a vector x it must have the length of x and defaults to the sample sizes stored by escalc.	None
subset	ArrayLike | None	0-based integer indices or boolean mask of the studies to use (vector input only).	None
data	DataFrame | None	data frame in which string values of x, vi, sei and ni are looked up as column names.	None
model	Literal['lm', 'rma']	'rma' | 'lm'. 'rma' (default) fits a meta-regression model (a mixed-effects model for a random-effects x), 'lm' the weighted regression with multiplicative dispersion (the classical Egger test).	'rma'
predictor	Literal['sei', 'vi', 'ni', 'ninv', 'sqrtni', 'sqrtninv']	'sei' | 'vi' | 'ni' | 'ninv' | 'sqrtni' | 'sqrtninv': the standard error (default), the sampling variance, the sample size, its inverse, its square root or the inverse of its square root. The last four need ni.	'sei'
ret_fit	bool	whether the printed summary also shows the fitted regression model (fit is in the result either way). It prints nothing extra for model='lm', which has no fit.	False
digits	int | None	number of decimals used when the result is printed. Default None: the digits of the model, or 4.	None
level	float | None	confidence level of the interval of the limit estimate and of the model fit, between 0 and 100 (as in metafor's level: 95 or 0.95 give a 95% interval, and a value up to 0.5 is read as the significance level). Default None: the level of the model, or 95.	None
method	str | None	tau^2 estimator of the meta-regression model, e.g. 'REML', 'DL' or 'FE'. Default None: the method of x, or 'REML' for a vector. For model='lm' it is only recorded in the result.	None
test	str | None	test for the model coefficients: 'z' | 't' | 'knha' | 'adhoc'. Default None: the test of x, or 'z' for a vector. Ignored for model='lm', which always uses a t-test.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	what to do with studies with missing values in a vector x: 'omit' | 'exclude' | 'pass' omit them with a warning, 'fail' raises. It has no effect on a fitted model.	'omit'

Returns:

Type	Description
RegtestResult	A RegtestResult with the test statistic zval, its p-value pval, the degrees of freedom ddf (None for
RegtestResult	a z-test), the limit estimate est with its confidence interval ci_lb, ci_ub (only when predictor is 'sei', 'vi', 'ninv' or
RegtestResult	'sqrtninv' and the model has no moderators, else None), and the regression model fit (None for model='lm').

Raises:

Type	Description
InputError	an argument or the data is invalid, or studies are missing and na_action='fail'.
NotSupportedError	x is a model of a class regtest is not available for (for example rma_mv, rma_glmm, rma_ls, selection models and robust fits).
EstimationError	the tau^2 estimator of the regression model fails.
InternalError	ni is given but converts to no vector.

Metafor reference

regtest

RegtestResult dataclass

RegtestResult(
    model: str,
    predictor: str,
    zval: float,
    pval: float,
    ddf: int | None,
    method: str,
    digits: int,
    ret_fit: bool,
    fit: RMAResult | None,
    est: float | None,
    ci_lb: float | None,
    ci_ub: float | None,
)

Bases: HtmlRepr

Result of regtest.

Attributes:

Name	Type	Description
model	str	'rma' or 'lm', the regression model used.
predictor	str	the predictor that was used ('sei', 'vi', 'ni', 'ninv', 'sqrtni' or 'sqrtninv').
zval	float	test statistic for the coefficient of the predictor. It is referred to a t-distribution with ddf degrees of freedom when ddf is not None (always for model='lm'), else to the standard normal distribution.
pval	float	p-value of that test.
ddf	int | None	degrees of freedom of the t-test (model='lm': the number of studies minus the number of coefficients; model='rma': tests 't', 'knha' and 'adhoc'), or None for a z-test.
method	str	tau^2 estimator of the regression model. For model='lm' no tau^2 is estimated and this is only the label of the estimator of x (or the method that was given).
digits	int	number of decimals used when printing.
ret_fit	bool	whether the printed summary shows the fitted model.
fit	RMAResult | None	the fitted regression model (RMAResult for model='rma'), or None.
est	float | None	the 'limit estimate': the intercept of the model, its estimate at zero of the predictor. It is defined (not None) only when the predictor is 'sei', 'vi', 'ninv' or 'sqrtninv' and the model has no moderators besides the intercept.
ci_lb	float | None	lower bound of the confidence interval of est (None when est is None).
ci_ub	float | None	upper bound of the confidence interval of est (None when est is None).

dfs property

dfs: int | None

Degrees of freedom of the test (alias of ddf); None for a z-test.

summary

summary(
    digits: int | None = None, ret_fit: bool | None = None
) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None
ret_fit	bool | None	whether to show the fitted regression model. Default None: the value stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

ranktest

Rank correlation test for funnel plot asymmetry (metafor's ranktest).

Begg & Mazumdar (1994), doi:10.2307/2533446. Kendall's tau between the standardised estimates and their sampling variances; the p-value follows R's cor.test(method='kendall'): exact (the default, exact=True) when there are no ties, a normal approximation otherwise. See https://wviechtb.github.io/metafor/reference/ranktest.html.

RanktestResult dataclass

RanktestResult(tau: float, pval: float, digits: int = 4)

Bases: HtmlRepr

Result of ranktest.

Attributes:

Name	Type	Description
tau	float	Kendall's rank correlation coefficient between the standardized effect sizes and the sampling variances.
pval	float	two-sided p-value of the test that the true tau is zero.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

pkendall

pkendall(q: int, n: int) -> float

P(T <= q) for Kendall's statistic (number of concordant pairs) of n untied observations.

kendall_test

kendall_test(
    x: NDArray[float64],
    y: NDArray[float64],
    exact: bool | None = None,
) -> tuple[float, float]

(tau, p-value) of R's two-sided cor.test(x, y, method='kendall', exact=exact); NaN p-value when undefined.

ranktest

ranktest(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | ArrayLike
    | str,
    vi: ArrayLike | str | None = None,
    *,
    sei: ArrayLike | str | None = None,
    subset: ArrayLike | None = None,
    data: DataFrame | None = None,
    digits: int | None = None,
    exact: bool = True,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> RanktestResult

Rank correlation test for funnel plot asymmetry (Begg and Mazumdar, 1994).

Mirrors metafor's ranktest. Kendall's rank correlation between the standardized effect sizes and their sampling variances is computed (Begg & Mazumdar, 1994, doi:10.2307/2533446). A significant correlation indicates funnel plot asymmetry.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | ArrayLike | str	a fitted model without moderators (its effect sizes and sampling variances are used), or the observed effect sizes (array-like, or the name of a column of data).	required
vi	ArrayLike | str | None	sampling variances of a vector x (array-like or column name of data); ignored with a warning when x is a model.	None
sei	ArrayLike | str | None	standard errors, used when vi is not given. One of vi and sei is required for a vector x.	None
subset	ArrayLike | None	0-based integer indices or boolean mask of the studies to use (vector input only).	None
data	DataFrame | None	data frame in which string values of x, vi and sei are looked up as column names.	None
digits	int | None	number of decimals used when the result is printed. Default None: the digits of the model, or 4.	None
exact	bool	whether the exact p-value is computed (default True; metafor takes this argument from ...). The exact p-value needs untied observations; with ties, or if the exact p-value cannot be computed, the normal approximation is used.	True
na_action	Literal['omit', 'exclude', 'pass', 'fail']	what to do with studies with missing values in a vector x: 'omit' | 'exclude' | 'pass' omit them with a warning, 'fail' raises. It has no effect on a fitted model.	'omit'

Returns:

Type	Description
RanktestResult	A RanktestResult with Kendall's tau and the two-sided p-value pval.

Raises:

Type	Description
InputError	an argument or the data is invalid (for example a model with moderators), or studies are missing and na_action='fail'.

Metafor reference

ranktest

RanktestResult dataclass

RanktestResult(tau: float, pval: float, digits: int = 4)

Bases: HtmlRepr

Result of ranktest.

Attributes:

Name	Type	Description
tau	float	Kendall's rank correlation coefficient between the standardized effect sizes and the sampling variances.
pval	float	two-sided p-value of the test that the true tau is zero.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

trimfill

Trim-and-fill method (metafor's trimfill).

Duval & Tweedie (2000), doi:10.1111/j.0006-341X.2000.00455.x and doi:10.1080/01621459.2000.10473905. See https://wviechtb.github.io/metafor/reference/trimfill.html.

TrimfillResult dataclass

TrimfillResult(
    beta: FloatArray,
    se: FloatArray,
    zval: FloatArray,
    pval: FloatArray,
    ci_lb: FloatArray,
    ci_ub: FloatArray,
    vb: FloatArray,
    coef_names: tuple[str, ...],
    tau2: float,
    se_tau2: float,
    k: int,
    p: int,
    m: int,
    btt: tuple[int, ...],
    QE: float,
    QEp: float,
    QM: float,
    QMp: float,
    QMdf: tuple[int, float | None],
    I2: float,
    H2: float,
    R2: float | None,
    vt: float,
    fit_stats_ml: FitStats,
    fit_stats_reml: FitStats,
    parms: int,
    method: str,
    test: Test,
    level: float,
    ddf: int | None,
    s2w: float,
    weighted: bool,
    weights: FloatArray | None,
    tau2_fix: bool,
    int_only: bool,
    int_incl: bool,
    allvipos: bool,
    yi: FloatArray,
    vi: FloatArray,
    X: FloatArray,
    slab: tuple[str, ...],
    data: MetaData,
    control: Control,
    iterations: int = 0,
    measure: str = 'GEN',
    robust: RobustInfo | None = None,
    digits: int = 4,
    coef_na: tuple[bool, ...] = (),
    X_f: FloatArray = (lambda: empty((0, 0)))(),
    add: float = 0.5,
    to: str = 'only0',
    drop00: bool = False,
    fill: BoolArray = (lambda: zeros(0, dtype=bool_))(),
    k0: int = 0,
    se_k0: float = nan,
    side: str = 'left',
    k0_est: str = 'L0',
    p_k0: float = nan,
    *,
    call: Call | None = None,
)

Bases: RMAResult

The model refitted to the observed and the filled-in studies, with the trim-and-fill details.

fill flags the imputed studies (they are last); k0 is the estimated number of missing studies (se_k0 its standard error), side the side of the funnel plot they are missing from, k0_est the estimator used ('L0', 'R0' or 'Q0') and p_k0 the p-value of the test of no missing studies (estimator 'R0' only, NaN for the others).

summary

summary(
    digits: int | Mapping[str, int] | None = None,
    showfit: bool = True,
    *,
    signif_stars: bool | None = None,
    signif_legend: bool | None = None,
    num: bool = False,
) -> str

Format the refitted model and the trim-and-fill details as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | Mapping[str, int] | None	number of decimals, or a mapping from the output parts ('est', 'se', ...) to decimals. Default None: stored digits.	None
showfit	bool	whether to print the fit statistics of the model (default True).	True
signif_stars	bool | None	whether to print significance stars. Default None: the metafopy option.	None
signif_legend	bool | None	whether to print the legend of the stars. Default None: the metafopy option.	None
num	bool	whether to number the lines of the coefficient table (default False).	False

Returns:

Type	Description
str	The printed output as a string.

sqrt_nan

sqrt_nan(x: float) -> float

R's sqrt: NaN with a warning for a negative number.

trimfill

trimfill(
    x: RMAResult,
    side: Literal['left', 'right'] | None = None,
    estimator: Literal['L0', 'R0', 'Q0'] = 'L0',
    maxiter: int = 100,
    verbose: bool = False,
    ilim: tuple[float, float] | None = None,
    **kwargs: Any,
) -> TrimfillResult

Trim-and-fill method for a model without moderators.

Mirrors metafor's trimfill. The number of studies missing from one side of the funnel plot is estimated (Duval & Tweedie, 2000, doi:10.1111/j.0006-341X.2000.00455.x), the corresponding mirror-image studies are filled in, and the model is refitted to the observed and the filled-in studies.

Parameters:

Name	Type	Description	Default
x	RMAResult	a fitted equal- or random-effects model (rma_uni result) without moderators.	required
side	Literal['left', 'right'] | None	'left' | 'right': the side of the funnel plot on which studies are missing. Default None: determined from the sign of the slope of a regression of the effect sizes on their standard errors (the 'right' side if it is negative).	None
estimator	Literal['L0', 'R0', 'Q0']	'L0' | 'R0' | 'Q0': the estimator of the number of missing studies (default 'L0').	'L0'
maxiter	int	maximum number of iterations of the algorithm (default 100); an error is raised when it does not converge.	100
verbose	bool	whether to print the iterations (number of missing studies and estimate) to stdout.	False
ilim	tuple[float, float] | None	(lower, upper) limits to which the effect sizes of the augmented data set are clipped; as in metafor's code this includes the observed effect sizes as well as the filled-in ones, and it is only applied when studies are filled in. Must have two elements. Default None: no clipping.	None
**kwargs	Any	level and test are passed on to the model fits; other keywords are ignored (metafor passes all extra arguments to rma.uni).	{}

Returns:

Type	Description
TrimfillResult	A TrimfillResult: the refitted model (all the attributes of an RMAResult) with the
TrimfillResult	additional fields fill (flags the filled-in studies, which come last), k0, se_k0, side, k0_est and p_k0. If no study is
TrimfillResult	missing (k0 == 0) the model is that of x.

Raises:

Type	Description
InputError	an argument or the data is invalid, x has moderators, k = 1, or the algorithm fails or does not converge.
ArgumentError	x is not an rma_uni result (for example an rma_mh result or a vector).
NotSupportedError	x is a robust fit, a location-scale model or a selection model.
EstimationError	the tau^2 estimator fails when the model is refitted to the trimmed or filled data.
InternalError	a weight matrix an estimator needs is missing.

Metafor reference

trimfill

TrimfillResult dataclass

TrimfillResult(
    beta: FloatArray,
    se: FloatArray,
    zval: FloatArray,
    pval: FloatArray,
    ci_lb: FloatArray,
    ci_ub: FloatArray,
    vb: FloatArray,
    coef_names: tuple[str, ...],
    tau2: float,
    se_tau2: float,
    k: int,
    p: int,
    m: int,
    btt: tuple[int, ...],
    QE: float,
    QEp: float,
    QM: float,
    QMp: float,
    QMdf: tuple[int, float | None],
    I2: float,
    H2: float,
    R2: float | None,
    vt: float,
    fit_stats_ml: FitStats,
    fit_stats_reml: FitStats,
    parms: int,
    method: str,
    test: Test,
    level: float,
    ddf: int | None,
    s2w: float,
    weighted: bool,
    weights: FloatArray | None,
    tau2_fix: bool,
    int_only: bool,
    int_incl: bool,
    allvipos: bool,
    yi: FloatArray,
    vi: FloatArray,
    X: FloatArray,
    slab: tuple[str, ...],
    data: MetaData,
    control: Control,
    iterations: int = 0,
    measure: str = 'GEN',
    robust: RobustInfo | None = None,
    digits: int = 4,
    coef_na: tuple[bool, ...] = (),
    X_f: FloatArray = (lambda: empty((0, 0)))(),
    add: float = 0.5,
    to: str = 'only0',
    drop00: bool = False,
    fill: BoolArray = (lambda: zeros(0, dtype=bool_))(),
    k0: int = 0,
    se_k0: float = nan,
    side: str = 'left',
    k0_est: str = 'L0',
    p_k0: float = nan,
    *,
    call: Call | None = None,
)

Bases: RMAResult

The model refitted to the observed and the filled-in studies, with the trim-and-fill details.

fill flags the imputed studies (they are last); k0 is the estimated number of missing studies (se_k0 its standard error), side the side of the funnel plot they are missing from, k0_est the estimator used ('L0', 'R0' or 'Q0') and p_k0 the p-value of the test of no missing studies (estimator 'R0' only, NaN for the others).

summary

summary(
    digits: int | Mapping[str, int] | None = None,
    showfit: bool = True,
    *,
    signif_stars: bool | None = None,
    signif_legend: bool | None = None,
    num: bool = False,
) -> str

Format the refitted model and the trim-and-fill details as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | Mapping[str, int] | None	number of decimals, or a mapping from the output parts ('est', 'se', ...) to decimals. Default None: stored digits.	None
showfit	bool	whether to print the fit statistics of the model (default True).	True
signif_stars	bool | None	whether to print significance stars. Default None: the metafopy option.	None
signif_legend	bool | None	whether to print the legend of the stars. Default None: the metafopy option.	None
num	bool	whether to number the lines of the coefficient table (default False).	False

Returns:

Type	Description
str	The printed output as a string.

fsn

Fail-safe N (metafor's fsn).

Rosenthal (1979), doi:10.1037/0033-2909.86.3.638; Orwin (1983), doi:10.3102/10769986008002157; Rosenberg (2005), doi:10.1111/j.0014-3820.2005.tb01004.x; Viechtbauer's general approach based on a random-effects model (Viechtbauer, 2024, talk at the Society for Research Synthesis Methodology). A sign-test ('Binomial') type is in metafor's code but not on its help page. See https://wviechtb.github.io/metafor/reference/fsn.html.

FsnResult dataclass

FsnResult(
    type: str,
    fsnum: float,
    est: float,
    tau2: float,
    pval: float,
    alpha: float,
    target: float,
    method: str | None,
    est_fsn: float,
    tau2_fsn: float,
    pval_fsn: float,
    ub_sign: str,
    digits: int = 4,
)

Bases: HtmlRepr

Result of fsn.

Attributes:

Name	Type	Description
type	str	the approach used ('Rosenthal', 'Orwin', 'Rosenberg', 'General' or 'Binomial').
fsnum	float	the fail-safe N (infinite when the target effect is 0).
est	float	average effect size of the observed studies: the inverse-variance weighted average for 'Orwin' (unweighted if no vi or sei is given) and 'Rosenberg', the pooled estimate of the fitted model for 'General'; NaN for the 'Rosenthal' and 'Binomial' types.
tau2	float	estimate of tau^2 of the observed studies ('General' type only, else NaN).
pval	float	p-value of the observed studies (one-tailed for 'Rosenthal', two-sided for 'Binomial', 'Rosenberg' and 'General', NaN for 'Orwin').
alpha	float	target significance level.
target	float	target average effect size ('Orwin' and 'General' with a target; the sign is flipped if it differs from that of the average effect), or NaN if the significance level is the criterion.
method	str | None	tau^2 estimator of the 'General' type, else None.
est_fsn	float	average effect size with the file-drawer studies added ('General' type only, else NaN).
tau2_fsn	float	tau^2 with the file-drawer studies added ('General' type only).
pval_fsn	float	p-value with the file-drawer studies added ('General' type only).
ub_sign	str	'>' if fsnum was cut off at maxint, else an empty string.
digits	int	number of decimals used when printing.

meanes property

meanes: float

Average effect size (alias of est).

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

fsn

fsn(
    x: RMAResult | ArrayLike | str,
    vi: ArrayLike | str | None = None,
    *,
    sei: ArrayLike | str | None = None,
    subset: ArrayLike | None = None,
    data: DataFrame | None = None,
    type: Literal[
        'Rosenthal',
        'Orwin',
        'Rosenberg',
        'General',
        'Binomial',
    ]
    | None = None,
    alpha: float = 0.05,
    target: float | None = None,
    method: str | None = None,
    exact: bool = False,
    verbose: bool | int = False,
    digits: int | None = None,
    pool: Literal['stouffer', 'fisher'] = 'stouffer',
    mumiss: float = 0,
    interval: tuple[float, float] | None = None,
    maxint: float = 10000000.0,
    tol: float = EPS**0.25,
    maxiter: int = 1000,
    tau2: float | None = None,
    test: str | None = None,
    weighted: bool | None = None,
    seed: int | None = None,
    rng: RRandom | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> FsnResult

Fail-safe N calculation.

Mirrors metafor's fsn. It computes the number of studies averaging a null result that would have to be added to a set of studies to reduce the significance level to a target value (or the average effect to a target size). The approaches (type) are Rosenthal's (1979, doi:10.1037/0033-2909.86.3.638), Orwin's (1983, doi:10.3102/10769986008002157), Rosenberg's (2005, doi:10.1111/j.0014-3820.2005.tb01004.x), a general approach that refits a random-effects model, and 'Binomial'. 'Binomial' is not on metafor's help page, but metafor's code (R/fsn.r, also in 5.2-1) has it: it takes the number of studies with a positive estimate, applies the two-sided exact binomial (sign) test of a probability of 0.5 and adds studies in pairs, one with a positive and one with a non-positive estimate, until the p-value reaches alpha; the fail-safe N is the number of studies added (0 if the observed p-value is already at least alpha).

Parameters:

Name	Type	Description	Default
x	RMAResult | ArrayLike | str	either a fitted model without moderators (then type='General' is used) or the observed effect sizes (array-like, or the name of a column of data).	required
vi	ArrayLike | str | None	sampling variances of a vector x (array-like or column name of data); a single value is repeated for all studies. Ignored with a warning when x is a model. Required for the 'Rosenthal', 'Rosenberg' and 'General' types. For 'Orwin' the average is weighted by 1/vi when vi or sei is given (and weighted is not False), else it is the unweighted average. For 'Binomial' the values are not used (metafor's code asks for them, here they are optional).	None
sei	ArrayLike | str | None	standard errors, used when vi is not given.	None
subset	ArrayLike | None	0-based integer indices or boolean mask of the studies to use (vector input only).	None
data	DataFrame | None	data frame in which string values of x, vi and sei are looked up as column names.	None
type	Literal['Rosenthal', 'Orwin', 'Rosenberg', 'General', 'Binomial'] | None	'Rosenthal' | 'Orwin' | 'Rosenberg' | 'General' | 'Binomial' (case-insensitive; a leading part of a name is enough, the first match in the order Rosenthal, Binomial, Orwin, Rosenberg, General is taken). Default None: 'Rosenthal' for a vector, always 'General' for a model (with a warning if another type is given).	None
alpha	float	target significance level (default 0.05) for the Rosenthal, Rosenberg, Binomial and General types.	0.05
target	float | None	target average effect size for the 'Orwin' and 'General' types; ignored by the other types. A target of the opposite sign to the observed average has its sign flipped, and a target of 0 gives an infinite fail-safe N. Default None: for 'Orwin' half of the average effect size (so the fail-safe N is k), for 'General' the p-value criterion alpha is used instead of a target.	None
method	str | None	tau^2 estimator of the random-effects model of the 'General' type, e.g. 'REML'. Default None: the method of x, or 'REML'.	None
exact	bool	for the 'General' type, whether the file-drawer studies are generated as random normal deviates (scaled to have the mean mumiss) and the model refitted (True), or the faster approximation is used (default False). The approximation is used anyway when the number of file-drawer studies exceeds 5000. It is set to True when test is not 'z'.	False
verbose	bool | int	print the steps of the search for the fail-safe N, and pass on to the model fit.	False
digits	int | None	number of decimals used when the result is printed. Default None: the digits of the model, or 4.	None
pool	Literal['stouffer', 'fisher']	'stouffer' | 'fisher': how the p-values are combined for the 'Rosenthal' type (default 'stouffer').	'stouffer'
mumiss	float	average effect of the file-drawer studies for the 'General' type (default 0).	0
interval	tuple[float, float] | None	(lower, upper) initial interval of the root search for the fail-safe N, which is extended if the root lies outside it. Default None: 0 to 50 times the number of studies.	None
maxint	float	largest fail-safe N that is returned; larger values are reported as '>' that value (default 1e7).	10000000.0
tol	float	tolerance of the root finding (default eps**0.25).	EPS ** 0.25
maxiter	int	maximum number of iterations of the root finding (default 1000).	1000
tau2	float | None	fixed value of tau^2 for the 'General' type. Default None: estimated (or the fixed value of a model x).	None
test	str | None	test for the 'General' type: 'z' | 't' | 'knha' | 'adhoc'. Default None: the test of x, or 'z'.	None
weighted	bool | None	whether weighted estimation is used for the 'General' type (for 'Orwin', False gives the unweighted average, True requires vi or sei). Default None: that of x, or True ('Orwin': weighted if vi or sei is given).	None
seed	int | None	seed of the R-compatible random number generator used for exact=True (see set_seed).	None
rng	RRandom | None	an existing generator to use instead of the global one.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	what to do with studies with missing values in a vector x: 'omit' | 'exclude' | 'pass' omit them with a warning, 'fail' raises. It has no effect on a fitted model.	'omit'

Returns:

Type	Description
FsnResult	An FsnResult with the fail-safe N fsnum (infinite if the target is 0), the approach used type, the average
FsnResult	effect est, tau2, pval, alpha and target, and, for the 'General' type, the values with the file drawer (est_fsn,
FsnResult	tau2_fsn, pval_fsn). The fail-safe N is 0 if the observed result already meets the criterion.

Raises:

Type	Description
InputError	an argument or the data is invalid, the model has moderators or custom weights, k = 1, or a sampling variance is not positive, or studies are missing and na_action='fail'.
NotSupportedError	x is a model other than an rma_uni result (for example rma_mh, rma_peto, rma_mv, rma_glmm, rma_ls, selection models and robust fits).
EstimationError	the tau^2 estimator of the random-effects model of the 'General' type fails.

Metafor reference

fsn

fsn_gen

fsn_gen(
    fsnum: float,
    yi: NDArray[float64],
    vi: NDArray[float64],
    vt: float,
    est: float,
    tau2: float,
    tau2_fix: float | None,
    test: str,
    weighted: bool,
    target: float | None,
    alpha: float,
    exact: bool,
    method: str,
    mumiss: float,
    maxint: float,
    newest: bool,
    rng: RRandom,
    *,
    verbose: bool = False,
    upperint: float = 0.0,
) -> Any

Port of metafor's internal .fsn.gen: the p-value (or estimate) minus its target after adding fsnum null studies.

Raises:

Type	Description
InputError	an argument or the data is invalid.
EstimationError	the tau^2 estimator of the refitted model with the file-drawer studies fails.

FsnResult dataclass

FsnResult(
    type: str,
    fsnum: float,
    est: float,
    tau2: float,
    pval: float,
    alpha: float,
    target: float,
    method: str | None,
    est_fsn: float,
    tau2_fsn: float,
    pval_fsn: float,
    ub_sign: str,
    digits: int = 4,
)

Bases: HtmlRepr

Result of fsn.

Attributes:

Name	Type	Description
type	str	the approach used ('Rosenthal', 'Orwin', 'Rosenberg', 'General' or 'Binomial').
fsnum	float	the fail-safe N (infinite when the target effect is 0).
est	float	average effect size of the observed studies: the inverse-variance weighted average for 'Orwin' (unweighted if no vi or sei is given) and 'Rosenberg', the pooled estimate of the fitted model for 'General'; NaN for the 'Rosenthal' and 'Binomial' types.
tau2	float	estimate of tau^2 of the observed studies ('General' type only, else NaN).
pval	float	p-value of the observed studies (one-tailed for 'Rosenthal', two-sided for 'Binomial', 'Rosenberg' and 'General', NaN for 'Orwin').
alpha	float	target significance level.
target	float	target average effect size ('Orwin' and 'General' with a target; the sign is flipped if it differs from that of the average effect), or NaN if the significance level is the criterion.
method	str | None	tau^2 estimator of the 'General' type, else None.
est_fsn	float	average effect size with the file-drawer studies added ('General' type only, else NaN).
tau2_fsn	float	tau^2 with the file-drawer studies added ('General' type only).
pval_fsn	float	p-value with the file-drawer studies added ('General' type only).
ub_sign	str	'>' if fsnum was cut off at maxint, else an empty string.
digits	int	number of decimals used when printing.

meanes property

meanes: float

Average effect size (alias of est).

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

hc

Henmi & Copas confidence interval (metafor's hc).

Henmi & Copas (2010), doi:10.1002/sim.4029. See https://wviechtb.github.io/metafor/reference/hc.html.

HcResult dataclass

HcResult(
    beta: float,
    se: float,
    ci_lb: float,
    ci_ub: float,
    beta_rma: float,
    se_rma: float,
    ci_lb_rma: float,
    ci_ub_rma: float,
    method: str,
    method_rma: str,
    tau2: float,
    tau2_rma: float,
    digits: int = 4,
)

Bases: HtmlRepr

Result of hc.

Attributes:

Name	Type	Description
beta	float	pooled estimate of the Henmi-Copas method: the inverse-variance weighted average of the effect sizes, with the weights of an equal-effects model (so not the random-effects estimate of the original model).
se	float	standard error of beta (NaN if a transformation was applied).
ci_lb	float	lower bound of the Henmi-Copas confidence interval.
ci_ub	float	upper bound of the Henmi-Copas confidence interval.
beta_rma	float	estimate of the original model.
se_rma	float	standard error of the original model (NaN if a transformation was applied).
ci_lb_rma	float	lower bound of the confidence interval of the original model.
ci_ub_rma	float	upper bound of the confidence interval of the original model.
method	str	tau^2 estimator of the Henmi-Copas method (always 'DL', the DerSimonian-Laird estimator).
method_rma	str	tau^2 estimator of the original model.
tau2	float	DerSimonian-Laird tau^2 estimate, which enters the standard error and the interval of the Henmi-Copas method.
tau2_rma	float	tau^2 estimate of the original model.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

hc

hc(
    obj: RMAResult,
    digits: int | None = None,
    transf: Callable[..., Any] | None = None,
    targs: Any = None,
    control: dict[str, Any] | None = None,
) -> HcResult

Henmi and Copas pooled estimate and confidence interval for a random-effects model.

Mirrors metafor's hc. The pooled estimate uses the inverse-variance weights of an equal-effects model, which do not depend on the amount of heterogeneity; the heterogeneity is estimated with the DerSimonian-Laird estimator and enters the standard error and the confidence interval (Henmi & Copas, 2010, doi:10.1002/sim.4029).

Parameters:

Name	Type	Description	Default
obj	RMAResult	a fitted equal- or random-effects model (rma_uni result) without moderators.	required
digits	int | None	number of decimals used when the result is printed. Default None: the digits of obj.	None
transf	Callable[..., Any] | None	function applied to the estimate and the confidence interval bounds (e.g. metafopy.transf.ilogit). The standard errors are then NaN. Default None: no transformation.	None
targs	Any	additional argument for transf, passed as its second argument (for the integral and mode transformations, a mapping with tau2, defaulting to the tau^2 of obj).	None
control	dict[str, Any] | None	mapping with tol (tolerance of the root search, default eps**0.25) and maxiter (default 1000); other keys are ignored.	None

Returns:

Type	Description
HcResult	An HcResult with the estimate beta, standard error se and bounds ci_lb, ci_ub of the Henmi-Copas
HcResult	interval and the tau^2 estimate tau2 it is based on, and the same quantities of the conventional model (beta_rma, se_rma,
HcResult	ci_lb_rma, ci_ub_rma, tau2_rma, method_rma).

Raises:

Type	Description
InputError	an argument or the data is invalid, obj has moderators, k = 1, a sampling variance is not positive, or the root search fails.
ArgumentError	obj is not an rma_uni result.
NotSupportedError	obj is a location-scale model or a selection model.

Metafor reference

hc

HcResult dataclass

HcResult(
    beta: float,
    se: float,
    ci_lb: float,
    ci_ub: float,
    beta_rma: float,
    se_rma: float,
    ci_lb_rma: float,
    ci_ub_rma: float,
    method: str,
    method_rma: str,
    tau2: float,
    tau2_rma: float,
    digits: int = 4,
)

Bases: HtmlRepr

Result of hc.

Attributes:

Name	Type	Description
beta	float	pooled estimate of the Henmi-Copas method: the inverse-variance weighted average of the effect sizes, with the weights of an equal-effects model (so not the random-effects estimate of the original model).
se	float	standard error of beta (NaN if a transformation was applied).
ci_lb	float	lower bound of the Henmi-Copas confidence interval.
ci_ub	float	upper bound of the Henmi-Copas confidence interval.
beta_rma	float	estimate of the original model.
se_rma	float	standard error of the original model (NaN if a transformation was applied).
ci_lb_rma	float	lower bound of the confidence interval of the original model.
ci_ub_rma	float	upper bound of the confidence interval of the original model.
method	str	tau^2 estimator of the Henmi-Copas method (always 'DL', the DerSimonian-Laird estimator).
method_rma	str	tau^2 estimator of the original model.
tau2	float	DerSimonian-Laird tau^2 estimate, which enters the standard error and the interval of the Henmi-Copas method.
tau2_rma	float	tau^2 estimate of the original model.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

tes

Test of excess significance (metafor's tes).

Ioannidis & Trikalinos (2007), doi:10.1177/1740774507079441. The power of each study is evaluated at an assumed true effect (by default the weighted average); the observed number of significant results is compared with the expected one. See https://wviechtb.github.io/metafor/reference/tes.html.

TesResult dataclass

TesResult(
    k: int,
    O: int,
    E: float,
    OEratio: float,
    test: str,
    X2: float,
    pval: float,
    power: FloatArray,
    sig: NDArray[bool_],
    theta: float | FloatArray,
    theta_lim: tuple[float, ...] | None,
    tes_alternative: str,
    tes_alpha: float,
    digits: int = 4,
)

Bases: HtmlRepr

Result of tes.

Attributes:

Name	Type	Description
k	int	number of studies.
O	int	observed number of significant studies.
E	float	expected number of significant studies (the sum of the powers).
OEratio	float	ratio of the observed to the expected number.
test	str	the test used ('chi2', 'binom' or 'exact').
X2	float	chi-square statistic (NaN unless test is 'chi2').
pval	float	p-value of the test of excess significance.
power	FloatArray	estimated power of each study.
sig	NDArray[bool_]	whether each study is significant.
theta	float | FloatArray	assumed true effect (a single value or one per study).
theta_lim	tuple[float, ...] | None	the 'limit estimate': the true effect at which the p-value of the test equals tes_alpha. For tes_alternative='two.sided' it is a pair, the limit estimates of the 'greater' and of the 'less' test, each at tes_alpha / 2. NaN where not estimable. None when find_lim is False or when theta has one value per study.
tes_alternative	str	alternative of the test of excess significance.
tes_alpha	float	significance level of the test of excess significance.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.

tes

tes(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | ArrayLike
    | str,
    vi: ArrayLike | str | None = None,
    *,
    sei: ArrayLike | str | None = None,
    subset: ArrayLike | None = None,
    data: DataFrame | None = None,
    H0: float = 0.0,
    alternative: Literal[
        'two.sided', 'greater', 'less'
    ] = 'two.sided',
    alpha: float = 0.05,
    theta: ArrayLike | None = None,
    tau2: float | None = None,
    test: Literal['chi2', 'binom', 'exact'] | None = None,
    tes_alternative: Literal[
        'two.sided', 'greater', 'less'
    ] = 'greater',
    tes_alpha: float = 0.1,
    progbar: bool = False,
    digits: int | None = None,
    correct: bool = False,
    rel_tol: float = EPS**0.25,
    subdivisions: int = 100,
    tau2_lb: float = 0.0,
    find_lim: bool = True,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> TesResult

Test of excess significance.

Mirrors metafor's tes. The power of each study is computed for an assumed true effect and the observed number of significant studies is compared with the expected number (Ioannidis & Trikalinos, 2007, doi:10.1177/1740774507079441). Also estimates the true effect theta_lim at which the test would be just significant.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | ArrayLike | str	a fitted model (the power is based on its estimate, or its fitted values with moderators, and its tau^2; then vi, sei, subset, theta and tau2 are ignored, without a warning), or the observed effect sizes (array-like, or the name of a column of data).	required
vi	ArrayLike | str | None	sampling variances of a vector x (array-like or column name of data).	None
sei	ArrayLike | str | None	standard errors, used when vi is not given. One of vi and sei is required for a vector x.	None
subset	ArrayLike | None	0-based integer indices or boolean mask of the studies to use (vector input only).	None
data	DataFrame | None	data frame in which string values of x, vi and sei are looked up as column names.	None
H0	float	value of the effect under the null hypothesis of the significance tests of the studies (default 0).	0.0
alternative	Literal['two.sided', 'greater', 'less']	'two.sided' | 'greater' | 'less': the alternative of the significance tests of the studies (default 'two.sided'). Unlike in metafor, abbreviations are not accepted (also for test and tes_alternative).	'two.sided'
alpha	float	significance level of those tests (default 0.05).	0.05
theta	ArrayLike | None	assumed true effect, a single value or one per study. Default None: the inverse-variance weighted average of the effects (with weights 1/(vi + tau2) when tau2 is used).	None
tau2	float | None	amount of heterogeneity in the true effects; the power of each study is then averaged over a normal distribution of the true effects with mean theta and variance tau2. Default None: homogeneous true effects. A value not above tau2_lb counts as none.	None
test	Literal['chi2', 'binom', 'exact'] | None	'chi2' | 'binom' | 'exact': the test of excess significance (chi-square, binomial or exact test). Default None: 'exact' if the number of terms in the sum of the exact test, the sum of the binomial coefficients choose(k, j) over the j involved (all j for tes_alternative='two.sided', j >= O for 'greater', j <= O for 'less'), is at most 10^6, else 'chi2'. The exact test is computed here without listing the combinations, so test='exact' also works for a large number of studies, where metafor stops.	None
tes_alternative	Literal['two.sided', 'greater', 'less']	'two.sided' | 'greater' | 'less': the alternative of the test of excess significance (default 'greater').	'greater'
tes_alpha	float	significance level of the test of excess significance, used for theta_lim (default 0.1).	0.1
progbar	bool	whether to show a progress bar on stderr during the exact test (metafor's default is True, here it is False).	False
digits	int | None	number of decimals used when the result is printed. Default None: the digits of the model, or 4.	None
correct	bool	whether the continuity correction of the chi-square test is used (default False).	False
rel_tol	float	tolerance (absolute and relative) of the numerical integration of the power over the distribution of the true effects (default eps**0.25).	EPS ** 0.25
subdivisions	int	maximum number of subdivisions of that integration (default 100).	100
tau2_lb	float	tau2 values not above this lower bound are treated as zero (default 0).	0.0
find_lim	bool	whether theta_lim is estimated (default True; only when theta is a single value or estimated).	True
na_action	Literal['omit', 'exclude', 'pass', 'fail']	what to do with studies with missing values in a vector x: 'omit' | 'exclude' | 'pass' omit them with a warning, 'fail' raises. It has no effect on a fitted model.	'omit'

Returns:

Type	Description
TesResult	A TesResult with the number of studies k, the observed number O and expected number E of significant
TesResult	studies, their ratio OEratio, the test used test with its statistic X2 (chi-square test only) and p-value pval, the power
TesResult	of each study power, the significance flags sig, the assumed effect theta and the limit estimate theta_lim.

Raises:

Type	Description
InputError	an argument or the data is invalid, or studies are missing and na_action='fail'.
NotSupportedError	x is a model of a class tes is not available for (for example rma_mv, rma_glmm, rma_ls, selection models and robust fits).

Metafor reference

tes

TesResult dataclass

TesResult(
    k: int,
    O: int,
    E: float,
    OEratio: float,
    test: str,
    X2: float,
    pval: float,
    power: FloatArray,
    sig: NDArray[bool_],
    theta: float | FloatArray,
    theta_lim: tuple[float, ...] | None,
    tes_alternative: str,
    tes_alpha: float,
    digits: int = 4,
)

Bases: HtmlRepr

Result of tes.

Attributes:

Name	Type	Description
k	int	number of studies.
O	int	observed number of significant studies.
E	float	expected number of significant studies (the sum of the powers).
OEratio	float	ratio of the observed to the expected number.
test	str	the test used ('chi2', 'binom' or 'exact').
X2	float	chi-square statistic (NaN unless test is 'chi2').
pval	float	p-value of the test of excess significance.
power	FloatArray	estimated power of each study.
sig	NDArray[bool_]	whether each study is significant.
theta	float | FloatArray	assumed true effect (a single value or one per study).
theta_lim	tuple[float, ...] | None	the 'limit estimate': the true effect at which the p-value of the test equals tes_alpha. For tes_alternative='two.sided' it is a pair, the limit estimates of the 'greater' and of the 'less' test, each at tes_alpha / 2. NaN where not estimable. None when find_lim is False or when theta has one value per study.
tes_alternative	str	alternative of the test of excess significance.
tes_alpha	float	significance level of the test of excess significance.
digits	int	number of decimals used when printing.

summary

summary(digits: int | None = None) -> str

Format the result as text, as metafor prints it.

Parameters:

Name	Type	Description	Default
digits	int | None	number of decimals. Default None: the digits stored in the result.	None

Returns:

Type	Description
str	The printed output as a string.