Plots

Plot functions, see Plots. They draw with matplotlib.

forest

Forest plots (metafor's forest.rma, forest.default, addpoly.rma and addpoly.default).

The layout logic follows the R code line by line: study rows are numbered k:1 from the top, the summary polygon sits at row -1 (prediction interval at -2), the axis limits are alim/xlim with the label and annotation areas reserved left and right of the plot, and the sizes of the arrow heads, CI end caps and summary polygons are fractions of the plot height.

See https://wviechtb.github.io/metafor/reference/forest.rma.html and https://wviechtb.github.io/metafor/reference/addpoly.html, and Viechtbauer (2010), doi:10.18637/jss.v036.i03.

ForestResult dataclass

ForestResult(
    ax: Axes,
    xlim: tuple[float, float],
    alim: tuple[float, float],
    at: FloatArray,
    ylim: tuple[float, float],
    rows: FloatArray,
    cex: float,
    cex_lab: float,
    cex_axis: float,
    ilab_xpos: FloatArray | None,
    ilab_pos: list[int] | None,
    textpos: tuple[float, float],
    areas: tuple[float, float, float] | None = None,
)

What metafor's forest() returns invisibly, plus the axes drawn on.

xlim/ylim are the limits of the plot region, alim the limits of the x axis, at the tick locations, rows the row of each plotted estimate, textpos the x positions of the study labels and annotations, areas the relative widths of the label, plot and annotation areas (forest of a fitted model only).

TransfRule dataclass

TransfRule(
    functions: tuple[Func, ...],
    inverse: Func,
    jacobian: Func,
    lo: float,
    hi: float,
)

How the density of a prediction is carried over to the scale of a back-transformation (the change of variables of metafor's funlist).

PredCurve dataclass

PredCurve(
    xs: FloatArray,
    ys: FloatArray,
    l0: BoolArray,
    g0: BoolArray,
    lower_tail: bool,
    limited: bool = False,
)

The density of the predictive distribution on the plotted scale: xs, ys, the parts below (l0) and above (g0) predtail.

limited is whether predlim was given ('dist' then keeps the whole density instead of dropping the part below 0.5% of the peak).

PredGeometry dataclass

PredGeometry(
    alim: tuple[float, float],
    ciendheight: float,
    arrowwidth: float,
    arrowheight: float,
    barheight: float,
    pipolheight: float,
    ef4: float,
    olim: tuple[float, float] | None = None,
)

The sizes and limits used to draw a prediction interval (see :func:draw_pred).

expand

expand(v: Any, k: int, name: str) -> list[Any]

R's .expand1() followed by the length check.

Raises:

Type	Description
InputError	an argument or the data is invalid.

pervec

pervec(
    v: Any,
    keep: NDArray[bool_],
    k: int,
    k_all: int,
    name: str,
) -> list[Any]

A per-study argument of a fitted model: a scalar is recycled, a vector may have one entry per supplied study.

compress_rows

compress_rows(
    rows: NDArray[float64], not_na: NDArray[bool_]
) -> NDArray[float64]

Close the gaps left by omitted (missing) estimates, as the na.omit branch of forest does.

strheight

strheight(ax: Axes, ylim: tuple[float, float]) -> float

strheight("O") in user coordinates (cap height of 12pt-scaled text relative to the axes height).

anno_symbol

anno_symbol(
    annosym: Sequence[str] | None, tabfig: int | None = None
) -> list[str]

The five symbols of the annotations (opening, separator, closing, minus, space); tabfig 1 to 3 replaces them with those for tabular figures.

Raises:

Type	Description
InputError	annosym does not have 3, 4 or 5 elements.

build_annotext

build_annotext(
    est: NDArray[float64],
    lb: NDArray[float64],
    ub: NDArray[float64],
    digits: Sequence[int],
    annosym: list[str],
    width: Sequence[int] | int | None,
    weights: NDArray[float64] | None,
    pi_row: bool,
    atransf: Callable[..., Any] | None,
    targs: Any,
    weight_pad_rows: tuple[int, ...] = (),
) -> tuple[list[str], list[int]]

The annotation strings (est [lb, ub]) and their column widths.

Raises:

Type	Description
InputError	an argument or the data is invalid.

ftxt

ftxt(
    ax: Axes,
    x: float,
    y: float,
    s: str,
    fnt: tuple[str, int],
    *,
    bold: bool = False,
    **kw: Any,
) -> Text

text() in the font (family, font) of fonts; bold=True is an explicit font=2, which wins over the font in fnt.

check_pred

check_pred(
    predstyle: str,
) -> Literal['line', 'polygon', 'bar', 'shade', 'dist']

The validated predstyle; like R's match.arg() an unambiguous abbreviation ('l', 'p', 'b', 's', 'd') is accepted.

Raises:

Type	Description
InputError	the style is not one of the allowed names.

transf_rule

transf_rule(
    transf: Callable[..., Any] | None,
) -> TransfRule | None

The :class:TransfRule of transf (None without a transformation).

Raises:

Type	Description
InputError	the transformation is not one metafor can draw a prediction distribution for.

parse_predtail

parse_predtail(
    predtail: float | str | None, pred: float
) -> tuple[float, bool]

metafor's predtail (a number or a string such as '<2'/'>2') as (value, lower_tail).

Raises:

Type	Description
InputError	the value cannot be interpreted.

parse_preddist

parse_preddist(
    preddist: tuple[ArrayLike, ArrayLike]
    | Mapping[str, Any]
    | None,
) -> (
    tuple[
        NDArray[float64], NDArray[float64], dict[str, Any]
    ]
    | None
)

A user-supplied predictive distribution as (xs, ys, extras) (extras may hold pi_lb, pi_ub and level).

Raises:

Type	Description
InputError	the distribution is invalid.

pred_curve

pred_curve(
    style: str,
    pred: float,
    pi_se: float | None,
    pi_dist: str,
    pi_ddf: float | None,
    pi_level: float,
    transf: Callable[..., Any] | None,
    predlim: Sequence[float] | None,
    preddist: tuple[NDArray[float64], NDArray[float64]]
    | None,
    predtail: float | str | None,
) -> PredCurve

The predictive distribution to draw for predstyle='shade' and 'dist' (metafor's code in forest.rma and addpoly.default).

pred is the (untransformed) predicted value, pi_se, pi_dist ('norm' or 't') and pi_ddf describe the distribution, pi_level is the alpha level of the prediction interval, predlim the limits of the distribution to draw (on the plotted scale), preddist a distribution supplied by the user (the values and the densities) and predtail the cut for the shading of 'dist'.

Raises:

Type	Description
InputError	the distribution cannot be drawn.

ramp_colors

ramp_colors(
    col_from: str, col_to: str, intensity: NDArray[float64]
) -> list[str]

R's colorRamp(c(col_from, col_to)) applied to intensity and written with rgb(..., maxColorValue = 255) (which truncates).

draw_shade

draw_shade(
    ax: Axes,
    curve: PredCurve,
    row: float,
    barheight: float,
    alim: tuple[float, float],
    olim: tuple[float, float] | None,
    col_from: str | None,
    col_to: str | None,
) -> None

predstyle='shade': rectangles along the prediction interval, shaded from col_from (the centre) to col_to (the ends).

Raises:

Type	Description
InputError	a colour is missing.

draw_dist

draw_dist(
    ax: Axes,
    curve: PredCurve,
    drow: float,
    pi_lb: float,
    pi_ub: float,
    alim: tuple[float, float],
    olim: tuple[float, float] | None,
    ef4: float,
    col: Sequence[str | None],
    border: Sequence[str | None],
) -> None

predstyle='dist': the predictive density, the tails beyond the interval and the parts either side of predtail shaded.

forest

forest(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | CumulResult
    | ArrayLike,
    vi: ArrayLike | None = None,
    sei: ArrayLike | None = None,
    ci_lb: ArrayLike | None = None,
    ci_ub: ArrayLike | None = None,
    annotate: bool = True,
    addfit: bool | None = None,
    addpred: bool
    | str
    | int
    | Sequence[str | int]
    | None = None,
    predstyle: str | None = None,
    preddist: tuple[ArrayLike, ArrayLike]
    | Mapping[str, Any]
    | None = None,
    showweights: bool | None = None,
    header: bool | str | Sequence[str] = True,
    xlim: Sequence[float] | None = None,
    alim: Sequence[float] | None = None,
    olim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    predlim: Sequence[float] | None = None,
    at: ArrayLike | None = None,
    steps: int = 5,
    level: float | None = None,
    refline: float | None = 0,
    digits: int | Sequence[float] | NDArray[floating] = 2,
    width: int | Sequence[int] | None = None,
    xlab: str | Sequence[str] | None = None,
    slab: Sequence[Any] | float | None = None,
    mlab: str | Sequence[str] | None = None,
    ilab: Any = None,
    ilab_lab: str | Sequence[str] | None = None,
    ilab_xpos: ArrayLike | None = None,
    ilab_pos: int | Sequence[int] | None = None,
    order: str | ArrayLike | None = None,
    subset: ArrayLike | None = None,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    rows: ArrayLike | float | None = None,
    efac: float | Sequence[float] = 1,
    pch: int | Sequence[int] = 15,
    psize: float | ArrayLike | None = None,
    plim: Sequence[float] = (0.5, 1.5),
    colout: str | Sequence[str] | None = None,
    colci: str | Sequence[str] | None = None,
    col: str | Sequence[str] | None = None,
    border: str | Sequence[str] | None = None,
    shade: bool | str | ArrayLike | None = None,
    colshade: str | None = None,
    lty: str | Sequence[str] | None = None,
    fonts: str
    | tuple[str, int]
    | Sequence[str | tuple[str, int]]
    | Mapping[str, int]
    | None = None,
    cex: float | None = None,
    cex_lab: float | None = None,
    cex_axis: float | None = None,
    *,
    ax: Axes | None = None,
    predtail: float | str | None = None,
    annosym: Sequence[str] | None = None,
    tabfig: int | None = None,
    textpos: Sequence[float] | None = None,
    rowadj: float | Sequence[float] | None = None,
    top: float = 3,
    at_lab: Sequence[str] | None = None,
    xlabadj: float | Sequence[float] | None = None,
    xlabfont: int | Sequence[int] = 1,
    decreasing: bool = False,
    measure: str | None = None,
    slab_null: bool | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
    predtype: str | None = None,
    pi_type: str | None = None,
    addcred: bool
    | str
    | int
    | Sequence[str | int]
    | None = None,
    clim: Sequence[float] | None = None,
) -> ForestResult

Forest plot of a fitted model (forest.rma), a cumulative analysis or of estimates with their variances (forest.default).

Mirrors metafor's forest() and forest.rma(). Each study is drawn as a marker with a confidence interval. For a fitted model the summary estimate is added as a polygon below the studies (with an optional prediction interval); for a model with moderators the fitted value of each study is added as a polygon on its row. Arguments follow metafor's names (. becomes _). Indices are 0-based where they refer to studies (subset); rows and the numeric form of shade are plot rows as in R.

Vector arguments of a fitted model (slab, ilab, pch, psize, colout, colci, order, a logical shade) must have one entry per study used in the fit or one per row of the original data (the entries of studies dropped for missing values are then removed, as in metafor). For a vector x they must have one entry per estimate.

The differences from metafor are that predstyle='line2' is not available, that refline takes a single value, that predtail must be a number or a string such as '<2' and that slab=nan is only accepted for a vector x.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | CumulResult | ArrayLike	A fitted model (from rma_uni and the other fitting functions), the result of cumul or a vector of estimates. A cumulative analysis is passed on to forest_cumul; the arguments slab, mlab, order, addfit, addpred, predstyle, showweights, predlim, colout and border then give a warning and are ignored. For a vector give the sampling variances (vi), standard errors (sei) or the CI bounds (ci_lb and ci_ub).	required
vi	ArrayLike | None	Sampling variances of the estimates in x (vector form only). Wins over sei.	None
sei	ArrayLike | None	Standard errors of the estimates in x (vector form only).	None
ci_lb	ArrayLike | None	Lower confidence interval bounds of the estimates in x (vector form only; with ci_ub). When given, the intervals are drawn from the bounds instead of from vi or sei; if neither of those is given the variances are derived from the bounds.	None
ci_ub	ArrayLike | None	Upper confidence interval bounds of the estimates in x (vector form only).	None
annotate	bool	Add the annotations (estimate and confidence interval) on the right of the plot. Default: True.	True
addfit	bool | None	Fitted model only: add the polygon of the pooled estimate (a model without moderators) or the polygon of the fitted value of each study (a model with moderators). Default: True. Ignored for a vector x.	None
addpred	bool | str | int | Sequence[str | int] | None	Add the prediction interval to the summary polygon (or, for a model with moderators, use the prediction instead of the confidence interval for the polygon of each study). True or False, or for an rma_mv model with several tau^2 values the levels of the inner factor to use. Has no effect for an equal-effects model. Default: False.	None
predstyle	str | None	Style of the prediction interval: 'line', 'polygon', 'bar', 'shade' (a bar shaded by the density of the predictive distribution) or 'dist' (the density itself, with the tails beyond the interval and the parts either side of predtail shaded); an unambiguous abbreviation is accepted. Setting it implies addpred=True; with moderators only 'line' is relevant (any other style gives a warning). Unlike R there is no 'line2'. 'shade' and 'dist' need transf to be one of numpy.exp, transf_ztor, numpy.tanh, transf_ilogit, plogis, transf_iarcsin, transf_iprobit, pnorm, transf_iahw or transf_iabt, or no transformation. Default: 'line'.	None
preddist	tuple[ArrayLike, ArrayLike] | Mapping[str, Any] | None	Predictive distribution to draw for 'shade' and 'dist': a pair of the values and the densities, or a mapping with the keys 'x', 'y' and optionally 'pi_lb', 'pi_ub' and 'level' (the bounds, else found numerically). Default: computed from the model.	None
showweights	bool | None	Fitted model: add the weights (in percent) of the studies as a column of the annotations; vector form: the weights are 1/vi, rescaled to percent. Not possible for the results of rma_glmm and selmodel. Default: False.	None
header	bool | str | Sequence[str]	True for the headings Study and, for the annotations, the estimate and CI level (for example Estimate [95% CI], dropped with annotate=False), False for none, a string for the left heading or a pair of strings for the left and right headings. Default: True.	True
xlim	Sequence[float] | None	Horizontal limits (left, right) of the plot region. Default: the CI bounds extended on both sides to leave room for the study labels, ilab columns and annotations.	None
alim	Sequence[float] | None	Limits of the x axis (the axis and the polygons are drawn within them; intervals beyond them end in an arrow). Default: the range of at, else the pretty range of the CI bounds.	None
olim	Sequence[float] | None	Limits (lower, upper) that bound the estimates and the confidence and prediction interval bounds (values beyond them are set to the limits; useful for bounded measures). Default: no limits.	None
ylim	Sequence[float] | None	Vertical limits of the plot region. A single value sets the lower limit only. Default: from the rows of the studies, top and the summary rows.	None
predlim	Sequence[float] | None	Limits (lower, upper) of the predictive distribution drawn by predstyle='dist', on the plotted scale.	None
at	ArrayLike | None	Positions of the x-axis tick marks, on the scale that is plotted (after transf, before atransf). Positions outside alim are moved to its ends. Default: chosen from alim and steps.	None
steps	int	Number of tick marks of the x axis: exact when alim is given, otherwise approximate (as pretty chooses). Ignored when at is given. Default: 5.	5
level	float | None	Level of the confidence (and prediction) intervals: 95, 0.95 and 0.05 all give a 95% interval. Default: that of the model, or 95 for a vector x.	None
refline	float | None	Position of the dotted vertical reference line, or None for none. A single value (R also accepts several). Its line type is not affected by lty. Default: 0.	0
digits	int | Sequence[float] | NDArray[floating]	Number of decimals of the annotations, of the x-axis labels and of the weights, in this order. A single value is used for all three; two values give the third the value of the first. An integer (such as 2) drops trailing zeros from the axis labels, a float (such as 2.0) keeps them. Default: 2.	2
width	int | Sequence[int] | None	Minimum width (number of characters) of the annotation columns: one value for all columns or one per column. A column is never narrower than its longest entry. Default: the width of the longest entry.	None
xlab	str | Sequence[str] | None	Label of the x axis, or three (left end, centre, right end) or two (left and right end) labels. Default: the name of the measure (for example 'Log Risk Ratio'), else 'Observed Outcome', adjusted for transf and atransf.	None
slab	Sequence[Any] | float | None	Study labels, one per study. Default: the labels of the model, else Study 1, Study 2, .... For a vector x nan suppresses the labels; for a fitted model a labels vector cannot be suppressed that way.	None
mlab	str | Sequence[str] | None	Label of the summary polygon of a fitted model, or with a prediction interval drawn by a style other than 'line' a pair of labels for the polygon and the interval. Default: 'Random-Effects Model', 'Equal-Effects Model', 'Fixed-Effect Model' or 'Common-Effect Model' by the method of the model.	None
ilab	Any	Extra columns of information on the left of the plot: a vector, a matrix or a data frame with one row per study.	None
ilab_lab	str | Sequence[str] | None	Headings of the ilab columns, one per column.	None
ilab_xpos	ArrayLike | None	X positions of the ilab columns, one per column. Default: spread over the left part of the plot region.	None
ilab_pos	int | Sequence[int] | None	Alignment of the ilab columns (one value or one per column), as the pos argument of R's text(): 1 (below the position), 2 (to the left, so right-aligned), 3 (above) or 4 (to the right, so left-aligned). Default: centred.	None
order	str | ArrayLike | None	Order of the studies. A string, for a fitted model 'est', 'obs', 'yi' (by the estimates), 'prec' or 'vi' (by the sampling variances), 'fit' (by the fitted values), 'resid' or 'rstandard' (by the residuals or standardized residuals), 'abs.resid' or 'abs.rstandard'; for a vector x only 'est', 'obs', 'yi', 'prec' and 'vi'. Or a vector to sort by (increasing, or decreasing with decreasing=True). Default: the order of the data.	None
subset	ArrayLike | None	Vector form only (a fitted model raises an error): which estimates to show, a boolean array or 0-based indices (R: 1-based).	None
transf	Callable[..., Any] | None	Function applied to the estimates and to the confidence and prediction interval bounds (for example numpy.exp). Cannot be used together with atransf.	None
atransf	Callable[..., Any] | None	Function applied to the x-axis labels and to the annotations (the plot stays on the original scale, so numpy.exp gives a log scale). Cannot be used together with transf.	None
targs	Any	Additional arguments passed to transf or atransf.	None
rows	ArrayLike | float | None	Rows (vertical positions) of the studies, one per study, or a single value for the row of the first study (the others follow below it). Default: k for the first study down to 1.	None
efac	float | Sequence[float]	Vertical expansion factors, (CI end bars, arrows, polygon, prediction interval). One value is used for all; for a fitted model two values are (CI end bars and arrows, polygon and prediction interval) and three are (CI end bars, arrows, polygon); for a vector x two values are (CI end bars, arrows). A value of 0 leaves the element out. Default: 1.	1
pch	int | Sequence[int]	Plotting symbol of the study markers, an R code (0 to 6 and 15 to 25 are drawn; another code gives a filled circle); one value or one per study. Default: 15 (a filled square).	15
psize	float | ArrayLike | None	Sizes of the study markers: one value or one per study. Default: scaled by the square root of the weights of the model (for a vector x, of the precisions) within plim.	None
plim	Sequence[float]	(smallest, largest) marker size when scaled by weight; nan for one of them scales relative to the other as in R, and a third value sets a minimum (when the first is nan) or maximum (when the second is nan) size. Default: (0.5, 1.5).	(0.5, 1.5)
colout	str | Sequence[str] | None	Fitted model: colour of the study markers and, unless colci is given, of the interval lines; one value or one per study. Default: black. Not used for a vector x, where col does this.	None
colci	str | Sequence[str] | None	Colour of the confidence interval lines; one value or one per study. Default: that of the markers.	None
col	str | Sequence[str] | None	Fitted model: colour of the summary polygon (without moderators: up to four values for the polygon and the prediction interval, see below) or of the polygons of the fitted values (default '#CCCCCC'); the default for the summary polygon is black. Vector x: colour of the markers, interval lines and labels, one value or one per estimate (default black). For the prediction interval: col[1] is the colour of the interval (line, polygon or bar), for 'shade' col[1] and col[2] are the colours of the centre and the ends of the shading (defaults black and '#F2F2F2') and for 'dist' col[1] is the colour of the tails beyond the interval (default '#666666') and col[2] and col[3] are those of the regions on either side of predtail (defaults '#CCCCCC' and transparent).	None
border	str | Sequence[str] | None	Border colour of the summary polygon (border[0]) and of the prediction interval polygon, bar or curve (border[1]). For the polygons of the fitted values of a model with moderators the default is '#B3B3B3'; otherwise black.	None
shade	bool | str | ArrayLike | None	Shade rows. True or 'zebra' (alternate rows, counted from the bottom row, which is the last study; 'zebra1' is the same), 'zebra2' (the other rows) or 'all'; a boolean array with one entry per study; or numbers, the plot rows (as rows) to shade. Any other string raises an error. Default: no shading.	None
colshade	str | None	Colour of the shading. Default: '#E5E5E5' (light grey).	None
lty	str | Sequence[str] | None	Line types: for a fitted model (CI lines, prediction interval, horizontal lines), defaults 'solid', 'dotted' and 'solid' ('blank' removes the horizontal lines); for a vector x (CI lines, horizontal lines). A single value sets the first. The reference line is always dotted.	None
fonts	str | tuple[str, int] | Sequence[str | tuple[str, int]] | Mapping[str, int] | None	Font family and font of the study labels, the annotations and the ilab columns: a family such as 'serif', 'sans' or 'mono', a (family, font) pair with font 1 to 4 for plain, bold, italic, bold italic, a {family: font} mapping, or a sequence of up to three of these (one entry is used for all, two are completed with the first). Headings are always bold.	None
cex	float | None	Character expansion factor of the text and symbols. Default: 1, reduced when the number of rows would not fit on the axes (so the returned cex can be below 1).	None
cex_lab	float | None	Character expansion factor of the x-axis label. Default: the value of cex.	None
cex_axis	float | None	Character expansion factor of the x-axis tick labels. Default: the value of cex.	None
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
predtail	float | str | None	Cut point of the shading for predstyle='dist', on the scale of the model (before transf): a number or a string such as '<2' or '>2' (the region below a '<' cut point, or above a '>' cut point or a plain number, is filled with col[2], the other region with col[3]). The strings 'lower' and 'upper' are not accepted. Default: 0, with the side towards zero filled with col[2].	None
annosym	Sequence[str] | None	Symbols of the annotations: left bracket, separator and right bracket (default ' [', ', ' and ']'), optionally a fourth for the minus sign (default '-') and a fifth for the space used in place of digits (default ' '). Three, four or five strings are accepted; another length raises an error.	None
tabfig	int | None	1, 2 or 3 replaces annosym by the symbols for fonts with tabular figures: thin spaces before the bracket and after the separator, a minus (1 and 3) or en dash (2) for the minus sign and an en space (1 and 2) or figure space (3) for the space. Other values are ignored.	None
textpos	Sequence[float] | None	(left, right) positions of the study labels (left aligned) and the annotations (right aligned); nan takes the limit of xlim. Default: the limits of xlim.	None
rowadj	float | Sequence[float] | None	Vertical adjustment of the study labels, the annotations and the ilab texts: one value (labels and annotations), two (the third is 0) or three. Default: 0.	None
top	float	Number of rows above the first study (for the headings). Default: 3.	3
at_lab	Sequence[str] | None	Labels of the tick marks, one per position. Default: the (atransf-transformed) positions.	None
xlabadj	float | Sequence[float] | None	Alignment of the left and right x-axis labels when two or three labels are given: 0 (left aligned), 1 (right aligned) or another value (centred), for the left label, the right label getting 1 minus that; or a pair for the two labels. Default: centred.	None
xlabfont	int | Sequence[int]	Font (1 to 4 as in fonts) of the x-axis labels: one value for all, or two with the second for the middle one of three labels. With one value the middle label gets that font, or the font from fonts when there are three labels. Default: 1.	1
decreasing	bool	Sort in decreasing order when order is a vector. Default: False.	False
measure	str | None	Vector form only: the measure used for the axis label and the header. Default: the attrs['measure'] of a pandas Series, else 'GEN'.	None
slab_null	bool | None	Vector form only: whether the labels are the default ones (which gives the study labels less room). Default: True when slab is not given.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with studies dropped for missing values (metafor's options(na.action=)): 'omit' (leave them out), 'pass' or 'exclude' (keep them as empty rows of the plot), or 'fail' (raise an error if there are any). Another value is not rejected and acts like 'omit'. Default: 'omit'.	'omit'
predtype	str | None	Type of prediction interval passed on to predict: 'default', 'simple', 'riley' or 't'.	None
pi_type	str | None	Old spelling of predtype.	None
addcred	bool | str | int | Sequence[str | int] | None	Old spelling of addpred; wins over it.	None
clim	Sequence[float] | None	Old spelling of olim; wins over it.	None

Returns:

Type	Description
ForestResult	A ForestResult (metafor returns the same values invisibly) with the fields ax, xlim, alim, at, ylim, rows,
ForestResult	cex, cex_lab, cex_axis, ilab_xpos, ilab_pos, textpos and areas (the relative widths of the label, plot and
ForestResult	annotation areas; None for a vector x). The markers, interval lines, polygons and texts are ordinary matplotlib artists on ax.

Raises:

Type	Description
NotSupportedError	x is a location-scale model.
InputError	an argument or the data is invalid: both transf and atransf; a length that does not match the number of studies; missing values with na_action='fail'; subset for a fitted model; an unknown order, predstyle, shade or annosym; showweights for a rma_glmm or selmodel result.

Metafor reference

• forest
• forest.rma

summary_cols

summary_cols(
    col: Any, border: Any, predstyle: str = 'line'
) -> tuple[list[str | None], list[str | None]]

The colours of a summary polygon and its prediction interval: col (polygon, interval, shade end or below predtail, above it) and border.

draw_pred

draw_pred(
    ax: Axes,
    style: Literal[
        'line', 'polygon', 'bar', 'shade', 'dist'
    ],
    lb: float,
    ub: float,
    mid: float,
    row: float,
    geo: PredGeometry,
    lty: str,
    col: Sequence[str | None],
    border: Sequence[str | None],
    curve: PredCurve | None = None,
) -> None

The prediction interval of a summary (line, polygon, bar, shade or dist; col and border from :func:summary_cols).

Raises:

Type	Description
InputError	shade is drawn without the second and third colour.

forest_summary

forest_summary(
    model: Any,
    level: float,
    addpred: bool,
    pred_levels: list[str | int] | None,
    predtype: str | None = None,
    pi_type: str | None = None,
) -> PredictResult

The summary estimate (and prediction interval) drawn below the studies, as forest.rma computes it.

For an rma.mv model with several tau2 (or gamma2) values the prediction interval needs the levels of the inner factor(s), given via addpred; without them the first values are used (and only the CI is drawn).

Raises:

Type	Description
InputError	addpred=True for such a model without levels.

widen

widen(
    a: NDArray[float64], k: int, at: NDArray[intp]
) -> NDArray[float64]

a spread over k rows, at the positions at and missing elsewhere (the studies of a fit among those dropped for missing values).

per_study

per_study(
    values: Any,
    keep: NDArray[bool_],
    k: int,
    k_all: int,
    name: str,
) -> Any

Select the entries of a per-study argument that correspond to the studies used in the fit.

Raises:

Type	Description
InputError	an argument or the data is invalid.

addpoly

addpoly(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | PredictResult
    | ArrayLike,
    vi: ArrayLike | None = None,
    sei: ArrayLike | None = None,
    ci_lb: ArrayLike | None = None,
    ci_ub: ArrayLike | None = None,
    pi_lb: ArrayLike | None = None,
    pi_ub: ArrayLike | None = None,
    rows: ArrayLike | float | None = None,
    row: float = -2,
    level: float | None = None,
    annotate: bool | None = None,
    addpred: bool = False,
    predstyle: str | None = None,
    predlim: Sequence[float] | None = None,
    digits: int | Sequence[float] | None = None,
    width: int | Sequence[int] | None = None,
    mlab: str | Sequence[str] | None = None,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    efac: float | Sequence[float] | None = None,
    col: str | Sequence[str] | None = None,
    border: str | Sequence[str] | None = None,
    lty: str | Sequence[str] | None = None,
    fonts: str
    | tuple[str, int]
    | Sequence[str | tuple[str, int]]
    | Mapping[str, int]
    | None = None,
    cex: float | None = None,
    constarea: bool = False,
    *,
    ax: Axes | None = None,
    preddist: tuple[ArrayLike, ArrayLike]
    | Mapping[str, Any]
    | None = None,
    predtail: float | str | None = None,
    pi_se: float | None = None,
    pi_dist: str = 'norm',
    pi_ddf: float | None = None,
    pi_level: float | None = None,
    alim: Sequence[float] | None = None,
    olim: Sequence[float] | None = None,
    annosym: Sequence[str] | None = None,
    textpos: Sequence[float] | None = None,
    rowadj: float | Sequence[float] | None = None,
    lcol: str | Sequence[str] | None = None,
    predtype: str | None = None,
    pi_type: str | None = None,
    addcred: bool | None = None,
    cr_lb: ArrayLike | None = None,
    cr_ub: ArrayLike | None = None,
) -> Axes

Add polygons (summary estimates) to a forest plot (addpoly.rma, addpoly.predict.rma and addpoly.default).

Mirrors metafor's addpoly(). Options not given (alim, digits, width, annotate, transf, atransf, targs, efac, fonts, cex, annosym, textpos, rowadj, olim, ...) are taken from the last forest call on the same axes; without one the limits of the axes are used. Unlike R there is no predstyle='line2' and no tabfig argument.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | PredictResult | ArrayLike	A fitted model without moderators (its pooled estimate and confidence interval are drawn at row), the result of predict (its predicted values and intervals are drawn in rows, which then defaults to row), or a vector of estimates. For a vector give the sampling variances (vi), standard errors (sei) or the CI bounds (ci_lb and ci_ub).	required
vi	ArrayLike | None	Sampling variances of the estimates in x (vector form only).	None
sei	ArrayLike | None	Standard errors of the estimates in x (vector form only).	None
ci_lb	ArrayLike | None	Lower confidence interval bounds (vector form only; used with ci_ub, else vi or sei give the intervals).	None
ci_ub	ArrayLike | None	Upper confidence interval bounds (vector form only).	None
pi_lb	ArrayLike | None	Lower prediction interval bounds (vector form only). The prediction intervals of a vector x are drawn whenever pi_lb and pi_ub are both given, whatever addpred is.	None
pi_ub	ArrayLike | None	Upper prediction interval bounds (vector form only).	None
rows	ArrayLike | float | None	Rows (vertical positions) of the polygons, one per estimate, or a single value for the first (the others follow below it). Default: -1, -2, ... for a vector x, row for a predict result.	None
row	float	Row of the polygon of a fitted model. Default: -2.	-2
level	float | None	Confidence interval level: 95, 0.95 and 0.05 all give a 95% interval. Default: that of the model; for a vector x that of the last forest call, else 95.	None
annotate	bool | None	Add the annotation (estimate and interval) on the right. Default: as in the last forest call, else True.	None
addpred	bool	Fitted model or predict result: add the prediction interval. For a model without prediction interval (an equal-effects model) a warning is given and nothing is drawn for the interval. Default: False.	False
predstyle	str | None	Style of the prediction interval: 'line', 'polygon', 'bar', 'shade' or 'dist' (an unambiguous abbreviation is accepted; the last two draw the predictive distribution, see forest). Setting it implies addpred. Styles other than 'line' need prediction interval bounds, a single polygon and use two rows (the interval is drawn in the second, below the polygon). Default: 'line'.	None
predlim	Sequence[float] | None	Limits (lower, upper) of the predictive distribution drawn by predstyle='dist', on the plotted scale.	None
digits	int | Sequence[float] | None	Number of decimals of the annotation; only the first value of a sequence is used. Default: as in the last forest call, else 2.	None
width	int | Sequence[int] | None	Minimum width (number of characters) of the annotation columns. Default: the widths of the last forest call (so the annotations line up with those of the studies).	None
mlab	str | Sequence[str] | None	Label of the polygon(s), one string per polygon (a fitted model: one string). Default: the label for the method of a fitted model, none for a vector x.	None
transf	Callable[..., Any] | None	Function applied to the estimates and interval bounds before drawing. Default: as in the last forest call.	None
atransf	Callable[..., Any] | None	Function applied to the annotations only (the axis is not touched). Default: as in the last forest call. Cannot be used together with transf.	None
targs	Any	Additional arguments passed to transf or atransf. Default: as in the last forest call.	None
efac	float | Sequence[float] | None	Vertical expansion factors, (CI end bars, arrows, polygon, prediction interval). One value is used for all. For predstyle='line' two values are (polygon, prediction interval end bars and arrows) and three are (polygon, end bars, arrows); for the other styles two values are (polygon, prediction interval height) and three are (polygon, prediction interval height, arrows). A value of 0 leaves the element out. Default: as in the last forest call, else 1.	None
col	str | Sequence[str] | None	Colour of the polygon: one value per polygon. For a single polygon up to four values as for col of forest (polygon, then the colours of the prediction interval). Default: black.	None
border	str | Sequence[str] | None	Border colour of the polygon (one value per polygon; for a single polygon a second value is the border colour of the prediction interval). Default: black.	None
lty	str | Sequence[str] | None	Line types of the prediction interval for predstyle='line': (line, end bars); one value sets the line and leaves the end bars solid. Default: ('dotted', 'solid').	None
fonts	str | tuple[str, int] | Sequence[str | tuple[str, int]] | Mapping[str, int] | None	Fonts of the labels and annotations, as in forest (the first entry for the labels, the second for the annotations). Default: those of the last forest call.	None
cex	float | None	Character expansion factor. Default: that of the last forest call, else 1 or less, as small as the height of the axes needs.	None
constarea	bool	Draw the polygons with a constant area (the height shrinks as the interval widens) rather than a constant height. Default: False.	False
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
preddist	tuple[ArrayLike, ArrayLike] | Mapping[str, Any] | None	Predictive distribution for 'shade' and 'dist', as in forest. Only for the numeric form, and for a single estimate.	None
predtail	float | str | None	Cut point of the shading for 'dist', as in forest (a number or a string such as '<2').	None
pi_se	float | None	Vector form only: standard error of the predictive distribution, for 'shade' and 'dist'. Taken from the model for a fitted model or predict result.	None
pi_dist	str	Vector form only: the predictive distribution, 'norm' (the default) or 't'.	'norm'
pi_ddf	float | None	Vector form only: degrees of freedom of the 't' distribution (must exceed 1 to draw it).	None
pi_level	float | None	Vector form only: level of the prediction interval, as level. Default: level.	None
alim	Sequence[float] | None	Limits of the x axis: polygons are cut off at them. Default: taken from the last forest call, else the limits of the axes.	None
olim	Sequence[float] | None	Limits (lower, upper) that bound the estimates and interval bounds, as in forest. Default: taken from the last forest call.	None
annosym	Sequence[str] | None	Symbols of the annotations, as in forest (three, four or five strings). Default: as in the last forest call.	None
textpos	Sequence[float] | None	(left, right) positions of the labels and annotations. Default: taken from the last forest call, else the limits of the axes.	None
rowadj	float | Sequence[float] | None	Vertical adjustment of the labels and of the annotations; one value for both, or two. Default: as in the last forest call.	None
lcol	str | Sequence[str] | None	Colour of the prediction interval line, its end bars and arrows for predstyle='line'; one value or one per polygon. Default: black.	None
predtype	str | None	Type of prediction interval passed on to predict for a fitted model: 'default', 'simple', 'riley' or 't'.	None
pi_type	str | None	Old spelling of predtype.	None
addcred	bool | None	Old spelling of addpred (fitted model only); wins over it.	None
cr_lb	ArrayLike | None	Old spelling of pi_lb; wins over it.	None
cr_ub	ArrayLike | None	Old spelling of pi_ub; wins over it.	None

Returns:

Type	Description
Axes	The matplotlib axes drawn into.

Raises:

Type	Description
InputError	an argument or the data is invalid: a fitted model with moderators; a predict result of scale values; both transf and atransf; a predstyle other than 'line' without prediction interval bounds or with several polygons; preddist with a fitted model; a length that does not match the number of polygons; no polygon left after dropping missing values.

Metafor reference

addpoly

addpoly

addpoly(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | PredictResult
    | ArrayLike,
    vi: ArrayLike | None = None,
    sei: ArrayLike | None = None,
    ci_lb: ArrayLike | None = None,
    ci_ub: ArrayLike | None = None,
    pi_lb: ArrayLike | None = None,
    pi_ub: ArrayLike | None = None,
    rows: ArrayLike | float | None = None,
    row: float = -2,
    level: float | None = None,
    annotate: bool | None = None,
    addpred: bool = False,
    predstyle: str | None = None,
    predlim: Sequence[float] | None = None,
    digits: int | Sequence[float] | None = None,
    width: int | Sequence[int] | None = None,
    mlab: str | Sequence[str] | None = None,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    efac: float | Sequence[float] | None = None,
    col: str | Sequence[str] | None = None,
    border: str | Sequence[str] | None = None,
    lty: str | Sequence[str] | None = None,
    fonts: str
    | tuple[str, int]
    | Sequence[str | tuple[str, int]]
    | Mapping[str, int]
    | None = None,
    cex: float | None = None,
    constarea: bool = False,
    *,
    ax: Axes | None = None,
    preddist: tuple[ArrayLike, ArrayLike]
    | Mapping[str, Any]
    | None = None,
    predtail: float | str | None = None,
    pi_se: float | None = None,
    pi_dist: str = 'norm',
    pi_ddf: float | None = None,
    pi_level: float | None = None,
    alim: Sequence[float] | None = None,
    olim: Sequence[float] | None = None,
    annosym: Sequence[str] | None = None,
    textpos: Sequence[float] | None = None,
    rowadj: float | Sequence[float] | None = None,
    lcol: str | Sequence[str] | None = None,
    predtype: str | None = None,
    pi_type: str | None = None,
    addcred: bool | None = None,
    cr_lb: ArrayLike | None = None,
    cr_ub: ArrayLike | None = None,
) -> Axes

Add polygons (summary estimates) to a forest plot (addpoly.rma, addpoly.predict.rma and addpoly.default).

Mirrors metafor's addpoly(). Options not given (alim, digits, width, annotate, transf, atransf, targs, efac, fonts, cex, annosym, textpos, rowadj, olim, ...) are taken from the last forest call on the same axes; without one the limits of the axes are used. Unlike R there is no predstyle='line2' and no tabfig argument.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | PredictResult | ArrayLike	A fitted model without moderators (its pooled estimate and confidence interval are drawn at row), the result of predict (its predicted values and intervals are drawn in rows, which then defaults to row), or a vector of estimates. For a vector give the sampling variances (vi), standard errors (sei) or the CI bounds (ci_lb and ci_ub).	required
vi	ArrayLike | None	Sampling variances of the estimates in x (vector form only).	None
sei	ArrayLike | None	Standard errors of the estimates in x (vector form only).	None
ci_lb	ArrayLike | None	Lower confidence interval bounds (vector form only; used with ci_ub, else vi or sei give the intervals).	None
ci_ub	ArrayLike | None	Upper confidence interval bounds (vector form only).	None
pi_lb	ArrayLike | None	Lower prediction interval bounds (vector form only). The prediction intervals of a vector x are drawn whenever pi_lb and pi_ub are both given, whatever addpred is.	None
pi_ub	ArrayLike | None	Upper prediction interval bounds (vector form only).	None
rows	ArrayLike | float | None	Rows (vertical positions) of the polygons, one per estimate, or a single value for the first (the others follow below it). Default: -1, -2, ... for a vector x, row for a predict result.	None
row	float	Row of the polygon of a fitted model. Default: -2.	-2
level	float | None	Confidence interval level: 95, 0.95 and 0.05 all give a 95% interval. Default: that of the model; for a vector x that of the last forest call, else 95.	None
annotate	bool | None	Add the annotation (estimate and interval) on the right. Default: as in the last forest call, else True.	None
addpred	bool	Fitted model or predict result: add the prediction interval. For a model without prediction interval (an equal-effects model) a warning is given and nothing is drawn for the interval. Default: False.	False
predstyle	str | None	Style of the prediction interval: 'line', 'polygon', 'bar', 'shade' or 'dist' (an unambiguous abbreviation is accepted; the last two draw the predictive distribution, see forest). Setting it implies addpred. Styles other than 'line' need prediction interval bounds, a single polygon and use two rows (the interval is drawn in the second, below the polygon). Default: 'line'.	None
predlim	Sequence[float] | None	Limits (lower, upper) of the predictive distribution drawn by predstyle='dist', on the plotted scale.	None
digits	int | Sequence[float] | None	Number of decimals of the annotation; only the first value of a sequence is used. Default: as in the last forest call, else 2.	None
width	int | Sequence[int] | None	Minimum width (number of characters) of the annotation columns. Default: the widths of the last forest call (so the annotations line up with those of the studies).	None
mlab	str | Sequence[str] | None	Label of the polygon(s), one string per polygon (a fitted model: one string). Default: the label for the method of a fitted model, none for a vector x.	None
transf	Callable[..., Any] | None	Function applied to the estimates and interval bounds before drawing. Default: as in the last forest call.	None
atransf	Callable[..., Any] | None	Function applied to the annotations only (the axis is not touched). Default: as in the last forest call. Cannot be used together with transf.	None
targs	Any	Additional arguments passed to transf or atransf. Default: as in the last forest call.	None
efac	float | Sequence[float] | None	Vertical expansion factors, (CI end bars, arrows, polygon, prediction interval). One value is used for all. For predstyle='line' two values are (polygon, prediction interval end bars and arrows) and three are (polygon, end bars, arrows); for the other styles two values are (polygon, prediction interval height) and three are (polygon, prediction interval height, arrows). A value of 0 leaves the element out. Default: as in the last forest call, else 1.	None
col	str | Sequence[str] | None	Colour of the polygon: one value per polygon. For a single polygon up to four values as for col of forest (polygon, then the colours of the prediction interval). Default: black.	None
border	str | Sequence[str] | None	Border colour of the polygon (one value per polygon; for a single polygon a second value is the border colour of the prediction interval). Default: black.	None
lty	str | Sequence[str] | None	Line types of the prediction interval for predstyle='line': (line, end bars); one value sets the line and leaves the end bars solid. Default: ('dotted', 'solid').	None
fonts	str | tuple[str, int] | Sequence[str | tuple[str, int]] | Mapping[str, int] | None	Fonts of the labels and annotations, as in forest (the first entry for the labels, the second for the annotations). Default: those of the last forest call.	None
cex	float | None	Character expansion factor. Default: that of the last forest call, else 1 or less, as small as the height of the axes needs.	None
constarea	bool	Draw the polygons with a constant area (the height shrinks as the interval widens) rather than a constant height. Default: False.	False
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
preddist	tuple[ArrayLike, ArrayLike] | Mapping[str, Any] | None	Predictive distribution for 'shade' and 'dist', as in forest. Only for the numeric form, and for a single estimate.	None
predtail	float | str | None	Cut point of the shading for 'dist', as in forest (a number or a string such as '<2').	None
pi_se	float | None	Vector form only: standard error of the predictive distribution, for 'shade' and 'dist'. Taken from the model for a fitted model or predict result.	None
pi_dist	str	Vector form only: the predictive distribution, 'norm' (the default) or 't'.	'norm'
pi_ddf	float | None	Vector form only: degrees of freedom of the 't' distribution (must exceed 1 to draw it).	None
pi_level	float | None	Vector form only: level of the prediction interval, as level. Default: level.	None
alim	Sequence[float] | None	Limits of the x axis: polygons are cut off at them. Default: taken from the last forest call, else the limits of the axes.	None
olim	Sequence[float] | None	Limits (lower, upper) that bound the estimates and interval bounds, as in forest. Default: taken from the last forest call.	None
annosym	Sequence[str] | None	Symbols of the annotations, as in forest (three, four or five strings). Default: as in the last forest call.	None
textpos	Sequence[float] | None	(left, right) positions of the labels and annotations. Default: taken from the last forest call, else the limits of the axes.	None
rowadj	float | Sequence[float] | None	Vertical adjustment of the labels and of the annotations; one value for both, or two. Default: as in the last forest call.	None
lcol	str | Sequence[str] | None	Colour of the prediction interval line, its end bars and arrows for predstyle='line'; one value or one per polygon. Default: black.	None
predtype	str | None	Type of prediction interval passed on to predict for a fitted model: 'default', 'simple', 'riley' or 't'.	None
pi_type	str | None	Old spelling of predtype.	None
addcred	bool | None	Old spelling of addpred (fitted model only); wins over it.	None
cr_lb	ArrayLike | None	Old spelling of pi_lb; wins over it.	None
cr_ub	ArrayLike | None	Old spelling of pi_ub; wins over it.	None

Returns:

Type	Description
Axes	The matplotlib axes drawn into.

Raises:

Type	Description
InputError	an argument or the data is invalid: a fitted model with moderators; a predict result of scale values; both transf and atransf; a predstyle other than 'line' without prediction interval bounds or with several polygons; preddist with a fitted model; a length that does not match the number of polygons; no polygon left after dropping missing values.

Metafor reference

addpoly

funnel

Funnel plots (metafor's funnel.rma and funnel.default).

Plots the observed effects against a measure of their precision (standard error, variance, their inverses, sample size, weight, ...); for sei, vi, seinv and vinv the pseudo confidence-interval regions around the reference line are drawn (level may be a vector for contour-enhanced funnel plots, with shade the colours of the regions). For a fitted model with moderators the residuals are plotted; a trim-and-fill result (an :class:~metafopy.RMAResult with a boolean fill attribute) shows the imputed studies as open symbols.

See https://wviechtb.github.io/metafor/reference/funnel.html, Sterne & Egger (2001), doi:10.1016/S0895-4356(01)00377-8 and Peters et al. (2008), doi:10.1016/j.jclinepi.2007.11.010.

FunnelResult dataclass

FunnelResult(
    ax: Axes,
    x: FloatArray,
    y: FloatArray,
    slab: tuple[str, ...],
    fill: NDArray[bool_] | None = None,
)

The plotted coordinates (what metafor's funnel() returns invisibly) and the axes drawn on.

x holds the observed outcomes (or residuals), y the values on the vertical axis, fill marks imputed studies of a trim-and-fill result (None otherwise).

yvalues

yvalues(
    yaxis: str,
    sei: NDArray[float64],
    vi: NDArray[float64],
    ni: NDArray[float64] | None,
    weights: NDArray[float64] | None,
) -> NDArray[float64]

The values plotted on the vertical axis.

funnel

funnel(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult
    | ArrayLike,
    vi: ArrayLike | None = None,
    sei: ArrayLike | None = None,
    ni: ArrayLike | None = None,
    subset: ArrayLike | None = None,
    yaxis: str = 'sei',
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    slab: Sequence[Any] | None = None,
    steps: int = 5,
    at: ArrayLike | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    digits: int | Sequence[int] | None = None,
    level: float | Sequence[float] | None = None,
    addtau2: bool = False,
    type: str = 'rstandard',
    back: str | None = None,
    shade: str | Sequence[str] | None = None,
    hlines: str | None = None,
    refline: float | None = None,
    lty: Any = 3,
    pch: int | Sequence[int] | None = None,
    pch_fill: int = 21,
    col: str | Sequence[str] | None = None,
    bg: str | Sequence[str] | None = None,
    label: bool | int | str = False,
    offset: float = 0.4,
    legend: bool | str | dict[str, Any] = False,
    *,
    ax: Axes | None = None,
    refline2: float | None = None,
    level2: float | None = None,
    lty2: Any = 3,
    ci_res: int = 1000,
    colref: str | None = None,
    colci: str | None = None,
    colbox: str | None = None,
    at_lab: Sequence[str] | None = None,
    measure: str | None = None,
    main: str | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
    transf: Any = None,
) -> FunnelResult

Funnel plot of a fitted model (funnel.rma) or of estimates with their variances (funnel.default).

Mirrors metafor's funnel().

yaxis is one of 'sei' (default), 'vi', 'seinv', 'vinv', 'ni', 'ninv', 'sqrtni', 'sqrtninv', 'lni' or 'wi'. level (a percentage; a vector draws several CI regions, a contour-enhanced funnel plot) defaults to the confidence level of the model (95 for the numeric form), shade colours the regions (back the background of the plotting region), refline is the reference line (the pooled estimate, or 0 for models with moderators and the numeric form), addtau2 adds the model's tau^2 to the sampling variances in the CI regions, label (True/'all', 'out' or the number of the most extreme studies) labels points with slab, and type selects the residuals plotted for models with moderators ('rstandard' or 'rstudent'). Pass ni (or fit the model with ni) for the sample-size axes. For a trim-and-fill result the imputed studies are drawn with symbol pch_fill (by default a circle with a grey fill). main is the title of the plot. legend is only approximated (a matplotlib legend). transf only warns, as in metafor (use atransf). na_action stands for R's options(na.action=): estimates with missing values are left out, except for 'fail', which stops; it has no effect on a fitted model.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult | ArrayLike	A fitted model (rma_uni, rma_mh, rma_peto, rma_glmm, rma_mv or a trim-and-fill result), or a vector of effect sizes (then give vi or sei, and ni for the sample-size axes).	required
vi	ArrayLike | None	Sampling variances of the effect sizes in x (vector form only; negative values are set to 0).	None
sei	ArrayLike | None	Standard errors of the effect sizes in x (vector form only; one of vi and sei is enough, vi takes precedence).	None
ni	ArrayLike | None	Sample sizes, for the sample-size yaxis values (vector form only; for a fitted model those stored in the model are used, and for a vector taken from an escalc result those stored with it).	None
subset	ArrayLike | None	Which of the effect sizes to plot: a boolean array or an array of 0-based indices (vector form only, ignored for a fitted model).	None
yaxis	str	Quantity on the vertical axis: 'sei' (default, standard errors), 'vi', 'seinv', 'vinv', 'ni', 'ninv', 'sqrtni', 'sqrtninv', 'lni' or 'wi' (weights in percent). The confidence regions are drawn only for 'sei', 'vi', 'seinv' and 'vinv'; the sample-size axes need sample sizes.	'sei'
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high). Default: wide enough for the confidence region at the bottom of the plot and the points, extended by 10 percent on each side.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high), in either order; they must be >= 0 (> 0 for 'seinv' and 'vinv'). Default: derived from the data. The axis is reversed (largest at the bottom) for 'sei', 'vi', 'ninv' and 'sqrtninv'.	None
xlab	str | None	Label of the horizontal axis. Default: derived from the effect size measure, or 'Residual Value' for a model with moderators.	None
ylab	str | None	Label of the vertical axis. Default: derived from yaxis.	None
slab	Sequence[Any] | None	Study labels (for label). Default: those of the model, or '1', '2', ... in the vector form. For a fitted model give one per row of the data passed to the model fit.	None
steps	int	Number of tick marks of the vertical axis (and of the horizontal grid lines). Default: 5.	5
at	ArrayLike | None	Positions of the tick marks of the horizontal axis (those outside its range are dropped). Default: chosen automatically.	None
atransf	Callable[..., Any] | None	Function applied to the horizontal-axis tick labels only (for example numpy.exp).	None
targs	Any	Additional arguments passed to atransf.	None
digits	int | Sequence[int] | None	Number of decimals of the tick labels: one integer for both axes or two (horizontal axis, vertical axis). Default: 2 and 3 (2 and 0 for yaxis='ni', 2 and 2 for 'wi').	None
level	float | Sequence[float] | None	Confidence level(s) in percent of the pseudo confidence regions (95 or 0.95 for 95 percent). A vector draws several regions, for a contour-enhanced funnel plot. Default: the level of the model (95 for the vector form).	None
addtau2	bool	Add the model's tau^2 to the sampling variances in the confidence regions. Ignored, with a warning, for models with moderators, rma_mv and location-scale models. Default: False.	False
type	str	Residuals plotted for models with moderators: 'rstandard' (the default) or 'rstudent'.	'rstandard'
back	str | None	Colour of the plotting-region background. Default: light grey. (metafor's NULL, which suppresses it, is not supported.)	None
shade	str | Sequence[str] | None	Colour of the confidence regions; one colour per level (a single colour with several levels gives a ramp). Default: white; with several levels white for the first and shades of grey for the others.	None
hlines	str | None	Colour of the horizontal lines at the vertical-axis ticks. Default: white.	None
refline	float | None	Position of the vertical reference line, around which the confidence region is centred. Default: the pooled estimate, or 0 for models with moderators (where residuals are plotted) and the vector form.	None
lty	Any	Line type of the confidence region boundaries and of the reference line: one value for both or a pair (boundaries, reference line). Default: 3, dotted. Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	3
pch	int | Sequence[int] | None	Plotting symbol of the points (R's pch code), or one per study. Default: 19, a filled circle.	None
pch_fill	int	Plotting symbol of the imputed studies of a trim-and-fill result. Default: 21, a circle with border col and fill bg.	21
col	str | Sequence[str] | None	Border colour of the points, or one per study (a matplotlib colour). For a trim-and-fill result a pair (observed, imputed); a single colour then applies to the observed studies. Default: black.	None
bg	str | Sequence[str] | None	Fill colour of the points for symbols with a separate fill, or one per study; a pair (observed, imputed) for a trim-and-fill result. Default: light grey (a darker grey for the observed studies of a trim-and-fill result).	None
label	bool | int | str	Label points with the study labels: True or 'all', 'out' for the points outside the pseudo confidence region (all points for yaxis values without a region), or the number of the most extreme points (distance from refline) to label. Default: False.	False
offset	float	Distance of the labels from the points, as a fraction of the character size (R's text() offset). Labels sit right of points on or right of the reference line, left otherwise.	0.4
legend	bool | str | dict[str, Any]	Add a legend: True, a location (R's 'topright' and the like, or a matplotlib loc), or a mapping with the keys 'x' (the location), 'show' ('pvals', 'cis' or None) and 'studies' (bool); other keys are ignored. An approximation of metafor's legend: drawn with matplotlib. The study entries are omitted when pch, col or bg has one value per study.	False
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
refline2	float | None	Position of a second reference line, with its own confidence region for the four confidence-region yaxis values.	None
level2	float | None	Confidence level in percent of the region around refline2. Default: the level of the model (95 for the vector form).	None
lty2	Any	Line type of the second reference line and its region. Default: 3, dotted.	3
ci_res	int	Number of points used to draw the confidence region boundaries. Default: 1000.	1000
colref	str | None	Colour of the reference line(s). Default: grey.	None
colci	str | None	Colour of the confidence region boundaries. Default: grey.	None
colbox	str | None	Colour of the left and bottom axis lines (metafor's L-shaped box). Default: grey.	None
at_lab	Sequence[str] | None	Labels for the horizontal-axis tick marks, replacing the computed labels (give one per mark of at within the axis range).	None
measure	str | None	Vector form only: the effect size measure, used for the default horizontal-axis label. Default: the measure stored with x by escalc, if any.	None
main	str | None	Title of the plot. Default: none.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail'. In the vector form, estimates with missing values are left out, except for 'fail', which raises; it has no effect on a fitted model.	'omit'
transf	Any	Not available, as in metafor: only gives a warning (use atransf).	None

Returns:

Type	Description
FunnelResult	The plotted coordinates and the axes (x, y, the study labels and the axes).

Raises:

Type	Description
InputError	yaxis, type or na_action is unknown; ylim is out of range; no sample sizes are available for a sample-size yaxis; vi/sei is missing or the wrong length in the vector form; fewer than 2 effect sizes remain; slab, pch, col or bg has the wrong length; or values are missing and na_action='fail'.
NotSupportedError	yaxis='wi' for a model without weights, or a robust fit with moderators.

Metafor reference

funnel

funnel_legend

funnel_legend(
    ax: Axes,
    legend: bool | str | dict[str, Any],
    level: list[float],
    shade: list[str],
    back: str,
    yaxis: str,
    trimfill: bool,
    pch: list[Any],
    col: list[Any],
    bg: list[Any],
    pch_fill: int,
    pch_vec: bool,
    col_vec: bool,
    bg_vec: bool,
    colci: str,
) -> None

An approximation of metafor's funnel legend (CI-region p-value/CI entries and the study symbols).

labbe

L'Abbe plot (metafor's labbe.rma).

Plots the arm-level outcomes (log risks, log odds, risks, arcsine-transformed risks or the corresponding incidence rate measures) of the two groups of each study against each other, with a line for the estimated effect, see L'Abbe et al. (1987), doi:10.7326/0003-4819-107-2-224 and https://wviechtb.github.io/metafor/reference/labbe.html.

LabbeResult dataclass

LabbeResult(
    ax: Axes,
    x: FloatArray,
    y: FloatArray,
    cex: FloatArray,
    pch: tuple[int, ...],
    col: tuple[str, ...],
    bg: tuple[str, ...],
    ids: tuple[int, ...],
    slab: tuple[str, ...],
)

The plotted arm-level outcomes and point attributes (metafor's invisible return value) and the axes drawn on.

Rows dataclass

Rows(
    k: int,
    k_all: int,
    keep: NDArray[bool_],
    ids: tuple[int, ...],
    slab: tuple[str, ...],
    counts: dict[str, FloatArray] | None,
    frame: DataFrame | None,
)

The studies a L'Abbe plot draws: k of the k_all supplied rows (keep), with their 1-based ids and labels.

counts holds the arm-level counts kept by an rma_mh, rma_peto or rma_glmm fit, or by an rma_uni fit computed from counts (None for an rma_uni fit of yi and vi, whose counts come from its data); frame is the data the model was fitted to.

column

column(
    rows: Rows, name: str, value: ArrayLike | str | None
) -> NDArray[float64]

The counts name for the studies of the model (stored in the model, a column of the model's data, or an array).

Raises:

Type	Description
InputError	an argument or the data is invalid.

labbe

labbe(
    x: RMAResult | FixedBinaryResult | GLMMResult,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    lim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    flip: bool = False,
    ci: bool | str = False,
    pi: bool | str = False,
    grid: bool | str = False,
    legend: bool | str | dict[str, Any] = False,
    add: float | None = None,
    to: str | None = None,
    transf: Callable[..., Any] | None = None,
    targs: Any = None,
    pch: int | Sequence[int] = 21,
    psize: float | Sequence[float] | None = None,
    plim: Sequence[float] = (0.5, 3.5),
    col: str | Sequence[str] | None = None,
    bg: str | Sequence[str] | None = None,
    lty: str | Sequence[str] | None = None,
    *,
    ai: ArrayLike | str | None = None,
    bi: ArrayLike | str | None = None,
    ci_counts: ArrayLike | str | None = None,
    di: ArrayLike | str | None = None,
    x1i: ArrayLike | str | None = None,
    x2i: ArrayLike | str | None = None,
    t1i: ArrayLike | str | None = None,
    t2i: ArrayLike | str | None = None,
    llim: Sequence[float] | None = None,
    addyi: bool = True,
    addvi: bool = True,
    ax: Axes | None = None,
    bty: str = 'o',
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> LabbeResult

L'Abbe plot of a model without moderators fitted to 2x2 table data or incidence rates (labbe.rma).

Mirrors metafor's labbe().

x is an rma_uni, rma_mh or rma_glmm fit (rma_peto fits have measure='PETO', which has no arm-level outcomes). rma_mh and rma_glmm fits keep the counts, and add/to default to the model's (for an rma_uni fit they do not, unlike metafor).

The model's measure must be 'RR', 'OR', 'RD', 'AS', 'IRR', 'IRD' or 'IRSD'. A fitted RMAResult does not keep the raw counts, so they are taken from the columns ai, bi, ci, di (x1i, t1i, x2i, t2i for the rate measures) of the data the model was fitted to, or passed as the keyword arguments ai, bi, ci_counts (the ci counts; ci itself draws the confidence region as in metafor), di, x1i, x2i, t1i and t2i (column names or arrays). ci and pi shade the confidence and prediction interval of the line of the estimated effect (a colour string sets the colour), flip swaps the groups, psize/plim set the point sizes (default: proportional to the precision between plim), transf is applied to the arm-level outcomes, and add and to (see below for the defaults), lim/llim as in metafor. bty is the type of box around the plot ('o', 'l', '7', 'c', 'u', ']' or 'n'), which metafor passes on to plot(). na_action stands for R's options(na.action=); an unknown value raises, as in metafor, and every valid value gives the same result (metafor sets na.pass while it computes).

Parameters:

Name	Type	Description	Default
x	RMAResult | FixedBinaryResult | GLMMResult	A model without moderators fitted by rma_uni, rma_mh or rma_glmm to 2x2 table or rate data, with measure one of 'RR', 'OR', 'RD', 'AS', 'IRR', 'IRD' or 'IRSD' (rma_peto fits have measure='PETO').	required
xlim	Sequence[float] | None	Limits of the horizontal axis (the outcome in group 1) as (low, high). Default: the range of all the arm-level outcomes.	None
ylim	Sequence[float] | None	Limits of the vertical axis (the outcome in group 2) as (low, high). Default: the range of all the arm-level outcomes.	None
lim	Sequence[float] | None	Limits of both axes as (low, high); used instead of xlim and ylim.	None
xlab	str | None	Label of the horizontal axis. Default: derived from the measure, with (Group 1).	None
ylab	str | None	Label of the vertical axis. Default: derived from the measure, with (Group 2).	None
flip	bool	Swap the groups plotted on the two axes. Default: False.	False
ci	bool | str	Shade the confidence region of the line of the estimated effect; a colour string sets the colour (default light grey). Default: False.	False
pi	bool | str	Shade the prediction region of the line of the estimated effect; a colour string sets the colour (default lighter grey). Default: False.	False
grid	bool | str	Add a grid. True, False or a colour string for the grid lines. Default: False.	False
legend	bool | str | dict[str, Any]	Add a legend: True, a corner such as 'topleft' (or a matplotlib legend loc), or a mapping of which only 'x' (the location) is used. The default location is the lower right if the estimate is positive, else the upper left. An approximation of metafor's legend: drawn with matplotlib. Default: False.	False
add	float | None	Constant added to the cell counts (see escalc). Default: for rma_mh and rma_glmm fits the model's, otherwise 1/2 (0 for 'AS' and 'IRSD'); unlike metafor an rma_uni fit does not pass on its own add.	None
to	str | None	Which tables get add: 'all', 'only0', 'if0all' or 'none'. Default: for rma_mh and rma_glmm fits the model's, otherwise 'only0'.	None
transf	Callable[..., Any] | None	Function applied to the arm-level outcomes (and to the lines) before they are plotted, for example numpy.exp.	None
targs	Any	Additional arguments passed to transf.	None
pch	int | Sequence[int]	Plotting symbol of the points (R's pch code), or one per study. Default: 21, a circle with border col and fill bg.	21
psize	float | Sequence[float] | None	Sizes (expansion factors) of the points, a number or one per study. Default: proportional to the precision (inverse standard error of the difference), rescaled to plim.	None
plim	Sequence[float]	Range (min, max) of the point sizes when psize is not given, with an optional third value; NaN for min scales the largest to max (the third value then enforces a minimum size), NaN for max scales the smallest to min (the third value then enforces a maximum size). Default: (0.5, 3.5).	(0.5, 3.5)
col	str | Sequence[str] | None	Border colour of the points, or one per study (a matplotlib colour). Default: black.	None
bg	str | Sequence[str] | None	Fill colour of the points for symbols with a separate fill, or one per study. Default: grey.	None
lty	str | Sequence[str] | None	Line types of the line of equality (no effect) and of the line of the estimated effect, as a pair (one value serves both). Default: ('solid', 'dashed'); 'blank' suppresses a line. Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	None
ai	ArrayLike | str | None	Counts of the upper left cells (column name of the data the model was fitted to, or array); only needed if the model does not keep the counts and its data have no ai column.	None
bi	ArrayLike | str | None	Counts of the upper right cells (column name or array); as ai.	None
ci_counts	ArrayLike | str | None	Counts of the lower left cells (column name or array); as ai. (ci draws the confidence region, as in metafor.)	None
di	ArrayLike | str | None	Counts of the lower right cells (column name or array); as ai.	None
x1i	ArrayLike | str | None	Number of events in group 1 (rate measures); as ai.	None
x2i	ArrayLike | str | None	Number of events in group 2 (rate measures); as ai.	None
t1i	ArrayLike | str | None	Person-times of group 1 (rate measures); as ai.	None
t2i	ArrayLike | str | None	Person-times of group 2 (rate measures); as ai.	None
llim	Sequence[float] | None	Limits (low, high) of the line of the estimated effect that is drawn, in arm-level outcome units (length 2). Default: chosen from the measure.	None
addyi	bool	Passed to escalc: apply add to the outcomes. Default: True.	True
addvi	bool	Passed to escalc: apply add to the sampling variances. Default: True.	True
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
bty	str	Type of box around the plot: 'o' (the default), 'l', '7', 'c', 'u', ']' or 'n' (none).	'o'
na_action	Literal['omit', 'exclude', 'pass', 'fail']	R's options(na.action=): 'omit' | 'exclude' | 'pass' | 'fail'. Every valid value gives the same plot.	'omit'

Returns:

Type	Description
LabbeResult	A LabbeResult with the axes ax, the plotted outcomes of group 1 (x) and group 2 (y), the point sizes cex, the symbols pch,
LabbeResult	colours col and bg, and the 1-based study numbers ids and labels slab of the studies plotted.

Raises:

Type	Description
InputError	na_action is unknown; the model has moderators or an unsupported measure; to is unknown; llim does not have length 2; the counts are not available or have the wrong length; pch, col, bg or psize has the wrong length; or no study has all the arm-level outcomes.
NotSupportedError	x is an rma_mv, location-scale or selection-model fit.

Metafor reference

labbe

labbe_legend

labbe_legend(
    ax: Axes,
    legend: bool | str | dict[str, Any],
    intrcpt: float,
    lty: list[Any],
    ci: bool,
    pi: bool,
    ci_col: str,
    pi_col: str,
    lvl: float,
) -> None

An approximation of metafor's legend (reference line, line of the estimated effect and the CI/PI regions).

radial

Radial (Galbraith) plot (metafor's radial.rma).

Plots the standardised effects z_i = y_i / sqrt(v_i + tau^2) against the precisions x_i = 1 / sqrt(v_i + tau^2); the slope of the line through the origin and a point is the estimate, shown on the arc to the right. See Galbraith (1988), doi:10.1080/00401706.1988.10488400, and https://wviechtb.github.io/metafor/reference/radial.html.

RadialResult dataclass

RadialResult(
    ax: Axes,
    x: FloatArray,
    y: FloatArray,
    ids: tuple[int, ...],
    slab: tuple[str, ...],
)

The plotted coordinates of a radial plot (metafor's invisible return value) and the axes drawn on.

asch

asch(v: float) -> str

as.character() of a number.

arc

arc(
    len_: float, at: NDArray[float64], asp: float
) -> tuple[NDArray[float64], NDArray[float64]]

Points on the arc of radius len_ (in the metric of the plot) at the slopes at.

radial

radial(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult,
    center: bool = False,
    xlim: Sequence[float] | None = None,
    zlim: Sequence[float] | None = None,
    xlab: str | None = None,
    zlab: str | None = None,
    atz: ArrayLike | None = None,
    aty: ArrayLike | None = None,
    steps: int = 7,
    level: float | None = None,
    digits: int = 2,
    transf: Callable[..., Any] | None = None,
    targs: Any = None,
    pch: int = 21,
    col: str | None = None,
    bg: str | None = None,
    back: str | None = None,
    arc_res: int | Sequence[int] = 100,
    cex: float | None = None,
    cex_lab: float | None = None,
    cex_axis: float | None = None,
    *,
    ax: Axes | None = None,
) -> RadialResult

Radial (Galbraith) plot of a model without moderators (radial.rma); metafopy.plot.galbraith is an alias.

Mirrors metafor's radial().

center plots the deviations from the pooled estimate, atz/aty set the ticks of the z-axis and the values on the arc (aty in the units of the effect sizes, transf is applied to the arc labels), steps the number of arc ticks, level the confidence level of the shaded band (default: the model's), digits the digits of the arc labels and arc_res the resolution of the arcs (a second number sets that of the confidence interval arc, default a quarter).

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult	A fitted model without moderators (not a robust, rma_mv, location-scale or selection model).	required
center	bool	Plot the standardized deviations from the pooled estimate, which centers the plot horizontally at the pooled estimate. Default: False.	False
xlim	Sequence[float] | None	Limits of the horizontal axis (the precision). Default: 0 to 1.3 times the largest precision.	None
zlim	Sequence[float] | None	Limits of the vertical axis (the standardized effects); these are the actual limits of the plotting region. Default: derived from the data, at least -5 to 5.	None
xlab	str | None	Label of the horizontal axis. Default: derived from the model (a math-text label).	None
zlab	str | None	Label of the vertical axis. Default: derived from the model and center (a math-text label).	None
atz	ArrayLike | None	Positions of the tick marks and labels of the vertical axis (those outside zlim are dropped). Default: -2, 0 and 2, with unlabelled marks at -4 to 4.	None
aty	ArrayLike | None	Positions (in the units of the effect sizes, before transf) of the tick marks on the arc; steps is then ignored. Default: steps marks spread from the smallest to the largest estimate.	None
steps	int	Number of tick marks on the arc. Default: 7.	7
level	float | None	Confidence level of the shaded band (the z-axis error region), between 0 and 100 (95 or 0.95 for 95 percent). Default: the level of the model.	None
digits	int	Number of decimals of the arc labels. Default: 2.	2
transf	Callable[..., Any] | None	Function applied to the arc labels.	None
targs	Any	Additional arguments passed to transf.	None
pch	int	Plotting symbol of the points (R's pch code). Default: 21, a circle with border col and fill bg.	21
col	str | None	Border colour of the points (a matplotlib colour). Default: the foreground colour (black).	None
bg	str | None	Fill colour of the points for symbols with a separate fill. Default: a grey adjusted from the background.	None
back	str | None	Colour of the shaded band. Default: a light grey. (metafor's NA, which suppresses the shading, is not supported.)	None
arc_res	int | Sequence[int]	Number of points used to draw the arc of the estimates; a second value sets that of the confidence interval arc. Default: 100 and, when one number is given, a quarter of it (rounded up) for the confidence interval arc.	100
cex	float | None	Expansion factor of the point symbols only (as in metafor). Default: 1.	None
cex_lab	float | None	Expansion factor of the axis labels. Default: 1.	None
cex_axis	float | None	Expansion factor of the tick labels (the labels of the arc are drawn at 0.85 times this). Default: 1.	None
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None

Returns:

Type	Description
RadialResult	The plotted values: x (precisions), y (standardized effects), ids and slab, and the axes.

Raises:

Type	Description
InputError	the model has moderators, level is outside 0 to 100, or an estimate or precision is infinite and xlim and zlim are not given.
NotSupportedError	x is a robust, rma_mv, location-scale or selection-model fit.
ArgumentError	x is not a fitted model.

Metafor reference

radial

baujat

Baujat plot (metafor's baujat.rma).

Plots each study's contribution to the overall heterogeneity (squared Pearson residual) against its influence on the pooled result (the standardised squared change in the fitted value when the study is left out), see Baujat et al. (2002), doi:10.1002/sim.1221, and https://wviechtb.github.io/metafor/reference/baujat.html.

BaujatResult dataclass

BaujatResult(
    ax: Axes,
    x: FloatArray,
    y: FloatArray,
    ids: tuple[int, ...],
    slab: tuple[str, ...],
)

The plotted coordinates of a Baujat plot (what metafor's baujat() returns invisibly) and the axes drawn on.

baujat

baujat(
    x: RMAResult | FixedBinaryResult,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    cex: float | None = None,
    symbol: str | int | Sequence[int] = 'ids',
    grid: bool | str = True,
    progbar: bool = False,
    *,
    ax: Axes | None = None,
    bty: str = 'o',
    las: int | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> BaujatResult

Baujat plot of a fitted rma_uni, rma_mh or rma_peto model (baujat.rma).

Mirrors metafor's baujat().

symbol is 'ids' (the 1-based study numbers), 'slab' (the study labels) or one plotting symbol (a number, or one per study); grid adds a grid (a colour string sets its colour). progbar=True prints a progress bar to stderr while the studies are left out in turn. Each study is left out in turn and the model refitted; the x-axis shows the study's squared Pearson residual and the y-axis the squared change in its fitted value, standardised by the variance of the prediction without the study. bty (the type of box around the plot: 'o', 'l', '7', 'c', 'u', ']' or 'n') and las (the orientation of the tick labels, 0 to 3) are passed on to plot() by metafor. na_action stands for R's options(na.action=): an unknown value raises, 'fail' raises when a study has missing values (in metafor the refits stop on them and baujat() ends with "need finite 'ylim' values"), the others give the same result (metafor sets na.pass while it computes).

Parameters:

Name	Type	Description	Default
x	RMAResult | FixedBinaryResult	A model fitted by rma_uni, rma_mh or rma_peto.	required
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high). Default: derived from the data.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high). Default: derived from the data.	None
xlab	str | None	Label of the horizontal axis. Default: derived from the model.	None
ylab	str | None	Label of the vertical axis. Default: derived from the model.	None
cex	float | None	Character expansion factor of the symbols. Default: 0.8 (times the base font size, as metafor's par("cex") * 0.8).	None
symbol	str | int | Sequence[int]	Plotting symbol: 'ids' (the 1-based study numbers, the default), 'slab' (the study labels), one plotting symbol (a number), or one per study.	'ids'
grid	bool | str	Add a grid. True, False or a colour string for the grid lines.	True
progbar	bool	Print a progress bar to stderr while the studies are left out in turn.	False
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
bty	str	Type of box around the plot: 'o' (the default), 'l', '7', 'c', 'u', ']' or 'n' (none).	'o'
las	int | None	Orientation of the axis tick labels, 0 to 3 as in R (0 parallel to the axis, 1 horizontal, 2 perpendicular, 3 vertical).	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail' (raise an error if a study has missing values); the first three give the same plot.	'omit'

Returns:

Type	Description
BaujatResult	The plotted coordinates and the axes (x is the contribution of each study to the overall heterogeneity, y its influence).

Raises:

Type	Description
InputError	na_action is unknown, or 'fail' and a study has missing values, k is 1, the length of symbol does not match the studies, or las is not 0 to 3.
NotSupportedError	x is an rma_mv, rma_glmm, location-scale, robust or selection-model fit.
ArgumentError	x is not a fitted model.

Metafor reference

baujat

uni_coordinates

uni_coordinates(
    x: RMAResult, progbar: bool = False
) -> tuple[
    NDArray[float64], NDArray[float64], NDArray[intp], int
]

The squared Pearson residuals, the influence values, the 0-based rows of the studies and k_all of an rma_uni fit.

binary_coordinates

binary_coordinates(
    x: FixedBinaryResult, progbar: bool = False
) -> tuple[
    NDArray[float64], NDArray[float64], NDArray[intp], int
]

As :func:uni_coordinates for an rma_mh or rma_peto fit: each table with complete counts is left out in turn (baujat.rma).

qqnorm

Normal quantile-quantile plot of the (standardised or studentised) residuals (metafor's qqnorm.rma.uni).

The plot can show a simulated pseudo confidence envelope around the line of equality, obtained by simulating normal data and applying the model's hat matrix (Cook & Weisberg, 1982, as cited by metafor); see https://wviechtb.github.io/metafor/reference/qqnorm.rma.html.

QQNormResult dataclass

QQNormResult(
    ax: Axes,
    x: FloatArray,
    y: FloatArray,
    lb: FloatArray | None = None,
    ub: FloatArray | None = None,
)

Theoretical (x) and sample (y) quantiles (what qqnorm() returns), the envelope (if drawn) and the axes.

qqnorm

qqnorm(
    y: RMAResult
    | RMAMVResult
    | RMALSResult
    | FixedBinaryResult,
    type: str = 'rstandard',
    pch: int = 21,
    col: str | None = None,
    bg: str | None = None,
    grid: bool | str = False,
    envelope: bool | str = True,
    level: float | None = None,
    bonferroni: bool = False,
    reps: int = 1000,
    smooth: bool = True,
    bass: float = 0,
    label: bool | int | str = False,
    offset: float = 0.3,
    pos: int = 13,
    lty: str | Sequence[str] | None = None,
    *,
    seed: int | None = None,
    rng: RRandom | None = None,
    ax: Axes | None = None,
    main: str = 'Normal Q-Q Plot',
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> QQNormResult

Normal Q-Q plot of the residuals of a model (qqnorm.rma.uni, qqnorm.rma.mh and qqnorm.rma.peto).

Mirrors metafor's qqnorm.rma().

type selects 'rstandard' or 'rstudent' residuals. envelope draws the simulated pseudo CI (a colour string sets its colour; level its confidence level, bonferroni applies a Bonferroni correction, reps the number of simulations, smooth/bass the Friedman super smoother applied to its bounds); seed seeds the R-compatible generator so that the envelope reproduces R's set.seed(seed). label (True/'all', a number of the most deviating points or 'out' for the points outside the envelope) labels points with the study labels at position pos (1-4, or 13/24 to place them depending on the side of the line). grid adds a grid, lty the line types of the line of equality and the envelope. main is the title of the plot. na_action stands for R's options(na.action=): 'fail' stops when studies were left out of the fit, the other choices give the same plot. For rma_mh and rma_peto fits no envelope is drawn (so label='out' labels nothing), as in metafor.

Parameters:

Name	Type	Description	Default
y	RMAResult | RMAMVResult | RMALSResult | FixedBinaryResult	A fitted model (rma_uni, rma_mh, rma_peto or a location-scale model).	required
type	str	Residuals to plot: 'rstandard' (the default) or 'rstudent'.	'rstandard'
pch	int	Plotting symbol of the points (R's pch code; the default 21 is a circle with border col and fill bg).	21
col	str | None	Border colour of the points (a matplotlib colour, R names such as 'gray50' are translated). Default: the foreground colour (black).	None
bg	str | None	Fill colour of the points for symbols with a separate fill. Default: a grey adjusted from the background.	None
grid	bool | str	Add a grid. True, False or a colour string for the grid lines.	False
envelope	bool | str	Draw the simulated pseudo confidence envelope; a colour string sets its colour (default: light grey). No envelope is drawn for rma_mh and rma_peto fits. With label='out' and a bool envelope the envelope is drawn, as in metafor.	True
level	float | None	Confidence level of the envelope, between 0 and 100 (95 or 0.95 for 95 percent). Default: the level of the model.	None
bonferroni	bool	Apply a Bonferroni correction to the envelope.	False
reps	int	Number of simulations for the envelope.	1000
smooth	bool	Smooth the bounds of the envelope with the Friedman super smoother.	True
bass	float	Degree of smoothing of the super smoother (metafor: a number between 0 and 10, higher is smoother).	0
label	bool | int | str	Label points with the study labels: True or 'all', 'out' for the points outside the envelope, or a number from 1 to k (rounded) for how many of the most extreme points to label. Default: False.	False
offset	float	Distance of the labels from the points, as a fraction of the character size (R's text() offset).	0.3
pos	int	Position of the labels: 1 to 4 as in R (below, left, above, right); 13 places a label below the point if it is below the reference line and above otherwise; 24 places it to the left if the point is above the reference line and to the right otherwise.	13
lty	str | Sequence[str] | None	Line types of the line of equality and of the envelope bounds, as a pair (one value gives both the same type). Default: ('solid', 'dotted'). Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	None
seed	int | None	Seed of the R-compatible generator, so that the envelope reproduces R's set.seed(seed).	None
rng	RRandom | None	An explicit R-compatible random number generator, used instead of seed if both are given. Without either, the package's shared generator.	None
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
main	str	Title of the plot (default 'Normal Q-Q Plot').	'Normal Q-Q Plot'
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail'; the first three give the same plot, 'fail' raises when studies were left out of the fit.	'omit'

Returns:

Type	Description
QQNormResult	The plotted theoretical quantiles and residuals, the envelope and the axes.

Raises:

Type	Description
InputError	type or na_action is unknown, k is 1, label is a number outside 1 to k, level is outside 0 to 100, or 'fail' and studies were left out of the fit.
NotSupportedError	y is an rma.mv, rma.glmm, robust or selection-model fit (qqnorm.rma.mv only stops in metafor).
ArgumentError	y is not a fitted model.
InternalError	an envelope is drawn for a model class that has no hat matrix.

Metafor reference

qqnorm.rma

plot_rma

plot_rma(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult,
    qqplot: bool = False,
    *,
    seed: int | None = None,
    ax: Axes | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
    **kwargs: Any,
) -> PlotRmaResult | SelPlotResult

Draw the forest, funnel, radial and residual plots of a model (metafor's plot() of an rma.uni, rma.mh or rma.peto fit).

Mirrors metafor's plot.rma.uni().

For a model without moderators the panels are forest, funnel, radial and the standardized residuals (rstandard) of the studies in order; for a meta-regression the funnel plot shows the residuals and the radial plot is replaced by the standardized residuals against the fitted values. qqplot=True draws qqnorm (with seed for its envelope) instead of the last panel. The panels fill ax (default: the current axes) in a 2 x 2 grid, as par(mfrow = c(2, 2)) does. A selection model (rma.uni.selmodel) is drawn by plot_selmodel, which gets kwargs, as R's plot() dispatches to plot.rma.uni.selmodel. na_action stands for R's options(na.action=): with 'omit' (default) the last panel and the third panel of a meta-regression show the studies used in fitting, with 'exclude' and 'pass' every study of the subset (a gap where a value is missing), and 'fail' stops when studies were left out of the fit.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult	A model fitted by rma_uni, rma_mh or rma_peto, or a selection model.	required
qqplot	bool	Draw the normal Q-Q plot instead of the last panel. Default: False.	False
seed	int | None	Seed of the R-compatible generator for the envelope of the Q-Q plot (only with qqplot=True). Default: the package's shared generator.	None
ax	Axes | None	Matplotlib axes whose area the four panels fill (2 x 2 grid). Default: the current axes.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail'. See above for what each shows.	'omit'
**kwargs	Any	plot_selmodel arguments, for selection models only. (Unlike metafor's ..., they are not passed on to the panels of the other models, which take no further arguments.)	{}

Returns:

Type	Description
PlotRmaResult | SelPlotResult	A PlotRmaResult with the four axes, the results of the panels (forest, funnel, radial and qqnorm; radial is None for a
PlotRmaResult | SelPlotResult	meta-regression and qqnorm unless qqplot=True), the standardized residuals z and their 1-based study numbers ids of the last
PlotRmaResult | SelPlotResult	panel (empty with qqplot=True) and the fitted values of the third panel of a meta-regression (empty otherwise). For a selection model, the
PlotRmaResult | SelPlotResult	result of plot_selmodel.

Raises:

Type	Description
ArgumentError	kwargs are given for a model that is not a selection model.
InputError	na_action is unknown, or 'fail' and studies were left out of the fit.
NotSupportedError	the model is an rma_mv, rma_glmm, location-scale or robust fit (metafor has no such method).

Metafor reference

plot.rma

plot_infl

plot_infl(
    x: InfluenceResult,
    plotinf: bool | int | Sequence[int] = True,
    plotdfbs: bool | int | Sequence[int] = False,
    dfbsnew: bool = False,
    logcov: bool = True,
    slab_style: int = 1,
    las: int = 0,
    pch: int = 21,
    bg: str | None = None,
    bg_infl: str = 'red',
    col_na: str | None = None,
    *,
    ids: Iterable[int | str] | None = None,
    na_action: str = 'omit',
    mfrow: tuple[int, int] | None = None,
    ax: Axes | None = None,
    layout: object = None,
) -> PlotInflResult

Plot the case-deletion diagnostics returned by influence (plot.infl.rma.uni).

Mirrors metafor's plot.infl.rma.uni().

plotinf selects the diagnostics (True for all eight, or their numbers 1-8: rstudent, dffits, cook.d, cov.r, tau2.del, QE.del, hat and weight) and plotdfbs the DFBETAS (True for all, or the numbers of the coefficients, starting at 1 as in metafor). Influential studies are drawn in bg_infl. slab_style chooses the labels of the x-axis (1 = ids, 2 = study labels, 3 = abbreviated study labels); ids defaults to 1..k. na_action is 'omit' (leave out studies with missing diagnostics) or 'exclude'/'pass' (keep them, joining the other points with a line in col_na). The diagnostics are drawn into a grid of panels filling ax, with the number of rows and columns of metafor's default (par(mfrow = ...)) unless mfrow=(rows, columns) is given, e.g. (8, 1) for one column of panels; the DFBETAS are drawn on a new figure if the diagnostics are also plotted (or dfbsnew is true), as metafor starts a new page for them. layout is accepted for old code and ignored with a warning, as metafor does.

Parameters:

Name	Type	Description	Default
x	InfluenceResult	The case-deletion diagnostics returned by influence.	required
plotinf	bool | int | Sequence[int]	Diagnostics to plot: True for all eight, or their numbers 1 to 8 (rstudent, dffits, cook.d, cov.r, tau2.del, QE.del, hat, weight; numbers outside 1 to 8 are dropped, others rounded). False plots none, which needs plotdfbs.	True
plotdfbs	bool | int | Sequence[int]	DFBETAS to plot: True for all, or the numbers of the coefficients (starting at 1 as in metafor; numbers outside 1 to the number of coefficients are dropped). Default: False.	False
dfbsnew	bool	Has no effect here: the DFBETAS are always drawn on a new figure when the diagnostics are drawn too, and on ax when they are not (metafor's dfbsnew=FALSE waits for a page change on the same device).	False
logcov	bool	Plot the covariance ratios (diagnostic 4) on a log scale. Default: True.	True
slab_style	int	Labels of the horizontal axis: 1 for the study numbers (or ids), 2 for the study labels, 3 for abbreviated study labels. Default: 1.	1
las	int	Orientation of the horizontal-axis tick labels (R's par(las=) values 0 to 3): 2 and 3 draw them vertical, 0 and 1 horizontal. The vertical-axis labels are not affected, and other values are not checked. Default: 0.	0
pch	int	Plotting symbol of the points (R's pch code). Default: 21, a circle with border black and fill bg.	21
bg	str | None	Fill colour of the points. Default: grey.	None
bg_infl	str	Fill colour of the influential studies. Default: 'red'.	'red'
col_na	str | None	Colour of the line joining the points around missing diagnostics (na_action 'exclude' or 'pass'). Default: light grey.	None
ids	Iterable[int | str] | None	Study identifiers for the horizontal axis when slab_style is 1, one per study. Default: 1..k.	None
na_action	str	What to do with missing diagnostics (R's options(na.action=)): 'omit' (the default) leaves out studies with missing diagnostics, 'exclude' and 'pass' keep them (a gap, with the other points joined by a line in col_na) and 'fail' raises if there are any.	'omit'
mfrow	tuple[int, int] | None	Number of rows and columns of the grid of panels for the diagnostics, e.g. (8, 1) for one column. Default: one panel for 1, two rows for 2, three for 3, 2 x 2 for 4, 5 x 1 for 5, 3 x 2 for 6, 7 x 1 for 7 and 4 x 2 for 8 diagnostics (as metafor does).	None
ax	Axes | None	Matplotlib axes whose area the panels fill. Default: the current axes.	None
layout	object	Accepted for old code and ignored with a warning, as metafor does.	None

Returns:

Type	Description
PlotInflResult	A PlotInflResult with the axes of the diagnostics (axes) and of the DFBETAS (dfbs_axes, empty unless drawn).

Raises:

Type	Description
ArgumentError	x is not an InfluenceResult, for example a fitted model (influence itself is not available for rma_mv fits, so there is no such result for them either).
InputError	plotinf or plotdfbs selects nothing, neither is requested, na_action is unknown or 'fail' and diagnostics are missing, ids or the labels have the wrong length, or mfrow has fewer panels than diagnostics.

Metafor reference

plot.infl.rma.uni

plot_profile

plot_profile(
    x: ProfileResult
    | LSProfileResult
    | Sequence[ProfileResult | LSProfileResult],
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    pch: int = 19,
    xlab: str | Sequence[str] | None = None,
    ylab: str | Sequence[str] | None = None,
    main: str | Sequence[str] | None = None,
    refline: bool = True,
    cline: bool | float = False,
    *,
    ax: Axes | None = None,
    log: str | None = None,
    cex: float = 1.0,
    lwd: float = 1.0,
) -> Axes | list[Axes]

Plot the profile (log-)likelihood computed by profile (plot.profile.rma).

Mirrors metafor's plot.profile.rma(), which is documented with profile.rma.

refline marks the estimate and its (log-)likelihood with dotted lines, cline (True for a significance level of 0.05, or a number as for metafor's level arguments) adds a horizontal line at the likelihood-ratio test's critical value. The estimate itself is added to the profile if it lies within the range of the grid. Returns the axes.

x may also be the list of profiles that profile returns for models with several variance components (rma_mv, location-scale and selection models): one panel per component is drawn in a grid, as par(mfrow = n2mfrow(comps)) makes it (inside ax if given), and the list of axes is returned. xlab, ylab and main are then one string for all panels or one per panel. Unlike metafor, refline also applies to the panels of a list. log ('x', 'y' or 'xy') draws logarithmic axes, cex is the size of the points and lwd the width of the line, which metafor passes on through ....

Parameters:

Name	Type	Description	Default
x	ProfileResult | LSProfileResult | Sequence[ProfileResult | LSProfileResult]	A profile from profile, or the list of profiles it returns for models with several variance components (rma_mv, location-scale and selection models; one panel per component).	required
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high). Default: those stored in the profile (x.xlim).	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high). Default: those stored in the profile (x.ylim).	None
pch	int	Plotting symbol of the points (R's pch code). Default: 19.	19
xlab	str | Sequence[str] | None	Label of the horizontal axis; for a list of profiles one string for all panels or one per panel. Default: derived from the profiled component (for example tau^2 Value).	None
ylab	str | Sequence[str] | None	Label of the vertical axis; for a list of profiles one string for all panels or one per panel. Default: 'Log-Likelihood' (or 'Likelihood' if the profile was computed with exp), preceded by 'Restricted ' for REML.	None
main	str | Sequence[str] | None	Title; for a list of profiles one string for all panels or one per panel. Default: 'Profile Plot for' and the component.	None
refline	bool	Mark the estimate and its (log-)likelihood with dotted lines (unlike metafor, also applies to the panels of a list). Default: True.	True
cline	bool | float	Add a horizontal dotted line at the critical value of the likelihood-ratio test: True for a significance level of 0.05, or a number read as metafor's level is (95 or 0.95 for 95 percent, 0.05 for a significance level of 5 percent). Default: False.	False
ax	Axes | None	Matplotlib axes to draw into (for a list of profiles, the area the panels fill). Default: the current axes.	None
log	str | None	Logarithmic axes: 'x', 'y' or 'xy'. Default: linear axes.	None
cex	float	Size of the points relative to the default. Default: 1.	1.0
lwd	float	Width of the line. Default: 1.	1.0

Returns:

Type	Description
Axes | list[Axes]	The axes drawn into (a list of axes, one per component, for a list of profiles).

Raises:

Type	Description
InputError	xlab, ylab or main does not have one entry per profile (or is not a single string for a single profile), a limit of a logarithmic axis is not positive, or cline is outside 0 to 100.

Metafor reference

profile.rma

plot_gosh

plot_gosh(
    x: GoshResult,
    het: str = 'I2',
    pch: int = 16,
    cex: float | None = None,
    out: int | None = None,
    col: str | Sequence[str] | None = None,
    alpha: float | Sequence[float] | None = None,
    border: str | Sequence[str] | None = None,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    xhist: bool = True,
    yhist: bool = True,
    hh: float | Sequence[float] = 0.3,
    breaks: Any = None,
    adjust: float | Sequence[float] | None = None,
    lwd: float | Sequence[float] | None = None,
    labels: Sequence[str] | None = None,
    trim: float
    | Sequence[float | Sequence[float]]
    | None = None,
    *,
    ax: Axes | None = None,
) -> PlotGoshResult

Plot the results of gosh (plot.gosh.rma).

Mirrors metafor's plot.gosh.rma().

For a model without moderators the heterogeneity statistic het ('QE', 'I2', 'H2', 'tau2' or 'tau') is plotted against the estimate, with marginal histograms and kernel density estimates (xhist, yhist; hh the relative sizes of the marginal plots, breaks, adjust and lwd their settings, each a single value or a pair for the two margins); with moderators a scatterplot matrix of het and the coefficients is drawn. out (0-based) highlights the subsets that do (col[0]) or do not include that study, alpha gives the transparency of the points, histogram and density line, trim removes the most extreme subsets (a proportion or a list of proportions per column). The panels fill the area of ax.

Parameters:

Name	Type	Description	Default
x	GoshResult	The result of gosh.	required
het	str	Heterogeneity statistic to plot: 'QE', 'I2' (the default), 'H2', 'tau2' or 'tau' ('I^2', 'H^2' and 'tau^2' are accepted too). 'tau2' and 'tau' are not available for equal-effects models.	'I2'
pch	int	Plotting symbol of the points (R's pch code). Default: 16, a filled circle without border.	16
cex	float | None	Expansion factor of the points. Default: 0.5.	None
out	int | None	0-based index of a study to highlight (metafor's out counts from 1): the subsets that include it are drawn in col[0], those without in col[1]. Default: no highlighting.	None
col	str | Sequence[str] | None	Colour of the points. Default: black. With out it must be two colours (subsets with the out study, subsets without it), default ('red', 'blue').	None
alpha	float | Sequence[float] | None	Transparency (0 transparent to 1 opaque) of the points, of the histogram bars and of the density lines: one value for the points (the histograms then get 0.5 and the density lines 0.9), two for points and histograms, or all three. Default: n ** -0.2 for n subsets.	None
border	str | Sequence[str] | None	Border colour of the histogram bars, one for both or a pair (horizontal, vertical margin). Default: light grey. (metafor's FALSE, which omits the borders, is not supported.)	None
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high); models without moderators only. Default: the range of the histogram breaks of the estimates.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high); models without moderators only. Default: the range of the histogram breaks of het.	None
xhist	bool	Draw the marginal histogram and density of the estimates; models without moderators only. Default: True.	True
yhist	bool	Draw the marginal histogram and density of the heterogeneity statistic; models without moderators only. Default: True.	True
hh	float | Sequence[float]	Relative size of the marginal plots, between 0 and 1 (checked for models without moderators); a single value or a pair for the two margins. For models with moderators it stretches the height of the histograms on the diagonal. Default: 0.3.	0.3
breaks	Any	Histogram breaks of the marginal plots, as for R's hist; a single value or a pair. Default: 'Sturges'.	None
adjust	float | Sequence[float] | None	Bandwidth adjustment of the kernel density estimates (larger is smoother); a single value or a pair. Default: 1.	None
lwd	float | Sequence[float] | None	Width of the density lines, 0 omits them; a single value or a pair. Default: 2.	None
labels	Sequence[str] | None	The labels of the horizontal and vertical axes (no moderators) or the names of the variables of the scatterplot matrix. Default: derived from the effect size measure, het and the coefficient names.	None
trim	float | Sequence[float | Sequence[float]] | None	Remove the most extreme subsets before plotting (an undocumented argument of metafor, passed through ...): the proportion to cut from each tail of every variable (het and the coefficients), or a list with one proportion, or a (lower, upper) pair, per variable.	None
ax	Axes | None	Matplotlib axes whose area the panels fill. Default: the current axes.	None

Returns:

Type	Description
PlotGoshResult	A PlotGoshResult: for a model without moderators main is the scatterplot and xhist and yhist the marginal histograms (None if
PlotGoshResult	not drawn); for a scatterplot matrix main, xhist and yhist are None and panels holds the axes row by row. axes lists
PlotGoshResult	whichever were drawn.

Raises:

Type	Description
InputError	het is unknown or 'tau2'/'tau' is used for an equal-effects model, out is not a study, col does not have two colours when out is used, or hh is outside 0 to 1.

Metafor reference

plot.gosh.rma

plot_selmodel

plot_selmodel(
    x: SelmodelResult,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    n: int = 1000,
    prec: str | float = 'max',
    scale: bool = False,
    ci: bool | str = False,
    reps: int = 1000,
    shade: bool | str = True,
    rug: bool = True,
    add: bool = False,
    lty: str | int | Sequence[str | int] = LINE_STYLES,
    lwd: float | Sequence[float] = (2.0, 1.0),
    seed: int | None = None,
    draw: bool = True,
    *,
    ax: Axes | None = None,
    bty: str = 'o',
    col: str | None = None,
) -> SelPlotResult

Draw the selection function of a selection model against the p-value.

Mirrors metafor's plot.rma.uni.selmodel().

prec fixes the precision at which the function is drawn ('min', 'max', 'mean', 'median' or a number). ci adds a confidence region: 'wald' transforms the Wald bounds of the selection parameters, 'boot' (or True) simulates reps parameter vectors from their estimated multivariate normal distribution (with NumPy's generator seeded by seed, so the bounds agree with metafor only up to simulation error). scale rescales the curve to the unit interval, shade fills the region, rug marks the observed p-values and add draws into existing axes. draw=False only computes the curve. bty (the type of box around the plot) and col (the colour of the lines) are passed on to plot() and lines() by metafor. The curve is returned as SelPlotResult.

Parameters:

Name	Type	Description	Default
x	SelmodelResult	A selection model from selmodel.	required
xlim	Sequence[float] | None	Limits of the horizontal axis (the p-values for which the function is drawn), within 0 and 1. Default: the model's smallest p-value pval_min to 1 - pval_min, which is 0 to 1 unless the selection function or the pval.min control of selmodel sets a small positive minimum (1e-5 for some functions).	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high). Default: 0 to 1 for the bounded selection functions (halfnorm, halfnorm2, logistic, logistic2, negexp, negexp2, negexppow, power, power2), otherwise the range of the curve (and of the confidence region).	None
n	int	Number of p-values within xlim at which the function is computed. Default: 1000. For step functions the step points are added.	1000
prec	str | float	Precision at which a selection function that involves one is drawn: 'min' (the most precise study), 'max' (the default, the least precise study), 'mean', 'median' or a number (1 corresponds to 'max', smaller values to higher precision; the number is replaced by 1 if the model was fitted without the prec argument of selmodel).	'max'
scale	bool	Rescale the curve (and region) to the 0 to 1 range. Default: False.	False
ci	bool | str	Add a confidence region around the curve: False (the default), True or 'boot' (parametric bootstrap: reps parameter vectors are simulated from the estimated multivariate normal distribution of the selection parameters, with NumPy's generator, so the bounds agree with metafor only up to simulation error), or 'wald' (the curve at the Wald bounds of the parameter; for models with a single selection parameter and for step functions). Nothing is drawn if the model has no standard errors for the parameters.	False
reps	int	Number of simulated parameter vectors for the 'boot' region. Default: 1000.	1000
shade	bool | str	Shade the confidence region: True (the default, light grey), False or a colour.	True
rug	bool	Mark the observed p-values along the horizontal axis (not with add). Default: True.	True
add	bool	Add the curve to the existing axes without drawing a new frame, labels or rug. Default: False.	False
lty	str | int | Sequence[str | int]	Line types of the selection function and of the confidence region bounds, as a pair (a single value serves the curve and the bounds get 'dotted'). Default: ('solid', 'dotted'). Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	LINE_STYLES
lwd	float | Sequence[float]	Line widths of the selection function and of the confidence region bounds, as a pair (a single value serves the curve and the bounds get 1). Default: (2, 1).	(2.0, 1.0)
seed	int | None	Seed of NumPy's generator for the 'boot' region (not R's generator). Default: not seeded.	None
draw	bool	If False only compute the curve and do not draw (the returned ax is None). Default: True.	True
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
bty	str	Type of box around the plot: 'o' (the default), 'l', '7', 'c', 'u', ']' or 'n' (none). Ignored with add.	'o'
col	str | None	Colour of the curve and of the confidence region bounds (the shading has its own colour shade). Default: black.	None

Returns:

Type	Description
SelPlotResult	A SelPlotResult with the p-values xs, the selection function ys, the confidence bounds ys_lb and ys_ub (NaN without a
SelPlotResult	confidence region) and the axes ax (None if draw is false).

Raises:

Type	Description
InputError	the model has a truncated selection function or none; ci is unknown; xlim or ylim does not have two values or xlim is outside 0 to 1; prec is an unknown string; or ci='wald' is not possible for the model.

Metafor reference

plot.rma.uni.selmodel

regplot

Meta-analytic scatterplot (metafor's regplot.rma) and its points method (points.regplot).

Plots the observed effects against one moderator of a meta-regression model, with the size of each point given by its weight (or a precision), the fitted regression line and, optionally, the pointwise confidence and prediction bands. See https://wviechtb.github.io/metafor/reference/regplot.html, https://github.com/wviechtb/metafor/blob/master/R/regplot.rma.r, https://github.com/wviechtb/metafor/blob/master/R/points.regplot.r and Thompson & Higgins (2002), doi:10.1002/sim.1187.

RegplotResult dataclass

RegplotResult(
    ax: Axes,
    xi: FloatArray,
    yi: FloatArray,
    psize: FloatArray,
    pred: FloatArray | None,
    label: NDArray[bool_],
    slab: tuple[str, ...],
    order: NDArray[intp],
    offset: tuple[float, ...],
    labsize: float,
    ids: NDArray[intp],
    pch: tuple[int, ...],
    col: tuple[Any, ...],
    bg: tuple[Any, ...],
)

The plotted points (what metafor's regplot() returns invisibly) and the axes drawn on.

xi and yi are the coordinates of the studies drawn (yi after any transformation), psize the symbol sizes (the cex of the points), label which studies were labelled, pred the fitted values and order the order in which the points were drawn (largest symbols first). ids are the 0-based positions of the studies among the rows supplied, pch, col and bg the symbols and colours of the points, and offset and labsize those of the labels, so that :func:points_regplot can redraw the points and labels (metafor's points() of a regplot object).

points

points(ax: Axes | None = None) -> None

Redraw the points and labels; see :func:points_regplot.

expand

expand(v: Any, n: int, name: str) -> list[Any]

An argument that is one value or one value per study (.expand1() and the length check of metafor).

Raises:

Type	Description
InputError	v has one value per study but not n of them.

find_moderator

find_moderator(
    x: FitView,
    names: Sequence[str],
    mod: str | int | None,
    grep: bool = False,
    fixed: bool = False,
) -> int

The 0-based position of the moderator among the coefficients (metafor's mod, with its grep and fixed arguments).

A string is matched against the coefficient names by charmatch() (exactly, or as the start of a single name); with grep=True it is searched for in the names as a regular expression (fixed=True: as a literal string) and must be found in exactly one.

Raises:

Type	Description
InputError	mod is None for a model with several predictors, is not found or not unique, or is a position outside the model.

symbol_sizes

symbol_sizes(
    psize: Any,
    weights: NDArray[float64],
    vi: NDArray[float64],
    plim: Sequence[float],
) -> NDArray[float64]

The cex of the points: the given sizes, or the weights (or 'seinv'/'vinv') rescaled to plim.

Raises:

Type	Description
InputError	a numeric psize has the wrong length, plim has fewer than two values, or psize is an unknown string.

sorted_pair

sorted_pair(
    lb: NDArray[float64], ub: NDArray[float64]
) -> tuple[NDArray[float64], NDArray[float64]]

.psort(): the smaller of each pair first (transformations may reverse the order).

regplot

regplot(
    x: RMAResult
    | RMAMVResult
    | FixedBinaryResult
    | RMALSResult
    | SelmodelResult
    | GLMMResult,
    mod: str | int | None = None,
    pred: bool | PredictResult = True,
    ci: bool = True,
    pi: bool = False,
    shade: bool | str | Sequence[str] = True,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    predlim: Sequence[float] | None = None,
    olim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    at: ArrayLike | None = None,
    digits: float | Sequence[float] = 2,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    level: float | None = None,
    pch: int | Sequence[int] = 21,
    psize: float | str | Sequence[float] | None = None,
    plim: Sequence[float] = (0.5, 3.0),
    col: str | Sequence[str] | None = None,
    bg: str | Sequence[str] | None = None,
    slab: Sequence[Any] | None = None,
    grid: bool | str = False,
    refline: float | None = None,
    label: bool | str | Sequence[Any] = False,
    offset: float | Sequence[float] = (1.0, 1.0),
    labsize: float = 1.0,
    lcol: str | Sequence[str] | None = None,
    lwd: float | Sequence[float] | None = None,
    lty: str | int | Sequence[str | int] | None = None,
    legend: bool | str | dict[str, Any] = False,
    xvals: ArrayLike | None = None,
    *,
    bty: str = 'o',
    las: int = 0,
    grep: bool = False,
    fixed: bool = False,
    ax: Axes | None = None,
    xaxt: str = 's',
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
    at_lab: Sequence[str] | None = None,
    box_lty: str = 'solid',
) -> RegplotResult

Meta-analytic scatterplot of a meta-regression model (regplot.rma).

Mirrors metafor's regplot().

mod is the moderator on the horizontal axis (its name, or its 0-based position among the coefficients; it may be left out when the model has a single moderator). The regression line (pred) and the confidence (ci) and prediction (pi) bands are drawn for the other moderators set to their means; xvals gives the moderator values to predict at, and pred may be a PredictResult for those values. transf transforms the effects and the bands, atransf only the labels of the vertical axis, and olim limits the values drawn. The points have the cex psize (or the square roots of the weights rescaled to plim; give 'seinv' or 'vinv' to scale the inverse standard errors or variances instead). label labels the studies (True/'all', 'ciout'/'piout' for those outside the bands, a boolean array or 0-based indices), with offset the distance from the point in percent of the vertical range and labsize the text size. legend adds a legend (True, a location such as 'topright' or a dict with x and cex); box_lty is the line type of its frame ('blank' for none). at_lab gives the labels of the ticks at of the vertical axis (one per value of at, or per tick when at is not given) instead of the formatted values.

bty ('o' or 'l') is the box type and las the orientation of the labels of the vertical axis (0 = parallel to it, 1 = horizontal). xaxt='n' leaves out the horizontal axis. grep=True makes a string mod a regular expression searched for in the coefficient names (which must find exactly one) and fixed=True a literal string instead (the grep and fixed arguments metafor reads through ...). na_action stands for R's options(na.action=): 'fail' stops when the regression line is drawn (pred=True) and studies were left out of the fit, the other choices give the same plot.

x is a fit of rma, including location-scale models, of selmodel, of rma_mv or of rma_glmm; the bands are the predictions of the model, so no prediction interval is drawn where predict gives none (location-scale models). The sizes of the points are equal for the models without weights (selmodel and rma_glmm fits).

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | FixedBinaryResult | RMALSResult | SelmodelResult | GLMMResult	A fitted meta-regression model: rma_uni (including location-scale models), selmodel, rma_mv or rma_glmm.	required
mod	str | int | None	Moderator on the horizontal axis: its name (matched exactly or as the start of one coefficient name), or its 0-based position among the coefficients (the intercept, if any, is position 0). May be left out when the model has a single moderator.	None
pred	bool | PredictResult	Draw the regression line (the other moderators are set to their means), or give a PredictResult for the values in xvals. Default: True.	True
ci	bool	Draw the confidence band. Default: True.	True
pi	bool	Draw the prediction band (none is drawn, with a warning, where the model gives no prediction interval). Default: False.	False
shade	bool | str | Sequence[str]	Shade the bands: True (the default, light greys), False, or colour(s) for the confidence and prediction bands (a single colour serves both).	True
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high). Default: the range of the moderator.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high). Default: the range of the (transformed) estimates and of the prediction band (if drawn) or confidence band, extended to include at.	None
predlim	Sequence[float] | None	Limits (low, high) of the moderator values for the regression line and bands. Default: the range of the moderator extended by 4 percent on each side.	None
olim	Sequence[float] | None	Limits (low, high) the estimates and the line and band bounds cannot exceed, for bounded measures. Default: none.	None
xlab	str | None	Label of the horizontal axis. Default: the coefficient name.	None
ylab	str | None	Label of the vertical axis. Default: derived from the effect size measure and transf/atransf.	None
at	ArrayLike | None	Positions of the tick marks of the vertical axis (on the transformed scale of transf, before atransf). Default: chosen automatically.	None
digits	float | Sequence[float]	Number of decimals of the vertical-axis tick labels (trailing zeros are kept) and of the level in the legend. Default: 2.	2
transf	Callable[..., Any] | None	Function applied to the estimates and to the line and band bounds before they are drawn. Not together with atransf.	None
atransf	Callable[..., Any] | None	Function applied to the vertical-axis tick labels only. Not together with transf.	None
targs	Any	Additional arguments passed to transf or atransf.	None
level	float | None	Confidence level of the bands (95 or 0.95 for 95 percent). Default: the level of the model.	None
pch	int | Sequence[int]	Plotting symbol of the points (R's pch code), or one per study used in the fit. Default: 21, a circle with border col and fill bg.	21
psize	float | str | Sequence[float] | None	Size (expansion factor) of the points: a number, one per study used in the fit, or 'seinv'/'vinv' to make the sizes proportional to the inverse standard errors or variances (rescaled to plim). Default: the square roots of the weights rescaled to plim (equal sizes for models without weights).	None
plim	Sequence[float]	Range (min, max) of the point sizes when psize is not a number or vector, with an optional third value as the minimum size. NaN for min scales the largest to max (the third value then enforces a minimum size); NaN for max scales the smallest to min (the third value then enforces a maximum size). Default: (0.5, 3).	(0.5, 3.0)
col	str | Sequence[str] | None	Border colour of the points, or one per study used in the fit (a matplotlib colour). Default: black.	None
bg	str | Sequence[str] | None	Fill colour of the points for symbols with a separate fill, or one per study used in the fit. Default: grey.	None
slab	Sequence[Any] | None	Study labels (for label): one per row of the data passed to the model fit, those of studies left out of the fit are dropped. Default: those of the model.	None
grid	bool | str	Add a grid: True, False or a colour string for the grid lines. Default: False.	False
refline	float | None	Position of a horizontal reference line. Default: none.	None
label	bool | str | Sequence[Any]	Label the studies: True or 'all', 'ciout'/'piout' for those outside the confidence/prediction band, a boolean array (one per study used in the fit) or 0-based indices of the studies used in the fit. Labels are above the points above the regression line, otherwise below. Default: False.	False
offset	float | Sequence[float]	Distance of the labels from the points, in percent of the vertical range: one value (a multiple of the point size) or a pair (added distance, multiple of the point size). Default: (1, 1).	(1.0, 1.0)
labsize	float	Text size of the labels, as an expansion factor. Default: 1.	1.0
lcol	str | Sequence[str] | None	Colours of up to four lines: the regression line, the confidence band bounds, the prediction band bounds and the reference line. A single colour serves all four; two give (line, both bounds) and three leave the reference line at its default. Default: black, black, black and grey.	None
lwd	float | Sequence[float] | None	Line widths of the same four lines, expanded like lcol. Default: 3, 1, 1 and 2.	None
lty	str | int | Sequence[str | int] | None	Line types of the same four lines, expanded like lcol. Default: solid, dashed, dotted and solid. Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	None
legend	bool | str | dict[str, Any]	Add a legend: True, a corner such as 'topright' (or a matplotlib legend loc), or a mapping whose 'x' is the location and 'cex' the size (other keys are ignored). Default: False.	False
xvals	ArrayLike | None	Moderator values to predict at, for the regression line and bands; required with a pred that is a PredictResult. Default: 1000 equally spaced values over predlim.	None
bty	str	Type of box around the plot, as R's bty: 'o' (the default), 'l', '7', 'c', 'u', ']' or 'n' (none).	'o'
las	int	Orientation of the vertical-axis tick labels: 0 (the default) parallel to the axis, any other value horizontal.	0
grep	bool	Treat a string mod as a regular expression searched for in the coefficient names (must match exactly one). Default: False.	False
fixed	bool	Treat a string mod as a literal string, not a regular expression (with grep). Default: False.	False
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
xaxt	str	'n' leaves out the horizontal axis; 's' (the default) draws it.	's'
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail'; the first three give the same plot, 'fail' raises when the regression line is drawn (pred=True) and studies were left out of the fit.	'omit'
at_lab	Sequence[str] | None	Labels of the vertical-axis tick marks at (one per value of at or, without at, per tick), instead of the formatted values.	None
box_lty	str	Line type of the frame of the legend ('blank' for none). Default: 'solid'.	'solid'

Returns:

Type	Description
RegplotResult	The plotted coordinates and the axes; pass it to points_regplot to redraw the points.

Raises:

Type	Description
InputError	the model has no moderator; mod is not found or not unique; transf and atransf are both given; psize is an unknown string or label an unknown string; a vector argument has the wrong length; predlim, olim or ylim has the wrong length; xvals is missing with a PredictResult; or na_action='fail' and studies were left out.
NotSupportedError	x is an rma_mh or rma_peto fit.
ArgumentError	x is not a fitted model.

Metafor reference

regplot

draw_points

draw_points(
    ax: Axes,
    xi: NDArray[float64],
    yi: NDArray[float64],
    pch: Sequence[int],
    psize: NDArray[float64],
    col: Sequence[Any],
    bg: Sequence[Any],
    order: NDArray[intp],
) -> None

Draw the points in order (the largest symbols first, so that the small ones are on top).

draw_labels

draw_labels(
    ax: Axes,
    xi: NDArray[float64],
    yi: NDArray[float64],
    pred: NDArray[float64] | None,
    psize: NDArray[float64],
    flags: NDArray[bool_],
    slab: Sequence[str],
    offset: Sequence[float],
    labsize: float,
) -> None

Label the flagged points above the point where the observed value is above the fitted one and below otherwise.

points_regplot

points_regplot(
    x: RegplotResult, ax: Axes | None = None
) -> None

Redraw the points (and the labels, if there were any) of a regplot (metafor's points.regplot).

Mirrors metafor's points() method for regplot objects (points.regplot).

The points are drawn on ax (default: the axes of the plot) in the order of x.order, which puts the points with the smallest symbols on top again after other elements were added to the plot.

Parameters:

Name	Type	Description	Default
x	RegplotResult	The result of regplot.	required
ax	Axes | None	Matplotlib axes to draw on. Default: the axes of the plot.	None

Raises:

Type	Description
InputError	x is not the result of regplot.

Metafor reference

regplot

dash

dash(name: str) -> Any

The matplotlib line style of an R line type name, or the name itself when it is already a style.

regplot_legend

regplot_legend(
    ax: Axes,
    legend: bool | str | dict[str, Any],
    addpred: bool,
    ci: bool,
    pi: bool,
    level: float,
    digits: int,
    lty: list[str],
    lcol: list[str],
    lwd: list[float],
    shade: list[str],
    col: list[Any],
    bg: list[Any],
    pch: list[int],
    box_lty: str = 'solid',
) -> None

The legend of regplot(): studies, regression line and the confidence and prediction intervals.

points_regplot

points_regplot(
    x: RegplotResult, ax: Axes | None = None
) -> None

Redraw the points (and the labels, if there were any) of a regplot (metafor's points.regplot).

Mirrors metafor's points() method for regplot objects (points.regplot).

The points are drawn on ax (default: the axes of the plot) in the order of x.order, which puts the points with the smallest symbols on top again after other elements were added to the plot.

Parameters:

Name	Type	Description	Default
x	RegplotResult	The result of regplot.	required
ax	Axes | None	Matplotlib axes to draw on. Default: the axes of the plot.	None

Raises:

Type	Description
InputError	x is not the result of regplot.

Metafor reference

regplot

forest_cumul

forest_cumul(
    x: CumulResult,
    *,
    annotate: bool = True,
    header: bool | str | Sequence[str] = True,
    xlim: Sequence[float] | None = None,
    alim: Sequence[float] | None = None,
    olim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    at: ArrayLike | None = None,
    steps: int = 5,
    refline: float | None = 0,
    digits: int | Sequence[float] | NDArray[floating] = 2,
    width: int | Sequence[int] | None = None,
    xlab: str | Sequence[str] | None = None,
    ilab: Any = None,
    ilab_lab: str | Sequence[str] | None = None,
    ilab_xpos: ArrayLike | None = None,
    ilab_pos: int | Sequence[int] | None = None,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    rows: ArrayLike | float | None = None,
    efac: float | Sequence[float] = 1,
    pch: int | Sequence[int] = 15,
    psize: float | ArrayLike = 1,
    col: str | Sequence[str] | None = None,
    colci: str | Sequence[str] | None = None,
    shade: bool | str | ArrayLike | None = None,
    colshade: str | None = None,
    lty: str | Sequence[str] | None = None,
    fonts: Any = None,
    cex: float | None = None,
    cex_lab: float | None = None,
    cex_axis: float | None = None,
    ax: Axes | None = None,
    annosym: Sequence[str] | None = None,
    tabfig: int | None = None,
    textpos: Sequence[float] | None = None,
    rowadj: float | Sequence[float] | None = None,
    top: float = 3,
    at_lab: Sequence[str] | None = None,
    xlabadj: float | Sequence[float] | None = None,
    xlabfont: int | Sequence[int] = 1,
) -> ForestResult

Cumulative forest plot (forest.cumul.rma): one row per step of a cumul analysis.

Mirrors metafor's forest.cumul.rma().

The first row is labelled with the first study, the others with + and the added study (Study and its label when the model had no study labels). The plot is that of forest for a vector of estimates with confidence intervals: there is no summary polygon, the arguments mean what they mean there for a vector x (so col colours the markers, interval lines and labels) and the confidence level is that of the cumulative analysis. forest(cumul(res), ...) is the same call (with warnings for the arguments of the fitted-model form that this plot does not have).

Parameters:

Name	Type	Description	Default
x	CumulResult	The result of cumul.	required
annotate	bool	Add the annotations (estimate and confidence interval) on the right. Default: True.	True
header	bool | str | Sequence[str]	True for the headings Study and, for the annotations, the estimate and CI level, False for none, a string for the left heading or a pair of strings for the left and right headings. Default: True.	True
xlim	Sequence[float] | None	Horizontal limits of the plot region. Default: the CI bounds extended on both sides for the labels and annotations.	None
alim	Sequence[float] | None	Limits of the x axis. Default: the range of at, else the pretty range of the CI bounds.	None
olim	Sequence[float] | None	Limits (lower, upper) that bound the estimates and the confidence interval bounds (values beyond them are set to the limits). Default: no limits.	None
ylim	Sequence[float] | None	Vertical limits of the plot region; a single value sets the lower limit only.	None
at	ArrayLike | None	Positions of the x-axis tick marks, on the scale that is plotted (after transf, before atransf). Default: chosen from alim and steps.	None
steps	int	Number of tick marks of the x axis: exact when alim is given, otherwise approximate. Ignored when at is given. Default: 5.	5
refline	float | None	Position of the dotted vertical reference line, or None for none. Not affected by lty. Default: 0.	0
digits	int | Sequence[float] | NDArray[floating]	Number of decimals of the annotations and of the x-axis labels, in this order (a third value is for weights, which this plot does not have). A single value is used for both. An integer drops trailing zeros from the axis labels, a float keeps them. Default: 2.	2
width	int | Sequence[int] | None	Minimum width (number of characters) of the annotation columns, one value or one per column. Default: the longest entry.	None
xlab	str | Sequence[str] | None	Label of the x axis, or three or two labels (see forest). Default: the 'Overall' label of the measure of the analysis (for example 'Overall Estimate' for no measure), adjusted for transf and atransf.	None
ilab	Any	Extra columns of information on the left: a vector, a matrix or a data frame with one row per step.	None
ilab_lab	str | Sequence[str] | None	Headings of the ilab columns.	None
ilab_xpos	ArrayLike | None	X positions of the ilab columns.	None
ilab_pos	int | Sequence[int] | None	Alignment of the ilab columns, as the pos argument of R's text(): 1 (below), 2 (to the left, so right-aligned), 3 (above) or 4 (to the right, so left-aligned). Default: centred.	None
transf	Callable[..., Any] | None	Function applied to the estimates and interval bounds. Cannot be used together with atransf.	None
atransf	Callable[..., Any] | None	Function applied to the x-axis labels and to the annotations. Cannot be used together with transf.	None
targs	Any	Additional arguments passed to transf or atransf.	None
rows	ArrayLike | float | None	Rows in which the steps are drawn: one per step, or a single value for the first. Default: counted down from the number of steps.	None
efac	float | Sequence[float]	Vertical expansion factors of the CI end bars and of the arrows: one value for both or two. Default: 1.	1
pch	int | Sequence[int]	Plotting symbol of the markers (an R code; 15 is a filled square). Default: 15.	15
psize	float | ArrayLike	Size of the markers: one value or one per step. Unlike forest the markers are not scaled by precision. Default: 1.	1
col	str | Sequence[str] | None	Colour of the markers, interval lines and labels: one value or one per step. Default: black.	None
colci	str | Sequence[str] | None	Colour of the confidence interval lines. Default: that of the markers.	None
shade	bool | str | ArrayLike | None	Shade rows: True or 'zebra' (alternate rows from the bottom), 'zebra2' (the other rows), 'all', a boolean array with one entry per step, or numbers, the plot rows to shade. Default: no shading.	None
colshade	str | None	Colour of the shading. Default: '#E5E5E5' (light grey).	None
lty	str | Sequence[str] | None	(CI lines, horizontal lines); a single value sets the first. Default: solid for both.	None
fonts	Any	Font family and font of the labels, annotations and ilab columns, as in forest.	None
cex	float | None	Character expansion factor of the text and symbols. Default: 1, reduced when the rows would not fit on the axes.	None
cex_lab	float | None	Character expansion factor of the x-axis label. Default: the value of cex.	None
cex_axis	float | None	Character expansion factor of the x-axis tick labels. Default: the value of cex.	None
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
annosym	Sequence[str] | None	Symbols of the annotations, as in forest (three, four or five strings).	None
tabfig	int | None	1, 2 or 3 replaces annosym by the symbols for fonts with tabular figures, as in forest.	None
textpos	Sequence[float] | None	(left, right) positions of the labels and annotations. Default: the limits of xlim.	None
rowadj	float | Sequence[float] | None	Vertical adjustment of the labels, annotations and ilab texts, as in forest. Default: 0.	None
top	float	Number of rows above the first step. Default: 3.	3
at_lab	Sequence[str] | None	Labels of the tick marks, one per position.	None
xlabadj	float | Sequence[float] | None	Alignment of the left and right x-axis labels, as in forest. Default: centred.	None
xlabfont	int | Sequence[int]	Font (1 to 4) of the x-axis labels, as in forest. Default: 1.	1

Returns:

Type	Description
ForestResult	A ForestResult as for forest (areas is None), with the artists on its ax.

Raises:

Type	Description
InputError	x is not the result of cumul, or an argument is invalid as for forest.

Metafor reference

forest.cumul.rma

plot_cumul

plot_cumul(
    x: CumulResult,
    yaxis: str | None = None,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    at: ArrayLike | None = None,
    transf: Callable[..., Any] | None = None,
    atransf: Callable[..., Any] | None = None,
    targs: Any = None,
    digits: int | Sequence[int] | None = None,
    cols: Sequence[str] | None = None,
    grid: bool | str = True,
    pch: int = 19,
    cex: float = 1.0,
    lwd: float = 2.0,
    *,
    las: int = 0,
    ax: Axes | None = None,
    addgrid: bool | str | None = None,
    na_action: Literal[
        'omit', 'exclude', 'pass', 'fail'
    ] = 'omit',
) -> PlotCumulResult

Plot of the results of a cumulative meta-analysis (plot.cumul.rma).

Mirrors metafor's plot.cumul.rma().

The pooled estimates (horizontal axis) are plotted against the amount of heterogeneity (yaxis 'tau2', 'tau', 'I2' or 'H2'; 'tau2' unless the model is a fixed-effects one), joined in order by a line whose colour runs from the first of cols to the last (light to dark by default). transf transforms the estimates, atransf only the labels of the horizontal axis, digits are the digits of the labels of the two axes and grid draws the dotted grid (a colour for the lines of the grid; addgrid is the old spelling that metafor reads from ... and wins).

na_action stands for R's options(na.action=): an unknown value raises, the others give the same result (metafor sets na.pass while it computes). With 'fail' missing values in the results stop the plot.

Parameters:

Name	Type	Description	Default
x	CumulResult	The result of cumul.	required
yaxis	str | None	Heterogeneity statistic on the vertical axis: 'tau2', 'tau', 'I2' or 'H2' (the first two need a random-effects model). Default: 'tau2' for a random-effects model, 'I2' for an equal-effects one.	None
xlim	Sequence[float] | None	Limits of the horizontal axis as (low, high), in either order. Default: the range of the (transformed) pooled estimates.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high), in either order. Default: the range of the heterogeneity statistic.	None
xlab	str | None	Label of the horizontal axis. Default: derived from the effect size measure.	None
ylab	str | None	Label of the vertical axis. Default: derived from yaxis.	None
at	ArrayLike | None	Positions of the tick marks of the horizontal axis (on the scale after transf, before atransf); the horizontal limits are widened to include them. Default: chosen automatically.	None
transf	Callable[..., Any] | None	Function applied to the pooled estimates before drawing. Not together with atransf.	None
atransf	Callable[..., Any] | None	Function applied to the labels of the horizontal axis only. Not together with transf.	None
targs	Any	Additional arguments passed to transf or atransf.	None
digits	int | Sequence[int] | None	Number of decimals of the tick labels of the horizontal axis and of the vertical axis: one integer for both or a pair (horizontal, vertical). Default: 2 and 3 for 'tau2'/'tau', 2 and 1 for 'I2'/'H2'.	None
cols	Sequence[str] | None	Colours (matplotlib colours) of the first and last step; the points and the line change from the first to the last. Only the first and last colour are used (metafor interpolates through all of them). Default: light grey to dark grey.	None
grid	bool | str	Draw the dotted grid; a colour string sets the colour of its lines. Default: True.	True
pch	int	Plotting symbol of the points (R's pch code). Default: 19, a filled circle.	19
cex	float	Expansion factor of the points. Default: 1.	1.0
lwd	float	Width of the line joining the steps. Default: 2.	2.0
las	int	Orientation of the vertical-axis tick labels: 0 (the default) parallel to the axis, any other value horizontal.	0
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None
addgrid	bool | str | None	Old spelling of grid (read from ... by metafor); wins over it when given.	None
na_action	Literal['omit', 'exclude', 'pass', 'fail']	What to do with missing values (R's options(na.action=)): 'omit' (the default), 'exclude', 'pass' or 'fail'; the first three give the same plot (steps with a missing estimate or statistic are left out), 'fail' raises when the results contain missing values.	'omit'

Returns:

Type	Description
PlotCumulResult	A PlotCumulResult with the axes ax, the plotted (transformed) pooled estimates estim, the heterogeneity statistic yval and the
PlotCumulResult	colour col of each step.

Raises:

Type	Description
InputError	x is not the result of cumul; yaxis or na_action is unknown, or yaxis needs a random-effects model; transf and atransf are both given; or 'fail' and results are missing.

Metafor reference

plot.cumul.rma

llplot

Plot of the likelihood functions of the individual studies (metafor's llplot).

For measure='GEN' each study contributes the normal likelihood of its effect size yi with sampling variance vi; for measure='OR' the likelihood of the (log) odds ratio is the conditional one given the margins of the 2x2 table, which follows Fisher's non-central hypergeometric distribution (Fog 2008, doi:10.1080/03610910701790236). With scale=True every likelihood is rescaled to area one, so that the curves show how much information each study has about the effect. See https://wviechtb.github.io/metafor/reference/llplot.html and van Houwelingen et al. (1993), doi:10.1002/sim.4780122405.

LlplotResult dataclass

LlplotResult(ax: Axes, xs: FloatArray, lls: FloatArray)

The likelihoods drawn (what metafor's llplot() returns invisibly): lls[i, j] is the likelihood of study i at xs[j].

Values outside of the (very wide) confidence interval of a study are NaN and not drawn.

odds_ratio_likelihood

odds_ratio_likelihood(
    a: NDArray[float64],
    b: NDArray[float64],
    c: NDArray[float64],
    d: NDArray[float64],
    xs: NDArray[float64],
) -> NDArray[float64]

The conditional likelihood of each table at the log odds ratios xs (rows are studies).

r_rank

r_rank(x: NDArray[float64]) -> NDArray[intp]

rank(x) as an integer index (average ranks of ties are truncated when used to index a vector, as R does).

llplot

llplot(
    measure: str = 'GEN',
    yi: ArrayLike | str | None = None,
    vi: ArrayLike | str | None = None,
    sei: ArrayLike | 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,
    data: Any = None,
    subset: ArrayLike | None = None,
    drop00: bool = True,
    xvals: int = 1000,
    xlim: Sequence[float] | None = None,
    ylim: Sequence[float] | None = None,
    xlab: str | None = None,
    ylab: str | None = None,
    scale: bool = True,
    lty: str | Sequence[str] | None = None,
    lwd: float | Sequence[float] | None = None,
    col: str | Sequence[str] | None = None,
    level: float = 99.99,
    refline: float | None = 0,
    *,
    onlyo1: bool = False,
    addyi: bool = True,
    addvi: bool = True,
    ax: Axes | None = None,
) -> LlplotResult

Plot the likelihood function of the true effect given the data of each study (llplot).

Mirrors metafor's llplot().

measure is 'GEN' (give yi with vi or sei) or 'OR' (give the counts ai, bi, ci, di, or ai, n1i, ci, n2i). Studies with no cases (or only cases) in both groups (drop00) are left out for 'OR'; if kept, they are drawn dotted, and tables with a single zero count dashed, as in metafor. xvals is the number of points of each curve, level the confidence level of the interval outside which the curves are not drawn, scale rescales each likelihood to area one, and lty, lwd and col are per study (by default the more precise studies get thicker and darker lines). refline draws a vertical line.

Parameters:

Name	Type	Description	Default
measure	str	'GEN' (the default; give yi with vi or sei) or 'OR' (give the counts ai, bi, ci, di, or ai, n1i, ci, n2i).	'GEN'
yi	ArrayLike | str | None	Observed effect sizes (array or column name of data), for measure='GEN'.	None
vi	ArrayLike | str | None	Sampling variances (array or column name), for measure='GEN'.	None
sei	ArrayLike | str | None	Standard errors (array or column name), for measure='GEN'; an alternative to vi, which takes precedence.	None
ai	ArrayLike | str | None	2x2 table counts, upper left cell (array or column name), for measure='OR'.	None
bi	ArrayLike | str | None	2x2 table counts, upper right cell.	None
ci	ArrayLike | str | None	2x2 table counts, lower left cell.	None
di	ArrayLike | str | None	2x2 table counts, lower right cell.	None
n1i	ArrayLike | str | None	Size of group 1 (the row total of the first row); an alternative to bi (bi = n1i - ai).	None
n2i	ArrayLike | str | None	Size of group 2 (the row total of the second row); an alternative to di (di = n2i - ci).	None
data	Any	Data frame holding the variables named (as column names) in the other arguments.	None
subset	ArrayLike | None	Which studies to use: a boolean array or an array of 0-based indices (into the data, so lty, lwd and col still have one value per study of the whole data).	None
drop00	bool	Drop studies with no cases (or only cases) in both groups (measure='OR'). If False they are kept and drawn dotted. Default: True.	True
xvals	int	Number of points at which each likelihood is evaluated. Default: 1000.	1000
xlim	Sequence[float] | None	Limits of the horizontal axis (the range of the curves) as (low, high), in either order. Default: the range of the confidence intervals of the studies at level.	None
ylim	Sequence[float] | None	Limits of the vertical axis as (low, high), in either order. Default: 0 to the largest likelihood.	None
xlab	str | None	Label of the horizontal axis. Default: 'Observed Outcome' for 'GEN', 'Log Odds Ratio' for 'OR'.	None
ylab	str | None	Label of the vertical axis. Default: 'Scaled Likelihood' or, without scale, 'Likelihood'.	None
scale	bool	Rescale each likelihood so that the area under its curve is (about) 1. Default: True.	True
lty	str | Sequence[str] | None	Line type of the curves: one value or one per study (of the whole data). Default: solid for 'GEN'; for 'OR' solid, dashed for tables with a single zero count and dotted for those with no cases (or only cases) in both groups. Accepts R names ('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash', 'blank'), R codes 0 to 6 or a matplotlib line style.	None
lwd	float | Sequence[float] | None	Line width of the curves: one value or one per study. Default: 4 to 0.4, thicker for the more precise studies (by the rank of the sampling variance).	None
col	str | Sequence[str] | None	Colour of the curves: one value or one per study (a matplotlib colour). Default: shades of grey from dark (the most precise study) to light (the least precise study).	None
level	float	Confidence level in percent of the interval of each study outside which its curve is not drawn (and which sets the default xlim). Default: 99.99.	99.99
refline	float | None	Position of a vertical reference line, or None (or NaN) for none. Default: 0.	0
onlyo1	bool	Passed to escalc: only the first outcome of the 2x2 tables is used.	False
addyi	bool	Passed to escalc: apply add to the effect size.	True
addvi	bool	Passed to escalc: apply add to the sampling variance.	True
ax	Axes | None	Matplotlib axes to draw into. Default: the current axes.	None

Returns:

Type	Description
LlplotResult	A LlplotResult with the axes ax, the xs at which the likelihoods were evaluated and the matrix lls of the likelihoods (one row per
LlplotResult	study, NaN outside the confidence interval of the study at level).

Raises:

Type	Description
ArgumentError	a count passed to escalc has the wrong type.
InputError	measure is not 'GEN' or 'OR'; the required variables are missing, of different lengths or the counts are invalid; lty, lwd or col has the wrong length; or no study remains.

Metafor reference

llplot

plot_permutest

plot_permutest(
    x: PermutestResult | LSPermutestResult,
    beta: Sequence[int | str] | int | str | None = None,
    alpha: Sequence[int | str] | int | str | None = None,
    QM: bool = False,
    QS: bool = False,
    breaks: object = 'Scott',
    freq: bool = False,
    col: str | None = None,
    border: str | None = None,
    col_out: str | None = None,
    col_ref: str | None = None,
    col_density: str | None = None,
    trim: float = 0.0,
    adjust: float = 1.0,
    lwd: float | Sequence[float] = (2, 0, 0, 4),
    legend: bool | str = False,
    *,
    alternative: str | None = None,
    p2defn: str | None = None,
    stat: str | None = None,
    ax: Axes | None = None,
    xlim: Sequence[float] | None = None,
    layout: object = None,
) -> PlotPermutestResult

Plot the permutation distributions of a permutest result (plot.permutest.rma.uni).

Mirrors metafor's plot.permutest.rma.uni().

One panel is drawn per selected element, in the order of metafor: the omnibus test of the location coefficients (QM=True), the location coefficients, the omnibus test of the scale coefficients (QS=True) and the scale coefficients. Each panel is the histogram of the permuted test statistics (or coefficients), the observed value is a dashed line and the tails beyond it are filled with col_out. The theoretical null distribution and the kernel density estimate are omitted by default (their lwd is 0). A single-coefficient plot has no panel title.

Trimming only affects the histogram; the kernel density estimate uses all permutations.

For an omnibus test with a single degree of freedom (QM=True and one coefficient tested) the theoretical density is infinite at 0. That point is left out of the curve and of the y range, whereas metafor stops with an infinite ylim there.

Parameters:

Name	Type	Description	Default
x	PermutestResult | LSPermutestResult	The result of permutest; a location-scale permutation test gives LSPermutestResult.	required
beta	Sequence[int | str] | int | str | None	Location coefficients to plot, as names or 0-based positions (R: 1-based). A single name or position is allowed. Default None: all coefficients but the intercept (the intercept only when it is the only coefficient). [] selects none.	None
alpha	Sequence[int | str] | int | str | None	Scale coefficients to plot, selected as beta. Only used for LSPermutestResult; default None: all but the intercept.	None
QM	bool	Add the panel of the omnibus test of the location coefficients (ignored for an intercept-only model). Default: False.	False
QS	bool	Add the panel of the omnibus test of the scale coefficients (LSPermutestResult only). Default: False.	False
breaks	object	The breaks argument of R's hist(): a number of bins, a rule name or a vector of break points. Default: 'Scott'.	'Scott'
freq	bool	Draw counts instead of densities. Forces lwd[1] and lwd[2] to 0, so no curves are drawn. Default: False.	False
col	str | None	Fill colour of the histogram bars. Default: '#B3B3B3' (light grey).	None
border	str | None	Border colour of the bars. Default: '#E5E5E5' (lighter grey).	None
col_out	str | None	Fill colour of the bars in the tails beyond the observed value. Default: '#FF000080' (semi-transparent red).	None
col_ref	str | None	Colour of the theoretical null distribution. Default: '#4C4C4C' (dark grey). The dashed line at the observed value and the vertical line at zero are always black.	None
col_density	str | None	Colour of the kernel density estimate. Default: 'blue'.	None
trim	float	Fraction of the permutations dropped from the histogram, which must be below 0.5. The omnibus panels drop the upper trim fraction, the coefficient panels drop trim / 2 from each tail. Default: 0.	0.0
adjust	float	Bandwidth adjustment of the kernel density estimate, as the adjust argument of R's density(). Default: 1.	1.0
lwd	float | Sequence[float]	Line widths of the dashed line at the observed value, of the theoretical null distribution, of the kernel density estimate and of the vertical line at zero (coefficient panels only). A width of 0 leaves the element out. A single number is used for the first three and 4 for the last; two or three values are completed to four (the second is repeated for the third, the last defaults to 4). Default: (2, 0, 0, 4).	(2, 0, 0, 4)
legend	bool | str	True or a location (for example 'topleft') for a legend naming the curves; drawn in the first panel only and only when a curve is drawn. True places it at the top right. Default: False.	False
alternative	str | None	'two.sided', 'greater' or 'less'. Default: that of the test.	None
p2defn	str | None	Definition of the two-sided p-value, 'abs' or 'px2'. Default: that of the test.	None
stat	str | None	Statistic plotted, 'test' (z or t values) or 'coef' (coefficients). Default: that of the test.	None
ax	Axes | None	Matplotlib axes to draw into; the panels are laid out inside it. Default: the current axes.	None
xlim	Sequence[float] | None	Limits of the horizontal axis of every panel. Default: the range of the histogram breaks. The plotted axis extends 4 percent beyond the limits, as in R.	None
layout	object	Deprecated and ignored; a warning is issued, as in metafor.	None

Returns:

Type	Description
PlotPermutestResult	A PlotPermutestResult with the fields axes (the axes of the panels drawn) and names ('QM', 'QS' or the
PlotPermutestResult	coefficient name of each panel, in the same order).

Raises:

Type	Description
InputError	trim is 0.5 or more; alternative, p2defn or stat is not a valid value; a coefficient name or position in beta or alpha does not exist; no panel is selected.

Metafor reference

plot.permutest.rma.uni

plot_vif

plot_vif(
    x: VIFResult,
    breaks: object = 'Scott',
    freq: bool = False,
    col: str | None = None,
    border: str | None = None,
    col_out: str | None = None,
    col_density: str | None = None,
    trim: float = 0.0,
    adjust: float = 1.0,
    lwd: float | Sequence[float] = (2, 0),
    *,
    tail: str = 'upper',
    ax: Axes | None = None,
    xlim: Sequence[float] | None = None,
    layout: object = None,
) -> PlotVifResult

Plot the simulated (G)VIFs of a vif result obtained with sim=True (plot.vif.rma).

Mirrors metafor's plot.vif.rma().

One panel is drawn per (G)VIF in x, titled Coefficient: name (Coefficients: name for a set of coefficients). Each panel is the histogram of the (G)VIFs simulated under independence of the moderators, with the observed (G)VIF as a dashed black vertical line and the bars beyond it filled with col_out. A (G)VIF beyond the right edge of the plot is drawn at the edge, with an arrow pointing to it. The kernel density estimate is omitted by default (its lwd is 0).

Parameters:

Name	Type	Description	Default
x	VIFResult	The result of vif obtained with sim=True.	required
breaks	object	The breaks argument of R's hist(): a number of bins, a rule name or a vector of break points. Default: 'Scott'.	'Scott'
freq	bool	Draw counts instead of densities. This turns off the kernel density estimate. Default: False.	False
col	str | None	Fill colour of the histogram bars. Default: '#B3B3B3' (light grey).	None
border	str | None	Border colour of the bars. Default: '#E5E5E5' (lighter grey).	None
col_out	str | None	Fill colour of the bars beyond the observed (G)VIF. Default: '#FF000080' (semi-transparent red). The observed value itself is always drawn in black.	None
col_density	str | None	Colour of the kernel density estimate. Default: 'blue'.	None
trim	float	Fraction (below 0.5) of the largest simulated values dropped from the histogram. Default: 0.	0.0
adjust	float	Bandwidth adjustment of the kernel density estimate, as the adjust argument of R's density(). Default: 1.	1.0
lwd	float | Sequence[float]	Line widths of the dashed line at the observed (G)VIF and of the kernel density estimate; a width of 0 leaves the element out. A single number is used for both. Default: (2, 0).	(2, 0)
tail	str	Tail of the simulated distribution filled beyond the observed (G)VIF, 'upper' or 'lower'. Not in metafor, which always fills the upper tail. Default: 'upper'.	'upper'
ax	Axes | None	Matplotlib axes to draw into; the panels are laid out inside it. Default: the current axes.	None
xlim	Sequence[float] | None	Limits of the horizontal axis of every panel. Default: the range of the histogram breaks. The plotted axis extends 4 percent beyond the limits, as in R.	None
layout	object	Deprecated and ignored; a warning is issued, as in metafor.	None

Returns:

Type	Description
PlotVifResult	A PlotVifResult with the fields axes (one axes per panel) and names (the coefficient names of the panels).

Raises:

Type	Description
InputError	x was not obtained with sim=True; trim is 0.5 or more; tail is neither 'lower' nor 'upper'.

Metafor reference

plot.vif.rma