可视化

图表数据模型、原生 HTML/SVG 构建器、Plotly/Bokeh 文档以及可选的 ImPlot 后端。

面向任务的使用示例请参阅使用指南。以下签名与本站其余内容在同一提交中由公共头文件生成。

class bokeh_backend

原生 Bokeh 兼容后端。

在原生图表数据上镜像 fincore.viz.interactive.bokeh_backend.BokehBackend 的产物行为。show 为无头模式并返回 false。

公共函数

explicit bokeh_backend(std::string theme = "light", int height = 500, int width = 800, std::string sizing_mode = "fixed")

使用主题、尺寸和尺寸模式创建后端。

dark 主题选择深色填充、网格和文本颜色；其他名称使用浅色。高度或宽度不为正时抛出 input_error。

inline const std::string &theme() const noexcept

返回配置的主题名称。

inline int height() const noexcept

返回配置的绘图高度。

inline int width() const noexcept

返回配置的绘图宽度。

inline const std::string &sizing_mode() const noexcept

返回配置的尺寸模式。

inline const std::string &background_fill_color() const noexcept

返回解析后的绘图背景色。

inline const std::string &grid_line_color() const noexcept

返回解析后的网格线颜色。

inline const std::string &text_color() const noexcept

返回解析后的文本颜色。

bokeh_document create_document(std::string title) const

使用配置的尺寸、颜色和坐标轴创建基础文档。

bokeh_document plot_returns(const series_chart &chart) const

构建累积收益文档。

图表没有序列，或序列标签与值数量不一致时，抛出 input_error。

bokeh_document plot_drawdown(const series_chart &chart) const

使用面积图元和线图元构建回撤文档。

图表没有序列，或序列标签与值数量不一致时，抛出 input_error。

bokeh_document plot_rolling_sharpe(const series_chart &chart, std::size_t window = 252) const

构建滚动夏普比率文档。

记录的 chart.window 非零时优先；对于未记录窗口的图表，window 为回退值。图表没有序列或长度不一致时抛出 input_error。

bokeh_document plot_monthly_heatmap(const heat_grid &grid) const

构建月度收益热力图文档。

没有年份，或值不是年数 x 12 时，抛出 input_error。

bool show(const bokeh_document &document) const

无头模式：返回 false，记录 NOT_RUN_INTERACTIVE。

void save_html(const bokeh_document &document, const std::string &path) const

将文档以自包含 HTML 形式写入 path。

路径为空，或文件无法打开或写入时，抛出 input_error。

inline std::string_view last_show_status() const noexcept

返回最近一次 show 调用记录的状态。

class html_report_builder

持有型原生自包含 HTML 绩效报告构建器。

镜像 fincore.viz.html_backend.HtmlReportBuilder：标题/小标题/原始 HTML 小节、统计表、指标卡片、累积收益/回撤/滚动夏普比率表以及月度收益透视表。所有图表数值都来自预先计算的原生图表数据；构建器从不重新计算金融内核。build() 是确定性的，且不包含任何外部样式表、脚本或图片引用。

公共函数

html_report_builder &add_title(std::string title = "Performance Report")

追加转义的 1 级标题小节。

html_report_builder &add_heading(std::string text, int level = 2)

追加转义的小标题，级别限制在 1 到 6 之间。

html_report_builder &add_stats_table(const std::vector<html_metric> &stats)

追加两列统计表，数值保留四位小数。

缺失值打印为 nan，与 Python oracle 一致。

html_report_builder &add_metric_cards(const std::vector<html_metric> &stats)

按输入顺序使用每个指标的键追加指标卡片。

html_report_builder &add_metric_cards(const std::vector<html_metric> &stats, const std::vector<std::string> &keys)

按请求顺序为各键追加指标卡片。

缺失或非有限值呈现为 N/A。

html_report_builder &add_html(std::string raw_html)

追加未经转义的原始 HTML。

html_report_builder &plot_returns(const chart_series &series)

追加累积收益表小节。

html_report_builder &plot_drawdown(const chart_series &series)

追加回撤表小节。

html_report_builder &plot_rolling_sharpe(const chart_series &sharpe, const chart_series *benchmark = nullptr, std::size_t window = 252)

追加滚动夏普比率表和可选的基准表。

html_report_builder &plot_monthly_heatmap(const heat_grid &grid)

追加以百分比表示的月度热力图表格。

grid.values 不是年数 x 12 时抛出 input_error；缺失单元格打印 NaN。

std::string build() const

构建自包含的确定性 HTML 文档。

void save(const std::string &path) const

将构建的文档写入 path。

路径为空，或文件无法打开或写入时，抛出 input_error。

inline const std::vector<std::string> &sections() const noexcept

按顺序返回已追加的小节片段。

公共静态函数

static std::string_view css()

稳定的报告 CSS（Python HtmlReportBuilder._CSS 代码块）。

class plotly_backend

原生 Plotly 兼容后端。

镜像 fincore.viz.interactive.plotly_backend.PlotlyBackend 的产物行为。图表输入为原生图表数据，而非 pandas 对象。show 为无头模式，始终报告 NOT_RUN_INTERACTIVE。

公共函数

explicit plotly_backend(std::string theme = "light", int height = 500, std::optional<int> width = std::nullopt, std::optional<std::string> template_name = std::nullopt, bool show_legend = true)

使用主题、尺寸、模板和图例选项创建后端。

dark 和 plotly_dark 主题解析为深色以及 plotly_dark 默认模板；其他名称使用浅色和 plotly_white。高度或宽度不为正时抛出 input_error。

inline const std::string &theme() const noexcept

返回配置的主题名称。

inline const plotly_color_theme &colors() const noexcept

返回解析后的主题颜色。

inline const std::string &default_template() const noexcept

返回由主题派生的默认模板名称。

const std::string &effective_template() const noexcept

返回显式模板；未设置时返回主题默认模板。

inline int height() const noexcept

返回配置的图形高度。

inline const std::optional<int> &width() const noexcept

返回配置的图形宽度（若有）。

inline bool show_legend() const noexcept

返回文档图例是否启用。

plotly_document create_document(std::string title) const

具有配置模板、尺寸和主题颜色的基础文档。

plotly_document plot_returns(const series_chart &chart)

构建并记录累积收益图形。

图表没有序列，或序列标签与值数量不一致时，抛出 input_error。

plotly_document plot_drawdown(const series_chart &chart)

构建并记录带填充序列的回撤图形。

图表没有序列，或序列标签与值数量不一致时，抛出 input_error。

plotly_document plot_rolling_sharpe(const series_chart &chart, std::size_t window = 252)

构建并记录滚动夏普比率图形。

记录的 chart.window 非零时优先；对于未记录窗口的图表，window 为回退值。图表没有序列或长度不一致时抛出 input_error。

plotly_document plot_monthly_heatmap(const heat_grid &grid)

构建并记录月度收益热力图。

没有年份，或值不是年数 x 12 时，抛出 input_error。

plotly_document plot_correlation_matrix(const correlation_matrix &matrix)

构建并记录相关性热力图。

标签为空，或值不是标签数 x 标签数时，抛出 input_error。

plotly_document plot_efficient_frontier(const frontier_chart_data &frontier)

构建并记录有效前沿图形。

volatilities 与 returns 长度不同时抛出 input_error。

void set_figure(plotly_document document)

将外部组装的文档记录为当前图形。

inline bool has_figure() const noexcept

返回是否已记录图形。

const plotly_document &figure() const

尚未运行任何绘图方法时抛出 input_error。

void save_html(const std::string &path) const

将记录的图形写为自包含 HTML。

不存在图形或路径无法写入时抛出 input_error。

void save_image(const std::string &path) const

将记录的图形写为 SVG。

不存在图形或路径无法写入时抛出 input_error。

bool show() const

无头模式：返回 false，记录 NOT_RUN_INTERACTIVE。

inline std::string_view last_show_status() const noexcept

返回最近一次 show 调用记录的状态。

class printf_tick_formatter

PrintfTickFormatter 的原生等价实现。

支持一个 printf 转换——%[flags][width][.precision] 后接 f、e、g、d 或 i 之一——以及 %%。无效格式会抛出 input_error，而不是 Python 的 ValueError/TypeError。

公共函数

explicit printf_tick_formatter(std::string format = "%.1f")

创建格式化器并校验 format。

存在内嵌 NUL、不支持的转换、不完整的格式或多于一个转换时，抛出 input_error。

std::string format(double value) const

使用配置的转换格式化 value。

inline const std::string &format_string() const noexcept

返回配置的格式字符串。

class renderer_snapshot

显式注册的原生渲染器回调的持有型快照。

名称按 ASCII 空白裁剪，并按 ASCII 规则转为小写。归一化后为空或重复的名称，或空回调会被拒绝。该快照不扫描插件、不导入可选依赖，也不修改进程级注册表。render 在调用期间将模型副本传给回调；需要排队处理工作的回调必须在返回前复制该模型。回调捕获的可变状态仍由调用方负责。内置 HTML 渲染仍是对 report_document 调用 render_html。

公共函数

explicit renderer_snapshot(renderer_map renderers)

创建所提供渲染器回调的不可变快照。

归一化名称为空、回调为空，或名称在裁剪和 ASCII 小写化后冲突时，抛出 input_error。

renderer_callback resolve_renderer(std::string_view name) const

返回名称归一化后以 name 注册的回调。

归一化名称为空或未知时抛出 input_error。

report_document render(std::string_view name, const render_model &model) const

使用模型副本渲染 name，并返回其报告文档。

渲染器未知时抛出 input_error；回调引发的异常原样传播。

struct bar_chart

行主序的分组柱状图数据。

公共成员

std::vector<std::string> group_labels

x 轴上的分组标签。

std::vector<std::string> series_labels

按绘制顺序排列的序列名称。

std::vector<double> values

行主序的组数 x 序列数值。

struct bokeh_document

持有型 Bokeh 兼容图表文档。

生成具有等价数据、坐标轴、图例和序列的自包含 HTML/JSON 文档。不复制 BokehJS 的模型身份。

公共函数

std::string to_json() const

将文档序列化为确定性的 Bokeh 兼容 JSON。

矩形图元的 x、y 和值长度不一致，或图元的 x 与 y 长度不一致时，抛出 input_error。

std::string to_svg() const

文档的确定性 SVG 渲染（不使用第三方资源）。

std::string to_html() const

返回包含内联 SVG 和 JSON 负载的自包含 HTML。

void save_html(const std::string &path) const

将 to_html() 的输出写入 path。

路径为空，或文件无法打开或写入时，抛出 input_error。

公共成员

std::string title

文档标题。

std::string x_axis_type = "datetime"

X 轴类型。

std::string x_axis_label

X 轴标签。

std::string y_axis_label

Y 轴标签。

int height = 500

绘图高度。

int width = 800

绘图宽度。

std::string sizing_mode = "fixed"

Bokeh 尺寸模式。

std::string background_fill_color = "#FFFFFF"

绘图背景。

std::string border_fill_color = "#FFFFFF"

外层背景。

std::string grid_line_color = "#E0E0E0"

网格线颜色。

std::string text_color = "#424242"

文本颜色。

std::string axis_location

坐标轴位置；为空则省略。

std::string toolbar_location

工具栏位置；为空则省略。

bool grid_visible = true

网格线是否可见。

bool axis_visible = true

坐标轴是否可见。

std::string major_label_text_font_size

主刻度字体大小。

int major_label_standoff = 0

主刻度偏移距离。

int color_bar_desired_ticks = 10

请求的色条刻度数量。

std::vector<bokeh_glyph> glyphs

按绘制顺序排列的图元。

std::vector<bokeh_hover> hovers

悬停工具。

std::vector<bokeh_span> spans

跨度标注。

std::string legend_location

图例位置。

std::string legend_click_policy

图例点击策略。

std::vector<std::string> x_factors

分类 x 因子。

std::vector<std::string> y_factors

分类 y 因子。

std::string color_mapper_palette

颜色映射器调色板。

bool mapper_range_set = false

映射器范围是否生效。

double mapper_low = 0.0

设置时的映射器下界。

double mapper_high = 0.0

设置时的映射器上界。

bool color_bar = false

是否输出色条。

std::string color_bar_ticker = "BasicTicker"

色条刻度器类型。

struct bokeh_glyph

一个持有型 Bokeh 兼容图元渲染器。

值从原生图表数据复制；此处不重新计算任何内核。NaN 图表值序列化为 JSON null（显式缺口），而并行的标签数组保持其长度。

公共类型

enum class kind

支持的图元种类。

取值：

enumerator line

线图元。

enumerator varea

垂直面积图元。

enumerator rect

矩形热力图图元。

公共成员

kind type = kind::line

图元种类。

std::string x_field

用于 x 值的数据字段。

std::string y_field

用于 y 值的数据字段。

std::vector<std::string> x_labels

用于日期时间 x 轴的 ISO 日期标签；优先于 x_values。

std::vector<double> x_values

x_labels 为空时使用的数值 x 值。

std::vector<double> y_values

y 值；NaN 条目序列化为 JSON null。

std::string color

线颜色。

double line_width = 2.0

线宽。

std::string line_dash

线虚线样式，例如 "solid" 或 "dashed"。

std::string fill_color

面积填充颜色。

double fill_alpha = 1.0

面积填充不透明度。

std::string legend_label

图例条目标签。

std::vector<std::string> rect_x

矩形 x 类别标签。

std::vector<std::string> rect_y

矩形 y 类别标签。

std::vector<double> rect_values

展平的热力图单元格值；NaN 条目序列化为 JSON null。

std::string palette

命名调色板。

bool mapper_range_set = false

映射器范围是否生效。

double mapper_low = 0.0

设置时的映射器下界。

double mapper_high = 0.0

设置时的映射器上界。

struct bokeh_hover

Bokeh 兼容文档的悬停工具配置。

公共成员

std::vector<std::pair<std::string, std::string>> tooltips

工具提示对。

std::string mode = "mouse"

悬停模式。

std::map<std::string, std::string> formatters

字段格式化器名称。

struct bokeh_span

横跨绘图绘制的跨度标注。

公共成员

double location = 0.0

跨度在其坐标轴上的位置。

std::string dimension = "width"

跨度维度，即宽度或高度。

std::string line_color

跨度线颜色。

double line_alpha = 1.0

跨度线不透明度。

struct chart_series

图表中的一个带标签线序列。

公共成员

std::string label

图例标签。

std::vector<timestamp> index

观测时间戳。

std::vector<double> values

与索引对齐的值。

bool benchmark = false

此序列是否为基准序列。

bool dashed = false

线条是否为虚线。

struct correlation_matrix

两两 Pearson 相关矩阵。

公共成员

std::vector<std::string> labels

按矩阵顺序排列的资产标签。

std::vector<double> values

行主序的标签数 x 标签数；未定义时为 NaN。

std::vector<bool> present

每个矩阵单元格是否有定义。

std::string unit = "correlation"

值单位。

struct frontier_chart_data

可直接用于图表的有效前沿点和标记坐标。

公共成员

std::vector<double> volatilities

前沿波动率点。

std::vector<double> returns

前沿收益点。

std::vector<double> sharpe

前沿夏普比率点。

double min_variance_volatility = 0.0

最小方差波动率。

double min_variance_return = 0.0

最小方差收益。

double max_sharpe_volatility = 0.0

最大夏普比率波动率。

double max_sharpe_return = 0.0

最大夏普比率收益。

std::string x_label = "Volatility"

X 轴标签。

std::string y_label = "Return"

Y 轴标签。

struct heat_grid

以百分比表示的月度收益热力图数据。

公共成员

std::string title = "Monthly returns"

图表标题。

std::vector<int> years

行年份标签。

std::vector<std::string> columns

每列的月份标签。

std::vector<double> values

行主序的年数 x 12；缺失时为 NaN。

std::vector<bool> present

与 values 形状相同；缺失不等于零。

std::string unit = "percent"

值单位。

double color_min = -10.0

颜色刻度下界。

double color_max = 10.0

颜色刻度上界。

bool color_centered = true

颜色刻度是否居中。

struct histogram_bins

直方图边界、计数和密度。

公共成员

std::vector<double> edges

递增的分箱边界；比 bins 多一个。

std::vector<double> counts

每个分箱的有限观测计数。

std::vector<double> density

计数 / (n_observations * 分箱宽度)。

std::size_t n_observations = 0U

有限观测的数量。

struct html_metric

原生 HTML 报告构建器的一个持有型键/值条目。

Python 构建器接受浮点数的 pd.Series；原生构建器使用此显式条目，因此值要么是经过有限性检查的数字，要么是文本，要么不存在。缺失值的呈现遵循 Python oracle：统计表打印 nan，指标卡片打印 N/A。

公共成员

std::string key

指标显示键。

std::optional<double> number

存在时的数值。

std::optional<std::string> text

没有数字时的文本值。

公共静态函数

static html_metric number_metric(std::string key, double value)

创建带数值的指标。

static html_metric text_metric(std::string key, std::string value)

创建带文本值的指标。

static html_metric missing(std::string key)

创建不带值的指标。

struct plotly_annotation

布局坐标中的文本注释。

公共成员

std::string text

注释文本。

double x = 0.0

X 位置。

double y = 0.0

Y 位置。

std::string xref = "paper"

X 参考坐标系。

std::string yref = "paper"

Y 参考坐标系。

bool show_arrow = false

是否绘制箭头。

struct plotly_axis

Plotly 兼容文档的坐标轴配置。

公共成员

std::string title

坐标轴标题。

std::string side

坐标轴侧，例如 bottom。

bool reversed = false

坐标轴范围是否反向。

std::string tickmode

刻度模式，例如 array。

std::vector<double> tick_values

显式刻度位置。

std::vector<std::string> tick_text

显式刻度标签。

struct plotly_color_theme

原生 Plotly 兼容文档使用的主题颜色。

公共成员

std::string background

绘图区和纸张背景色。

std::string grid

网格线和零线颜色。

std::string text

标题、坐标轴和刻度文本颜色。

std::string positive

正标记的颜色。

std::string negative

负序列的颜色。

std::string neutral

基准或中性序列的颜色。

std::string highlight

主序列高亮颜色。

std::string warning

次标记颜色。

bool dark = false

主题是否使用深色背景。

struct plotly_document

持有型原生 Plotly 兼容图表文档。

to_json() 是确定性的（固定键顺序、Python 风格浮点文本），并覆盖 Plotly schema 中实际输出的子集：带 scatter/heatmap 字段的数据轨迹，以及包含标题、坐标轴、图例、形状和注释的布局。不声称与 Plotly.js 对象身份一致。

公共函数

std::string to_json() const

将文档序列化为确定性的 Plotly 兼容 JSON。

热力图轨迹的 heatmap_z/heatmap_columns 尺寸无效，或其标签与矩阵不匹配时，抛出 input_error。

std::string to_svg() const

文档的确定性 SVG 渲染（不使用第三方资源）。

std::string to_html() const

自包含 HTML：内联 SVG 加上确定性 JSON 负载。

void save_html(const std::string &path) const

将 to_html() 的输出写入 path。

路径为空，或文件无法打开或写入时，抛出 input_error。

void save_image(const std::string &path) const

写入 SVG；已声明与 Plotly 的 PNG 导出存在格式差异。

公共成员

std::string title

文档标题。

std::string template_name

Plotly 模板名称；为空则省略。

std::optional<int> height = 500

布局高度；为 nullopt 则省略。

std::optional<int> width

布局宽度；为 nullopt 则省略。

bool show_legend = true

是否显示图例。

std::string hovermode

悬停模式；为空则省略。

std::string font_color

字体颜色；为空则省略字体块。

std::string plot_background

绘图背景色。

std::string paper_background

纸张背景色。

std::string grid_color

网格线和零线颜色。

plotly_axis x_axis

X 轴配置。

plotly_axis y_axis

Y 轴配置。

std::vector<plotly_trace> traces

按绘制顺序排列的轨迹。

std::vector<plotly_shape> shapes

布局形状。

std::vector<plotly_annotation> annotations

布局注释。

struct plotly_shape

添加到布局的水平或线形形状。

公共成员

std::string type = "line"

形状类型。

double y0 = 0.0

第一个 y 坐标。

double y1 = 0.0

第二个 y 坐标。

std::string yref = "y"

Y 参考轴。

std::string xref = "paper"

X 参考坐标系。

double x0 = 0.0

第一个 x 坐标。

double x1 = 1.0

第二个 x 坐标。

std::string line_color

形状线颜色。

double line_width = 1.0

形状线宽。

std::string line_dash

形状线虚线样式。

struct plotly_trace

一个持有型 Plotly 兼容轨迹。

值从原生图表数据（series_chart、heat_grid、correlation_matrix、frontier_chart_data）复制；渲染从不重新计算金融内核。NaN 条目序列化为 JSON null，使缺失性显式可见。

公共类型

enum class kind

支持的轨迹种类。

取值：

enumerator scatter

散点或线轨迹。

enumerator heatmap

热力图轨迹。

公共成员

kind type = kind::scatter

轨迹种类。

std::string name

图例使用的轨迹名称。

std::string mode

Plotly 模式，例如 lines 或 markers。

std::string line_color

线颜色；为空则省略颜色。

double line_width = 0.0

线宽；为零则省略线块。

std::string line_dash

线虚线样式。

std::string fill

填充模式，例如 tozeroy。

std::string fill_color

填充颜色。

double marker_size = 0.0

标记大小；为零则禁用标记。

std::string marker_color

标记颜色。

std::string marker_symbol

标记符号，例如 star。

std::string hovertemplate

悬停模板字符串。

std::vector<std::string> x_labels

日期或类别标签；优先于 x_values。

std::vector<double> x_values

x_labels 为空时使用的数值 x 值。

std::vector<double> y_values

y 值；NaN 条目序列化为 JSON null。

std::vector<double> custom_data

逐点自定义数据；NaN 条目序列化为 JSON null。

std::vector<std::string> heatmap_x

热力图列标签。

std::vector<std::string> heatmap_y

热力图行标签。

std::vector<double> heatmap_z

行主序的热力图值；NaN 条目序列化为 JSON null。

std::size_t heatmap_columns = 0U

heatmap_z 中的列数。

std::string colorscale

命名颜色刻度。

std::vector<std::pair<double, std::string>> color_stops

以值/颜色对表示的自定义颜色刻度停靠点。

bool color_range_set = false

显式颜色范围是否生效。

double color_min = 0.0

设置时的颜色下界。

double color_max = 0.0

设置时的颜色上界。

bool zmid_zero = false

颜色刻度是否以零居中。

std::string colorbar_title

色条标题；为空则省略。

std::string colorbar_tickformat

色条刻度格式。

struct render_model

传给原生可视化渲染器的结构化、持有型输入。

这映射 fincore/viz/base.py（4b8f31b1b59707480d5db9603704d83bbf7e6946）中锁定的 Python RenderModel 字段：returns、可选的 factor_returns 和 period。C++ 使用原生频率枚举，而不是 Python 的字符串约定。

公共函数

explicit render_model(dataframe returns, std::optional<dataframe> factor_returns = std::nullopt, frequency period = frequency::daily)

根据提供的帧和周期创建持有型渲染模型。

公共成员

dataframe returns

投资组合收益帧。

std::optional<dataframe> factor_returns

可选的因子收益帧。

frequency period = frequency::daily

收益频率。

struct series_chart

持有型多序列折线图数据。

公共成员

std::string title

图表标题。

std::string y_label

Y 轴标签。

std::vector<chart_series> series

按绘制顺序排列的序列。

bool zero_line = false

是否绘制零线。

bool fill_to_zero = false

是否向下填充至零。

std::size_t window = 0U

记录的滚动窗口，或 0。

struct series_chart_spec

要从帧复制的一个序列的描述。

公共成员

std::string column

源 double 列名称。

std::string label

图例标签。

bool benchmark = false

该序列是否为基准。

bar_chart fincore::build_bar_chart(std::vector<std::string> group_labels, std::vector<std::string> series_labels, std::vector<double> values)

根据标签和行主序值构建分组柱状数据。

任一标签列表为空、某个标签为空、values 不含组数 x 序列数个条目，或某个值非有限时，抛出 input_error。

correlation_matrix fincore::build_correlation_matrix(const dataframe &frame)

从 double 列构建两两相关矩阵。

有限观测少于两个或方差为零的配对保持 NaN，且 present == false。不存在 double 列或列名称为空时抛出 input_error。

series_chart fincore::build_drawdown_chart(const dataframe &frame, std::string_view column = "drawdown", std::string_view label = "Drawdown")

构建启用填充至零的回撤图表。

列缺失或无效时抛出 input_error。

frontier_chart_data fincore::build_frontier_chart(const efficient_frontier_result &frontier)

根据有效前沿结果构建图表数据。

点向量长度不同，或任一值或标记坐标非有限时，抛出 input_error。

histogram_bins fincore::build_histogram(std::span<const double> values, std::size_t bins = 10U)

根据有限观测构建直方图分箱。

非有限值被忽略。当所有有限值都相等时，范围在每侧扩大 0.5。bins 为零或不存在有限观测时抛出 input_error。

heat_grid fincore::build_monthly_heatmap(const dataframe &returns, std::string_view column = returns_column)

根据收益列构建月度百分比热力图。

帧索引必须按升序排序，且 column 必须指定一个 double 列。没有有限复合值的月份保持 NaN，且 present == false；颜色范围覆盖观测值，若不存在值则默认为 -10..10。输入无效时抛出 input_error。

series_chart fincore::build_returns_chart(const dataframe &frame, std::string_view column = "cumulative_returns", std::string_view label = "Cumulative Returns")

根据帧列构建累积收益图表。

该图表包含零线，并使用 "Cumulative Returns" 和 "Cumulative Return" 作为标题和坐标轴标签。列缺失或无效时抛出 input_error。

series_chart fincore::build_rolling_sharpe_chart(const dataframe &portfolio, std::string_view column, std::size_t window, const dataframe *benchmark = nullptr, std::string_view benchmark_column = "benchmark_sharpe", std::string_view label = "Portfolio Sharpe", std::string_view benchmark_label = "Benchmark Sharpe")

构建滚动夏普比率图表并记录窗口。

benchmark 非空时，从 benchmark_column 读取虚线基准序列。列缺失或无效、投资组合标签为空，或在提供基准时基准标签为空，都会抛出 input_error。

series_chart fincore::build_series_chart(const dataframe &frame, const std::vector<series_chart_spec> &specs, std::string title, std::string y_label, bool zero_line = false, bool fill_to_zero = false)

根据命名帧列构建折线图。

每个序列复制帧索引和请求的 double 列。基准序列标记为 benchmark 并使用虚线。specs 为空、标签为空，或列缺失或无效时，抛出 input_error。

void fincore::plot_bar_chart(const bar_chart &chart)

根据柱状图数据绘制分组柱。

void fincore::plot_correlation_matrix(const correlation_matrix &matrix)

绘制带标签坐标轴的相关性热力图。

void fincore::plot_cumulative_returns(const dataframe &frame, std::string_view column)

绘制带日期轴的累积收益列。

void fincore::plot_drawdown(const dataframe &frame, std::string_view column)

绘制带日期轴的回撤列。

void fincore::plot_drawdown_chart(const series_chart &chart)

将回撤序列绘制为带叠加线条的阴影区域。

void fincore::plot_events_distribution_chart(const events_distribution_chart &chart)

将事件计数绘制为按时间分桶的柱。

void fincore::plot_frontier_chart(const frontier_chart_data &chart)

绘制有效前沿曲线及其标记点。

void fincore::plot_histogram(const histogram_bins &bins)

绘制按分箱中心排列的直方图计数。

void fincore::plot_monthly_heatmap(const heat_grid &grid)

绘制月度热力图网格；空网格会被忽略。

void fincore::plot_monthly_ic_heatmap(const monthly_ic_heatmap_chart &chart)

绘制固定颜色范围 -0.2 到 0.2 的月度 IC 热力图。

void fincore::plot_qq_chart(const qq_chart &chart)

绘制观测分位数与理论分位数的对比，并带参考线。

void fincore::plot_quantile_cumulative_chart(const quantile_cumulative_chart &chart)

按日期绘制累积分位数序列。

void fincore::plot_rolling_metric(const dataframe &frame, std::string_view column, std::string_view label)

使用 label 作为标题和图例绘制滚动指标列。

void fincore::plot_series_chart(const series_chart &chart)

绘制折线图的每个序列，包括可选的零线。

void fincore::plot_spread_time_series(const spread_time_series_chart &chart)

绘制价差、滚动均值、带和零线。

void fincore::plot_violin_chart(const violin_chart &chart)

按组绘制分位数密度形状和中位数。

using fincore::renderer_callback = std::function<report_document(const render_model &model)>

将渲染模型转换为报告文档的回调。

using fincore::renderer_map = std::map<std::string, renderer_callback>

以调用方提供的名称为键的渲染器回调。

constexpr std::string_view fincore::NOT_RUN_INTERACTIVE = "NOT_RUN_INTERACTIVE"

由原生 show 入口记录的无头交互状态。

原生构建从不打开浏览器或 GUI 窗口。show 返回 false，此常量是文档中说明的状态，调用方可记录它而不声称进行了交互显示。

constexpr std::string_view fincore::month_labels[] = {"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"}

月度热力图列使用的英文月份标签。