forestploter.read_forest_data

forestploter.read_forest_data(source, *, sheet_name=0, header_row=1, mapping=None, encoding='utf-8-sig')[source]

Read an XLSX or CSV file that follows the forest long-table contract.

Parameters:
sourcestr or pathlib.Path

Path to an .xlsx or .csv file. Other suffixes are not guessed.

sheet_namestr or int, default 0

XLSX worksheet name or zero-based index. CSV has no worksheets and rejects any value other than the default 0.

header_rowint, default 1

One-based physical row containing field names. Every non-empty physical row below it is one source record.

mappingForestDataMapping, optional

Reserved-field name mapping. The nine standard names are used by default.

encodingstr, default “utf-8-sig”

CSV text encoding. Ignored for XLSX.

Returns:
ForestData

Long-table values, supported XLSX merges, and traceable source-cell references.

Raises:
FileNotFoundError

Raised when source does not exist.

TypeError

Raised for invalid header_row, sheet_name, or mapping types.

ValueError

Raised when the file type, header, worksheet, merge, or cached formula result violates the contract.

ImportError

Raised when XLSX support is requested without openpyxl.

Parameters:

  • source (str | Path)

  • sheet_name (str | int)

  • header_row (int)

  • mapping (ForestDataMapping | None)

  • encoding (str)

Return type:

ForestData

Notes

Use a first worksheet named Forest and one row of unique field names. Two orders are deliberately independent:

  • The columns argument of forestploter.forest() is the only thing that determines the final left-to-right plot order. Display columns may appear before or after any CI column.

  • The XLSX/CSV header order exists for readable data entry and does not determine plot order. A recommended file places display fields that precede the first CI first, then estimate/lower/upper as the physical representation of that CI, then trailing display fields, and finally the six controls _plot_row, _series, _ci_column, _row_type, _indent, and _is_summary.

Enter only one statistical triple per estimate record. For three series, the recommended hierarchy uses one header record for the shared outcome, sample size, and other group-level values, followed by three series rows with distinct _plot_row values and _indent=1. Put each series label and CI text on its child row. This conventional layout works identically in XLSX and CSV and requires no merged cells. Supported vertical XLSX merges remain available when a centered multirow display value is specifically desired. 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 the same series in two CI columns, duplicate its record, use a different _ci_column, and retain the same _plot_row. The two plotted intervals will share one y position.

Merges are accepted only in display fields and must be single-column, vertical ranges below the header. Merges in reserved fields, horizontal or rectangular merges, and merges crossing the header are rejected. Blank values are never forward-filled. All three of estimate/lower/upper may be blank to skip an interval; a partially blank triple fails validation in forestploter.forest().

The package does not evaluate Excel formulas. It uses cached results saved in the workbook and asks the user to recalculate and save when a required formula has no cache. CSV follows the same record and _plot_row rules, but cannot represent merges. Excel fonts, fills, borders, row heights, and column widths do not override forestploter.ForestTheme or forestploter.ForestColumn settings.

Examples

>>> from forestploter import read_forest_data
>>> df = read_forest_data("forest_input.xlsx", sheet_name="Forest")
>>> df.frame.columns[:5].tolist()
['Outcome', 'estimate', 'lower', 'upper', 'Effect [95% CI]']