Interactive charts

Interactive Vega-Lite charts, see Interactive charts. They need the interactive extra.

forest_chart

forest_chart(
    x: RMAResult | RMAMVResult | ChartData,
    *,
    transf: Callable[[ArrayLike], ndarray] | None = None,
    xlab: str | None = None,
    refline: float | None = 0.0,
    order: Literal['obs', 'weight', 'input'] = 'input',
    width: int = 560,
    **data_kwargs: Any,
) -> VConcatChart

Return an interactive forest plot: a row per study, then the pooled rows.

Each study is a rule from ci_lb to ci_ub and a square sized by weight; each pooled row is a diamond with its prediction interval as a thin rule. Hovering a study shows its estimate, interval and weight; clicking a linked study follows its href, and clicking a study highlights it (selection_point on slab). When x is a fit, the remaining keyword arguments go to chart_data. The chart inlines its data and uses fixed colours, so it renders alike in any embedding.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult | ChartData	An intercept-only fit, or a ChartData (hand-built or from chart_data()).	required
transf	Callable[[ArrayLike], ndarray] | None	Transformation of the estimates and intervals (for example numpy.exp). Required for a ChartData whose intervals are transformed, so the study estimates are drawn on the same scale.	None
xlab	str | None	Title of the x axis, default the effect size measure.	None
refline	float | None	Position of the reference line on the transformed scale; None draws none.	0.0
order	Literal['obs', 'weight', 'input']	Order of the study rows: 'input' (as given), 'obs' (by estimate) or 'weight' (largest weight first).	'input'
width	int	Plot width in pixels.	560
**data_kwargs	Any	Passed to chart_data() when x is a fit (slab, href, groups, group_fits, level).	{}

Returns:

Type	Description
VConcatChart	The chart; chart.to_dict() is the Vega-Lite specification.

Raises:

Type	Description
InputError	x is a ChartData missing a column, or with transformed intervals and no transf, or keyword arguments for chart_data() are given with a ChartData.

funnel_chart

funnel_chart(
    x: RMAResult | TrimfillResult | ChartData,
    *,
    yaxis: Literal['sei', 'vi'] = 'sei',
    level: float | None = None,
    href: Sequence[str | None] | None = None,
    slab: Sequence[str] | None = None,
    width: int = 420,
) -> LayerChart

Return an interactive funnel plot of a single-level model.

The pseudo-confidence region is estimate +/- z(level) * sei with the y axis reversed, as metafor's funnel() draws it. Each observed study is a filled circle with a tooltip, a link to its href and a selection_point on slab. A TrimfillResult draws its imputed studies (fill) as open circles after the observed ones. A ChartData draws its studies on the untransformed yi scale against the first pooled row's estimate, with its fill column marking imputed studies. The chart inlines its data and uses fixed colours.

Parameters:

Name	Type	Description	Default
x	RMAResult | TrimfillResult | ChartData	An intercept-only single-level fit, a trim-and-fill result, or an untransformed ChartData.	required
yaxis	Literal['sei', 'vi']	'sei' (standard error) or 'vi' (sampling variance) on the y axis.	'sei'
level	float | None	Confidence level in percent of the region, default that of x (95 for a ChartData).	None
href	Sequence[str | None] | None	A link per study, for a fit (see chart_data).	None
slab	Sequence[str] | None	Study labels, for a fit.	None
width	int	Plot width in pixels.	420

Returns:

Type	Description
LayerChart	The chart; chart.to_dict() is the Vega-Lite specification.

Raises:

Type	Description
NotSupportedError	x is a multilevel fit, for which metafor's funnel() has no single-level pseudo-confidence region.
InputError	x is a ChartData with no pooled row, with transformed intervals, or missing a column, or href or slab is given with a ChartData.

chart_data

chart_data(
    x: RMAResult | RMAMVResult,
    *,
    transf: Callable[[ArrayLike], ndarray] | None = None,
    slab: Sequence[str] | None = None,
    href: Sequence[str | None] | None = None,
    groups: Sequence[str] | None = None,
    group_fits: Mapping[str, RMAResult | RMAMVResult]
    | None = None,
    level: float | None = None,
) -> ChartData

Return the per-study and pooled frames a forest or funnel chart draws.

Per-study intervals are yi +/- z(level) * sqrt(vi), as metafor's forest() draws them, then passed through transf. Weights are weights_() of x, as percentages. The pooled rows come from predict(x, transf=transf) for x, then one row per entry of group_fits, labelled by its key, in the mapping's order. groups gives each study's group label; it is required when group_fits is given and must have one entry per study of x. slab, href and groups index the studies of x before the omission of studies with a missing yi or vi. href gives each study a link (any URL, including an in-page #anchor); None leaves that study unlinked.

Parameters:

Name	Type	Description	Default
x	RMAResult | RMAMVResult	An intercept-only rma_uni or rma_mv fit.	required
transf	Callable[[ArrayLike], ndarray] | None	Transformation of the intervals and the pooled rows (for example numpy.exp).	None
slab	Sequence[str] | None	Study labels, default those of x.	None
href	Sequence[str | None] | None	A link per study.	None
groups	Sequence[str] | None	A group label per study.	None
group_fits	Mapping[str, RMAResult | RMAMVResult] | None	A fit per group label, drawn as an extra pooled row.	None
level	float | None	Confidence level in percent, default that of x.	None

Returns:

Type	Description
ChartData	The frames, a ChartData.

Raises:

Type	Description
InputError	slab, href or groups has the wrong length, or group_fits is given without groups, or x has moderators (a forest of a meta-regression is not a pooled estimate).

ChartData dataclass

ChartData(
    studies: DataFrame,
    pooled: DataFrame,
    measure: str,
    transformed: bool,
)

The frames a chart draws: one row per study, and one row per pooled estimate.

studies has the columns slab, yi, vi, sei, ci_lb, ci_ub, weight, order, href, group, fill (ci_lb and ci_ub on the transformed scale when transformed; weight in percent; order the position of the study in the input); pooled has label, estimate, ci_lb, ci_ub, pi_lb, pi_ub, k, tau2, I2, one row per fit.