Reports

Report models, HTML/Plotly/Bokeh/XLSX renderers, portfolio and risk report builders.

See the usage guide for task-oriented examples. Signatures below are generated from the public headers at the same commit as the rest of this site.

struct portfolio_transaction

One executed trade used by the transaction activity projection.

Public Members

timestamp date = 0: UTC nanosecond timestamp; trades are grouped by calendar day.

std::string symbol: Traded symbol.

double amount = 0.0: Signed quantity; notional is computed as |amount| * price.

double price = 0.0: Execution price per unit.

struct report_artifact

One emitted artifact (in-memory content and/or a written path).

Public Members

std::string name: Logical name, such as “figure”, “file” or "axis:<section>.<series>".

std::string path: Written file path; empty for artifacts that stay in memory.

bool owned = true: True for self-owned in-memory artifacts; false for caller-supplied axes and for the file artifact returned by write_pdf.

std::string content: Serialized figure or axis JSON, or written bytes for a file artifact.

struct report_artifact_bundle

Owning native artifact bundle returned by report renderers.

Mirrors the pinned ArtifactBundle shape: metadata always carries backend and report_digest; artifacts carries named outputs.

Public Functions

const report_artifact *find(std::string_view name) const

Finds an artifact by logical name.

Parameters:: name – Artifact name to search for.
Returns:: Pointer to the first matching artifact, or nullptr when no artifact has name.

const std::string &report_digest() const

Returns the bundle’s report digest.

Throws:: input_error – If metadata has no “report_digest” entry.
Returns:: Value of the “report_digest” metadata entry.

Public Members

std::map<std::string, std::string> metadata: Bundle metadata; renderers set “backend” and “report_digest”.

std::vector<report_artifact> artifacts: Named outputs.

std::optional<plotly_document> plotly: Plotly figure when produced by render_plotly.

std::optional<bokeh_document> bokeh: Bokeh document when produced by render_bokeh.

std::vector<report_static_axes> axes: Static axes when produced by render_matplotlib.

struct report_cell

One typed cell in a report_table.

Public Types

enum class kind

Cell value kind.

missing carries no value and serializes as null, number uses number, text uses text, and boolean uses boolean.

Values:

enumerator missing

enumerator number

enumerator text

enumerator boolean

Public Members

kind type = kind::missing : Value kind that selects the active field.

double number = 0.0: Numeric value used when type is number.

bool boolean = false: Boolean value used when type is boolean.

std::string text: Text value used when type is text.

Public Static Functions

static inline report_cell missing()

Constructs a missing cell.

Returns:: Cell whose type is kind::missing.

static inline report_cell number_cell(double value)

Constructs a numeric cell.

Parameters:: value – Numeric value to store.
Returns:: Cell whose type is kind::number.

static inline report_cell text_cell(std::string value)

Constructs a text cell.

Parameters:: value – Text to move into the cell.
Returns:: Cell whose type is kind::text.

static inline report_cell boolean_cell(bool value)

Constructs a boolean cell.

Parameters:: value – Boolean value to store.
Returns:: Cell whose type is kind::boolean.

struct report_document

Versioned report document shared by report builders and renderers.

Public Functions

const report_section &section(std::string_view key) const

Finds a section by key.

Parameters:: key – Section key to search for.
Throws:: input_error – If the document is invalid or no section has key.
Returns:: Const reference to the matching section.

report_section &section(std::string_view key)

Finds a section by key for in-place modification.

Parameters:: key – Section key to search for.
Throws:: input_error – If the document is invalid or no section has key.
Returns:: Mutable reference to the matching section.

std::string to_json() const

Serializes the validated document as deterministic JSON.

Offline asset content is embedded as JSON string values and map keys are emitted in sorted order.

Throws:: input_error – If the schema version is unsupported, section keys are duplicated, section metadata is invalid, or a value is non-finite or malformed.
Returns:: JSON text terminated by a newline.

std::string semantic_payload() const

Serializes the validated document with offline asset content hashed.

Each asset value is replaced by its SHA-256 hexadecimal digest, so the payload reflects asset identity without embedding the bytes.

Throws:: input_error – For the same validation failures as to_json().
Returns:: JSON text terminated by a newline.

std::string semantic_digest() const

Computes the provenance digest of the semantic payload.

The digest is SHA-256 over a versioned frame and semantic_payload(); report renderers expose it as the report_digest bundle metadata.

Throws:: input_error – If semantic_payload() fails validation.
Returns:: Lowercase hexadecimal SHA-256 digest.

Public Members

std::string domain: Report domain, such as “portfolio”, “risk” or “factor”.

std::string title: Document title.

std::vector<report_section> sections: Ordered sections; keys must be unique.

std::map<std::string, std::string> metadata: Free-form metadata.

int schema_version = report_document_schema_version : Schema version; must equal report_document_schema_version to serialize.

std::map<std::string, std::string> offline_assets: Embedded asset name to content mapping; to_json writes the content as string values while semantic_payload writes its SHA-256 digest.

struct report_html_options

HTML rendering options.

Public Members

std::string language = "en": UI language: “en” or “zh”.

report_chart_backend chart_backend = report_chart_backend::inline_svg : Chart renderer for report series.

struct report_metric

Named scalar metric with one optional typed value.

Public Members

std::string key: Stable identifier used by section metadata.

std::string label: Display label.

std::string unit: Value unit, such as “ratio” or “count”.

std::optional<double> number: Numeric value; takes precedence over boolean and text.

std::optional<bool> boolean: Boolean value used when number is unset.

std::optional<std::string> text: Text value used when number and boolean are unset.

struct report_section

One titled group of metrics, tables, series and notes.

Public Functions

std::string semantic_payload() const

Serializes this section as deterministic JSON.

Every units and legends key must match a metric, table or series key in the section, and their values must be non-empty.

Throws:: input_error – If section metadata references an unknown key or has an empty value, or if a number, table row or series is malformed.
Returns:: JSON text terminated by a newline.

Public Members

std::string key: Document-unique section key.

std::string title: Display title.

std::vector<report_metric> metrics: Scalar metrics.

std::vector<report_table> tables: Tables.

std::vector<report_series> series: Chart series.

std::vector<std::string> notes: Free-form notes.

std::map<std::string, std::string> units: Unit overrides keyed by a metric, table or series key in this section.

std::map<std::string, std::string> legends: Chart legends keyed by a series key in this section.

struct report_series

Named numeric series for chart rendering.

Public Members

std::string key: Stable identifier used by legends and artifacts.

std::string title: Display title.

std::string x_label: X-axis label.

std::string y_label: Y-axis label.

std::string unit: Value unit, such as “ratio” or “growth_multiple”.

std::vector<double> x: X values; must have the same length as y.

std::vector<double> y: Y values.

struct report_static_axes

Static native replacement for a Matplotlib axis.

The Python renderer returns one axis per section series, keyed axis:<section>.<series>. The native artifact carries the same prepared values; there is no Matplotlib object and no kernel recomputation.

Public Members

std::string name: Name in the form "axis:<section>.<series>".

std::string section_key: Source section key.

std::string series_key: Source series key.

std::string title: "<section title>: <legend or series key>".

std::string label: Section legend for the series, or the series key when none is set.

std::string x_label: X-axis label copied from the series.

std::string y_label: Section unit for the series, or empty when none is defined.

std::string unit: Same value as y_label.

std::vector<double> x: X values copied from the series.

std::vector<double> y: Y values copied from the series.

bool owned = true: False when the caller supplied the matching axis key.

struct report_table

Named table of typed cells.

Public Members

std::string key: Stable identifier used by section metadata and renderers.

std::string title: Display title.

std::vector<std::string> columns: Column headers.

std::vector<std::vector<report_cell>> rows: Rows; each row must have columns.size() cells when serialized.

struct xlsx_render_options

Worksheet naming options for render_xlsx.

Public Members

std::string sheet_prefix: Prefix prepended to each section key to form worksheet names.

enum class fincore::report_chart_backend

Chart renderer used by render_html.

Values:

enumerator inline_svg: Draw each series as an inline SVG polyline.

enumerator echarts: Embed the pinned offline ECharts 5.5.0 script and chart payloads.

report_document fincore::build_portfolio_report(const dataframe &returns, const dataframe *benchmark = nullptr, std::string title = "Portfolio Report", const dataframe *positions = nullptr, std::size_t rolling_window = 63U, std::span<const portfolio_transaction> transactions = {})

Builds a portfolio report document from prepared return and position data.

The document has domain “portfolio”. It always contains a “performance” section, adds a “benchmark” section when benchmark is supplied, adds a “portfolio” section when positions is supplied, and adds a “transactions” section when transactions is non-empty. Metrics are computed once from the supplied inputs; renderers do not recompute them.

Parameters:

returns – Daily simple returns with a required “returns” double column.
benchmark – Optional benchmark frame with a “benchmark” double column; enables the benchmark comparison section.
title – Document title.
positions – Optional positions frame with a “cash” column, a unique index, finite values, and a row for every return timestamp; enables the portfolio exposure section.
rolling_window – Rolling window for the rolling Sharpe, volatility and beta series; must be positive.
transactions – Optional transactions used for the transaction section and, with positions, for turnover.

Throws:

input_error – If rolling_window is zero, a required column is missing or has the wrong type, positions are empty, duplicated, not finite or do not cover the return timestamps, or a transaction has a non-finite amount or price.

Returns:

Report document with observations, daily period and rolling-window metadata.

report_document fincore::build_risk_report(const risk_validation_report &report, std::string title = "Risk Validation Report")

Builds a risk validation report document from a walk-forward VaR report.

The document has domain “risk” and one “risk_validation” section with the walk-forward status, forecast and refit counts, optional diagnostics and backtest metrics, forecast-event and refit tables, and the report disclosure as a note.

Parameters:

report – Native walk-forward risk validation report to project.
title – Document title.

Returns:

Report document using report_document_schema_version.

report_artifact_bundle fincore::render_bokeh(const report_document &document)

Projects prepared report series into one Bokeh-compatible document.

One line glyph per series, with the series key as the y field and the section legend or "<section title>: <series key>" as the legend label. Values are copied, not recomputed.

Parameters:: document – Prepared report document.
Throws:: input_error – If a series has mismatched x and y lengths or the document fails semantic digest validation.
Returns:: Bundle whose metadata identifies the bokeh backend and whose “figure” artifact contains the document JSON.

std::string fincore::render_html(const report_document &document, const report_html_options &options = {})

Renders a report document as one self-contained HTML page.

Text is HTML-escaped, styles are embedded, and no external asset URL is referenced; the ECharts backend embeds the pinned chart script. Output is deterministic for the same document and options.

Parameters:

document – Prepared report document.
options – Language and chart backend selection.

Throws:

input_error – If the language or chart backend is unknown, a numeric or series value is non-finite, a table row does not match its column count, or an ECharts series has mismatched x and y lengths.

Returns:

Complete HTML text starting with “<!doctype html>”.

report_artifact_bundle fincore::render_matplotlib(const report_document &document, const std::vector<std::string> &supplied_axes = {})

Projects prepared report series into static Matplotlib-compatible axes.

supplied_axes lists "<section>.<series>" keys the caller already owns; those artifacts are marked owned = false, matching the Python axes argument ownership rule.

Parameters:

document – Prepared report document.
supplied_axes – Axis keys in the form "<section>.<series>" already owned by the caller.

Throws:

input_error – If the document fails semantic digest validation.

Returns:

Bundle whose metadata identifies the matplotlib backend, with one "axis:<section>.<series>" artifact per series and matching entries in axes.

std::string fincore::render_pdf_bytes(const report_document &document)

Renders deterministic native PDF 1.4 bytes for a report document.

Includes text, headings, tables and simple line-series vector paths. Uses base-14 Helvetica fonts; characters outside WinAnsi are replaced with ? (declared format variance from the Chromium-backed Python writer).

Parameters:: document – Report document to render.
Returns:: PDF 1.4 bytes ending with “%%EOF\n”.

report_artifact_bundle fincore::render_plotly(const report_document &document)

Projects prepared report series into one Plotly-compatible document.

One scatter trace per report_section::series entry; the trace name is the section legend or "<section title>: <series key>". Values are copied, not recomputed. report_series::x is numeric in the native model, so the Python DatetimeIndex x-axis is a declared date-axis format variance.

Parameters:: document – Prepared report document.
Throws:: input_error – If a series has mismatched x and y lengths or the document fails semantic digest validation.
Returns:: Bundle whose metadata identifies the plotly backend and whose “figure” artifact contains the figure JSON.

std::string fincore::render_xlsx(const report_document &document, const xlsx_render_options &options = {})

Renders a report document as an in-memory XLSX workbook.

One worksheet is emitted per section. Worksheet names combine options.sheet_prefix with the section key, replace invalid characters with ‘_’, and are capped at 31 characters; duplicates receive a “_2”, “_3”, … suffix. An empty document produces a single worksheet named “report” or the prefix when one is set. No file is written.

Parameters:

document – Prepared report document.
options – Worksheet naming options.

Throws:

input_error – If a numeric value is non-finite, a table row does not match its column count, or a series has mismatched x and y lengths.

Returns:

ZIP-compressed XLSX bytes, deterministic for the same document and options.

report_artifact_bundle fincore::write_pdf(const report_document &document, const std::string &target)

Writes the native PDF to target and returns the artifact bundle.

Parent directories are created like the Python writer, and an existing file at target is truncated. Byte identity with the Python PDF backend is not claimed.

Parameters:

document – Report document to render.
target – Output path; must not be empty.

Throws:

input_error – If target is empty, its parent directory cannot be created, the file cannot be opened or written, or the document fails semantic digest validation.

Returns:

Bundle whose metadata identifies the pdf backend and whose “file” artifact records target, owned = false and the written bytes.

constexpr int fincore::report_document_schema_version = 2: Schema version accepted by report_document validation and serialization.