forest Module#

Forest plot visualizations.

This module provides functions for creating forest plots for stratified analysis, meta-analysis, and regression results.

Functions#

episia.viz.forest.plot_forest(result, *, title='Forest Plot', xlabel='Estimate', animate=False, backend='plotly', theme='scientific', config=None)[source]#

Forest plot for stratified or regression results.

Parameters:

  • result (Any) – StratifiedResult, RegressionResult, or AssociationResult.

  • title (str) – Figure title.

  • xlabel (str) – X-axis label.

  • animate (bool) – Rows appear one by one (Plotly only).

  • backend (str) – ‘plotly’ or ‘matplotlib’.

  • theme (str) – Theme name.

  • config (PlotConfig | None) – Full PlotConfig override.

Returns:

Figure object.

Return type:

Any

Example:

from episia.viz.forest import plot_forest
plot_forest(stratified_result, title="Stratified OR by age group").show()
episia.viz.forest.plot_meta_forest(estimates, ci_lowers, ci_uppers, labels, *, weights=None, pooled_estimate=None, pooled_ci=None, i_squared=None, tau_squared=None, p_heterogeneity=None, null_value=1.0, title='Meta-Analysis Forest Plot', xlabel='Effect Estimate', backend='plotly', theme='scientific', config=None)[source]#

Meta-analysis style forest plot with heterogeneity statistics.

Marker sizes are proportional to study weights. I² and τ² annotations are included when provided.

Parameters:

  • estimates (List[float]) – Per-study point estimates.

  • ci_lowers (List[float]) – Per-study lower CI bounds.

  • ci_uppers (List[float]) – Per-study upper CI bounds.

  • labels (List[str]) – Study / stratum labels.

  • weights (List[float] | None) – Relative weights (e.g. 1/variance). Auto-normalised.

  • pooled_estimate (float | None) – Pooled (diamond) point estimate.

  • pooled_ci (Tuple[float, float] | None) – (lower, upper) for pooled estimate.

  • i_squared (float | None) – I² heterogeneity statistic (%).

  • tau_squared (float | None) – τ² between-study variance.

  • p_heterogeneity (float | None) – P-value for Q heterogeneity test.

  • null_value (float) – Null reference line position (1.0 for ratios).

  • xlabel (str) – Labels.

  • backend (str) – ‘plotly’ or ‘matplotlib’.

  • theme (str) – Theme name.

  • config (PlotConfig | None) – Full PlotConfig override.

  • title (str)

  • xlabel

Returns:

Figure object.

Return type:

Any

Examples#

Stratified analysis forest plot:

from episia.stats.stratified import mantel_haenszel_or
from episia.viz.forest import plot_forest

# Perform Mantel-Haenszel analysis
mh_result = mantel_haenszel_or(stratified_tables)

# Forest plot with strata
fig = plot_forest(
    mh_result,
    title="Stratified Analysis by Age Group"
)
fig.show()

Regression forest plot:

from episia.viz.forest import plot_forest

fig = plot_forest(
    regression_result,  # From logistic_regression()
    title="Logistic Regression - Odds Ratios"
)

Meta-analysis forest plot:

from episia.viz.forest import plot_meta_forest

# Study-level data
estimates = [1.2, 1.5, 1.8, 1.3]
ci_lowers = [0.9, 1.1, 1.4, 1.0]
ci_uppers = [1.5, 1.9, 2.2, 1.6]
labels = ["Study 1", "Study 2", "Study 3", "Study 4"]
weights = [25, 30, 20, 25]  # Study weights (e.g., sample size)

fig = plot_meta_forest(
    estimates,
    ci_lowers,
    ci_uppers,
    labels,
    weights=weights,
    pooled_estimate=1.45,
    pooled_ci=(1.25, 1.65),
    i_squared=35.2,
    p_heterogeneity=0.042,
    title="Meta-Analysis of Intervention Effect"
)