forestploter.forest

forestploter.forest(data, *, columns, ref_line=0.0, ideal_line=None, ideal_line_columns=None, xlim=None, ticks_at=None, arrow_lab=None, theme=None, title=None, figure_width=12.0, row_height=0.36, series_styles=None, legend=None, table_layout=None, reference_legend=None)[source]

Render a table-style forest plot from an explicit long table.

Parameters:
dataForestData or pandas.DataFrame

Result of read_forest_data(), or a long-form DataFrame using the default reserved field names. One source record may describe only one series in one CI column with one estimate/lower/upper triple.

columnssequence of ForestColumn

Display and CI columns in final left-to-right plot order. This sequence is the sole authority for visual order: text may appear before or after any CI column regardless of XLSX/CSV header order. Display keys must be source fields; CI keys are targeted by _ci_column records.

ref_linefloat, default 0

Reference line shared by all CI columns.

ideal_linefloat, optional

Optional additional ideal or target line shared by the selected CI columns.

ideal_line_columnssequence of str, optional

Active CI-column keys in which to draw ideal_line. None preserves the default behavior of drawing it in every active CI column; an empty sequence suppresses the additional line and cannot be paired with an ideal-line legend label. Requires ideal_line.

xlimtuple of float, optional

Shared linear range (minimum, maximum). When omitted, it is derived from all nonblank intervals.

ticks_atsequence of float, optional

Shared tick values. Five ticks are generated within xlim when omitted.

arrow_labtuple of str, optional

Left and right direction labels below the first active CI column.

themeForestTheme, optional

Colors, font size, table rules, optional full borders, and guide-line styles. The default table has rules above and below its column headers and at its bottom.

titlestr, optional

In-figure title.

figure_widthfloat, default 12

Minimum Figure width in inches.

row_heightfloat, default 0.36

Physical height of each unique _plot_row in inches.

series_stylesmapping of str to ForestSeriesStyle, optional

Mapping keyed by _series values. Supplied keys must exactly match observed series. Defaults follow first-appearance order.

legendForestLegendSpec, optional

Series legend placed in one column header or in the bottom region.

table_layoutForestTableLayoutSpec, optional

Automatic column width, header wrapping, and padding rules. Header height adapts to measured text and header legends independently of the body-row height.

reference_legendForestReferenceLegendSpec, optional

Reference/ideal-line legend. It uses the same placement semantics as the series legend. When both exist, they stack with the series legend first.

Returns:
ForestPlotResult

Figure, Axes, column boundaries, visual-row centers, clipping count, and layout diagnostics.

Raises:
TypeError

Raised for invalid data or series-style types.

ValueError

Raised when the long table, intervals, styles, coordinates, legends, columns, or layout settings are invalid.

Parameters:
Return type:

ForestPlotResult

Notes

Prefer read_forest_data() for XLSX. For three series under one outcome, the recommended hierarchy uses one header row for the shared outcome-level values and three child _plot_row values with _indent=1. Put the series label and its CI text on each child row. This conventional layout needs no merged cells. Supported vertical XLSX merges remain available for specialized display needs. On the header record, leave _series, _ci_column, and estimate/lower/upper blank; use _row_type="header", _indent=0, and _is_summary=False.

To show one series in several CI columns, duplicate the record, retain the same _plot_row, and change only _ci_column. CSV uses the same logical fields but has no merge metadata; blanks are never inferred or forward-filled.

A readable file-header order is recommended but does not control output. Place display fields before the first CI, then estimate/lower/upper as the first CI’s physical representation, then trailing display fields, and finally the six controls _plot_row, _series, _ci_column, _row_type, _indent, and _is_summary. The columns sequence remains authoritative for the actual rendered order.

_row_type controls row semantics. _is_summary must be boolean and controls marker shape only. A fully blank triple skips an interval; a partially blank triple is invalid. At an axis overflow, an arrow replaces the cap on that side. A fully off-scale interval shows only the nearest outward arrow.

This function uses one global linear axis configuration. It performs no logarithmic transformation and computes no effect size, confidence interval, or meta-analysis statistic. ideal_line_columns controls only the additional line’s visibility; all CI columns still share the same reference value, limits, and ticks.

Examples

>>> import pandas as pd
>>> from forestploter import ForestColumn, forest
>>> df = pd.DataFrame({
...     "Outcome": ["Overall survival"],
...     "estimate": [0.72], "lower": [0.58], "upper": [0.90],
...     "Effect": ["0.72 [0.58, 0.90]"],
...     "_plot_row": ["os-a"],
...     "_series": ["Treatment A"],
...     "_ci_column": ["ci"],
...     "_row_type": ["estimate"], "_indent": [0],
...     "_is_summary": [False],
... })
>>> result = forest(df, columns=[
...     ForestColumn("Outcome", "Outcome", "text", 2),
...     ForestColumn("ci", "Treatment effect", "ci", 3, "center"),
...     ForestColumn("Effect", "Effect [95% CI]", "numeric", 2, "right"),
... ], xlim=(0.4, 1.4), ref_line=1.0)
>>> result.row_centers
(0.5,)