macroforecast.reporting#

macroforecast.reporting is separate from macroforecast.output.

Module	Owns	Does not own
`macroforecast.output`	Generate output tables/JSON summaries and write artifacts.	Paper/table presentation style.
`macroforecast.reporting`	Format tables, render LaTeX/HTML/Markdown, create figure-ready data, and produce paper-facing metric/test tables.	Model fitting, evaluation, testing, or artifact writing.

The reporting functions are callable and in-memory. They do not write files. Call them through the namespace, for example mf.reporting.report_table(...). Reporting helpers are not exported as top-level shortcuts.

report_table#

macroforecast.reporting.report_table(
    table,
    *,
    columns=None,
    rename=None,
    sort_by=None,
    ascending=True,
    index=False,
    precision=3,
    percent_columns=(),
    missing="",
    caption=None,
    label=None,
    notes=(),
    metadata=None,
) -> ReportTable

Creates a presentation-ready table from a pandas-like object.

Argument	Default	Meaning
`columns`	`None`	Optional selected column order. Missing columns raise `KeyError`.
`rename`	`None`	Mapping from source names to display names.
`sort_by`	`None`	Optional sort column or columns.
`ascending`	`True`	Sort direction.
`index`	`False`	Whether to include the original index as columns.
`precision`	`3`	Digits after the decimal for numeric values.
`percent_columns`	`()`	Display columns as percentages after renaming.
`missing`	`""`	Display value for missing or non-finite numeric values.
`caption`, `label`, `notes`	`None`, `None`, `()`	Presentation metadata for rendered output.
`metadata`	`None`	User metadata stored on the `ReportTable`.

Output: ReportTable(data, caption, label, notes, metadata).

ReportTable.data is a formatted DataFrame and carries attrs["macroforecast_metadata_schema"]["kind"] = "report_table". Formatting metadata such as source shape, precision, and percentage columns is stored separately in attrs["macroforecast_metadata"].

metric_report_table#

macroforecast.reporting.metric_report_table(
    results,
    *,
    table="scores",
    columns=None,
    rename=None,
    sort_by=None,
    ascending=True,
    precision=3,
    percent_columns=(),
    missing="",
    caption=None,
    label=None,
    notes=(),
    metadata=None,
) -> ReportTable

Creates a paper-facing metric table from an EvaluationReport or a raw metric-like DataFrame. For an EvaluationReport, table selects which component to display:

`table`	Source
`"scores"`	`report.scores`
`"ranking"`	`report.ranking`
`"benchmark"`	`report.benchmark`
`"regime"`	`report.regime`
`"decomposition"`	`report.decomposition`

Default display labels convert common columns such as model, horizon, rmse, relative_mse, and r2_oos to Model, H, RMSE, Relative MSE, and R2 OOS. Use columns to choose the paper table spine, rename to override labels, and percent_columns when a column should be displayed as a percentage.

evaluation_report_tables#

macroforecast.reporting.evaluation_report_tables(
    report,
    *,
    include=("scores", "ranking", "benchmark", "regime", "decomposition"),
    include_aggregations=False,
    captions=None,
    labels=None,
    precision=3,
    percent_columns=(),
    missing="",
    metadata=None,
) -> ReportBundle

Creates a named ReportBundle from an EvaluationReport. Unavailable optional tables are skipped. Set include_aggregations=True or include "aggregations" in include to add all report.aggregations under names like aggregation_model_horizon_target.

accuracy_table#

macroforecast.reporting.accuracy_table(
    results,
    *,
    columns=None,
    sort_by=("horizon", "rmse"),
    ascending=True,
    precision=3,
    percent_columns=("r2_oos", "mse_reduction", "success_ratio"),
    missing="",
    caption="Forecast accuracy",
    label=None,
    notes=("Lower error metrics and higher R2 OOS are better.",),
    metadata=None,
) -> ReportTable

Paper-table preset for forecast accuracy. Input is an EvaluationReport or a raw score DataFrame. Output is a ReportTable. If columns=None, the preset uses available columns from model, horizon, rmse, mae, r2_oos, and relative_mse; missing optional columns are skipped rather than raising.

model_comparison_table#

macroforecast.reporting.model_comparison_table(
    results,
    *,
    columns=None,
    sort_by=("horizon", "rank"),
    ascending=True,
    precision=3,
    percent_columns=("r2_oos",),
    missing="",
    caption="Model comparison",
    label=None,
    notes=("Ranks are computed by the evaluation report rank metric.",),
    metadata=None,
) -> ReportTable

Paper-table preset for model ranking/comparison. Input is an EvaluationReport or ranking-like DataFrame. Output is a ReportTable. If columns=None, the preset uses available columns from rank, model, horizon, rmse, mae, r2_oos, and relative_mse.

forecast_test_table#

macroforecast.reporting.forecast_test_table(
    results,
    *,
    columns=None,
    include_reference=False,
    stars=True,
    star_levels=((0.01, "***"), (0.05, "**"), (0.1, "*")),
    precision=3,
    p_value_precision=3,
    missing="",
    caption="Forecast comparison tests",
    label=None,
    notes=(),
    metadata=None,
) -> ReportTable

Paper-table preset for forecast-comparison tests. Input is a TestResult, a mapping of named TestResult objects, or any object accepted by test_report_table(...). Output is a ReportTable. Use this preset when the paper needs the standard test statistic, p-value, rejection, and sample-size columns; use test_provenance_table(...) for source-alignment details.

test_report_table#

macroforecast.reporting.test_report_table(
    results,
    *,
    columns=None,
    include_reference=False,
    stars=True,
    star_levels=((0.01, "***"), (0.05, "**"), (0.1, "*")),
    precision=3,
    p_value_precision=3,
    missing="",
    caption=None,
    label=None,
    notes=(),
    metadata=None,
) -> ReportTable

Creates a paper-facing table from one or more forecast-test outputs. Input can be a TestResult, a mapping or sequence of TestResult objects, a raw macroforecast.output.test_table(...), or a stacked table from functions such as macroforecast.tests.equal_predictive_tests(...).

Default output columns:

Column	Meaning
`Test`	Requested key, such as `dm`, `gw`, `dmp`, or `hn`.
`Name`	Display name from component metadata.
`Ref.`	Statistic reference family, such as `t` or `z`.
`Statistic`	Formatted test statistic.
`p-value`	Formatted p-value, optionally with significance markers.
`Reject`	`Yes` or `No` based on the component decision flag.
`N`	Number of aligned observations used by the component test.

Set include_reference=True to add a compact Source column. For detailed R/source alignment, use test_provenance_table(...) instead of placing long source text in the main paper table.

test_provenance_table#

macroforecast.reporting.test_provenance_table(
    results,
    *,
    columns=None,
    missing="",
    caption=None,
    label=None,
    notes=(),
    metadata=None,
) -> ReportTable

Creates a source-alignment table for appendices, replication packages, or audit logs. It keeps the null hypothesis, p-value reference distribution, source reference, R reference, and alignment note separate from the compact paper table.

Default output columns:

Column	Meaning
`Test`, `Name`	Requested key and display name.
`Null`	Null hypothesis recorded by the component test.
`P-value ref.`	Reference distribution for the p-value.
`Status`	P-value availability flag.
`Source`	Package/source formula reference.
`R reference`	Exact R comparator when one is claimed; blank otherwise.
`Alignment`	Text description of exact, partial, or unavailable source alignment.

Renderers#

macroforecast.reporting.latex_table(table, *, booktabs=True) -> str
macroforecast.reporting.html_table(table) -> str
macroforecast.reporting.markdown_table(table) -> str

Each renderer accepts either a ReportTable or a raw table-like object. Raw objects are passed through report_table() first.

latex_table(..., booktabs=True) uses \toprule, \midrule, and \bottomrule. Set booktabs=False to use \hline.

figure_data#

macroforecast.reporting.figure_data(
    data,
    *,
    x=None,
    y=None,
    group=None,
    columns=None,
    rename=None,
    dropna=True,
) -> pandas.DataFrame

Creates a tidy plotting/export frame. Use columns for an explicit selected column set, or use x, y, and group to select plot roles.

Output: DataFrame with attrs["macroforecast_metadata_schema"]["kind"] = "figure_data". Figure-role metadata such as x, y, group, dropna, and source shape is stored in attrs["macroforecast_metadata"].

report_bundle#

macroforecast.reporting.report_bundle(
    *,
    tables=None,
    figures=None,
    metadata=None,
) -> ReportBundle

Collects named report tables and figure data without writing files.

Field	Meaning
`tables`	Mapping from name to `ReportTable`. Raw table-like objects are converted with `report_table()`.
`figures`	Mapping from name to figure-ready `DataFrame`. Raw objects are converted with `figure_data()`.
`metadata`	Bundle-level metadata.

render_tables#

macroforecast.reporting.render_tables(bundle, *, format="latex") -> dict[str, str]

Renders every table in a ReportBundle or table mapping. Supported formats: "latex", "html", and "markdown".

Example#

report = mf.reporting.report_table(
    scores,
    columns=("model", "horizon", "rmse", "r2_oos"),
    rename={"model": "Model", "rmse": "RMSE", "r2_oos": "R2 OOS"},
    sort_by="rmse",
    precision=3,
    percent_columns=("R2 OOS",),
    caption="Forecast accuracy",
    label="tab:forecast_accuracy",
    notes=("Lower RMSE is better.",),
)

latex = report.to_latex()

Evaluation reporting example:

report = mf.evaluation.evaluate_report(
    forecast_result,
    metrics=("rmse", "mae", "relative_mse", "r2_oos"),
    benchmark_model="historical_mean",
    include_decomposition=True,
)

accuracy_table = mf.reporting.accuracy_table(report)
model_table = mf.reporting.model_comparison_table(report)

paper_tables = mf.reporting.evaluation_report_tables(
    report,
    include=("scores", "ranking", "benchmark", "decomposition"),
    percent_columns=("r2_oos",),
)

Forecast-test reporting example:

tests = mf.tests.equal_predictive_tests(
    loss_a,
    loss_b,
    tests=("dm", "gw", "dmp", "hn"),
    error_a=error_a,
    error_b=error_b,
)

main_table = mf.reporting.forecast_test_table(
    tests,
    label="tab:equal_predictive_tests",
)
appendix_table = mf.reporting.test_provenance_table(tests)

latex = main_table.to_latex()