因子研究

因子数据准备、PIT 对齐、前向收益率、成本、研究评估、详细研究、tear sheet 与序列化。

面向任务的示例参见使用指南。以下签名由公共头文件生成，与本网站其余部分取自同一提交。

class dataframe_snapshot

自有原生 DataFrame 快照（替代 pandas pickle 快照）。

公共函数

dataframe_snapshot() = default: 构造一个摘要为空的空快照。

explicit dataframe_snapshot(dataframe value)

对 value 建立快照并计算其内容摘要。

参数:: value -- Dataframe to take ownership of.
抛出:: fincore_error -- If a column type cannot be encoded in the canonical content representation.

inline const dataframe &data() const noexcept: 返回自有的 DataFrame。

inline dataframe copy() const: 返回自有 DataFrame 的副本。

inline const std::string &content_sha256() const noexcept: 返回小写十六进制内容摘要；对默认构造的快照为空。

class enhanced_non_matching_timezone_error : public fincore::factor_data_error 

增强内核时区校验错误（Python 中继承自 ValueError）。

公共函数

inline explicit enhanced_non_matching_timezone_error(const std::string &message = "factor and prices have different timezones")

用给定的消息构造该增强错误。

参数:: message -- Failure description; defaults to the pinned mismatch text.

class factor_data_error : public std::invalid_argument

报告无效的因子数据或操作输入。

Subclassed by fincore::enhanced_non_matching_timezone_error, fincore::factor_loss_exceeded

class factor_loss_exceeded : public fincore::factor_data_error 

报告超出配置预算的因子清洗损失。

公共函数

inline factor_loss_exceeded(const std::string &message, factor_loss_report report)

用消息和损失报告构造该错误。

参数:

message -- Failure description.
report -- Cleaning-loss breakdown that exceeded the budget.

公共成员

factor_loss_report loss_report: 清洗损失明细。

class factor_value

因子序列化使用的确定性原生值模型。

对象为有序映射，因此无论插入顺序如何，JSON 输出与指纹都保持稳定。双精度数在规范编码中保留其 IEEE-754 位模式；NaN 载荷会被规范化为同一个静默 NaN。

公共类型

using array_type = std::vector<factor_value>: 值的有序数组。

using object_type = std::map<std::string, factor_value>: 从字符串键到值的有序映射。

公共函数

factor_value() = default: 构造空值（null）。

inline factor_value(std::nullptr_t): 由 nullptr 构造空值。

inline factor_value(bool value): 构造布尔值。

inline factor_value(int value): 由 int 构造 64 位整数值。

inline factor_value(std::int64_t value): 构造 64 位整数值。

inline factor_value(double value): 构造浮点数值。

inline factor_value(std::string value): 构造字符串值，并取得 value 的所有权。

inline factor_value(const char *value): 通过复制 value 构造字符串值。

inline factor_value(array_type value): 构造数组值，并取得 value 的所有权。

inline factor_value(object_type value): 构造对象值，并取得 value 的所有权。

inline bool is_null() const noexcept: 返回值是否为 null。

inline bool is_bool() const noexcept: 返回值是否持有布尔值。

inline bool is_integer() const noexcept: 返回值是否持有 64 位整数。

inline bool is_number() const noexcept: 返回值是否持有浮点数；整数是单独的另一种取值。

inline bool is_string() const noexcept: 返回值是否持有字符串。

inline bool is_array() const noexcept: 返回值是否持有数组。

inline bool is_object() const noexcept: 返回值是否持有对象。

inline bool as_bool() const

返回存储的布尔值。

抛出:: std::bad_variant_access -- If the value holds another type.

inline std::int64_t as_integer() const

返回存储的 64 位整数。

抛出:: std::bad_variant_access -- If the value holds another type.

inline double as_number() const

返回存储的浮点数。

抛出:: std::bad_variant_access -- If the value holds another type.

inline const std::string &as_string() const

返回存储的字符串。

抛出:: std::bad_variant_access -- If the value holds another type.

inline const array_type &as_array() const

返回存储的数组。

抛出:: std::bad_variant_access -- If the value holds another type.

inline const object_type &as_object() const

返回存储的对象。

抛出:: std::bad_variant_access -- If the value holds another type.

inline array_type &as_array()

返回存储的数组以便修改。

抛出:: std::bad_variant_access -- If the value holds another type.

inline object_type &as_object()

返回存储的对象以便修改。

抛出:: std::bad_variant_access -- If the value holds another type.

const factor_value &at(std::string_view key) const

返回存储在 key 下的值。

参数:: key -- Object key to look up.
抛出:: input_error -- If the value is not an object or key is absent.
返回:: Reference to the stored value.

const factor_value *find(std::string_view key) const noexcept

查找存储在 key 下的值。

参数:: key -- Object key to look up.
返回:: Pointer to the stored value, or nullptr when the value is not an object or key is absent.

友元

friend bool operator==(const factor_value&, const factor_value&) = default

template<typename Value> class frozen_mapping

不可变有序映射。

构造时对给定的映射建立快照；调用方无法修改已存储的条目，修改源对象也不产生影响。

公共类型

using storage_type = std::map<std::string, Value>: 用于存储条目的有序映射类型。

using const_iterator = typename storage_type::const_iterator: 对已存储条目的只读迭代器。

公共函数

frozen_mapping() = default: 构造空映射。

inline explicit frozen_mapping(storage_type values)

构造取得 values 所有权的映射。

参数:: values -- Entries to store; the map is moved into the snapshot.

inline frozen_mapping(std::initializer_list<typename storage_type::value_type> values)

由初始化列表构造映射。

参数:: values -- Entries to copy into the mapping.

inline const Value &at(const std::string &key) const

返回存储在 key 下的值。

参数:: key -- Entry key to look up.
抛出:: std::out_of_range -- If key is absent.
返回:: Reference to the stored value.

inline const Value *find(const std::string &key) const noexcept

查找存储在 key 下的值。

参数:: key -- Entry key to look up.
返回:: Pointer to the stored value, or nullptr when key is absent.

inline bool contains(const std::string &key) const noexcept

返回 key 是否存在。

参数:: key -- Entry key to look up.

inline std::size_t size() const noexcept: 返回条目数量。

inline bool empty() const noexcept: 返回映射是否没有任何条目。

inline const_iterator begin() const noexcept: 返回指向按键顺序排列的首个条目的迭代器。

inline const_iterator end() const noexcept: 返回尾后迭代器。

inline storage_type snapshot() const: 返回所存储映射的可变副本。

友元

friend bool operator==(const frozen_mapping&, const frozen_mapping&) = default

class grid_figure

替代基于 Matplotlib 的 GridFigure 的原生布局模型。

它只拥有几何信息（图尺寸、间距和已分配单元格）；不声明 Python 图对象标识。close 是幂等的，之后的任何分配都会失败，与源实现的生命周期一致。

公共函数

grid_figure(std::size_t rows, std::size_t cols)

创建具有 rows 行、cols 列的网格。

参数:

rows -- Row count; must be positive.
cols -- Column count; must be positive.

抛出:

factor_data_error -- If rows or cols is zero.

inline std::size_t rows() const noexcept: 返回配置的行数。

inline std::size_t cols() const noexcept: 返回配置的列数。

inline std::size_t current_row() const noexcept: 返回当前游标行。

inline std::size_t current_col() const noexcept: 返回当前游标列。

inline bool closed() const noexcept: 返回是否已调用 close()。

inline double width() const noexcept: 返回固定的图宽度 14。

inline double height() const noexcept: 返回图高度，每行七个单位。

inline double wspace() const noexcept: 返回固定的水平间距 0.4。

inline double hspace() const noexcept: 返回固定的垂直间距 0.3。

inline const std::vector<grid_cell> &cells() const noexcept: 按分配顺序返回已分配的单元格；close() 之后为空。

std::uint64_t create_new_figure() const

返回自有的图标识符（每个原生网格均为 1）。

抛出:: std::runtime_error -- If the grid is closed.
返回:: Figure identifier, always 1.

grid_cell next_row()

分配下一个整行。

抛出:

std::runtime_error -- If the grid is closed.
std::out_of_range -- If the next row lies beyond the grid.

返回:

Allocated full-row cell.

grid_cell next_cell()

分配下一个单元格，必要时推进到新的一行。

抛出:

std::runtime_error -- If the grid is closed.
std::out_of_range -- If the next cell lies beyond the grid.

返回:

Allocated cell.

void close() noexcept

关闭此网格的图并释放布局状态。

该调用是幂等的。

class max_loss_exceeded_error : public std::runtime_error

用于清洗损失预算被拒绝的固定严格标识。

公共函数

inline explicit max_loss_exceeded_error(std::string message = "", factor_loss_report report = {})

用可选的消息和损失报告构造该错误。

参数:

message -- Failure description.
report -- Cleaning-loss breakdown associated with the failure.

公共成员

factor_loss_report loss_report: 该错误的清洗损失明细。

class non_matching_timezone_error : public std::runtime_error

用于因子与价格时区不匹配的固定严格标识。

公共函数

inline explicit non_matching_timezone_error(const std::string &message = "factor and prices have different timezones")

用给定的消息构造该错误。

参数:: message -- Failure description; defaults to the pinned mismatch text.

class research_config_error : public fincore::research_error 

类别为 ConfigError 的研究错误。

公共函数

inline explicit research_config_error(const std::string &message, std::string code = default_code, std::map<std::string, std::string> report = {})

构造配置错误。

参数:

message -- Human-readable failure description.
code -- Machine-readable identifier; defaults to invalid_config.
report -- Optional structured diagnostic fields.

公共静态属性

static constexpr const char *default_category = "ConfigError": 配置失败时报告的类别名。

static constexpr const char *default_code = "invalid_config": 无效配置的默认机器可读代码。

class research_data_quality_error : public fincore::research_error 

类别为 DataQualityError 的研究错误。

公共函数

inline explicit research_data_quality_error(const std::string &message, std::string code = default_code, std::map<std::string, std::string> report = {})

构造数据质量错误。

参数:

message -- Human-readable failure description.
code -- Machine-readable identifier; defaults to data_quality.
report -- Optional structured diagnostic fields.

公共静态属性

static constexpr const char *default_category = "DataQualityError": 数据质量失败时报告的类别名。

static constexpr const char *default_code = "data_quality": 数据质量失败的默认机器可读代码。

class research_dataset_error : public fincore::research_error 

类别为 DatasetError 的研究错误。

公共函数

inline explicit research_dataset_error(const std::string &message, std::string code = default_code, std::map<std::string, std::string> report = {})

构造数据集错误。

参数:

message -- Human-readable failure description.
code -- Machine-readable identifier; defaults to invalid_dataset.
report -- Optional structured diagnostic fields.

公共静态属性

static constexpr const char *default_category = "DatasetError": 数据集失败时报告的类别名。

static constexpr const char *default_code = "invalid_dataset": 无效数据集的默认机器可读代码。

class research_dependency_error : public fincore::research_error 

类别为 DependencyError 的研究错误。

公共函数

inline explicit research_dependency_error(const std::string &message, std::string code = default_code, std::map<std::string, std::string> report = {})

构造依赖错误。

参数:

message -- Human-readable failure description.
code -- Machine-readable identifier; defaults to missing_dependency.
report -- Optional structured diagnostic fields.

公共静态属性

static constexpr const char *default_category = "DependencyError": 依赖缺失时报告的类别名。

static constexpr const char *default_code = "missing_dependency": 依赖缺失的默认机器可读代码。

class research_error : public fincore::fincore_error 

原生结构化研究错误。

不复制 Python 的异常继承关系；category 保留源类名，code 携带稳定的机器可读标识符。

Subclassed by fincore::research_config_error, fincore::research_data_quality_error, fincore::research_dataset_error, fincore::research_dependency_error, fincore::research_factor_computation_error

公共函数

inline research_error(std::string category, std::string code, const std::string &message, std::map<std::string, std::string> report = {})

构造结构化研究错误。

参数:

category -- Source exception class name preserved for callers.
code -- Stable machine-readable error identifier.
message -- Human-readable failure description.
report -- Optional structured diagnostic fields.

class research_factor_computation_error : public fincore::research_error 

类别为 FactorComputationError 的研究错误。

公共函数

inline explicit research_factor_computation_error(const std::string &message, std::string code = default_code, std::map<std::string, std::string> report = {})

构造因子计算错误。

参数:

message -- Human-readable failure description.
code -- Machine-readable identifier; defaults to factor_computation_failed.
report -- Optional structured diagnostic fields.

公共静态属性

static constexpr const char *default_category = "FactorComputationError": 因子计算失败时报告的类别名。

static constexpr const char *default_code = "factor_computation_failed": 计算失败的默认机器可读代码。

struct cumulative_quantile_series

单个分位在图表各日期上的累计增长。

公共成员

int quantile = 0: 分位桶标签。

std::vector<timestamp> dates: 与 values 对齐的日期；在构建器输出中已排序且唯一。

std::vector<double> values: 从 1.0 开始的累计增长；没有有限均值的日期沿用前一个值。

struct event_window_cell

针对某个偏移、事件日期和资产的单个有限事件窗口值。

公共成员

int offset = 0: 相对事件日期的行偏移；负值表示之前。

timestamp event_date = 0: 事件日期。

std::string asset: 资产标签；日期均值输出时为空。

double value = 0.0: 窗口值，按请求为复利值或原始值。

struct event_window_result

事件对齐的窗口提取。

公共成员

int before = 0: 每个事件日期之前请求的行数。

int after = 0: 每个事件日期之后请求的行数。

std::vector<int> offsets: 实际观测到的偏移，升序并已裁剪。

std::vector<timestamp> event_dates: 在账本中找到的事件日期。

std::vector<std::string> asset_labels: 在事件日期出现的资产，已排序。

std::vector<event_window_cell> cells: 单元格；跳过非有限的账本值。

struct events_distribution_chart

每个等宽时间桶的事件数。

公共函数

std::string to_svg() const

将各桶计数渲染为确定性的原生 SVG 柱状图。

没有计数的图表仍带有标题和坐标轴标签。

公共成员

bool valid = true: 图表是否可绘制；构建器将其保留为 true。

std::string title = "Distribution of events in time": 图表标题。

std::string x_label = "Date": X 轴标签。

std::string y_label = "Number of events": Y 轴标签。

std::size_t requested_bars = 50U: 请求的等宽桶数量，按传入值存储。

std::vector<timestamp> bucket_starts: 桶起始时间戳，与 counts 对齐。

std::vector<double> counts: 与 bucket_starts 对齐的事件计数。

struct factor_alpha_beta_row

单个前向收益率标签的年化 alpha 与市场 beta。

公共成员

std::string label: 前向收益率标签。

double annual_alpha: 年化截距；未定义时为 NaN。

double beta: 对股票池均值的斜率；未定义时为 NaN。

struct factor_analysis_config

选择单次分析运行的标签与结果视图的选项。

periods 缩小所分析的前向收益率标签范围；其余标志选择权重构建方式，以及填充哪些按分组或按组合的成员。

公共成员

bool long_short = true: 对权重和收益率去均值；false 保留原始值。

bool group_neutral = false: 在日期与分组内去均值；需要分组。

bool equal_weight = false: 对正负两侧等权。

bool by_group = false: 增加按分组的视图；需要分组列。

std::vector<std::string> periods: 为空时选择所有前向收益率标签。

std::vector<int> turnover_periods = {1}: 正的、唯一的滞后值。

std::vector<std::string> time_aggregation = {"M"}: 原生仅实现按月 "M"/"ME" 聚合。

bool include_portfolio_inputs = true: 为第一个选中的周期构建输入。

std::string portfolio_benchmark_period = "1D": 记录在指纹中的非空标签。

struct factor_analysis_model

单次 analyze_factor 运行的完整结果。

每次运行都会构建聚合成员；仅当 config.by_group 为 true 时才出现按分组成员，而事件成员仅出现在接收事件收益率账本的重载中。

公共函数

std::string to_serializable() const

返回确定性的 JSON 序列化信封。

在 factor/serialization.cpp 中实现；在此声明，以便该模型保留源实现的 to_serializable 成员路径。

返回:: JSON text of the serialization envelope.

公共成员

prepared_factor_data factor_data: 所分析输入的自有副本。

std::vector<std::string> forward_periods: 选中的标签，按请求顺序。

std::vector<factor_quantile_statistics> quantile_statistics: 各分位的因子分布。

factor_ic_table information_coefficient: 按日期和标签的聚合秩 IC；从不用分组行填充。

factor_ic_summary mean_information_coefficient: 每个标签的有限聚合 IC 值的均值。

factor_return_table factor_returns: 按日期和标签的组合收益率。

std::vector<factor_weight_row> factor_weights: 逐观测权重。

quantile_return_table mean_returns_by_quantile: 聚合分位均值。

quantile_date_return_table mean_returns_by_date: 按日期的分位均值。

std::vector<factor_spread_row> mean_return_spread: 每个标签的多空收益差；观测到的分位少于两个时为空。

std::vector<factor_alpha_beta_row> alpha_beta: 每个标签的年化 alpha 与 beta。

std::vector<factor_turnover_series> quantile_turnover: 按请求滞后与观测分位的换手率。

std::vector<factor_rank_autocorrelation_series> rank_autocorrelation: 按请求滞后的秩自相关。

std::vector<factor_cumulative_curve> factor_cumulative_returns: 每个选中周期的复利因子收益曲线。

std::vector<factor_quantile_curve> quantile_cumulative_returns: 每个选中周期的复利分位增长曲线。

std::vector<factor_position_series> factor_positions: 每个选中周期的重叠持仓。

std::vector<factor_time_information_table> time_aggregated_information: 月度平均 IC，每个请求频率一张表。

std::vector<factor_group_analysis> grouped_results: by_group 为 true 时独立重跑的各子组。

std::optional<factor_event_model> event_analysis: 仅当调用提供事件收益率账本时才存在。

std::optional<dataframe> event_input_snapshot: 所分析事件账本的自有副本。

std::optional<factor_portfolio_inputs> portfolio_inputs: 请求时来自第一个选中周期的每日输入。

std::string result_fingerprint: 选项、输入与事件账本的 SHA-256 十六进制摘要。

std::optional<factor_ic_table> summary_information_coefficient: 仅当 group_neutral 使旧版汇总 IC 与 information_coefficient 不同时才存在；否则该字段是同一视图。

std::vector<factor_group_snapshot> group_snapshots: 按分组的主要视图，仅当 config.by_group 为 true 时填充。

factor_analysis_config config: 所请求选项的自有副本，包括原始 periods。

std::uint32_t result_fingerprint_version = factor_analysis_fingerprint_version : 随该结果记录的指纹编码版本。

struct factor_capacity_result

权重面板相对美元成交额的容量估计。

公共成员

double maximum_portfolio_value = 0.0: 各日期容量中最小的有限值。

std::vector<timestamp> dates: 升序排列的面板日期。

std::vector<double> maximum_portfolio_value_by_date: 每个日期的容量；该日期没有交易时为正无穷。

std::vector<std::string> assets: 升序排列的面板资产。

std::vector<double> trade_weights: 日期 × 资产的绝对交易权重。

double max_participation = 1.0: 估计所使用的参与率上限。

timestamp binding_date = 0: 达到最小容量的首个日期。

std::string binding_asset: 在约束日期上限制容量的资产。

struct factor_cost_model

交易成本的价差、市场冲击与参与率设置。

公共成员

double half_spread_bps = 0.0: 每单位交易权重的半价差（基点）。

double impact_coefficient = 0.0: 冲击项的尺度。

double max_participation = 1.0: 参与率上限，取值在 (0, 1] 内。

double impact_exponent = 0.5: 参与率指数；必须为正。

struct factor_cost_result

将成本模型应用于毛收益后产生的按日期成本账本。

公共成员

factor_cost_model model: 账本所使用的成本模型。

double portfolio_value = 0.0: 计算该账本时所用的组合市值。

std::vector<timestamp> dates: 升序排列的面板日期。

std::vector<std::string> assets: 升序排列的面板资产。

std::vector<double> gross_returns: 每个日期的毛收益，从输入复制。

std::vector<double> net_returns: 每个日期的毛收益减总成本。

std::vector<double> turnover: 每个日期的单边换手率。

std::vector<double> spread_cost: 每个日期的价差成本，以收益率占比表示。

std::vector<double> impact_cost: 每个日期的市场冲击成本，以收益率占比表示。

std::vector<double> borrow_cost: 每个日期的融券成本，以收益率占比表示。

std::vector<double> total_cost: 每个日期的价差、冲击与融券成本之和。

std::vector<double> trade_weights: 日期 × 资产的绝对交易权重。

std::vector<double> participation: 日期 × 资产的成交额与美元成交额之比。

factor_capacity_result capacity: 在模型参与率上限下的容量估计。

struct factor_cumulative_curve

单个前向收益率标签的复利因子收益曲线。

公共成员

std::string period: 前向收益率标签。

factor_series_result values: 从 1 开始复利计算的按日期增长。

struct factor_event_model

由可选的事件收益率账本构建的事件窗口汇总。

公共成员

std::vector<int> offsets: 窗口偏移，升序。

std::vector<timestamp> event_dates: 在两个输入中都出现的事件日期。

std::vector<double> mean_returns: 每个偏移的均值；为空时为 NaN。

std::vector<double> return_distribution: 窗口单元格，先按偏移再按事件日期排序。

std::vector<quantile_event_statistics> quantile_average_returns: 各分位的事件均值，按分位升序。

struct factor_event_tear_charts

可选事件研究的图表数据。

公共成员

std::vector<int> offsets: 以观测数表示的事件偏移。

series_chart mean_returns: 跨偏移的平均收益率。

histogram_bins return_distribution: 事件窗口收益率的直方图。

series_chart quantile_average_returns: 跨偏移的各分位平均收益率。

struct factor_group_analysis

在单个子组的行上重跑分析。

公共成员

std::string group: 选出这些行的分组标签。

std::vector<factor_quantile_statistics> quantile_statistics: 子组内的因子值分布。

std::vector<factor_weight_row> factor_weights: 子组权重；本次重跑关闭分组调整。

factor_return_table factor_returns: 子组的组合收益率。

quantile_return_table mean_returns_by_quantile: 子组的分位均值与标准误。

factor_ic_table information_coefficient: 子组按日期的秩 IC。

factor_ic_summary mean_information_coefficient: 子组每个前向收益率标签的平均 IC。

std::vector<factor_turnover_series> quantile_turnover: 子组按请求滞后与分位的换手率。

std::vector<factor_rank_autocorrelation_series> rank_autocorrelation: 子组按请求滞后的秩自相关。

struct factor_group_snapshot

Python 中主要的 by_group 结果视图，与 grouped_results 分开保存。

这些表是在选出分组行之前基于完整分析股票池计算的，因此 long_short 去均值可能跨越分组。

公共成员

std::string group: 选出这些行的分组标签。

quantile_return_table mean_returns_by_quantile: 聚合分位均值的分组行。

quantile_date_return_table mean_returns_by_date: 按日期分位均值的分组行。

std::vector<factor_spread_row> mean_return_spread: 该分组的多空收益差行。

factor_ic_table information_coefficient: 秩 IC 表的分组行。

factor_ic_summary mean_information_coefficient: 该分组的平均 IC 行。

std::vector<factor_time_information_table> time_aggregated_information: 限于该分组的月度 IC 表。

struct factor_group_tear_charts

单个因子分组的图表数据。

公共成员

std::string group: 分组标签。

series_chart information_coefficient: 按前向标签的信息系数。

bar_chart quantile_returns: 每个前向标签的各分位平均收益率。

series_chart turnover: 主滞后下的分位换手率。

bar_chart spread: 按周期的最高分位减最低分位多空收益差。

series_chart rank_autocorrelation: 按滞后的秩自相关。

struct factor_grouping

用于分组分位化与准备工作的资产到分组映射。

空的 group_by_asset 映射会禁用分组。

公共成员

std::map<std::string, std::string> group_by_asset: 资产到分组名称。

std::map<std::string, std::string> group_labels: 可选的分组标签重映射。

struct factor_hypothesis

单个信息系数标签的推断结果。

公共成员

std::string label: 前向收益率标签。

std::size_t n_observations = 0U: 使用的有限 IC 观测数。

double mean_ic = 0.0: 这些观测的均值。

double t_stat = 0.0: t 统计量；无法检验的标签为 NaN。

double p_value = 0.0: 双侧 p 值；无法检验时为 NaN。

double adjusted_p_value = 0.0: Benjamini-Hochberg 值；无法检验时为 NaN。

bool rejected = false: 当调整后的检验在 alpha 水平上拒绝时为 true。

bool testable = false: 至少有两个有限观测时为 true。

struct factor_ic_summary

每个标签或每个分组的平均信息系数。

公共成员

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> means: 标签或分组 × 标签。

std::vector<std::string> groups: 聚合输出时为空；否则 means 中每个分组行对应一个条目。

struct factor_ic_table

按日期和前向收益率标签的 Spearman 秩信息系数。

values 是矩形立方体：dates 的每个条目对应一行，labels 的每个条目对应一列；可用观测少于两个的单元格保持 NaN。

公共成员

std::vector<timestamp> dates: 行日期；按观测到的分组重复。

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> values: (date[, group]) 行 × 标签，缺失为 NaN。

std::vector<std::string> groups: 聚合输出时为空；否则与 dates 平行，其中 dates 按日期/分组顺序为每个观测到的 (date, group) 行重复一次。

struct factor_loss_report

单次因子准备的清洗损失核算。

每个 loss 成员是在该阶段丢弃的 input_count 占比，因此三个阶段损失之和等于 total_loss。

公共成员

std::size_t input_count = 0U: 输入因子面板中的行数。

std::size_t finite_factor_count = 0U: 因子值为有限值的行数。

std::size_t forward_returns_count = 0U: 所有前向标签均为有限值的行数。

std::size_t binning_count = 0U: 分位化后保留的行数。

double factor_input_loss = 0.0: 因因子值非有限而损失的比例。

double forward_returns_loss = 0.0: 因前向收益率缺失而损失的比例。

double binning_loss = 0.0: 分配分位时丢弃的比例。

double total_loss = 0.0: 三个阶段损失之和。

struct factor_model_envelope

原生信封能够恢复的序列化模型子集。

公共成员

std::string schema: 序列化 schema 标识符；本库写出并接受的值为 fincore-factor-analysis-native-v1。

std::uint32_t fingerprint_version = 0U: 信封中存储的结果指纹格式版本。

std::string result_fingerprint: 从信封恢复的结果指纹。

factor_analysis_config config: 从信封恢复的因子分析配置。

std::vector<std::string> forward_periods: 从信封恢复的前向收益率周期标签。

factor_loss_report loss_report: 从信封恢复的数据损失报告。

struct factor_operation_descriptor

因子运行时目录的稳定操作描述符。

公共成员

std::string operation_id: 稳定的操作标识符。

std::string capability_id: 生成时等于 operation_id。

std::string domain: 生成时等于 "factor_analysis"。

std::map<std::string, std::string> provenance: 所有者与内核键。

struct factor_portfolio_inputs

由单个因子周期构建的每日组合输入。

公共成员

factor_series_result returns: 由复利周期曲线生成的每日简单收益率。

std::vector<factor_weight_row> positions

每日总敞口归一化资产权重，外加每个时间戳一条显式现金行。

现金使每一行的带符号合计恰好为 1。

std::optional<factor_series_result> benchmark_returns: 当请求的周期对应某个前向收益率列时，为每日纯多头等权基准收益率；否则不存在。

struct factor_position_series

单个前向收益率标签的重叠组合持仓。

公共成员

std::string period: 前向收益率标签。

std::vector<factor_weight_row> positions: 该标签的持仓。

struct factor_quantile_curve

单个前向收益率标签的复利分位增长曲线。

公共成员

std::string period: 前向收益率标签。

std::vector<timestamp> dates: 曲线日期，升序。

std::vector<int> quantiles: 降序，与源渲染器一致。

std::vector<double> values: 日期 × 分位的复利增长。

struct factor_quantile_statistics

单个分位桶内的因子值分布。

只统计有限因子值，因此各矩描述的是通过准备阶段保留下来的值。

公共成员

int quantile = 0: 分位标签。

double minimum = 0.0: 最小的有限因子值。

double maximum = 0.0: 最大的有限因子值。

double mean = 0.0: 有限值的算术平均。

double stddev = 0.0: 样本标准差，少于两个值时为 NaN。

std::size_t count = 0U: 桶内的有限因子观测数。

double count_percent = 0.0: 占全部有限值的比例，以百分比表示。

struct factor_rank_autocorrelation_series

单个滞后的秩自相关序列。

公共成员

int lag = 1: 以观测数表示的日期滞后。

factor_series_result values: 按日期的秩相关；预热期内为 NaN。

struct factor_return_table

按日期与前向收益率标签的组合收益率。

公共成员

std::vector<timestamp> dates: 已排序的唯一日期。

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> values: 日期 × 标签；没有可用配对时为 0。

struct factor_row

一条准备好的因子观测。

公共成员

timestamp date = 0: 观测日期。

std::string asset: 资产标识符。

double factor = 0.0: 有限的因子值。

int quantile = 0: 从 1 开始计数的分位标签。

bool has_group = false: 是否解析出分组标签。

std::string group: 分组标签，未分组时为空。

std::vector<double> forward_returns: 与 forward_labels 对齐的收益率。

struct factor_series

长表形式的因子面板，日期、资产与值按行对齐。

每个索引是一条观测。准备与分位化要求三个向量长度相等，且 (date, asset) 对唯一。

公共成员

std::vector<timestamp> dates: 观测日期。

std::vector<std::string> assets: 资产标识符。

std::vector<double> values: 因子值，每行一个。

struct factor_series_result

带日期的标量序列。

公共成员

std::vector<timestamp> dates: 序列日期，与 values 平行。

std::vector<double> values: 值；NaN 表示缺失点。

struct factor_spread_row

单个标签的最高分位减最低分位收益率多空收益差。

公共成员

std::string period: 前向收益率标签。

double spread = 0.0: 上分位均值减下分位均值。

double standard_error = 0.0: 合成误差；任一侧为 NaN 时即为 NaN。

std::string group: 聚合行为空；按分组的多空收益差行有值。

struct factor_tear_charts

单次因子分析的图表集合。

grouped 条目携带全部面板，而 group_snapshots 条目只携带其信息系数、分位收益率与多空收益差面板。

公共成员

series_chart information_coefficient: 按前向标签的信息系数。

bar_chart quantile_returns: 每个前向标签的各分位平均收益率。

series_chart turnover: 主滞后下的分位换手率。

bar_chart spread: 每个前向周期的最高分位减最低分位多空收益差。

series_chart rank_autocorrelation: 按滞后的秩自相关。

std::vector<factor_group_tear_charts> grouped: 包含全部面板的按分组图表。

std::vector<factor_group_tear_charts> group_snapshots: 按分组的快照图表。

std::optional<factor_event_tear_charts> event_analysis: 存在时的事件研究图表。

struct factor_time_information_table

信息系数的月度聚合。

公共成员

std::string frequency: 请求的聚合标签。

std::vector<timestamp> dates: 月份行；每个分组重复一次。

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> means: (date[, group]) 行 × 标签；为空时为 NaN。

std::vector<std::string> groups: 聚合输出时为空；否则与 dates 平行。

struct factor_turnover_series

单个分位与滞后的换手率序列。

公共成员

int quantile = 0: 分位标签。

int lag = 1: 以观测数表示的日期滞后。

factor_series_result values: 按日期的换手率；预热期内为 NaN。

struct factor_weight_row

某个日期上单个资产的权重。

公共成员

timestamp date: 观测日期。

std::string asset: 资产标识符。

double weight: 总敞口归一化权重；总敞口为零的桶为 NaN。

struct factor_workflow

一个具名的、与渲染器无关的因子工作流。

build 是规范的分析构建器；它从不重跑特定工作流的内核。renderer 保持为空，因为原生工作流返回准备好的模型与图表数据，而不是 Matplotlib 图。

公共成员

std::string workflow_id: 工作流标识符，例如 "summary"。

std::string model_operation_id: 分析内核的操作标识符。

std::vector<std::string> sections: 有序的分析小节名称。

std::optional<std::string> renderer: 可选的渲染器 ID；此处为空。

factor_analysis_model (*build)(const prepared_factor_data&, const factor_analysis_config&) = &analyze_factor : 由准备好的数据和配置构建分析模型。

struct fama_macbeth_estimate

一条估计出的 Fama-MacBeth 系数序列。

公共成员

double mean = 0.0: 各日期估计值的均值。

double std_error = 0.0: 该均值的标准误。

double t_stat = 0.0: 均值与标准误之比。

struct fama_macbeth_result

Fama-MacBeth 横截面回归结果。

公共成员

fama_macbeth_estimate intercept: 跨横截面的截距。

fama_macbeth_estimate exposure: 跨横截面的暴露斜率。

std::size_t n_cross_sections = 0U: 拟合后的横截面。

fama_macbeth_covariance covariance = fama_macbeth_covariance::iid : 请求的估计量。

std::size_t newey_west_lags = 1U: 请求的滞后阶数；即使为 i.i.d. 也会记录。

struct fdr_result

Benjamini-Hochberg 逐步上升校正的输出。

公共成员

std::vector<double> p_values: 输入的 p 值，按输入顺序。

std::vector<double> adjusted_p_values: 调整后的值，按输入顺序。

std::vector<bool> rejected: 每个输入的拒绝标志，按输入顺序。

double alpha = 0.05: 请求的错误发现率。

struct forward_return_table

因子观测的前向收益率，按标签分别存储。

dates 与 assets 构成行键；values 为 labels 的每个条目保存一个向量，均与这些行对齐。

公共成员

std::vector<std::string> labels: 预测期标签，例如 "1D"。

std::vector<timestamp> dates: 行日期，与 assets 平行。

std::vector<std::string> assets: 行资产，与 dates 平行。

std::vector<std::vector<double>> values: 标签 × 行，缺失为 NaN。

struct grid_cell

某个已分配网格单元格的从 0 开始的位置。

公共成员

std::size_t row = 0U: 从 0 开始的行号。

std::size_t col = 0U: 从 0 开始的列号；整行单元格为 0。

bool full_row = false: 单元格是否跨越整行。

std::size_t index = 0U: 在 cells() 中的分配顺序。

struct ic_inference_result

带错误发现率调整的各标签 IC 推断。

公共成员

double alpha = 0.05: 请求的错误发现率。

std::vector<factor_hypothesis> hypotheses: 每个标签一个条目。

struct ic_interval

平均 IC 的对称置信区间。

公共成员

double lower: 下界；未定义时为 NaN。

double upper: 上界；未定义时为 NaN。

struct monthly_ic_heatmap_chart

单个周期与分组的月度信息系数热力图。

公共函数

std::string to_svg() const

为每个存在的热力图单元格渲染一个矩形为原生 SVG。

单元格颜色使用按最大绝对值归一化的红蓝发散色阶。不绘制年份与月份标签。

公共成员

std::string period: 前向收益率周期标签。

std::string group: 分组标签；聚合输出时为空。

std::string title: 图表标题。

std::vector<int> years: 行年份标签，升序。

std::vector<std::string> month_columns: 十二个月份标签，一月在首。

std::vector<double> values: 年份 × 12 的值，按行优先顺序；缺失月份为 NaN。

std::vector<bool> present: 与 values 对齐的单元格存在标志。

struct multi_horizon_prepared_factor_data

准备好的因子面板，每个前向收益率预测期一个。

公共成员

std::vector<std::pair<std::string, prepared_factor_data>> by_horizon: 标签与面板配对，按请求周期的顺序。

struct named_factor_panel

多因子评估器接受的具名因子面板。

公共成员

std::string name: 因子名称；必须非空且唯一。

factor_series values: 按 (date, asset) 的因子值。

struct named_research_result

用于对比诊断的具名单因子结果。

公共成员

std::string name: 因子或组合名称；必须非空且唯一。

research_result result: 存储的评估结果。

struct owned_figures

由 tear sheet 工作流返回的、归调用方所有的图标识符。

公共成员

std::vector<std::uint64_t> figures: 按显示顺序的图标识符。

std::vector<bool> closed: 与 figures 对齐的关闭标志；由 close_owned_figures 填充。

struct pit_observation

用于物化面板的、以资产为范围的时点观测。

公共成员

std::string asset: 非空的资产标识符。

pit_point point: 该资产因子值的修订。

bool in_universe = true: 该资产是否进入物化后的面板。

struct pit_point

资产因子值的一次时点修订。

日期必须满足 as_of <= known_at <= effective_from。

公共成员

timestamp as_of = 0: 该值所描述的日期。

timestamp known_at = 0: 该值被获知的日期；不早于 as_of。

timestamp effective_from = 0: 首个生效日期；不早于 known_at。

double value = 0.0: 因子值；必须为有限值。

struct prepare_factor_config

因子准备的完整配置。

公共成员

int quantiles = 5: 分位桶数量。

bool use_bins = false: 使用等宽分箱而非分位数。

std::vector<double> bins: 显式分箱边界；为空时自动推导。

std::vector<int> periods = {1, 5, 10}: 以观测数表示的前向预测期。

double max_loss = 0.35: 在 [0, 1] 内可容忍的最大总清洗损失。

bool binning_by_group = false: 在每个 (date, group) 横截面内做分位化。

std::optional<double> filter_zscore: 各资产前向收益率的 z 分数截断值。

bool zero_aware = false: 区分负值与非负值。

bool cumulative_returns = true: 为 true 时在预测期内复利计算收益率。

factor_grouping grouping: 资产到分组的映射；为空则禁用分组。

struct prepared_factor_data

准备好的因子行及其标签与清洗损失报告。

公共成员

std::vector<factor_row> rows: 保留的观测。

std::vector<std::string> forward_labels: 与行收益率对齐的标签。

factor_loss_report loss_report: 清洗损失核算。

struct qq_chart

一个或多个周期的 Q-Q 图数据。

公共函数

std::string to_svg() const

将 Q-Q 散点与对角参考线渲染为原生 SVG。

此渲染器不使用 reference_slope 与 reference_intercept。

公共成员

std::vector<qq_series> series: 按绘制顺序的序列。

std::string x_label = "Normal Distribution Quantile": X 轴标签。

std::string y_label = "Observed Quantile": Y 轴标签。

struct qq_series

单个周期信息系数的正态 Q-Q 序列。

公共成员

std::string period: 前向收益率周期标签。

std::vector<double> theoretical_quantiles: 位于 (i + 1) / (n + 1) 处的标准正态分位数。

std::vector<double> observed_quantiles: 与 theoretical_quantiles 对齐的已排序 IC 观测；仅当均值为非零、尺度为正且不为 1 时才标准化。

double mean = 0.0: 观测的均值；非有限 IC 值按零计入。

double scale = 1.0: 观测的总体标准差。

double reference_slope = 1.0: 交互式后端绘制的参考线斜率。

double reference_intercept = 0.0: 交互式后端绘制的参考线截距。

struct quantile_cumulative_chart

单个前向周期每个分位的累计收益率图表数据。

公共函数

std::string to_svg() const: 将图表渲染为确定性的原生 SVG 文档。

公共成员

std::string period: 标题中使用的前向收益率周期标签。

std::string title: 图表标题。

std::string y_label = "Log Cumulative Returns": Y 轴标签。

std::vector<cumulative_quantile_series> series: 分位，降序。

double y_min = 0.0: 累计增长轴的下界。

double y_max = 1.0: 累计增长轴的上界。

bool log_scale = true: 对数刻度标志；原生 SVG 渲染器以线性方式映射累计值。

double reference = 1.0: 水平参考值，位于边界内时由 to_svg() 绘制。

struct quantile_date_return_table

按日期的分位平均收益率与标准误。

公共成员

std::vector<timestamp> dates: 行键；每个观测到的分组重复。

std::vector<int> quantiles: 分位键。

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> means: (date[, group]) × 分位 × 标签。

std::vector<double> standard_errors: (date[, group]) × 分位 × 标签。

std::vector<std::string> groups: 聚合输出时为空；否则与 dates 平行。

struct quantile_event_statistics

单个分位的事件窗口均值。

公共成员

int quantile = 0: 分位标签。

std::vector<int> offsets: 连续的偏移，从首个到最后一个。

std::vector<double> means: 每个偏移的均值；为空时为 NaN。

std::vector<double> standard_deviations: 样本偏差；少于两个值时为 NaN。

struct quantile_return_table

分位平均收益率与标准误。

公共成员

std::vector<int> quantiles: 行键；存在多个分组时重复。

std::vector<std::string> labels: 前向收益率标签。

std::vector<double> means: (quantile[, group]) 行 × 标签。

std::vector<double> standard_errors: (quantile[, group]) 行 × 标签。

std::vector<std::string> groups: 聚合输出时为空；否则与 quantiles 平行。

struct quantile_spread_result

最高分位减最低分位的多空收益差。

公共成员

std::vector<std::string> labels: 周期；每个分组重复。

std::vector<double> spreads: 上均值减下均值。

std::vector<double> standard_errors: 合成误差；任一侧为 NaN 时即为 NaN。

std::vector<std::string> groups: 聚合输出时为空；否则与 labels 平行。

struct quantization_config

因子横截面的分桶设置。

公共成员

int quantiles = 5: use_bins 为 false 时的桶数量。

bool use_bins = false: 使用等宽分箱而非分位数。

std::vector<double> bins: 显式分箱边界；为空时自动推导。

bool by_group = false: 在每个 (date, group) 横截面内分桶。

bool no_raise = false: 失败的桶留空而非抛出异常。

bool zero_aware = false: 区分负值与非负值。

struct render_customization

customize 装饰器的原生替代：渲染器在图表调用前后应用的上下文。

它不携带任何可调用对象身份。

公共成员

bool set_context = true: 是否在调用前后应用 context。

bool colorblind_palette = true: 是否使用色盲友好配色。

bool despine_left = true: 是否移除左侧边框。

style_context context = {"notebook", 1.5, {{"lines.linewidth", "1.5"}}}: 当 set_context 为 true 时在图表调用前后应用的上下文。

style_context axes = {"darkgrid", 1.5, {}}: 在图表调用前后应用的坐标轴样式。

std::vector<std::string> palette{"#0173B2", "#DE8F05", "#029E73", "#D55E00", "#CC78BC", "#CA9161", "#FBAFE4", "#949494"}: colorblind_palette 为 true 时使用的色盲安全颜色循环。

struct research_capabilities

固定版本的原生研究接口能力声明。

公共成员

std::string api_version = research_api_version : 研究 API 版本字符串。

int result_schema_version = research_result_schema_version : 结果模式版本。

std::vector<std::string> labels{"close_to_close", "next_open_to_open", "precomputed"}: 支持的标签基准。

std::vector<std::string> preprocess{"cross_section_rank", "cross_section_zscore", "none"}: 预处理方法。

std::vector<std::string> metrics{"pearson_ic", "spearman_ic", "icir", "quantile_returns", "spread", "rank_autocorrelation", "quantile_turnover", "factor_correlation", "paired_comparison"}: 对外声明的指标标识符。

std::vector<std::string> result_tables{"signals", "labels", "ic", "ic_summary", "quantile_returns", "turnover", "spreads", "stability", "correlation", "comparisons", "coverage", "diagnostics"}: research_result::table() 接受的名称。

std::vector<std::string> export_formats = {"json", "csv"}: 对外声明的导出格式。

std::vector<std::string> statuses = {"OK", "PARTIAL", "UNEVALUABLE"}: 评估状态。

struct research_comparison_row

单个因子对在单一周期上的平均 IC 与 ICIR 比较。

公共成员

std::string comparison: 来自请求映射的比较名称。

std::string left: 左侧因子名称。

std::string right: 右侧因子名称。

std::string period: 前向收益率周期标签。

double mean_ic = 0.0: 左减右的平均 IC；任一侧不可用时为 NaN。

double icir = 0.0: 左减右的 ICIR；任一侧不可用时为 NaN。

double mean_ic_left = 0.0: 左侧因子的平均 IC；不可用时为 NaN。

double mean_ic_right = 0.0: 右侧因子的平均 IC；不可用时为 NaN。

double icir_left = 0.0: 左侧 ICIR；日期过少或偏差为零时为 NaN。

double icir_right = 0.0: 右侧 ICIR；日期过少或偏差为零时为 NaN。

std::size_t n_dates_left = 0U: 左侧因子使用的有限 IC 日期数。

std::size_t n_dates_right = 0U: 右侧因子使用的有限 IC 日期数。

struct research_correlation_row

一个有序因子对的相关性摘要。

公共成员

std::string left: 左侧因子名称。

std::string right: 右侧因子名称。

double mean_correlation = 0.0: Pearson 相关系数均值；无有效值时为 NaN。

double std_correlation = 0.0: 样本标准差；日期少于两个时为 NaN。

std::size_t n_dates = 0U: 相关性为有限的日期数量。

struct research_detailed_coverage_row

本 API 所评估的单一因子的覆盖计数。

公共成员

std::string factor: 因子名称。

std::string kind = "factor": 覆盖行种类；此处为 "factor"。

int direction = 1: 应用的方向，+1 或 -1。

std::size_t input_cells = 0U: 窗口/目标筛选之后的单元数量。

std::size_t finite_cells = 0U: 处理后因子为有限的单元数量。

std::size_t label_cells = 0U: 至少有一个有限标签的单元数量。

std::size_t evaluable_cells = 0U: 因子与标签均为有限的单元数量。

std::string status: "OK"、"PARTIAL" 或 "UNEVALUABLE"。

struct research_detailed_diagnostic

结构化、与源实现兼容的诊断行。

当 Python 表中可空的 factor 值缺失时，factor 为空。

公共成员

std::optional<std::string> factor: 因子名称；缺失时为空。

std::string stage: 发出该诊断的评估阶段。

std::string severity: 严重程度，例如 "warning" 或 "error"。

std::string code: 稳定的机器可读诊断代码。

std::string message: 人类可读的诊断文本。

struct research_detailed_export_outcome

组合的详细评估与导出返回的带所有权元数据。

信号行与标签行以流式方式写入 CSV 文件，不会保留在该结果中；其行数仍可在本结果与 manifest 中获取。

公共成员

std::string status: 从结果复制的评估状态。

std::map<std::string, std::string> manifest: 评估 manifest。

std::vector<research_detailed_diagnostic> diagnostics: 评估诊断。

std::size_t signal_rows = 0U: 写入 signals.csv 的信号行数。

std::size_t label_rows = 0U: 写入 labels.csv 的标签行数。

research_export_result exported: 目录与导出文件名。

struct research_detailed_ic_row

来自 Python 研究 ic 表的一条日期/因子/周期观测。

公共成员

timestamp time = 0: 以 UTC 纳秒表示的观测日期。

std::string factor: 因子名称。

std::string period: 前向收益率周期标签。

double ic = 0.0: 该日期的 Pearson IC；未定义时为 NaN。

double rank_ic = 0.0: Spearman 秩 IC；未定义时为 NaN。

std::size_t n_assets = 0U: 对该 IC 有贡献的配对资产数量。

struct research_detailed_ic_summary_row

Pearson 与 Spearman（秩）IC 的有限观测摘要。

公共成员

std::string factor: 因子名称。

std::string period: 前向收益率周期标签。

double mean_ic = 0.0: 有限 Pearson IC 值的均值。

double std_ic = 0.0: Pearson IC 的样本标准差。

double icir = 0.0: 平均 IC 除以其样本标准差。

double mean_rank_ic = 0.0: 有限秩 IC 值的均值。

double std_rank_ic = 0.0: 秩 IC 的样本标准差。

double rank_icir = 0.0: 平均秩 IC 除以其样本标准差。

std::size_t n_dates = 0U: 有限 Pearson IC 观测数量。

struct research_detailed_quantile_return_row

一条日期/因子/周期/分位的原始收益均值及其参与计数。

公共成员

timestamp time = 0: 以 UTC 纳秒表示的观测日期。

std::string factor: 因子名称。

std::string period: 前向收益率周期标签。

int quantile = 0: 从 1 开始计数的分位标签。

double mean_return = 0.0: 该分位内原始前瞻收益的均值。

std::size_t n_assets = 0U: 对该均值有贡献的标签单元数量。

struct research_detailed_result

版本 2 为因子级详细研究表持有带类型的行。

行序遵循固定版本 Python 1.0 评估器的追加顺序；所有数值缺失值都是静默 NaN。单因子入口以空向量表示 Python 的相关性与比较表。

公共成员

std::string status: 总体状态："OK" 或 "UNEVALUABLE"。

std::vector<research_signal_row> signals: 每个面板单元的信号行。

std::vector<research_label_row> labels: 完整的面板 × 周期网格，缺失标签的取值为 NaN。

std::vector<research_detailed_ic_row> ic: 逐日 Pearson/秩 IC。

std::vector<research_detailed_ic_summary_row> ic_summary: 每个周期一条。

std::vector<research_detailed_quantile_return_row> quantile_returns: 分位均值。

std::vector<research_detailed_turnover_row> turnover: 分位换手率。

std::vector<research_detailed_spread_row> spreads: 逐日多空收益差。

std::vector<research_detailed_stability_row> stability: 秩稳定性。

std::vector<research_correlation_row> correlation: 本 API 下为空。

std::vector<research_comparison_row> comparisons: 本 API 下为空。

std::vector<research_detailed_coverage_row> coverage: 因子覆盖。

std::vector<research_detailed_diagnostic> diagnostics: 警告与错误。

std::map<std::string, std::string> manifest: 元数据与行数。

int schema_version = research_detailed_result_schema_version : 模式版本。

struct research_detailed_spread_row

逐日最高减最低分位的多空收益差及其使用的分位。

公共成员

timestamp time = 0: 以 UTC 纳秒表示的观测日期。

std::string factor: 因子名称。

std::string period: 前向收益率周期标签。

double spread = 0.0: 最高分位均值减最低分位均值。

int top_quantile = 0: 已填充的最高分位标签。

int bottom_quantile = 0: 已填充的最低分位标签。

struct research_detailed_stability_row

针对一个请求滞后的、覆盖整个处理后面板的稳定性摘要。

公共成员

std::string factor: 因子名称。

int lag = 0: 以观测日期计的滞后阶数。

double mean_rank_autocorrelation = 0.0: 秩自相关均值。

double std_rank_autocorrelation = 0.0: 样本标准差。

std::size_t n_dates = 0U: 自相关值为有限的数量。

struct research_detailed_turnover_row

使用 Python API 的周期专属滞后的分位换手率。

公共成员

timestamp time = 0: 以 UTC 纳秒表示的观测日期。

std::string factor: 因子名称。

std::string period: 前向收益率周期标签。

int quantile = 0: 从 1 开始计数的分位标签。

double turnover = 0.0: 在滞后日期缺席的成分占比。

struct research_evaluation_input

填充默认值之前由调用方提供的取值。

未设置的可选项采用固定版本的默认值；unknown_fields 对应源实现对未知键的拒绝。

公共成员

std::optional<std::vector<std::string>> targets: 可选的目标列表；归一化要求提供。

std::optional<timestamp> start: 可选的窗口起点；归一化要求提供。

std::optional<timestamp> end: 可选的窗口终点；归一化要求提供。

std::optional<std::string> snapshot_id: 可选的快照 id；未设置时使用 unspecified。

std::optional<std::string> price_basis: 可选的价格基准；未设置时使用 unspecified。

std::optional<std::string> calendar_id: 可选的日历 id；未设置时使用 unspecified。

std::optional<std::string> frequency: 可选的频率；未设置时使用 unspecified。

std::optional<std::string> source_timezone: 可选的时区元数据；未设置时使用 UTC。

std::optional<std::string> feed_time_kind: 可选的数据推送类型；未设置时使用 close_time。

std::optional<std::vector<int>> periods: 可选的预测期；未设置时使用 {1, 5, 20}。

std::optional<std::string> label: 可选的标签基准；未设置时使用 next_open_to_open。

std::optional<std::string> precomputed_entry: 可选的入场约定；未设置时使用 next_open。

std::optional<int> quantiles: 可选的分位数量；未设置时使用 5。

std::optional<int> min_assets: 可选的最少资产数；未设置时使用 10。

std::optional<int> min_quantile_assets: 可选的分位最少观测数；未设置时使用 1。

std::optional<std::string> preprocess: 可选的方法；未设置时使用 cross_section_rank。

std::optional<double> max_loss: 可选的损失比例；未设置时使用 1.0。

std::optional<std::vector<int>> stability_lags: 可选的滞后阶；未设置时使用 {1, 5, 20}。

std::optional<std::map<std::string, int>> direction_overrides: 可选的逐资产符号（+1 或 -1）。

std::optional<std::map<std::string, std::map<std::string, double>>> combinations: 可选的加权混合；未设置时映射保持为空。

std::optional<std::map<std::string, std::pair<std::string, std::string>>> comparisons: 可选的因子对；未设置时映射保持为空。

std::optional<std::map<std::string, std::pair<std::string, std::string>>> segments: 可选的来源区间；未设置时映射保持为空。

std::vector<std::string> unknown_fields: 被归一化拒绝的未知键。

struct research_evaluation_spec

已校验并填充默认值的研究评估设定。

与固定版本 Python ResearchEvaluationSpec 的字段集合对应，包含原生的 UTC 纳秒窗口端点。

公共成员

std::vector<std::string> targets: 目标资产；非空且无重复。

timestamp start = 0: 闭区间窗口起点；不得晚于 end。

timestamp end = 0: 闭区间窗口终点。

std::string snapshot_id = "unspecified": 来源快照标识符。

std::string price_basis = "unspecified": 来源价格基准。

std::string calendar_id = "unspecified": 来源日历标识符。

std::string frequency = "unspecified": 来源数据频率。

std::string source_timezone = "UTC": 描述性的源时区；时间戳仍以 UTC 存储。

std::string feed_time_kind = "close_time": 描述性的推送时间戳约定。

std::vector<int> periods = {1, 5, 20}: 非空、为正且唯一的价行预测期。

std::string label = "next_open_to_open": 前瞻收益基准。

std::string precomputed_entry = "next_open": 预计算标签的入场约定。

int quantiles = 5: 分位桶数量；归一化要求至少一个。

int min_assets = 10: 最少资产数阈值。

int min_quantile_assets = 1: 每个分位的最少观测数。

std::string preprocess = "cross_section_rank": 截面预处理方法。

double max_loss = 1.0: 可容忍的数据损失比例，位于 [0, 1]。

std::vector<int> stability_lags = {1, 5, 20}: 为正的秩自相关滞后阶。

std::map<std::string, int> direction_overrides: 逐资产符号；取值必须为 +1 或 -1。

std::map<std::string, std::map<std::string, double>> combinations: 加权因子混合。

std::map<std::string, std::pair<std::string, std::string>> comparisons: 命名的因子对；两侧必须不同。

std::map<std::string, std::pair<std::string, std::string>> segments: 命名的来源区间。

struct research_export_result

export_factor_research() 写入的文件。

公共成员

std::string directory: 按传入原样记录的请求输出目录。

std::vector<std::string> files: 已写入文件的相对名称，按写入顺序排列。

struct research_factor_panel

用作相关性输入的命名因子面板。

公共成员

std::string name: 因子名称；必须非空且唯一。

factor_series values: 按 (date, asset) 的因子值。

struct research_label_row

一行前瞻收益标签记录。

公共成员

timestamp date = 0: 以 UTC 纳秒表示的观测日期。

std::string asset: 资产标识符。

std::string period: 前瞻收益周期标签，例如 1D。

double value = 0.0: 该周期的前瞻收益；缺失时为 NaN。

struct research_panel_result

聚合后的多因子评估结果。

当每个命名结果都为 OK 时 status 为 OK，全部为 UNEVALUABLE 时为 UNEVALUABLE，其余情况为 PARTIAL。

公共成员

std::string status: 聚合后的评估状态。

std::vector<named_research_result> factors: 先为输入因子，其后为组合。

std::vector<research_correlation_row> correlations: 成对的已处理面板相关性。

std::vector<research_comparison_row> comparisons: 比较行；未请求时为空。

std::vector<research_signal_row> signals: 拼接后的信号，并标注因子名称。

std::map<std::string, std::string> manifest: 计数以及 API/模式版本元数据。

struct research_result

聚合后的单因子研究结果。

当所有请求的预测期都有准备好的行时 status 为 OK；至少一个预测期没有行时为 PARTIAL；没有任何预测期被准备时为 UNEVALUABLE。

公共函数

research_table table(std::string_view name) const

返回一个命名的结果表。

未知名称会抛出结构化的 DatasetError（unknown_result_table）。在该单因子结果中，相关性与比较表暴露规范的列但没有行。

参数:: name -- Table name; one of research_capabilities::result_tables.
抛出:: research_dataset_error -- When name is not a known table, with code unknown_result_table.
返回:: Table with canonical columns and row-major cells.

std::string to_serializable() const

返回与 JSON 兼容的 status/manifest/tables/columns 载荷。

返回:: JSON text whose tables and columns objects contain all canonical result tables.

公共成员

std::string status: OK、PARTIAL 或 UNEVALUABLE。

std::vector<research_label_row> labels: 已准备单元的前瞻收益行。

std::vector<research_signal_row> signals: 已评估单元的信号行。

factor_ic_table information_coefficient: 按周期组织的逐日 Spearman 秩 IC；缺失为 NaN。

factor_ic_summary information_coefficient_summary: 每个周期的平均秩 IC。

quantile_return_table quantile_returns: 原始分位收益均值与标准误。

std::vector<factor_series_result> turnover: 每个分位的换手率序列，取第一个预测期。

std::vector<factor_series_result> stability: 每个滞后阶的秩自相关，取第一个预测期。

std::vector<int> stability_lags: 稳定性序列所使用的滞后阶。

std::vector<double> spread: 每个周期的最高减最低分位收益；缺失时为 NaN。

std::vector<std::size_t> coverage: 每个周期已准备的观测数量。

std::vector<std::string> diagnostics: 人类可读的状态说明。

std::map<std::string, std::string> manifest: 来源的键值元数据。

int schema_version = research_result_schema_version : 结果模式版本。

struct research_signal_row

一行信号：某个日期与资产的因子观测。

公共成员

timestamp date = 0: 以 UTC 纳秒表示的观测日期。

std::string asset: 资产标识符。

std::string factor: 因子名称；单因子评估时为 factor。

int direction = 1: 应用于因子取值的方向符号。

double value = 0.0: 经方向调整后的原始因子取值。

double processed_value = 0.0: 方向调整与预处理之后的取值。

std::string preprocess: 该面板使用的预处理方法。

std::string group: 配置的分组名称；未设置 groups 时为 default。

struct research_spec

研究评估器消费的强制执行设定。

公共成员

std::vector<std::string> targets: 请求的目标；为空时选择所有观测到的资产。

timestamp start = 0: 闭区间的 UTC 纳秒窗口起点。

timestamp end = 0: 闭区间的 UTC 纳秒窗口终点。

std::vector<int> periods = {1, 5, 20}: 前瞻价格行预测期；非空且为正。

int quantiles = 5: 分位桶数量；必须至少为二。

int min_assets = 1: 相关性与详细阈值所用最少资产数。

int min_quantile_assets = 1: 详细阈值所用每分位最少观测数。

std::string label = "close_to_close": 前瞻收益基准。

std::string preprocess = "cross_section_rank": 截面预处理方法。

double max_loss = 1.0: 可容忍的分桶数据损失比例，位于 [0, 1]。

std::vector<int> stability_lags = {1, 5, 20}: 为正的秩自相关滞后阶。

std::map<std::string, int> direction_overrides: 可选的逐资产符号（+1 或 -1）。

std::map<std::string, std::pair<std::string, std::string>> segments: 命名的来源区间。

std::map<std::string, std::pair<std::string, std::string>> comparisons: 面板评估器的因子对。

std::map<std::string, std::map<std::string, double>> combinations: 加权因子混合。

std::map<std::string, std::string> groups: 覆盖被评估资产的资产到分组映射。

std::string snapshot_id = "unspecified": 来源快照标识符。

std::string price_basis = "unspecified": 来源价格基准。

std::string calendar_id = "unspecified": 来源日历标识符。

std::string frequency = "unspecified": 来源数据频率。

struct research_table

以原生列形式表示的一个命名研究结果表。

公共成员

std::string name: 表名。

std::vector<std::string> columns: 按行单元顺序排列的列名。

std::vector<std::vector<factor_value>> rows: 与列对齐的行优先单元。

struct spread_time_series_chart

单一前瞻周期的多空差图数据。

公共函数

std::string to_svg() const

将多空差、滚动均值与可选带宽渲染为原生 SVG。

存在日期时添加零线；band_lower 为空时跳过量带多边形。

公共成员

std::string period: 标题中使用的前向收益率周期标签。

std::string title: 图表标题。

std::string y_label = "Difference In Quantile Mean Return (bps)": Y 轴标签。

std::vector<timestamp> dates: 观测时间戳。

std::vector<double> spreads: 以基点表示的多空差；非有限输入变为 NaN。

std::vector<double> rolling_mean: 以基点表示的 22 观测尾部均值；在出现 22 个连续有限多空差之前为 NaN。

std::vector<double> band_lower: 以基点表示的下带宽；未提供标准误时为空，输入非有限处为 NaN。

std::vector<double> band_upper: 以基点表示的上带宽，与 band_lower 对齐。

double y_limit = 1.0: 对称的 y 轴范围：有限绝对多空差的第 95 百分位，没有正值时回退为 1.0。

double bandwidth = 1.0: 构建带宽所使用的标准误倍数。

struct style_context

渲染器样式上下文（seaborn 的 plotting_context / axes_style）。

公共成员

std::string name: 上下文或样式名称，例如 "notebook"。

double font_scale = 1.5: 上下文携带的字体缩放因子。

std::map<std::string, std::string> rc: 按名称给出的 rc 参数覆盖。

struct trading_calendar

因子日历辅助函数使用的确定性交易日集合。

日历由本地日历日期定义：七个工作日标志加上一组节假日日序号（自 1970-01-01 起的 UTC 天数）。它有意不含时区对象；时间戳为 UTC 纳秒。

公共函数

bool is_trading_day(std::int64_t day_number) const noexcept

检查某个日序号是否为交易日。

参数:: day_number -- Days since 1970-01-01 in UTC.
返回:: true when the weekday is enabled and the day is not a holiday.

bool is_session(timestamp value) const noexcept

检查某个时间戳是否落在交易日。

参数:: value -- Timestamp in UTC nanoseconds.
返回:: true when the timestamp's UTC day is a trading day.

std::int64_t busday_count(std::int64_t start_day, std::int64_t end_day) const noexcept

当 start_day <= end_day 时统计 [start_day, end_day) 内的交易场次；否则返回 (end_day, start_day] 计数的相反数（NumPy busday_count 的半开区间语义）。

参数:

start_day -- First day number.
end_day -- Exclusive end day number for forward counts.

返回:

Signed number of trading sessions.

公共成员

bool weekdays[7] = {true, true, true, true, true, false, false}: 以周一为首位的工作日掩码。true 表示该工作日为交易日。

std::vector<std::int64_t> holidays: 已排序且唯一的节假日日序号。绝不包含非工作日。

struct violin_chart

单一前瞻周期的分位收益小提琴图数据。

公共函数

std::string to_svg() const

为每个组渲染一个小提琴多边形，输出为原生 SVG。

没有密度点或密度为零的组被跳过。

公共成员

std::string title = "Period Wise Return By Factor Quantile": 图表标题。

std::string y_label = "Return (bps)": Y 轴标签。

std::vector<violin_group> groups: 各组，按分位升序排列。

struct violin_group

某一前瞻周期某个分位的小提琴样本与四分位数。

公共成员

int quantile = 0: 分位桶标签。

std::string period: 前向收益率周期标签。

std::vector<double> samples: 以基点表示的有限周期收益。

double first_quartile = 0.0: 样本的第一四分位（基点）。

double median = 0.0: 样本的中位数（基点）。

double third_quartile = 0.0: 样本的第三四分位（基点）。

std::vector<double> density_x: 核密度估计的支撑点。

std::vector<double> density_y: 与 density_x 对齐的密度值；未计算密度时为空。

enum class fincore::fama_macbeth_covariance

Fama-MacBeth 标准误的协方差估计器。

取值：

enumerator iid: i.i.d. 样本标准误。

enumerator newey_west: 在 newey_west_lags 阶下的 Bartlett 核 HAC 标准误。

timestamp fincore::add_custom_calendar_timedelta(timestamp input, std::int64_t delta, const trading_calendar &calendar)

加上 delta 纳秒，其中整日部分按 calendar 计数。

时长被归一化为向下取整的整日分量加上非负余数；整日分量按日历滚动，之后再加上余数。这与 pandas 的 Timestamp + CalendarOffset(days) + remainder 行为一致。

参数:

input -- Starting timestamp or timestamps in UTC nanoseconds.
delta -- Signed duration in nanoseconds.
calendar -- Calendar used to roll whole-day components.

抛出:

factor_data_error -- When the shifted timestamp overflows.

返回:

The shifted timestamp, or one shifted timestamp per input value.

std::vector<timestamp> fincore::add_custom_calendar_timedelta(const std::vector<timestamp> &input, std::int64_t delta, const trading_calendar &calendar)

使用 calendar 为每个时间戳加上 delta 纳秒。

应用与标量重载相同的归一化与整日滚动规则，并保持输入顺序。

参数:

input -- Starting timestamps in UTC nanoseconds.
delta -- Signed duration in nanoseconds.
calendar -- Calendar used to roll whole-day components.

抛出:

factor_data_error -- When a shifted timestamp overflows.

返回:

One shifted timestamp per input value.

trading_calendar fincore::all_days_calendar()

返回把每一天都标记为交易日的日历，与 pandas 默认的 Day 偏移一致。

返回:: The all-days calendar.

factor_analysis_model fincore::analyze_factor(const prepared_factor_data &factor_data, const factor_analysis_config &config = {})

针对一个已准备的面板计算完整的因子分析模型。

在所选标签上运行信息系数、权重、收益、分位、多空差、换手、秩自相关、累积、持仓与月度汇总内核。返回的模型持有输入与所请求选项的副本。

参数:

factor_data -- Prepared rows, forward-return labels and cleaning losses.
config -- Labels and views to build; the defaults analyse every label with long-short aggregate output.

抛出:

factor_data_error -- If factor_data has no rows or labels, a row does not match the label count, turnover_periods or time_aggregation is empty, duplicated or invalid, portfolio_benchmark_period is empty, a selected period is not a prepared label or not a whole-day label, or by_group is set without a group column.

返回:

Aggregate views, optional per-group views and the input fingerprint.

factor_analysis_model fincore::analyze_factor(const prepared_factor_data &factor_data, const factor_analysis_config &config, const dataframe &event_returns, int event_before, int event_after)

同时计算分析模型与事件收益研究。

事件日期为 event_returns 中存在的因子日期。每个窗口从事件之前的 event_before 条账行延伸到事件之后的 event_after 行，并按账簿边界裁剪；账簿值按原样使用，当 config.long_short 为 true 时在整个股票池内做去均值处理。

参数:

factor_data -- Prepared rows, forward-return labels and cleaning losses.
config -- Labels and views to build; group_neutral must be false.
event_returns -- Rectangular ledger of double columns indexed by date.
event_before -- Non-negative ledger rows before each event date.
event_after -- Non-negative ledger rows after each event date.

抛出:

factor_data_error -- If the common validations fail, the ledger is not a rectangular double table, its index repeats, a factor asset is missing from it, an offset is negative, or group-neutral event analysis is requested.

返回:

Model with event_analysis and event_input_snapshot set.

factor_cost_result fincore::apply_factor_costs(std::span<const double> gross_returns, const std::vector<factor_weight_row> &weights, const dataframe &dollar_volume, double portfolio_value, const factor_cost_model &model, const dataframe *borrow_rates = nullptr, const dataframe *borrow_available = nullptr)

对毛收益应用点差、市场冲击与借券成本。

换手率为每个日期权重绝对变化之和的一半。点差成本按成交权重收取 half_spread_bps，冲击成本按每个资产收取 impact_coefficient * participation^impact_exponent，借券成本依据提供的借券面板在空头持仓上累积。

参数:

gross_returns -- One gross return per weight date.
weights -- Gross-normalized weights, one row per (date, asset).
dollar_volume -- Tradable dollar volume on a sorted, unique index spanning every weight date and asset, strictly positive.
portfolio_value -- Positive portfolio value, no larger than the estimated capacity.
model -- Cost parameters applied to every date.
borrow_rates -- Short-rate panel on the weight grid; required when any weight is negative and rejected otherwise.
borrow_available -- Availability panel on the weight grid, where 1.0 marks a lendable short; required alongside borrow_rates.

抛出:

factor_data_error -- When inputs are malformed, a short lacks borrow data or availability, the portfolio exceeds capacity, or a cost or participation value is non-finite.

返回:

Cost ledger with gross, net, turnover, cost components, trades, participation and capacity.

std::vector<quantile_event_statistics> fincore::average_cumulative_return_by_quantile(const prepared_factor_data &factor_data, const dataframe &returns, int before = 10, int after = 15, bool demeaned = true)

按分位对累积事件窗口收益求平均。

为每个观测到的分位构造一个事件面板，并以累积与日期均值输出调用 common_start_returns；每个偏移报告其单元的均值与样本标准差，没有单元的偏移均值与标准差为 NaN，仅含一个单元的偏移标准差为 NaN。

参数:

factor_data -- Prepared rows; their quantiles define the groups.
returns -- Ledger indexed by date with one double column per asset.
before -- Non-negative ledger rows before each event date.
after -- Non-negative ledger rows after each event date.
demeaned -- Subtract the full-universe date mean from each cell.

抛出:

factor_data_error -- If an offset is negative or the ledger is invalid for common_start_returns.

返回:

One statistics block per quantile, in ascending quantile order.

style_context fincore::axes_style(std::string style = "darkgrid", std::map<std::string, std::string> rc = {})

创建字体缩放固定为 1.5 的渲染器坐标轴样式。

参数:

style -- Style name.
rc -- rc parameter overrides keyed by parameter name.

返回:

Style context named style; font_scale is always 1.5.

factor_series fincore::backshift_returns_series(const factor_series &series, const std::vector<timestamp> &date_levels, int N)

将回溯型收益率序列沿日期层级前移 N 个位置。

date_levels 为来自源 MultiIndex 的完整、已排序、唯一的日期层级，包含未被使用的日期。层级位置小于 N 的行被丢弃。其余行保持其顺序、资产与取值（包括 NaN），但日期移动到层级中前 N 个位置。当 date_levels.size() <= N 时结果为空。

fdr_result fincore::benjamini_hochberg(std::span<const double> p_values, double alpha = 0.05)

应用 Benjamini-Hochberg 逐步提升校正。

调整后的取值为 n * p / rank 的单调滑动最小值，并截断到 [0, 1]。当某假设排序后的 p 值不高于 alpha * rank / n 时该假设被拒绝，从而拒绝直到最大通过秩的前缀块。空输入产生空输出。

参数:

p_values -- Finite probabilities in [0, 1].
alpha -- Target false-discovery rate in (0, 1].

抛出:

factor_data_error -- If alpha is outside (0, 1] or a p value is not a finite probability in [0, 1].

返回:

Copies of the inputs plus adjusted values and rejection flags.

quantile_cumulative_chart fincore::build_cumulative_returns_by_quantile(const quantile_date_return_table &returns, std::string period)

为单一周期的每个分位构造累积增长图表数据。

先按日期对所请求的分位与标签求均值，再按日期顺序从 1.0 起复利累积。没有有限均值的日期沿用前一个增长值。分位按降序输出，y 轴范围覆盖所有输出的增长值。

参数:

returns -- Mean returns by date, quantile and label.
period -- Forward-return label; must be present in returns.labels.

抛出:

factor_data_error -- If period is not present in returns.labels.

返回:

Chart data with one series per distinct quantile.

events_distribution_chart fincore::build_events_distribution(const std::vector<timestamp> &dates, const std::vector<double> &values = {}, std::size_t num_bars = 50U)

按等宽时间桶构造事件计数。

values 与 dates 对应；非有限值被跳过，values 为空时统计所有事件。除最后一个桶外各桶均为左闭右开，最后一个桶还覆盖最新日期。只有一个不同日期时产生一个桶。

参数:

dates -- Event timestamps.
values -- Optional event values aligned with dates.
num_bars -- Number of equal-width buckets; must be positive.

抛出:

factor_data_error -- If num_bars is zero, values is non-empty with a different length than dates, or the date span cannot form positive-width buckets.

返回:

Bucket starts and counts; no buckets are produced for empty dates.

factor_portfolio_inputs fincore::build_factor_portfolio_inputs(const prepared_factor_data &factor_data, std::string_view period_label, bool long_short = true, bool group_neutral = false, bool equal_weight = false, const std::vector<int> &quantiles = {}, const std::vector<std::string> &groups = {})

将复利的周期曲线与重叠持仓重采样为日频网格，加入显式的现金叠加层，并派生出可选的基准。

该内核不表示日内持仓剩余、按资本缩放的名义持仓以及自定义交易日历。

参数:

factor_data -- Prepared factor panel with forward-return labels.
period_label -- Forward-return label whose day count sets the holding.
long_short -- Enables long-short weighting when true.
group_neutral -- Applies group-neutral weighting when true.
equal_weight -- Uses equal weights within each bucket when true.
quantiles -- Optional quantile filter; empty keeps all quantiles.
groups -- Optional group filter; empty keeps all groups.

抛出:

factor_data_error -- When the period label is absent, the selection is empty, or grouped weights lack group labels.

返回:

Daily strategy returns, cash-overlaid positions, and benchmark returns for the period.

report_document fincore::build_factor_report(const factor_analysis_model &model, std::string title = "Factor Analysis Report")

由已计算的模型构造与渲染器无关的因子分析报告。

文档按该顺序包含 summary、information-coefficient、returns 与 turnover 各节。

参数:

model -- Computed factor analysis model.
title -- Document title.

返回:

Report document with domain "factor" and derived metadata.

factor_tear_charts fincore::build_factor_tear_charts(const factor_analysis_model &model)

为因子一览图构造带所有权的图表数据。

时序图省略非有限点，柱状图保持 model 的面板顺序，事件直方图由模型的有限收益分布重建。

参数:: model -- Analyzed factor model supplying every panel.
抛出:: input_error -- When event analysis is present without a finite return-distribution value.
返回:: Chart bundle that owns copies and outlives model.

std::vector<qq_chart> fincore::build_ic_qq(const factor_ic_table &ic)

由信息系数构造正态 Q-Q 图数据。

每个标签返回一个图，每个图包含一个序列，其观测值为该标签的 IC 值；非有限值按零处理。理论分位数使用标准正态分布的逆累积分布函数。

参数:: ic -- Information-coefficient table with values in date-major order.
返回:: One chart per label, in ic.labels order; empty when ic.dates or ic.labels is empty or no observations are available.

spread_time_series_chart fincore::build_mean_quantile_returns_spread_time_series(const std::vector<timestamp> &dates, const std::vector<double> &spreads, std::string period, const std::vector<double> &standard_errors = {}, double bandwidth = 1.0)

为单一前瞻周期构造多空差时序图数据。

多空差与标准误由小数收益转换为基点。滚动均值为 22 个观测的尾部窗口均值，在出现 22 个连续有限多空差之前保持 NaN；提供标准误时，带宽按 spread +/- standard_error * 10000 * bandwidth 构造。

参数:

dates -- Observation timestamps.
spreads -- Spreads in decimal return units, aligned with dates.
period -- Forward-return period label used in the title.
standard_errors -- Optional standard errors in decimal return units, aligned with spreads.
bandwidth -- Standard-error multiplier used for the band.

抛出:

factor_data_error -- If dates and spreads differ in length, or standard_errors is non-empty with a different length.

返回:

Chart data with bps spreads, rolling mean and optional band.

std::vector<monthly_ic_heatmap_chart> fincore::build_monthly_ic_heatmap(const factor_time_information_table &monthly)

为每个前瞻周期构造一个热力图（表已分组时还按分组构造）。

年份为所选分组中观测到的不同日历年，并按升序输出。没有有限均值的月份保持 NaN 且 present == false。当 monthly.labels 或 monthly.dates 为空时不返回任何图。

参数:: monthly -- Monthly information-coefficient table with means in date-major order and optional groups parallel to dates.
返回:: One chart per group and label; groups are emitted in sorted order.

violin_chart fincore::build_quantile_returns_violin(const quantile_date_return_table &returns, std::string period)

为单一前瞻周期构造分位收益的小提琴图数据。

每组收集某一空头的有限平均收益，并由小数收益转换为基点。四分位数在排序样本上使用线性插值；当样本数至少为二且其偏差为正时，密度为 64 个支撑点上的高斯核估计。分位按升序输出，没有有限样本的分位被省略。

参数:

returns -- Mean returns by date, quantile and label.
period -- Forward-return label; must be present in returns.labels.

抛出:

factor_data_error -- If period is not present in returns.labels.

返回:

Violin chart data with one group per quantile that has samples.

trading_calendar fincore::business_day_calendar()

返回一个周一至周五、不含节假日的日历。

返回:: The business-day calendar.

void fincore::close_owned_figures(owned_figures &figures)

将所有自有图形标记为已关闭。

标识符列表保持不变，因此该调用是幂等的。

参数:: figures -- Figure list whose closed flags are set to true.

event_window_result fincore::common_start_returns(const factor_series &factor, const dataframe &returns, int before, int after, bool cumulative = false, bool mean_by_date = false, const factor_series *demean_by = nullptr)

为因子面板抽取与事件对齐的收益窗口。

事件日期为收益索引中存在的因子日期。每个窗口从事件之前的 before 账行延伸到事件之后的 after 行，并按账簿边界裁剪，因此靠近边缘的偏移缺失。非有限的账簿值被跳过。cumulative 为真时账簿按已是累积值读取，否则将每列从 1 起复利为财富指数。demean_by 减去其资产在同一日期的截面均值，mean_by_date 为每个偏移与日期输出一个平均单元。

参数:

factor -- Event panel; its dates and assets select the windows.
returns -- Ledger indexed by date with one double column per asset.
before -- Non-negative ledger rows before each event date.
after -- Non-negative ledger rows after each event date.
cumulative -- Read the ledger as cumulative rather than simple returns.
mean_by_date -- Emit date means with an empty asset label.
demean_by -- Optional panel supplying the assets to demean against.

抛出:

factor_data_error -- If an offset is negative, the returns index has duplicates, a factor asset is missing from the ledger, or a demean asset is missing at an event date.

返回:

Observed offsets, event dates, asset labels and window cells.

forward_return_table fincore::compute_forward_returns(const factor_series &factor, const dataframe &prices, const std::vector<int> &periods = {1, 5, 10}, std::optional<double> filter_zscore = std::nullopt, bool cumulative_returns = true)

由价格面板为每个因子观测计算前瞻收益。

标签为按 "D" 形式渲染的请求周期。当因子日期不在价格中、预测期超出面板或基准价格为零时取值为 NaN。设置 filter_zscore 时，相对各资产均值偏离超过该标准差倍数的前瞻收益会按标签独立剔除。

参数:

factor -- Row-aligned factor panel supplying dates and assets.
prices -- Price panel indexed by date with one column per factor asset.
periods -- Positive horizons in price observations.
filter_zscore -- Optional per-asset z-score cutoff; nullopt keeps all.
cumulative_returns -- Compounded window return when true, otherwise a one-observation return.

抛出:

factor_data_error -- When the factor index is invalid, a period is not positive, an asset is missing from prices, no date is shared, or filter_zscore is non-finite.

返回:

Label-major forward returns aligned with the factor rows.

render_customization fincore::customize(bool set_context = true)

创建图表调用前后使用的原生渲染定制对象。

返回值使用默认的 plotting_context() 与 axes_style() 取值，并保留内置的八色配色。

参数:: set_context -- Whether the context is applied around the chart call.
返回:: Customization carrying the default context, axes style and palette.

factor_model_envelope fincore::deserialize_factor_model(std::string_view text)

从序列化的 JSON 文本恢复受支持的模型信封。

根节点必须是包含 schema、fingerprint_version、result_fingerprint、config、forward_periods 与 loss_report 的对象。schema 必须等于受支持的版本，指纹版本必须能用 32 位表示。多余的键会被忽略。

参数:: text -- Serialized JSON text.
抛出:: input_error -- If the text is not valid JSON, the root is not an object, a required field is missing, the schema is unsupported, or the fingerprint version is out of range.
返回:: Envelope with the schema, fingerprint fields, configuration, forward periods and loss report.

factor_value fincore::deserialize_serializable_value(std::string_view text)

将序列化的模型文本解析为原生值。

解析文本时不校验信封 schema；需要校验并恢复受支持子集时应使用 deserialize_factor_model。

参数:: text -- Serialized JSON text.
抛出:: input_error -- If the text is not valid strict JSON.
返回:: Parsed native value.

std::int64_t fincore::diff_custom_calendar_timedeltas(timestamp start, timestamp end, const trading_calendar &calendar)

返回 end - start，其中整日部分按日历计量。

保留钟表时间余数；仅将整日部分替换为工作日计数。两端都使用本地日历日期，与固定版本源实现一致。

参数:

start -- Start timestamp in UTC nanoseconds.
end -- End timestamp in UTC nanoseconds.
calendar -- Calendar used for the whole-day count.

返回:

Signed duration in nanoseconds with the wall-clock remainder.

factor_capacity_result fincore::estimate_factor_capacity(const std::vector<factor_weight_row> &weights, const dataframe &dollar_volume, double max_participation)

估计权重面板可交易的最大组合价值。

每个日期受最紧的资产级约束 max_participation * dollar_volume / |trade| 限制；面板容量为最小的有限日期上限。首个达到该上限的日期以及造成限制的资产作为绑定对报告。

参数:

weights -- Gross-normalized weights, one row per (date, asset).
dollar_volume -- Tradable dollar volume on a sorted, unique index spanning every weight date and asset, strictly positive.
max_participation -- Fraction of dollar volume allowed per asset, in (0, 1].

抛出:

factor_data_error -- When the weights are duplicated, non-finite or not gross-normalized, when dollar volume is missing, unsorted, non-finite or non-positive, or when no trade occurs.

返回:

Capacity summary carrying the trade panel and binding pair.

research_detailed_export_outcome fincore::evaluate_and_export_factor_research_detailed(std::string_view factor_name, const factor_series &factors, const dataframe &prices, const research_spec &spec, const std::string &directory)

评估单个因子并导出其详细结果，而不构造带所有权的信号与标签行向量。

大表由评估器的实时列同步写出；不存在逃逸出本次调用的借用视图。若评估或导出失败，本次调用创建的文件会被删除，而新建的目标目录仅在其为空时被删除。已存在的空目标会被保留，非空目标会被拒绝。评估与写入可能交错：传播最先遇到的失败，而不是套用两次独立调用的错误顺序。

参数:

factor_name -- Factor name used for output rows and direction overrides.
factors -- Factor panel with row-aligned dates, assets and values.
prices -- Price panel indexed by date with one column per asset.
spec -- Evaluation window, label, preprocessing and table settings.
directory -- Destination directory for the CSV files and manifest.

抛出:

factor_data_error -- When evaluation input is invalid or export validation or writing fails.

返回:

Owning outcome with status, manifest, diagnostics, row counts and export metadata.

research_result fincore::evaluate_factor_research(const factor_series &factors, const dataframe &prices, const research_spec &spec)

针对由价格派生的前瞻收益评估单个因子。

spec.label 必须为 close_to_close 或 next_open_to_open；预计算基准由前瞻收益表重载提供。周期标签由价格网格派生。close_to_close 标签从每个因子日期起跨越 period 个价格行；next_open_to_open 标签晚一行入场，并从该入场点起跨越 period 行。

参数:

factors -- Factor values by (date, asset).
prices -- Price dataframe with asset columns and a UTC timestamp index.
spec -- Execution spec; its inclusive window and target guards are applied before evaluation.

抛出:

factor_data_error -- When the spec, factor panel or price grid violates the evaluated contract, including unsupported labels, missing targets, an empty window, duplicates or malformed prices.

返回:

Aggregated result with OK, PARTIAL or UNEVALUABLE status.

research_result fincore::evaluate_factor_research(const factor_series &factors, const dataframe &prices, const research_spec &spec, const dataframe &universe)

在宽掩码约束下针对价格派生收益评估单个因子。

布尔掩码只保留 (date, asset) 项为 true 的单元，返回结果在其 manifest 中记录 universe=applied。

参数:

factors -- Factor values by (date, asset).
prices -- Price dataframe with asset columns and a UTC timestamp index.
spec -- Execution spec; the precomputed label basis is rejected.
universe -- Wide boolean eligibility mask (dates x assets).

抛出:

factor_data_error -- When the mask contains non-boolean columns, duplicate dates or removes every cell, or the underlying evaluation fails.

返回:

Aggregated result for the masked panel.

research_result fincore::evaluate_factor_research(const factor_series &factors, const forward_return_table &precomputed_returns, const research_spec &spec)

针对调用方提供的前瞻收益评估单个因子。

spec.label 不得为 next_open_to_open；结果 manifest 记录预计算标签。

参数:

factors -- Factor values by (date, asset).
precomputed_returns -- Label-major forward-return table covering the requested periods.
spec -- Execution spec selecting the periods and quantiles.

抛出:

factor_data_error -- When the table is empty, malformed, has duplicate keys, misses a requested period or yields no prepared rows, or the factor panel violates its contract.

返回:

Aggregated result for the supplied labels.

research_detailed_result fincore::evaluate_factor_research_detailed(std::string_view factor_name, const factor_series &factors, const dataframe &prices, const research_spec &spec)

针对价格派生的前瞻标签评估一个命名因子。

factor_name 提供用于方向覆盖与输出行的 Python DataFrame 列名。spec.start/end 及所有输入时间戳均为 UTC 纳秒。该基于价格的重载仅支持 close_to_close 与 next_open_to_open；预计算标签与多因子组合会被显式拒绝。

参数:

factor_name -- Factor name used for output rows and direction overrides.
factors -- Factor panel with row-aligned dates, assets and values.
prices -- Price panel indexed by date with one column per asset.
spec -- Evaluation window, label, preprocessing and table settings.

抛出:

factor_data_error -- When the factor, price or specification input is invalid, including unsupported labels or missing price columns.

返回:

Detailed result with signal, label, IC, quantile, stability, coverage and diagnostic tables.

research_panel_result fincore::evaluate_factor_research_panel(std::span<const named_factor_panel> factors, const dataframe &prices, const research_spec &spec)

评估多个命名因子面板并派生相关性/比较结果。

每个面板独立评估；随后在禁用预处理并清除方向覆盖的条件下，由已处理的面板混合出 spec.combinations，并追加命名的比较项。

参数:

factors -- Named factor panels; names must be non-empty and unique.
prices -- Price grid used for forward returns.
spec -- Execution spec including combinations and comparisons.

抛出:

factor_data_error -- When names are empty or duplicated, a combination or comparison references an unknown factor, weights are invalid, or a panel evaluation fails.

返回:

Named results, correlations, comparisons, concatenated signals and manifest counts.

research_export_result fincore::export_factor_research(const research_result &result, const std::string &directory, bool charts = false)

写入确定性的 CSV 表与 JSON manifest，且不覆盖已有内容。

已存在的目标目录会被拒绝并保持不动。若后续写入失败，本次调用创建的目录会被删除。charts=true 请求导出栅格图，而原生库不提供该能力；因此以失败关闭的方式处理，而不是静默跳过图表。

参数:

result -- Result tables to export.
directory -- Fresh destination directory.
charts -- Whether to request charts; the native library rejects true.

抛出:

factor_data_error -- When charts are requested, the result tables are malformed, the manifest uses reserved keys status or exports, the directory is empty, contains a null byte or already exists, or a file cannot be written.

返回:

The requested directory and the relative names of the files written.

research_export_result fincore::export_factor_research_detailed(const research_detailed_result &result, const std::string &directory)

将十张因子级详细研究表导出为 UTF-8/LF 的 CSV 文件，并附带带版本的 JSON manifest。

行保持 result 中的顺序。单因子结果的相关性与比较表必须为空；其缺失在 manifest 的 engine 元数据中标识。

非空目标目录绝不会被覆盖。若导出失败，只删除本次调用创建的文件；新建的目标目录仅在其为空时删除。已存在的空目标目录会被保留。

参数:

result -- Detailed result whose tables are written.
directory -- Destination directory for the CSV files and manifest.

抛出:

factor_data_error -- When the directory is invalid or non-empty, the result schema is unsupported, correlation or comparison tables are non-empty, or writing fails.

返回:

Created directory and exported file names.

std::vector<factor_alpha_beta_row> fincore::factor_alpha_beta(const prepared_factor_data &factor_data, bool demeaned = true, bool group_adjust = false, bool equal_weight = false)

将组合收益对同日期的股票池平均收益做回归。

斜率为对每个标签的等权股票池均值做 OLS 得到的 beta；截距按 252 / N 个周期年化，其中 N 为该标签前导的整日数。可用日期少于两个或市场方差为零时估计值为 NaN；没有前导日数的标签仅使 annual_alpha 为 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
demeaned -- Center the bucket values before weighting.
group_adjust -- Form weights per (date, group) and renormalize per date.
equal_weight -- Give each side of zero an equal share.

抛出:

factor_data_error -- If group_adjust is true and a row has no group.

返回:

One row per forward-return label, in label order.

factor_series_result fincore::factor_cumulative_returns(const prepared_factor_data &factor_data, std::string_view period_label, bool long_short = true, bool group_neutral = false, bool equal_weight = false, const std::vector<int> &quantiles = {}, const std::vector<std::string> &groups = {})

将所选周期的收益从 1 起复利累积。

参数:

factor_data -- Prepared factor panel with forward-return labels.
period_label -- Forward-return label to compound.
long_short -- Enables long-short weighting when true.
group_neutral -- Applies group-neutral weighting when true.
equal_weight -- Uses equal weights within each bucket when true.
quantiles -- Optional quantile filter; empty keeps all quantiles.
groups -- Optional group filter; empty keeps all groups.

抛出:

factor_data_error -- When the period label is absent, the selection is empty, or grouped weights lack group labels.

返回:

Compounded cumulative return series indexed by date.

factor_ic_table fincore::factor_information_coefficient(const prepared_factor_data &factor_data, bool group_adjust = false, bool by_group = false)

按日期与标签计算 Spearman 秩信息系数。

每个单元在一个日期桶的资产范围内将有限因子值与对应的前瞻收益做相关；可用配对少于两个时该单元为 NaN。group_adjust 先在每个 (date, group) 桶内对前瞻收益去均值，因此必须提供 groups；by_group 为每个 (date, group) 对输出一行，而不是每个日期一行。

参数:

factor_data -- Prepared rows and forward-return labels.
group_adjust -- Demean forward returns per date and group before ranking.
by_group -- Emit one row per (date, group) instead of one row per date.

抛出:

factor_data_error -- If group data is required or requested and a row has no group column.

返回:

IC table whose groups member stays empty unless grouped.

ic_inference_result fincore::factor_model_inference(const factor_analysis_model &model, double alpha = 0.05)

对模型执行 IC 推断与错误发现率校正。

将 model.information_coefficient 传给 information_coefficient_inference；不读取分组表。

参数:

model -- Analysed model whose aggregate IC table is read.
alpha -- Target false-discovery rate in (0, 1].

抛出:

factor_data_error -- If alpha is not a finite probability in (0, 1].

返回:

One hypothesis per IC label with the Benjamini-Hochberg adjustment.

const std::vector<factor_operation_descriptor> &fincore::factor_operation_descriptors()

返回因子运行时目录的稳定操作描述符。

返回:: Reference to the immutable descriptor list.

std::string fincore::factor_operations_digest()

在规范化的描述符列表（按标识符排序）上计算 SHA-256。

返回:: Lowercase hexadecimal SHA-256 digest.

std::vector<factor_weight_row> fincore::factor_positions(const prepared_factor_data &factor_data, std::string_view period_label, bool long_short = true, bool group_neutral = false, bool equal_weight = false, const std::vector<int> &quantiles = {}, const std::vector<std::string> &groups = {}, std::optional<std::vector<factor_weight_row>> weights = std::nullopt)

为单个因子周期构造重叠且按毛额归一化的交易持仓。

period_label 以整工作日计数（例如 "3D" 或 "1D2D"）；持仓在对应的周一至周五工作日历上到期，不考虑交易所节假日，与 pandas 默认的 BusinessDay 偏移一致。结果覆盖每一笔交易与到期时间戳，并在最后一个持仓到期之后包含一行为零的行。

参数:

factor_data -- Prepared factor panel with forward-return labels.
period_label -- Forward-return label whose day count sets the holding.
long_short -- Enables long-short weighting when true.
group_neutral -- Applies group-neutral weighting when true.
equal_weight -- Uses equal weights within each bucket when true.
quantiles -- Optional quantile filter; empty keeps all quantiles.
groups -- Optional group filter; empty keeps all groups.
weights -- Optional precomputed weights replacing derived weights.

抛出:

factor_data_error -- When the period label is absent or malformed, the selection is empty, or grouped weights lack group labels.

返回:

Gross-normalized position rows in date/asset order.

factor_series_result fincore::factor_rank_autocorrelation(const prepared_factor_data &factor_data, int period = 1)

计算因子在固定滞后阶上的秩自相关。

因子值在每个日期内取平均秩，然后在两个日期都存在的资产上与滞后秩做相关。非有限的因子值被排除；前 period 个日期、共有资产少于两个以及秩向量为常数都得到 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
period -- Positive lag in dates.

抛出:

factor_data_error -- If period is not positive.

返回:

Series over every unique date, sorted ascending.

factor_return_table fincore::factor_returns(const prepared_factor_data &factor_data, bool demeaned = true, bool group_adjust = false, bool equal_weight = false)

由因子权重计算组合收益。

以相同选项调用 factor_weights，并按日期与标签累加权重乘以前瞻收益，跳过任一取值非有限的配对。

参数:

factor_data -- Prepared rows and forward-return labels.
demeaned -- Center the bucket values before weighting.
group_adjust -- Form weights per (date, group) and renormalize per date.
equal_weight -- Give each side of zero an equal share.

抛出:

factor_data_error -- If group_adjust is true and a row has no group.

返回:

Returns per date and label; a cell with no usable pair stays zero.

std::vector<factor_weight_row> fincore::factor_weights(const prepared_factor_data &factor_data, bool demeaned = true, bool group_adjust = false, bool equal_weight = false)

计算逐观测的因子权重。

权重在每个 (date[, group]) 桶内形成：demeaned 对桶内值做中心化，equal_weight 让零的两侧各占相等份额，然后桶除以其绝对毛暴露。group_adjust 随后在每个日期的各组之间重新归一化。毛暴露为零或非有限的桶产生 NaN 权重。

参数:

factor_data -- Prepared rows and forward-return labels.
demeaned -- Center the bucket values before weighting.
group_adjust -- Form weights per (date, group) and renormalize per date.
equal_weight -- Give each side of zero an equal share.

抛出:

factor_data_error -- If group_adjust is true and a row has no group.

返回:

One row per prepared row, in input order.

const std::vector<factor_workflow> &fincore::factor_workflows()

返回内置的命名因子工作流。

列表涵盖 summary、returns、information、turnover、full、event_returns 与 event_study 工作流。

返回:: Reference to the immutable workflow list.

fama_macbeth_result fincore::fama_macbeth(const dataframe &returns, const dataframe &exposures, fama_macbeth_covariance covariance = fama_macbeth_covariance::iid, std::size_t newey_west_lags = 1U)

运行 Fama-MacBeth 截面回归。

对每个存在匹配暴露行的收益日期，或在各日期上广播的唯一个暴露行，在共有资产列上做截面回归。当有限资产少于两个或暴露没有变化时跳过该截面。随后用 i.i.d. 或 Bartlett Newey-West 标准误汇总系数序列；标准差不高于 1e-15 时 t 统计量为无穷，均值为零时取零。

参数:

returns -- Returns with at least two double asset columns.
exposures -- Per-date exposures for the same assets, or one row broadcast across every return date.
covariance -- Standard-error estimator for the coefficient series.
newey_west_lags -- Bartlett lags; must be smaller than the fitted cross-section count when covariance is newey_west.

抛出:

factor_data_error -- If an input is empty, has duplicate index values, lacks two double asset columns, misses return assets, is unsorted for Newey-West, or requests too many lags.

返回:

Slope and intercept estimates plus the fitted cross-section count.

const factor_workflow *fincore::find_factor_workflow(std::string_view workflow_id)

按标识符查找工作流，不存在时返回 nullptr。

参数:: workflow_id -- Workflow identifier to find.
返回:: Pointer to the matching workflow, or nullptr when absent.

std::string fincore::fingerprint_value(const factor_value &value)

返回在规范原生编码上的稳定 SHA-256 摘要。

摘要基于 detail::canonical_factor_value(value) 计算，为 64 个小写十六进制字符，且不受对象插入顺序与 NaN 载荷影响。

参数:: value -- Value to fingerprint.
返回:: Lowercase hexadecimal SHA-256 digest.

std::string fincore::fingerprint_value(const factor_analysis_model &model)

返回 serializable_value(model) 的指纹。

参数:: model -- Model to fingerprint.
返回:: Lowercase hexadecimal SHA-256 digest.

std::string fincore::fingerprint_value(const factor_loss_report &report)

返回 serializable_value(report) 的指纹。

参数:: report -- Loss report to fingerprint.
返回:: Lowercase hexadecimal SHA-256 digest.

std::string fincore::fingerprint_value(const research_result &result)

返回序列化研究结果的指纹。

参数:: result -- Research result to fingerprint.
返回:: Lowercase hexadecimal SHA-256 digest.

std::vector<std::string> fincore::get_forward_returns_columns(const std::vector<std::string> &columns, bool require_exact_day_multiple = false)

选取符合固定版本因子前瞻收益语法的标签。

结果保持输入顺序与重复项。非法标签被跳过。require_exact_day_multiple 为真时只保留重复的日成分；与 Python 实现不同，原生辅助函数静默跳过而不发出警告。

ic_interval fincore::ic_confidence_interval(std::span<const double> values, double z = 1.96)

计算平均 IC 的正态置信区间。

半宽为 z 乘以非 NaN 取值的样本标准误。可用取值少于两个时区间边界为 NaN。

参数:

values -- IC observations.
z -- Positive finite multiplier, conventionally 1.96 for 95%.

抛出:

factor_data_error -- If z is not finite and positive, or a value is infinite.

返回:

Interval bounds; both NaN below two usable values.

double fincore::ic_mean(std::span<const double> values)

计算 IC 取值样本的均值。

跳过 NaN 项；空样本或全 NaN 样本返回 NaN。

参数:: values -- IC observations.
抛出:: factor_data_error -- If a value is infinite.
返回:: Arithmetic mean of the non-NaN values.

double fincore::ic_t_stat(std::span<const double> values)

计算 IC 取值样本的 t 统计量。

统计量为均值除以由一阶自由度偏差计算的样本标准误。跳过 NaN 项；可用取值少于两个时返回 NaN；标准差低于 1e-15 时返回无穷或零，其符号跟随均值的符号。

参数:: values -- IC observations.
抛出:: factor_data_error -- If a value is infinite.
返回:: t statistic of the sample.

trading_calendar fincore::infer_trading_calendar(const std::vector<timestamp> &factor_dates, const std::vector<timestamp> &price_dates)

由因子与价格日期推断交易日的工作日与缺失交易日对应的节假日。

并集被归一化到日；空并集会被拒绝。

参数:

factor_dates -- Factor observation timestamps in UTC nanoseconds.
price_dates -- Price observation timestamps in UTC nanoseconds.

抛出:

factor_data_error -- When both input date lists are empty.

返回:

Calendar whose enabled weekdays and holidays cover the union.

ic_inference_result fincore::information_coefficient_inference(const factor_ic_table &information, double alpha = 0.05)

对每个 IC 标签检验均值为零，并做 FDR 校正。

对每个标签，汇总 IC 表中的有限项，并在 n - 1 自由度上做双侧 Student-t 检验。有限项少于两个的标签报告为不可检验，其 t 与 p 值为 NaN。只有可检验的标签进入 Benjamini-Hochberg 校正，该校正设置 rejected 与 adjusted_p_value。

参数:

information -- IC table whose rows are pooled per label.
alpha -- Target false-discovery rate in (0, 1].

抛出:

factor_data_error -- If alpha is outside (0, 1].

返回:

One hypothesis per label, in the table's label order.

double fincore::legacy_forward_returns_loss(const factor_loss_report &report)

固定版本严格门面的 stdout 输出所使用的损失措辞。

返回 (input_count - forward_returns_count) / input_count，空输入返回 0。

factor_series fincore::materialize_pit_factor(const std::vector<pit_observation> &observations, const std::vector<timestamp> &evaluation_dates)

由时点观测物化出因子面板。

对每个评估日期，资产取自在该日期已知且已生效、(effective_from, known_at, as_of) 最大的修订版本。被标记为股票池之外的资产被跳过，没有合格修订版本的资产在该日期缺失。

参数:

observations -- Point-in-time observations with non-empty assets.
evaluation_dates -- Strictly increasing dates to evaluate.

抛出:

factor_data_error -- When dates are unsorted, an asset is empty, a point is invalid, or a revision is duplicated.

返回:

Long-form panel ordered by date and asset.

factor_ic_summary fincore::mean_information_coefficient(const prepared_factor_data &factor_data, bool group_adjust = false, bool by_group = false)

按标签或按分组计算平均信息系数。

汇总输出在各日期之间对有限 IC 取值求平均；by_group 为 true 时改为在每个分组的各行之间求平均。没有有限取值的标签或分组返回 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
group_adjust -- Demean forward returns per date and group before ranking.
by_group -- Summarize one row per group instead of per label.

抛出:

factor_data_error -- If group data is required or requested and a row has no group column.

返回:

Summary with one mean per label or per group row.

quantile_return_table fincore::mean_return_by_quantile(const prepared_factor_data &factor_data, bool by_date = false, bool by_group = false, bool demeaned = true, bool group_adjust = false)

按分位计算前瞻收益均值。

每个日期的分位均值为该分位有限前瞻收益的等权均值；报告的均值是对这些日期均值再求平均，标准误是它们的样本标准差除以可用日期数的平方根。没有可用日期的分位保持 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
by_date -- Must be false; the by-date view has its own function.
by_group -- Emit one row per (quantile, group) pair.
demeaned -- Demean forward returns per date before averaging.
group_adjust -- Demean per date and group instead; implies groups.

抛出:

factor_data_error -- If by_date is true or group data is missing.

返回:

Quantile table with means and standard errors.

quantile_date_return_table fincore::mean_return_by_quantile_by_date(const prepared_factor_data &factor_data, bool demeaned = true, bool group_adjust = false, bool by_group = false)

计算逐日期的分位前瞻收益均值。

每个 (date, quantile, label) 单元对该桶内资产的前瞻收益有限值求平均；标准误为它们的样本标准差除以其数量的平方根，取值少于两个时保持 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
demeaned -- Demean forward returns per date before averaging.
group_adjust -- Demean per date and group instead; implies groups.
by_group -- Emit one row per (date, group) pair.

抛出:

factor_data_error -- If group data is missing while required.

返回:

Cube over (date[, group]) rows x quantiles x labels.

quantile_spread_result fincore::mean_return_spread(const quantile_return_table &table, int upper_quantile, int lower_quantile)

计算 upper 分位减 lower 分位的收益差。

多空差为 upper 分位均值减去 lower 分位均值，并在两者标准误都有限时按平方和开根的方式合并标准误。

参数:

table -- Quantile means and standard errors to read.
upper_quantile -- Quantile used as the long leg.
lower_quantile -- Quantile used as the short leg.

抛出:

factor_data_error -- If an aggregate table lacks either quantile, or a grouped table's groups are not parallel to its quantile rows.

返回:

Spread per label, or per group and label when the table is grouped.

research_evaluation_spec fincore::normalize_research_evaluation_spec(const research_evaluation_input &values)

校验调用方提供的取值并填充所有有文档记录的默认值。

参数:: values -- Caller-supplied optional fields and unknown keys.
抛出:: research_config_error -- When unknown fields are present or a supplied value violates its field contract; code() identifies the kind of failure.
返回:: Normalized evaluation spec with defaults applied.

factor_value fincore::parse_json_value(std::string_view text)

将严格的 JSON 解析为原生值。

能容纳的整数返回为 64 位整数值，其他数值返回为 double。对象的键必须为字符串。

参数:: text -- JSON text to parse.
抛出:: input_error -- If the text is malformed, has trailing content, uses an unsupported escape, or contains a number outside the finite double range.
返回:: Parsed native value.

std::int64_t fincore::parse_timedelta_nanoseconds(const std::string &label)

将前瞻收益的时长标签解析为纳秒。

接受可选的前导符号，其后为一个或多个成分，其中 unit 为 D、h、m、s、ms、us、ns 之一（不区分大小写）。格式非法的标签会被拒绝。

参数:: label -- Duration label such as "1D" or "2h30m".
抛出:: factor_data_error -- When the label is empty, malformed or names an unsupported unit.
返回:: Parsed duration in nanoseconds, negative when the label starts with -.

inline quantile_cumulative_chart fincore::plot_cumulative_returns_by_quantile(const quantile_date_return_table &returns, std::string period)

通过 build_cumulative_returns_by_quantile 构造累积增长图表数据。

参数与校验原样转发。

参数:

returns -- Mean returns by date, quantile and label.
period -- Forward-return label; must be present in returns.labels.

返回:

Chart data identical to the canonical builder's result.

inline events_distribution_chart fincore::plot_events_distribution(const std::vector<timestamp> &dates, const std::vector<double> &values = {}, std::size_t num_bars = 50U)

通过 build_events_distribution 构造事件分桶图表数据。

参数:

dates -- Event timestamps.
values -- Optional event values aligned with dates.
num_bars -- Number of equal-width buckets; must be positive.

返回:

Chart data identical to the canonical builder's result.

inline std::vector<qq_chart> fincore::plot_ic_qq(const factor_ic_table &ic)

通过 build_ic_qq 构造 Q-Q 图数据。

参数:: ic -- Information-coefficient table with values in date-major order.
返回:: One chart per label, in ic.labels order.

inline spread_time_series_chart fincore::plot_mean_quantile_returns_spread_time_series(const std::vector<timestamp> &dates, const std::vector<double> &spreads, std::string period, const std::vector<double> &standard_errors = {}, double bandwidth = 1.0)

通过 build_mean_quantile_returns_spread_time_series 构造多空差图数据。

参数:

dates -- Observation timestamps.
spreads -- Spreads in decimal return units, aligned with dates.
period -- Forward-return period label.
standard_errors -- Optional standard errors in decimal return units.
bandwidth -- Standard-error multiplier used for the band.

返回:

Chart data identical to the canonical builder's result.

inline std::vector<monthly_ic_heatmap_chart> fincore::plot_monthly_ic_heatmap(const factor_time_information_table &monthly)

通过 build_monthly_ic_heatmap 构造月度 IC 热力图数据。

参数:: monthly -- Monthly information-coefficient table.
返回:: One chart per group and label.

inline violin_chart fincore::plot_quantile_returns_violin(const quantile_date_return_table &returns, std::string period)

通过 build_quantile_returns_violin 构造分位收益小提琴图数据。

参数:

returns -- Mean returns by date, quantile and label.
period -- Forward-return label; must be present in returns.labels.

返回:

Violin chart data with one group per quantile that has samples.

style_context fincore::plotting_context(std::string context = "notebook", double font_scale = 1.5, std::map<std::string, std::string> rc = {})

创建带显式字体缩放的渲染器样式上下文。

返回的上下文以 context 作为名称，除在该键缺失时添加 lines.linewidth=1.5 之外保持 rc 不变。

参数:

context -- Context name.
font_scale -- Font scaling factor stored on the context.
rc -- rc parameter overrides keyed by parameter name.

返回:

Style context carrying the name, font scale and overrides.

prepared_factor_data fincore::prepare_factor_data(const factor_series &factor, const dataframe &prices, const prepare_factor_config &config = {})

由原始因子值与价格准备量化的因子面板。

前瞻收益按 config.periods 计算，任一标签都没有有限值的观测被丢弃，其余观测在配置的截面内进行量化。

参数:

factor -- Row-aligned factor panel to prepare.
prices -- Price panel used for forward returns.
config -- Horizons, bucket settings, grouping and loss budget.

抛出:

factor_data_error -- When an input or configuration value is invalid.
factor_loss_exceeded -- When total cleaning loss exceeds config.max_loss.

返回:

Retained rows, forward labels and the cleaning-loss report.

multi_horizon_prepared_factor_data fincore::prepare_factor_data_by_horizon(const factor_series &factor, const dataframe &prices, const prepare_factor_config &config = {})

为每个前瞻收益预测期准备一个量化面板。

每个预测期都针对该期收益为有限的截面分桶，并各自与 config.max_loss 校验。

参数:

factor -- Row-aligned factor panel to prepare.
prices -- Price panel used for forward returns.
config -- Horizons, bucket settings, grouping and loss budget.

抛出:

factor_data_error -- When an input is invalid or config.filter_zscore is set, since per-horizon preparation has no full-sample filter.
factor_loss_exceeded -- When a horizon exceeds config.max_loss.

返回:

Per-horizon prepared panels in the order of config.periods.

prepared_factor_data fincore::prepare_factor_data_from_forward_returns(const factor_series &factor, const forward_return_table &forward_returns, const prepare_factor_config &config = {})

由提供的前瞻收益表准备量化的因子面板。

表必须具有唯一的标签以及唯一的 (date, asset) 行，并且每行对每个标签都有一个值。配对不存在或取值非有限的观测被丢弃，并计入损失报告。

参数:

factor -- Row-aligned factor panel to prepare.
forward_returns -- Precomputed forward returns to align by date/asset.
config -- Bucket settings, grouping and loss budget.

抛出:

factor_data_error -- When the factor or forward table is malformed.
factor_loss_exceeded -- When total cleaning loss exceeds config.max_loss.

返回:

Retained rows, forward labels and the cleaning-loss report.

prepared_factor_data fincore::prepare_pit_factor_data(const std::vector<pit_observation> &observations, const dataframe &prices, const std::vector<timestamp> &evaluation_dates, const prepare_factor_config &config = {})

由时点观测准备量化的因子面板。

观测先被物化为因子面板，再针对价格准备，因此只有在每个评估日期已知且生效的信息才会进入输出。

参数:

observations -- Point-in-time observations with non-empty assets.
prices -- Price panel used for forward returns.
evaluation_dates -- Strictly increasing dates to evaluate.
config -- Horizons, bucket settings, grouping and loss budget.

抛出:

factor_data_error -- When config.filter_zscore is set, no eligible value materializes, or preparation inputs are invalid.
factor_loss_exceeded -- When total cleaning loss exceeds config.max_loss.

返回:

Retained rows, forward labels and the cleaning-loss report.

factor_series_result fincore::quantile_turnover(const prepared_factor_data &factor_data, int quantile, int period = 1)

计算固定滞后阶下的分位换手率。

某日的换手率为该分位资产中在前 period 个日期里缺席的比例；成员关系依据提供的行判定，即使因子值非有限也是如此。前 period 个日期以及该分期为空的日期为 NaN。

参数:

factor_data -- Prepared rows and forward-return labels.
quantile -- Quantile whose membership is tracked.
period -- Positive lag in dates.

抛出:

factor_data_error -- If period is not positive.

返回:

Series over every unique date, sorted ascending.

std::vector<std::optional<int>> fincore::quantize_factor(const factor_series &factor, const quantization_config &config = {}, const factor_grouping &grouping = {})

为因子观测分配从 1 开始的桶标签。

桶按日期构造；当 config.by_group 为 true 时按 (date, group) 对构造。非有限的因子值不获得标签。

参数:

factor -- Row-aligned factor panel to label.
config -- Bucket count, explicit bins and failure handling.
grouping -- Asset-to-group mapping required when binning by group.

抛出:

factor_data_error -- When no usable quantiles or bins are configured, a group is missing, or bucket edges are not unique.

返回:

One optional label per factor row; empty when no label applies.

research_capabilities fincore::research_capabilities_report()

返回固定版本的原生研究能力声明。

返回:: Capability record listing the supported labels, preprocessing methods, metrics, result tables, export formats and statuses.

std::vector<research_comparison_row> fincore::research_factor_comparisons(std::span<const named_research_result> results, const std::map<std::string, std::pair<std::string, std::string>> &comparisons)

按周期计算命名因子对的平均 IC 与 ICIR 之差。

周期标签为两侧已存储 IC 标签集合的并集。统计量只使用有限的 IC 取值；任一侧不可用时差值为 NaN。

参数:

results -- Named single-factor results; names must be non-empty and unique.
comparisons -- Comparison name to (left, right) factor names.

抛出:

factor_data_error -- When a result name is empty or duplicated, or a comparison references an unknown factor.

返回:

One row per comparison and union period label.

std::vector<research_correlation_row> fincore::research_factor_correlations(std::span<const research_factor_panel> factors, int min_assets = 1)

对每个因子对按日期在共有资产上计算 Pearson 相关系数。

共有有限资产少于 min_assets 的日期以及任一侧离散度为零的日期被跳过。因子对遵循输入顺序，每行汇总有贡献的日期。

参数:

factors -- Named factor panels; names must be non-empty and unique.
min_assets -- Minimum common assets per date; must be positive.

抛出:

factor_data_error -- When min_assets is not positive or a panel name is empty or duplicated.

返回:

One row per factor pair in input order, empty when factors is empty.

factor_value fincore::serializable_value(const research_result &result)

返回指纹与 JSON 信封使用的原生值形式。

参数:: result -- Research result to serialize.
返回:: Object with status, schema_version, manifest, tables and columns; non-finite numbers become null.

factor_value fincore::serializable_value(const factor_analysis_model &model)

将因子分析模型转换为其原生信封值。

信封包含模式标识符、指纹版本、结果指纹、配置、前瞻周期、损失报告、分位统计与表、IC 表、平均收益多空差、换手率与秩自相关序列，以及可选的事件分析。IC、分位、换手率、秩自相关与事件数组中的非有限项编码为 null。

参数:: model -- Model to serialize.
返回:: Native object value for the model.

factor_value fincore::serializable_value(const factor_loss_report &report)

将损失报告转换为原生对象值。

参数:: report -- Loss report to serialize.
返回:: Native object with the report counters and loss values.

std::vector<std::uint64_t> fincore::show_owned_figures(const owned_figures &figures)

按显示顺序返回图形标识符，且不打开窗口。

参数:: figures -- Figure list to display.
返回:: Copy of figures.figures.

dataframe_snapshot fincore::snapshot_pandas(const dataframe &value)

对原生 DataFrame 做快照并计算其确定性的内容摘要。

参数:: value -- Dataframe to copy.
抛出:: fincore_error -- If a column type cannot be encoded in the canonical content representation.
返回:: Snapshot owning an independent copy of value.

dataframe_snapshot fincore::snapshot_pandas(dataframe &&value)

通过接管存储的方式对原生 DataFrame 做快照。

参数:: value -- Dataframe to move.
抛出:: fincore_error -- If a column type cannot be encoded in the canonical content representation.
返回:: Snapshot owning value.

double fincore::student_t_two_sided_p(double statistic, double df)

返回双侧 Student-t 尾部概率。

使用 df 自由度的正则化不完全贝塔函数。统计量为 NaN，或 df 为非正/NaN 时返回 NaN；统计量为无穷时返回零。

参数:

statistic -- t statistic.
df -- Degrees of freedom; must be positive.

返回:

Two-sided p value, or NaN when it is undefined.

std::vector<int> fincore::timedelta_strings_to_integers(const std::vector<std::string> &sequence)

返回每个 pandas 风格时长字符串的整日部分。

参数:: sequence -- Duration labels to parse.
抛出:: factor_data_error -- When a label is malformed or a day component does not fit in int.
返回:: One whole-day component per label, in input order.

std::string fincore::timedelta_to_string(std::int64_t delta)

使用固定版本的前瞻收益标签语法格式化时长。

成分遵循 pandas 的归一化表示（向下取整的天数加非负余数），例如 -1h 变为 "-1D23h"，零时长变为 ""。

参数:: delta -- Duration in nanoseconds.
返回:: Pinned duration label; empty for a zero duration.

std::string fincore::to_json_string(const factor_value &value)

将原生值序列化为确定性、符合标准的 JSON 文本。

对象按键的排序顺序输出，因此同一取值产生的文本是稳定的。

参数:: value -- Value to serialize.
抛出:: input_error -- If the value contains a non-finite floating-point number or a string that is not valid UTF-8.
返回:: Deterministic JSON text.

research_spec fincore::to_research_spec(const research_evaluation_spec &values)

将已归一化的评估设定投影为执行设定。

参数:: values -- Normalized evaluation spec.
返回:: Execution spec carrying the shared fields; analysis-only metadata has no execution-spec counterpart.

std::string fincore::to_serializable(const factor_analysis_model &model)

返回 serializable_value(model) 的 JSON 文本形式。

这是 Python to_serializable 方法的原生等价实现。

参数:: model -- Model to serialize.
抛出:: input_error -- If a value cannot be represented as JSON, such as a non-finite loss-report number.
返回:: Deterministic JSON text for the model envelope.

void fincore::validate_pit_alignment(const std::vector<pit_point> &points)

校验时点顺序与有限性。

每个点必须携带有限取值，且 known_at 不早于 as_of、effective_from 不早于 known_at。

参数:: points -- Points to check; an empty batch is valid.
抛出:: factor_data_error -- When a point violates finiteness or ordering.

using fincore::factor_data_error_alias = factor_data_error : factor_data_error 的源名称别名。

using fincore::factor_loss_exceeded_error = factor_loss_exceeded : 保留 enhanced/strict 区分的源名称别名。

constexpr double fincore::DECIMAL_TO_BPS = 10'000.0: 与 Alphalens 兼容的小数转基点比例。

constexpr int fincore::EVALUATION_CONFIG_SCHEMA_VERSION = 1: 归一化后的研究评估配置的模式版本。

constexpr double fincore::decimal_to_bps = DECIMAL_TO_BPS : DECIMAL_TO_BPS 的别名。

constexpr int fincore::evaluation_config_schema_version = EVALUATION_CONFIG_SCHEMA_VERSION : EVALUATION_CONFIG_SCHEMA_VERSION 的小写别名。

constexpr std::uint32_t fincore::factor_analysis_fingerprint_version = 2U

原生结果指纹编码的版本。

混入每个结果指纹，并由 factor_analysis_model::result_fingerprint_version 回显。

constexpr const char *fincore::factor_analyze_operation_id = "factor_analysis.analysis.analyze_factor": 共享因子分析内核的操作标识符。

constexpr std::int64_t fincore::nanoseconds_per_day = 86'400'000'000'000LL: 一个日历日包含的纳秒数。

constexpr const char *fincore::research_api_version = "1.0": 能力声明与结果 manifest 报告的研究 API 版本。

constexpr const char *fincore::research_detailed_api_version = "2.0": 记录在结果与导出 manifest 中的详细研究 API 版本。

constexpr const char *fincore::research_detailed_export_schema_id = "fincore.factor_research_detailed.v2": 写入详细导出 manifest 的模式标识符。

constexpr int fincore::research_detailed_export_schema_version = 2: 写入详细导出 manifest 的模式版本。

constexpr int fincore::research_detailed_result_schema_version = 2: research_detailed_result 的模式版本。

constexpr int fincore::research_result_schema_version = 1: 研究结果信封及其 manifest 的模式版本。