指标

收益率、风险、回撤、分布、滚动、年度及绩效归因统计。

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

class matrix

行主序稠密矩阵，用于锁定版本的 Python 源码需要 NumPy 二维数组的场合。

values().size() 始终等于 rows() * columns()。

公共函数

matrix() = default: 构造一个空的 0 x 0 矩阵。

matrix(std::size_t row_count, std::size_t column_count, std::vector<double> values)

从行主序缓冲区构造一个 row_count x column_count 矩阵。

当形状无法表示，或 values.size() 与 row_count * column_count 不一致时，抛出 input_error。

std::size_t rows() const noexcept: 返回行数。

std::size_t columns() const noexcept: 返回列数。

std::span<const double> values() const noexcept: 返回行主序元素缓冲区，其长度为 rows() * columns()。

std::span<const double> row(std::size_t row_index) const: 返回 row_index 行的视图；越界时抛出 input_error。

double at(std::size_t row_index, std::size_t column_index) const: 返回 (row_index, column_index) 处的元素；任一索引越界时抛出 input_error。

double &at(std::size_t row_index, std::size_t column_index): 返回 (row_index, column_index) 处元素的可变引用；任一索引越界时抛出 input_error。

struct bootstrap_metric_stats

单个绩效指标的 bootstrap 分布。

公共成员

std::string name: 指标的显示名称。

std::vector<double> samples: 每次抽样的统计量，按抽样顺序排列。

distribution_stats summary: 样本汇总。

struct daily_consecutive_statistics

由收益率序列得到的日度连续段统计。

公共成员

double max_consecutive_up_days: 最长的正观测连续段。

double max_consecutive_down_days: 最长的负观测连续段。

double max_consecutive_gain: 正连续段上的最大求和。

double max_consecutive_loss: 负连续段上最负的求和。

struct distribution_stats

一组指标样本的描述性汇总。

样本为空时每个字段均为 NaN。分位数使用线性插值，std 为总体偏差。

公共成员

double mean: 算术平均值。

double median: 第 50 百分位。

double std: 总体标准差（除以样本数）。

double p5: 第 5 百分位。

double p25: 第 25 百分位。

double p75: 第 75 百分位。

double p95: 第 95 百分位。

double iqr: 四分位距，p75 - p25。

struct drawdown_period

一次水下期，从低于滚动峰值的首个观测起，经谷底和可选的恢复为止。

公共成员

timestamp start: 低于前一峰值的首个时间戳。

timestamp valley: 最深点的时间戳。

std::optional<timestamp> recovery: 回到前一峰值的收益率；该事件始终未恢复时为 nullopt。

double value: 谷底处的深度，为相对峰值的负比例。

std::size_t duration_periods: 从起点到谷底的观测数。

std::optional<std::size_t> recovery_duration_periods: 从谷底到恢复的观测数。

struct drawdown_table_row

gen_drawdown_table 的一行。

公共成员

double net_drawdown_percent = std::numeric_limits<double>::quiet_NaN(): 深度，为峰值财富的正百分比；未使用的行为 NaN。

std::optional<timestamp> peak: 前一峰值的时间戳。

std::optional<timestamp> valley: 最深点的时间戳。

std::optional<timestamp> recovery: 回到峰值的收益率（若有）。

std::optional<std::size_t> duration_business_days: 从峰值到恢复（含两端）的周一至周五天数；没有恢复时为 nullopt。

struct drawdown_window

一次回撤的峰值、谷底及可选的恢复时间戳。

公共成员

timestamp peak: 下跌前滚动峰值的时间戳。

timestamp valley: 最深点的时间戳。

std::optional<timestamp> recovery: 回到峰值的收益率；该事件始终未恢复时为 nullopt。

struct gpd_risk_estimates_result

收益率分布的广义帕累托尾部估计。

公共成员

double threshold: 为尾部拟合选择的损失阈值。

double scale: GPD 尺度参数。

double shape: GPD 形状参数（对拟合出的尾部为正）。

double var: 在所请求概率下的风险价值估计。

double es: 预期短缺估计。

struct named_returns

从收益率序列中提取的一个具名历史窗口。

公共成员

std::string name: 窗口标签，例如 "Lehman"。

dataframe returns: 窗口内所选列的收益率。

struct perf_attribution_result

逐日风险暴露与收益归因。

公共成员

dataframe risk_exposures: 归因索引上的因子暴露。

dataframe attribution: 因子贡献，加上总收益、共同收益、特定收益、倾斜收益和择时收益列。

struct perf_attribution_statistics

perf_attribution_result 的汇总统计。

公共成员

std::map<std::string, double> summary: 七项具名收益统计。

dataframe factor_summary: 每个因子一行：名称、平均暴露以及年化和累计贡献。

enum class fincore::frequency

收益率序列的复利周期。

取值：

enumerator daily: 日度观测，按 252 个周期年化。

enumerator weekly: 周度观测，按 52 个周期年化。

enumerator monthly: 月度观测，按 12 个周期年化。

enumerator quarterly: 季度观测，按 4 个周期年化。

enumerator yearly: 年度观测，按 1 个周期年化。

enum class fincore::return_aggregation_period

aggregate_returns 使用的日历分桶。

取值：

enumerator weekly: ISO-8601 周，以年内周序号为键。

enumerator monthly: 日历月。

enumerator quarterly: 日历季度。

enumerator yearly: 日历年。

dataframe fincore::adjust_returns(const dataframe &returns, double adjustment_factor, std::string_view column = returns_column)

返回 returns 的副本，其中 column 列的每个值都减去 adjustment_factor。

时间戳保持不变，结果存储在 column 下；NaN 值仍为 NaN。当 column 不存在、不是 double 列或与帧索引长度不一致时，抛出 input_error。

double fincore::adjusted_sharpe_ratio(const dataframe &returns, double risk_free = 0.0, std::string_view column = returns_column)

返回经收益率分布偏度和峰度调整的夏普比率。

夏普比率按 daily_annualization 年化，再乘以由非 NaN 值的有偏偏度和超额峰度构建的阻尼调整系数。原始观测少于 20 个时，调整系数被限制在 [0.9, 1.1]，否则限制在 [0.8, 1.3]。原始值少于四个或夏普比率为 NaN 时返回 NaN；column 中嵌入 NUL 会抛出 input_error。

dataframe fincore::aggregate_returns(const dataframe &returns, return_aggregation_period period = return_aggregation_period::monthly, std::string_view column = returns_column)

返回按 period 的日历分桶复合后的 returns。

输出索引保存每个分桶的起始时间戳（周为周一，并钳制到 1 月 1 日；月或季度为当月或当季第一天；年为 1 月 1 日），并包含整数 year 和 period 列，复合收益率存储在 column 下。NaN 收益率视为零。column 不得为 return_aggregation_year_column 或 return_aggregation_period_column；否则抛出 input_error。

std::pair<dataframe, dataframe> fincore::aligned_series(const dataframe &left, std::string_view left_column, const dataframe &right, std::string_view right_column)

返回按公共时间戳对齐的两个单列序列。

原生约定：公共索引按左帧顺序输出（align_on_common_index 语义），任一帧缺失的时间戳会被丢弃，而存在的 NaN 值会保留。两个索引都必须包含唯一时间戳，且不得包含 NaT 哨兵（numeric_limits::min()）；重复项对按键对齐而言存在歧义，会抛出 input_error。

已声明的源码差异：锁定版本的 Python 双 Series 路径使用 pd.concat(..., sort=False)（外并集，仅右侧存在的行以 NaN 保留），而其 DataFrame 及混合 DataFrame/Series 路径取交集。此原生辅助函数对所有输入都遵循 P101 的公共索引交集，并在源 DataFrame.align 路径按升序排序时输出左侧顺序。

std::pair<dataframe, dataframe> fincore::aligned_series(const dataframe &left, const dataframe &right)

返回按公共时间戳对齐的两个帧，按源列顺序保留每个帧的所有 double 列。

唯一性、NaT、缺失值和排序规则与单列重载相同。

double fincore::alpha(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回公共时间戳上的年化 Jensen alpha。

丢弃 NaN 对。每期超额收益均值减去 beta 乘以基准超额收益，再按 annualization 复合。beta 非有限时返回 NaN。两个序列都减去 risk_free。

std::pair<double, double> fincore::alpha_beta(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回在公共时间戳上计算的 {alpha, beta}。

仅使用有限对。剩余对少于两个、risk_free 或 annualization 非有限、annualization 非正，或任一结果非有限时，返回 {NaN, NaN}。

double fincore::alpha_percentile_rank(const dataframe &strategy_returns, std::span<const dataframe> peer_returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回严格低于该策略 alpha 的同业策略 alpha 占比。

观测少于三个或 alpha 为 NaN 的同业序列会被忽略。策略 alpha 不可用或没有可用的同业 alpha 时返回 NaN。列名中嵌入 NUL 字符会抛出 input_error。

double fincore::annual_active_return(const dataframe &returns, const dataframe &benchmark, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 与 benchmark 在公共时间戳上的年化收益率之差。

两个年化收益率都使用 annualization_factor(period, annualization)。对齐后为空时返回 NaN。未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::annual_active_return_by_year(const dataframe &returns, const dataframe &benchmark, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个 UTC 日历年的主动收益，存储在列 "annual_active_return" 中。

在分桶之前，两个帧先按公共时间戳对齐；每年使用 annualization_factor(period, annualization) 计算两个年化收益率之差。年份以 1 月 1 日为索引并按升序排序；对齐结果为空时返回空的有类型帧。未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::annual_alpha(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个 UTC 日历年的年度 alpha，以 1 月 1 日为索引，存储在列 "alpha" 中。

每年使用 annualization_factor(period, annualization) 以及与 alpha 相同的 NaN 对规则。

dataframe fincore::annual_beta(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个 UTC 日历年的年度 beta，以 1 月 1 日为索引，存储在列 "beta" 中。

period 和 annualization 被忽略，因为 beta 不进行年化。

double fincore::annual_return(const dataframe &returns, double annualization = daily_annualization, std::string_view column = returns_column)

返回 column 的几何年化收益率。

总财富取 annualization / observation_count 次幂，NaN 收益率视为零。空帧返回 NaN，期末财富非正时返回 -1。

dataframe fincore::annual_return_by_year(const dataframe &returns, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个 UTC 日历年的年度收益，存储在列 "annual_return" 中。

每年以其 1 月 1 日时间戳为索引，并使用 annual_return 与 annualization_factor(period, annualization)。年份按升序排序，而观测在年内保持输入顺序。空帧返回空的有类型帧；未知频率且未显式指定 annualization 时抛出 input_error。

double fincore::annual_volatility(const dataframe &returns, double annualization = daily_annualization, std::string_view column = returns_column)

返回 column 的年化样本标准差。

使用非 NaN 值并以一个自由度为分母，结果乘以 sqrt(annualization)；有效值少于两个时返回 NaN。

dataframe fincore::annual_volatility_by_year(const dataframe &returns, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个 UTC 日历年的年化波动率，存储在列 "annual_volatility" 中。

每年使用 annual_volatility（因此忽略 NaN 观测）以及 annualization_factor(period, annualization)。年份以 1 月 1 日为索引并按升序排序。空帧返回空的有类型帧；未知频率且未显式指定 annualization 时抛出 input_error。

double fincore::annualization_factor(frequency period, std::optional<double> annualization = std::nullopt)

返回用于对 period 年化的每年周期数。

显式给出的 annualization 值原样返回；否则默认值依次为 252、52、12、4 和 1，分别对应日度到年度观测。

double fincore::beta(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 对 benchmark 在公共时间戳上的 OLS beta。

丢弃 NaN 对，并在回归前从两个序列中减去 risk_free。有效对少于两个、基准方差接近零，或协方差/beta 结果非有限时返回 NaN。

double fincore::beta_fragility_heuristic(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回启发式的 beta 脆弱性得分，将按因子排序后样本低端和高端的收益率与中间观测进行比较。

至少需要三个对齐的非 NaN 对，否则返回 NaN。列名中嵌入 NUL 字符会抛出 input_error。

double fincore::burke_ratio(const dataframe &returns, double risk_free = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回超过 risk_free 的年化收益除以 Burke 回撤风险度量。

该风险度量为各回撤深度平方和的开方；没有回撤或回撤全为零时，回退到负收益的总体标准差（若没有负收益，则使用所有可用值的总体标准差）。年化收益按 annualization 复合。当风险度量低于 1e-10 且超额年化收益为正时返回正无穷，对应的非正情形返回 NaN；原始值少于两个或没有可用值时也返回 NaN。column 中嵌入 NUL 会抛出 input_error。

double fincore::cal_treynor_ratio(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 相对 benchmark 的年化特雷诺比率。

两个序列按公共时间戳对齐；超过 risk_free 的年化收益除以对齐后的 beta。对齐后剩余收益少于两个，或 beta 为 NaN、零或负数时返回 NaN。任一列名中嵌入 NUL 会抛出 input_error。

distribution_stats fincore::calc_distribution_stats(std::span<const double> values)

返回 values 的均值、偏差和百分位数。

values 按原样使用（不过滤 NaN）；百分位数在 (n - 1) * p / 100 处使用线性插值，std 除以样本数。空范围时每个字段均为 NaN。

double fincore::calmar_ratio(const dataframe &returns, double risk_free = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回超过 risk_free 的年化收益除以绝对最大回撤。

年化收益按 annualization 复合。序列从未下跌（最大回撤为零或 NaN），或商非有限时返回 NaN。

double fincore::capm_r_squared(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 CAPM 相关系数的平方，并限制在 [0, 1]。

相关系数不可用时返回 NaN。

double fincore::capture(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 的年化几何收益与 benchmark 的年化几何收益之比。

两个序列按公共时间戳对齐且只保留有限对；各侧在其配对观测上复合并按 annualization 年化。没有剩余对、任一年化收益非有限、基准年化收益为零，或商非有限时返回 NaN。

double fincore::common_sense_ratio(const dataframe &returns, std::string_view column = returns_column)

返回常识比率：尾部比率乘以胜率再除以败率。

两个分量都取自 column，并各自遵循其 NaN 规则。原始值少于两个、分量为 NaN 或胜率为零时返回 NaN；每个可用观测都是盈利时返回正无穷。column 中嵌入 NUL 会抛出 input_error。

dataframe fincore::compute_bayes_cone(const dataframe &predicted_returns, double starting_value = 1.0)

返回累计预测财富的跨路径百分位锥。

predicted_returns 的每个 double 列是一条路径，每一行是一个预测步，均按输入顺序排列。财富从 starting_value 开始，每行乘以 1 + 收益率，并在每行将跨路径的七个线性百分位存储到固定的 percentile_* 列中。输入索引（包括重复项）保持不变，返回的帧拥有其数值。

至少需要一列，每列都必须是匹配帧索引的 double 列，并且 starting_value、每个收益率、累计财富和插值百分位都必须有限；否则抛出 input_error，包括形状不可用和分配失败的情形。索引为空但列是有类型空列的帧会返回有类型的空七列帧。

std::vector<double> fincore::compute_consistency_score(const dataframe &returns_test, const matrix &predicted_returns, std::string_view column = returns_column)

返回每个日期上累计预测路径严格低于实际累计收益的占比。

predicted_returns 为行主序，每条抽样路径一行，每个样本外日期一列。returns_test 必须每列对应一个值。源公式：实际财富 = cumprod(1 + returns)，其中 NaN 收益率视为 0（源 cum_returns 策略）；预测财富 = 每行的 cumprod(1 + preds)；score[t] = |{path : cum_pred[path, t] < realized[t]}| / path_count。预测值必须有限且 1 + 值有限；实际值可为 NaN（视为 0）但不能为无穷。路径数为零时每个日期的得分均为 NaN，与源对空轴求均值的结果一致。

dataframe fincore::compute_exposures(const dataframe &positions, const dataframe &factor_loadings, std::span<const std::string_view> factor_column_names, std::string_view cash_column_name = cash_column, std::string_view symbol_column_name = attribution_symbol_column)

返回 positions 的逐日因子暴露。

对每个请求的因子，暴露为各资产头寸价值乘以因子载荷之和，按 (timestamp, symbol) 与 factor_loadings 匹配；NaN 乘积会被跳过。结果保留 positions 索引，并按 factor_column_names 的顺序为每个名称保留一列。头寸时间戳重复、因子名称为空/重复或与 symbol 冲突、symbol 列缺失或非字符串、因子载荷列非 double、(timestamp, symbol) 键重复，或某个有头寸的资产缺少对应键时，抛出 input_error。

double fincore::conditional_sharpe_ratio(const dataframe &returns, double cutoff = 0.05, double risk_free = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回由 cutoff 定义的左尾夏普比率。

cutoff 分位数在 (n - 1) * cutoff 处线性插值；所有小于等于该值的观测构成尾部。尾部超过 risk_free 的平均超额除以尾部样本偏差（一个自由度），再乘以 sqrt(annualization)。cutoff 不在 (0, 1) 内、任一原始值为 NaN、尾部少于两个值，或偏差为零或非有限时返回 NaN。column 中嵌入 NUL 会抛出 input_error。

double fincore::conditional_value_at_risk(const dataframe &returns, double cutoff = 0.05, std::string_view column = returns_column)

返回 column 中所有小于等于经验 cutoff 分位数的观测的均值。

除非每个值都有限且 cutoff 位于 [0, 1]，否则返回 NaN。

std::string fincore::cone_bounds_column_name(double num_std)

返回某个锥边界宽度的原生列标签，例如 cone_1 或 cone_-1。

宽度以其最短往返形式呈现；宽度非有限时抛出 input_error。

std::map<std::string, double> fincore::consecutive_stats(const dataframe &returns, std::string_view column = returns_column): 返回日度、周度和月度上行/下行连续段长度共六项的映射，以各自的 snake_case 名称为键。

double fincore::cornell_timing(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 Cornell 择时度量：上行市场斜率减去下行市场斜率。

用普通最小二乘拟合 excess_return = a + b * up + c * down（其中 up 为 max(0, excess_market)，down 为 min(0, excess_market)），并返回 b - c。只使用有限对，两个序列都减去 risk_free。可用对少于十个、risk_free 非有限、设计矩阵奇异或结果非有限时返回 NaN。

perf_attribution_statistics fincore::create_perf_attrib_stats(const perf_attribution_result &result, double annualization = daily_annualization)

返回归因的收益汇总和逐因子统计。

summary 保存 "Annualized Specific Return"、"Annualized Common Return"、"Annualized Total Return"、"Specific Sharpe Ratio"、"Cumulative SpecificReturn"、"Cumulative Common Return" 和 "Total Returns"；年化值按 annualization 复合，特定夏普比率也使用它。factor_summary 具有 0..n-1 的位置索引，列包括 "factor"、"Average Risk Factor Exposure"（非 NaN 暴露的均值）、"Annualized Return" 以及各因子贡献的 "Cumulative Return"。索引不匹配或缺少标准归因列时抛出 input_error。

double fincore::cumulative_return(const dataframe &returns, std::string_view column = returns_column): 返回 column 的总复合收益，NaN 收益率视为零；空帧返回 NaN。

double fincore::cumulative_return(const dataframe &returns, std::initializer_list<std::string_view> legacy_column)

返回旧式单一名称列形式的 cumulative_return。

初始化列表最多只能包含一个名称；多于一个会抛出 input_error。

double fincore::cumulative_return(const dataframe &returns, double starting_value, std::string_view column = returns_column)

返回按 starting_value 缩放的 column 最终累计值。

当 starting_value 非零时结果为 starting_value * wealth，为零时结果为 wealth - 1。NaN 收益率视为零。

dataframe fincore::cumulative_returns(const dataframe &returns, std::string_view column = returns_column): 返回 column 在每个时间戳上的累计增长 wealth - 1，NaN 收益率视为零。

dataframe fincore::cumulative_returns(const dataframe &returns, std::initializer_list<std::string_view> legacy_column)

返回旧式单一名称列形式的 cumulative_returns。

初始化列表最多只能包含一个名称；多于一个会抛出 input_error。

dataframe fincore::cumulative_returns(const dataframe &returns, double starting_value, std::string_view column = returns_column)

返回按 starting_value 缩放的 column 累计增长。

当 starting_value 非零时每个输出值为 starting_value * wealth，为零时为 wealth - 1。NaN 收益率视为零。

dataframe fincore::cumulative_returns_less_costs(const dataframe &returns, std::string_view returns_column_name = returns_column)

返回 returns_column_name 的 cumulative_returns。

此重载不进行成本扣减。

dataframe fincore::cumulative_returns_less_costs(const dataframe &returns, const dataframe &costs, std::string_view returns_column_name = returns_column, std::string_view costs_column_name = returns_column)

返回扣除逐日成本后的累计增长。

returns 和 costs 必须具有相同的索引；每个收益率先减去同一行的成本，再用 cumulative_returns 复合。索引不匹配、列格式错误或选择器无效时抛出 input_error。

daily_consecutive_statistics fincore::daily_consecutive_stats(const dataframe &returns, std::string_view column = returns_column)

返回 column 的日度连续段统计。

NaN 值会中断连续段。输入为空时所有字段均为 NaN；不存在该符号的连续段时，盈/亏字段同样为 NaN，而连续段长度为 0。

double fincore::deflated_sharpe_ratio(const dataframe &returns, double risk_free = 0.0, int num_trials = 1, std::string_view column = returns_column)

返回 num_trials 次试验下的紧缩夏普比率概率。

丢弃 NaN 观测，每期夏普比率使用一个自由度的偏差。按试验数调整的基准使用样本偏度和峰度，以及 num_trials 次独立试验的期望最大值（小于一的值按一处理）。结果为观测值超出该基准部分的标准正态 CDF；当估计的夏普方差非正时，结果为精确的 0 或 1。可用值少于三个时返回 NaN。column 中嵌入 NUL 会抛出 input_error。

std::pair<double, double> fincore::down_alpha_beta(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

仅使用基准收益率非正（包括零）的日期返回 {alpha, beta}。

其余情况遵循 alpha_beta。

double fincore::down_capture(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回基准收益率严格为负的日期上的捕获比率。

在选定的公共有限对上遵循 capture。没有符合条件的日期或比率非有限时返回 NaN。

double fincore::down_capture_return(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回基准收益率严格为负的日期上 returns 的年化几何收益。

除选择基准收益率为负的日期外，其余与 up_capture_return 一致，包括其 NaN 和 -1 结果以及嵌入 NUL 时抛出的 input_error。

double fincore::downside_risk(const dataframe &returns, double required_return = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回相对 required_return 的年化下行偏差。

结果为所有有限观测的平方短缺均值再开方，并乘以 sqrt(annualization)。没有有限值，或 annualization 为负或非有限时返回 NaN。

dataframe fincore::drawdown_series(const dataframe &returns, std::string_view column = returns_column)

返回 column 的水下序列：相对其滚动峰值的财富，表示为非正比例。

NaN 收益率视为零，结果存储在 returns_column 下。空帧返回空帧。

dataframe fincore::ensure_datetime_index_series(const dataframe &frame, frequency period = frequency::daily)

校验并规范化帧的 UTC 纳秒索引。

存在的索引必须严格递增、无重复且不含 NaT 哨兵；返回的帧为拥有数据的副本。没有索引但恰好有一个 double 列的帧会获得源由 pd.date_range("1970-01-01", periods=n, freq=...) 构建的合成 UTC 索引：daily -> 1970-01-01、1970-01-02、...；weekly -> 从 1970-01-04 起的周日；monthly -> 从 1970-01-31 起的月末；quarterly -> 从 1970-03-31 起的季末；yearly -> 1970-12-31、1971-12-31、...。空帧原样返回。具有多列但没有索引，或列与索引长度不一致的帧会抛出 input_error；源仅对无索引的 Series 静默重建索引。

dataframe fincore::ensure_datetime_index_series(std::span<const double> values, frequency period = frequency::daily, std::string_view column = returns_column)

返回带由 values 构建的合成索引的单列帧。

空范围返回空帧。值被原样复制（保留 NaN）。

double fincore::excess_sharpe(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回平均主动收益除以其样本偏差。

两个序列按公共时间戳对齐且只保留有限对。结果不进行年化。剩余对少于两个或跟踪误差低于 1e-15 时返回 NaN。

std::vector<named_returns> fincore::extract_interesting_date_ranges(const dataframe &returns, std::string_view column = returns_column)

返回与 returns 重叠的锁定的历史危机窗口。

每个窗口包含两个 UTC 端点，仅当其中至少有一个观测时才产生一个条目。条目遵循锁定窗口顺序，而观测保持输入顺序和输入列名；每个返回的帧拥有其数据。列中嵌入 NUL、为空或无效时抛出 input_error。

std::vector<double> fincore::flatten(const dataframe &frame)

返回展平为行主序向量的帧。

列按源插入顺序访问，行按索引顺序访问，因此结果为 row0[col0..colN]、row1[col0..colN]、...。仅支持 double 列；每列长度必须等于帧索引长度。存在的 NaN 单元格会保留（原生帧没有缺失单元格状态）；列长度大于索引长度（无索引数据）的帧会抛出 input_error。原始矩阵请使用 matrix 重载，它返回存储的行主序缓冲区。

std::vector<double> fincore::flatten(const matrix &values): 返回矩阵所存储行主序缓冲区的副本。

dataframe fincore::forecast_cone_bootstrap(const dataframe &in_sample_returns, std::size_t num_days, std::span<const double> cone_std = default_cone_standard_deviations, double starting_value = 1.0, std::size_t num_samples = 1000U, std::uint32_t random_seed = 0U, std::string_view column = returns_column)

通过组合 simulate_paths 和 summarize_paths 返回预测锥。

模拟路径使用 starting_value、num_samples、random_seed 和 column；锥使用 cone_std 和 starting_value。错误为两个组合函数各自的错误。

dataframe fincore::forecast_cone_bootstrap(const dataframe &in_sample_returns, std::size_t num_days, double cone_std, double starting_value = 1.0, std::size_t num_samples = 1000U, std::uint32_t random_seed = 0U, std::string_view column = returns_column): 返回针对单个锥宽度的 forecast_cone_bootstrap。

std::string_view fincore::frequency_name(frequency period): 返回原生频率的规范源名称。

std::vector<drawdown_table_row> fincore::gen_drawdown_table(const dataframe &returns, std::size_t top = 10, std::string_view column = returns_column)

返回最深回撤窗口的顶部表格行。

排名与 get_top_drawdowns 一致。未使用的行保持 NaN 的 net_drawdown_percent 和 nullopt 时间戳。

std::vector<double> fincore::get_all_drawdowns(const dataframe &returns, std::string_view column = returns_column)

按时间顺序返回每个不同水下期的深度。

值为负比例；尚未恢复的水下期按其当前深度计入。

std::vector<drawdown_period> fincore::get_all_drawdowns_detailed(const dataframe &returns, std::string_view column = returns_column): 按时间顺序返回每个不同水下期及其起点、谷底、恢复和持续时间。

std::vector<drawdown_window> fincore::get_top_drawdowns(const dataframe &returns, std::size_t top = 10, std::string_view column = returns_column)

返回最多 top 个最深且互不重叠的回撤窗口，按深度排序。

并列时保留较早的窗口。输入为空或 top == 0 时返回空向量。

gpd_risk_estimates_result fincore::gpd_risk_estimates(const dataframe &returns, double var_p = 0.01, std::string_view column = returns_column)

返回损失的 GPD 尾部估计（负收益取相反数），以最大似然拟合，阈值搜索从 0.2 开始并逐次减半。

var_p 为尾部概率。收益率少于三个、未找到正形状的拟合，或搜索不收敛时，所有字段为零。

double fincore::henriksson_merton_timing(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 Henriksson-Merton 择时系数。

拟合 excess_return = a + b * excess_market + c * down（其中当超额市场收益为负时 down 为一，否则为零），并返回 c。只使用有限对，两个序列都减去 risk_free。可用对少于十个、risk_free 非有限、设计矩阵奇异或系数非有限时返回 NaN。

double fincore::historical_value_at_risk(const dataframe &returns, double cutoff = 0.05, std::string_view column = returns_column)

使用线性插值返回 column 的经验 cutoff 分位数。

不进行年化。除非每个值都有限且 cutoff 位于 [0, 1]，否则返回 NaN。

double fincore::hurst_exponent(const dataframe &returns, std::string_view column = returns_column)

返回 column 的重标极差 Hurst 指数，忽略 NaN 值。

估计值限制在 [0, 1]。可用值少于八个，或极差/偏差退化时返回 NaN。

double fincore::information_ratio(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 相对 benchmark 的年化信息比率。

只使用有限的公共对。年化平均主动收益除以按 sqrt(annualization) 缩放的主动样本偏差。剩余对少于两个、annualization 非有限或非正，或年化跟踪误差为零或非有限时返回 NaN。

dataframe fincore::information_ratio_by_year(const dataframe &returns, const dataframe &benchmark, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个 UTC 日历年的信息比率，存储在列 "information_ratio" 中。

在分桶之前，两个帧先按公共时间戳对齐；每年使用 information_ratio 与 annualization_factor(period, annualization)；非有限对在其所属年份内被丢弃。年份以 1 月 1 日为索引并按升序排序；对齐结果为空时返回空的有类型帧。未知频率且未显式指定 annualization 时抛出 input_error。

double fincore::kappa_three_ratio(const dataframe &returns, double mar = 0.0, std::string_view column = returns_column)

返回 Kappa 3 比率：超过 mar 的平均超额除以三阶下偏矩的立方根。

下偏矩对非 NaN 值求 max(0, mar - value)^3 的平均。可用值少于两个、mar 为 NaN，或均值未超过 mar 而矩低于 1e-30 时返回 NaN；同样的退化情形下若均值超过 mar 则返回正无穷。column 中嵌入 NUL 会抛出 input_error。

double fincore::kurtosis(const dataframe &returns, std::string_view column = returns_column)

返回 column 的有偏超额峰度（四阶矩除以方差平方再减 3），忽略 NaN 值。

可用值少于四个或方差为零时返回 NaN。

double fincore::loss_rate(const dataframe &returns, std::string_view column = returns_column)

返回 column 中严格为负的可用观测占比。

忽略 NaN 值；输入为空时返回 NaN。

double fincore::m_squared(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 returns 相对 benchmark 的 M 平方度量。

两个序列按公共时间戳对齐。超额年化收益按基准波动率与组合波动率之比重新缩放，并加回 risk_free。对齐后剩余收益少于两个、组合波动率为零、负或 NaN，或基准波动率为 NaN 时返回 NaN。任一列名中嵌入 NUL 会抛出 input_error。

double fincore::mar_ratio(const dataframe &returns, double annualization = daily_annualization, std::string_view column = returns_column)

返回年化算术平均收益除以绝对最大回撤。

均值使用非 NaN 值，并按 annualization 缩放而非复合。原始值少于两个、最大回撤非负或为 NaN，或商非有限时返回 NaN。column 中嵌入 NUL 会抛出 input_error。

double fincore::market_timing_return(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 Treynor-Mazuy 系数乘以超额市场收益平方的均值。

使用与 treynor_mazuy_timing 相同的二次拟合、有限对过滤和最少十个观测的要求。在相同条件下，或所得乘积非有限时返回 NaN。

double fincore::max_consecutive_down_days(const dataframe &returns, std::string_view column = returns_column)

返回 column 中最长的严格为负观测连续段。

不存在时返回 0，输入为空时返回 NaN。

std::optional<timestamp> fincore::max_consecutive_down_end_date(const dataframe &returns, std::string_view column = returns_column)

返回最长负连续段的最后一个时间戳。

并列时保留最早的连续段；不存在负连续段时返回 nullopt。

double fincore::max_consecutive_down_months(const dataframe &returns, std::string_view column = returns_column)

返回复合收益为负的最长连续日历月数。

跳过没有观测的月份。不存在时返回 0，输入为空时返回 NaN。

std::optional<timestamp> fincore::max_consecutive_down_start_date(const dataframe &returns, std::string_view column = returns_column)

返回最长负连续段的第一个时间戳。

并列时保留最早的连续段；不存在负连续段时返回 nullopt。

double fincore::max_consecutive_down_weeks(const dataframe &returns, std::string_view column = returns_column)

返回复合收益为负的最长连续日历周数（以周日结束）。

跳过没有观测的周。不存在时返回 0，输入为空时返回 NaN。

double fincore::max_consecutive_gain(const dataframe &returns, std::string_view column = returns_column)

返回连续正收益段上的最大收益率之和。

不存在正连续段时返回 NaN。

double fincore::max_consecutive_loss(const dataframe &returns, std::string_view column = returns_column)

返回连续负收益段上最负的收益率之和。

不存在负连续段时返回 NaN。

double fincore::max_consecutive_up_days(const dataframe &returns, std::string_view column = returns_column)

返回 column 中最长的严格为正观测连续段。

不存在时返回 0，输入为空时返回 NaN。

std::optional<timestamp> fincore::max_consecutive_up_end_date(const dataframe &returns, std::string_view column = returns_column)

返回最长正连续段的最后一个时间戳。

并列时保留最早的连续段；不存在正连续段时返回 nullopt。

double fincore::max_consecutive_up_months(const dataframe &returns, std::string_view column = returns_column)

返回复合收益为正的最长连续日历月数。

跳过没有观测的月份。不存在时返回 0，输入为空时返回 NaN。

std::optional<timestamp> fincore::max_consecutive_up_start_date(const dataframe &returns, std::string_view column = returns_column)

返回最长正连续段的第一个时间戳。

并列时保留最早的连续段；不存在正连续段时返回 nullopt。

double fincore::max_consecutive_up_weeks(const dataframe &returns, std::string_view column = returns_column)

返回复合收益为正的最长连续日历周数（以周日结束）。

跳过没有观测的周。不存在时返回 0，输入为空时返回 NaN。

double fincore::max_drawdown(const dataframe &returns, std::string_view column = returns_column)

返回 column 的最深回撤，以负比例表示。

序列从未下跌时返回 0，空帧返回 NaN。

dataframe fincore::max_drawdown_by_year(const dataframe &returns, std::string_view column = returns_column)

返回每个 UTC 日历年的最大回撤，存储在列 "max_drawdown" 中。

每年使用 max_drawdown，因此从未下跌的年份报告 0。年份以 1 月 1 日为索引并按升序排序。空帧返回空的有类型帧。

double fincore::max_drawdown_days(const dataframe &returns, std::string_view column = returns_column)

返回最深回撤从峰值到谷底的 UTC 经过天数。

序列从未下跌时返回 0，空帧返回 NaN。时间戳未对齐到午夜时，该值为小数。

double fincore::max_drawdown_months(const dataframe &returns, std::string_view column = returns_column): 返回 max_drawdown_days 除以 30（近似月数）。

std::pair<std::optional<timestamp>, std::optional<timestamp>> fincore::max_drawdown_period(const dataframe &returns, std::string_view column = returns_column)

返回最大回撤的 {peak, valley} 时间戳。

序列从未下跌时返回 {first timestamp, first timestamp}，空帧返回 {nullopt, nullopt}。

double fincore::max_drawdown_recovery_days(const dataframe &returns, std::string_view column = returns_column)

返回最深回撤从谷底到恢复的 UTC 经过天数。

该事件尚未恢复或帧为空时返回 NaN，序列从未下跌时返回 0。

double fincore::max_drawdown_recovery_months(const dataframe &returns, std::string_view column = returns_column): 返回 max_drawdown_recovery_days 除以 30（近似月数）。

double fincore::max_drawdown_recovery_weeks(const dataframe &returns, std::string_view column = returns_column): 返回 max_drawdown_recovery_days 除以 7（小数周数）。

std::optional<drawdown_window> fincore::max_drawdown_underwater(const dataframe &underwater, std::string_view column = "drawdown")

从预先计算的水下序列返回峰值/谷底/恢复窗口。

序列从未低于零时，源辅助函数返回 (NaT, NaT, NaT)；原生形式在该情形以及空数据/非有限数据时返回 nullopt。

double fincore::max_drawdown_weeks(const dataframe &returns, std::string_view column = returns_column): 返回 max_drawdown_days 除以 7（小数周数）。

std::optional<drawdown_window> fincore::max_drawdown_window(const dataframe &returns, std::string_view column = returns_column)

返回最深事件的峰值、谷底及可选的恢复。

序列从未下跌或输入为空时返回 nullopt。

double fincore::max_single_day_gain(const dataframe &returns, std::string_view column = returns_column): 返回 column 中最大的非 NaN 观测；输入为空时返回 NaN。

std::optional<timestamp> fincore::max_single_day_gain_date(const dataframe &returns, std::string_view column = returns_column)

返回 column 中最大非 NaN 观测的时间戳。

并列时保留最早出现者；不存在值时返回 nullopt。

double fincore::max_single_day_loss(const dataframe &returns, std::string_view column = returns_column): 返回 column 中最小的非 NaN 观测；输入为空时返回 NaN。

std::optional<timestamp> fincore::max_single_day_loss_date(const dataframe &returns, std::string_view column = returns_column)

返回 column 中最小非 NaN 观测的时间戳。

并列时保留最早出现者；不存在值时返回 nullopt。

dataframe fincore::normalize(const dataframe &values, double starting_value = 1.0, std::string_view column = returns_column)

返回重新缩放后的 values，使 column 的第一个值等于 starting_value。

第一个值为零会使所有输出为 NaN；其他 NaN 值会传播。结果保持输入时间戳和列名。

dataframe fincore::normalize_attribution_positions(const dataframe &positions, bool positions_in_dollars = true, std::string_view cash_column_name = cash_column)

在请求时返回转换为逐时间戳权重的 positions。

除 cash_column_name 外的每个 double 列都会保留；非 double 列被忽略。在 positions_in_dollars 下，每个值除以该行的总敞口（非 NaN 头寸绝对值之和），因此 NaN 头寸仍为 NaN，全零行得到 NaN 权重。否则值被复制。输入索引和顺序保持不变。时间戳重复、cash 列非 double、资产名称为空，或没有资产列时抛出 input_error。

double fincore::omega_ratio(const dataframe &returns, double risk_free = 0.0, double required_return = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回 column 在所需阈值之上的 Omega 比率。

丢弃非有限值。每期阈值为 risk_free 加上转换为每期利率的 required_return（当 annualization 不为一时）。阈值之上的收益与阈值之下的损失分别求和，比率为收益之和除以损失之和。可用值少于两个、参数非有限、annualization 非正、required return 小于等于 -1 且 annualization 不为 1，或收益/损失之和非正或非有限时返回 NaN。

frequency fincore::pandas_frequency(std::string_view period)

将一个规范源频率字符串映射到原生频率枚举。

源约定（fincore.metrics.frequencies.pandas_frequency）：只接受五个规范名称；其他任何值都会抛出 ValueError，消息为 "Period cannot be ...: unknown frequency"。原生函数以相同的判定条件和消息文本抛出 input_error。

std::string_view fincore::pandas_frequency_alias(frequency period)

返回 period 对应的 pandas 重采样别名（D, W, ME, QE, YE）。

这是锁定版本 pandas（>= 2.2）环境中的别名，作为源映射的溯源信息暴露；原生代码使用枚举而非别名字符串。

perf_attribution_result fincore::perf_attrib(const dataframe &returns, const dataframe &positions, const dataframe &factor_returns, const dataframe &factor_loadings, bool positions_in_dollars = true, std::string_view returns_column_name = returns_column, std::string_view cash_column_name = cash_column, std::string_view symbol_column_name = attribution_symbol_column)

从原始头寸返回风险暴露与归因。

在 positions_in_dollars 下，positions 先经 normalize_attribution_positions 处理；否则被视为权重并原样传递。计算和错误分别来自所用的 normalize_attribution_positions，随后是 perf_attrib_core。

perf_attribution_result fincore::perf_attrib_core(const dataframe &returns, const dataframe &normalized_positions, const dataframe &factor_returns, const dataframe &factor_loadings, std::string_view returns_column_name = returns_column, std::string_view cash_column_name = cash_column, std::string_view symbol_column_name = attribution_symbol_column)

返回规范化头寸的风险暴露与收益归因。

returns、normalized_positions 和 factor_returns 必须具有相同且无重复的索引。因子为 factor_returns 的所有 double 列，且至少需要一个；其名称不得与 symbol 列及保留的归因名称相同。归因帧按因子收益的列顺序为每个因子保留一个贡献列，随后依次为 "total_returns"（输入收益）、"common_returns"（有限贡献之和）、"specific_returns"（total - common）、"tilt_returns"（每个因子的平均暴露乘以该日的因子收益）和 "timing_returns"（common - tilt）。两个返回的帧都拥有其数据。

索引不匹配或重复、symbol 列缺失或非字符串、因子列缺失或非 double、因子名称为保留名称、因子载荷键重复，或因子载荷键未覆盖所有头寸时，抛出 input_error。

std::map<std::string, double> fincore::perf_stats(const dataframe &returns, frequency period = frequency::daily, std::string_view returns_column_name = returns_column)

返回以显示名称为键的 returns 标准绩效统计。

该映射始终包含十三个键："Annual return"、"Cumulativereturns"、"Annual volatility"、"Sharpe ratio"、"Calmar ratio"、"Stability"、"Max drawdown"、"Omega ratio"、"Sortino ratio"、"Skew"、"Kurtosis"、"Tailratio" 和 "Daily value at risk"。对期间敏感的指标使用 annualization_factor(period)，而 Omega 比率始终按日年化。column 必须是匹配帧索引的 double 列，否则抛出 input_error。

std::map<std::string, double> fincore::perf_stats(const dataframe &returns, const dataframe &benchmark, frequency period = frequency::daily, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回一元统计以及 "Alpha" 和 "Beta"。

十三个一元键按一元重载的方式计算。alpha 和 beta 来自公共时间戳上的 alpha_beta，无论 period 为何都使用零无风险利率和 daily_annualization。两个选择器都必须是匹配各自帧索引的 double 列，否则抛出 input_error。

std::vector<bootstrap_metric_stats> fincore::perf_stats_bootstrap(const dataframe &returns, std::size_t n_samples = 1000, std::uint64_t seed = 0, std::string_view column = returns_column)

返回十三个 perf_stats 指标的 bootstrap 分布。

n_samples 次抽样中的每一次都使用以 seed 播种的 std::mt19937_64，从 column 中有放回地重抽样 returns.size() 个观测；NaN 值按原样抽取。对期间敏感的指标使用 daily_annualization。结果始终按固定的 bootstrap 指标顺序包含十三个条目；输入为空时样本为空、汇总为 NaN。column 中嵌入 NUL、为空或无效时抛出 input_error。

std::vector<bootstrap_metric_stats> fincore::perf_stats_bootstrap(const dataframe &returns, std::span<const std::vector<std::size_t>> draw_indices, std::string_view column = returns_column)

返回由调用方提供的抽取索引得到的 bootstrap 分布。

每次抽样包含指向原始输入列的位置行索引。各行长度必须与输入总体相同。空输入只接受空的抽取矩阵，并保持带种子重载的空结果。索引越界或 column 中嵌入 NUL 时抛出 input_error。

double fincore::r_cubed(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 safe_correlation 的立方。

相关系数本身为 NaN 时返回 NaN。列名中嵌入 NUL 字符会抛出 input_error。

double fincore::r_cubed_turtle(const dataframe &returns, double annualization = daily_annualization, std::string_view column = returns_column)

返回 RAR/Turtle 比率：NAV 对时间的年化斜率除以年度最大回撤幅度的均值。

当该平均回撤实际为零且年化斜率为正时返回无穷；无法计算时返回 NaN。

double fincore::relative_win_rate(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column): 返回策略收益严格大于基准收益的公共有限日期占比。

double fincore::residual_risk(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回超额策略收益对超额基准收益做 CAPM 回归后残差的年化样本标准差。

risk_free 或 beta 非有限时返回 NaN。

dataframe fincore::roll_alpha(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个窗口末端的滚动年化 Jensen alpha。

窗口由两个帧的公共时间戳构建，并连同 risk_free 和 annualization_factor(period, annualization) 交给 alpha。每个完整窗口产生一行，以对齐后的窗口末端为索引；对齐观测少于 window 个（包括没有公共时间戳）时返回空的有类型帧。window 为零、未知频率且未显式指定 annualization，或列无效时抛出 input_error。

dataframe fincore::roll_alpha_beta(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回滚动 alpha 和 beta，存储在列 "alpha" 和 "beta" 中。

窗口由公共时间戳构建，并连同 risk_free 和 annualization_factor(period, annualization) 交给 alpha_beta；alpha_beta 无法拟合的窗口在两列中都保留 NaN。每个完整窗口产生一行，以对齐后的窗口末端为索引；对齐观测少于 window 个时返回空的二列帧。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::roll_annual_volatility(const dataframe &returns, std::size_t window, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个窗口末端的年化滚动波动率。

与 rolling_volatility 不同，只有完整窗口才有行，且每个窗口内的 NaN 观测由 annual_volatility 丢弃，因此只要仍有至少两个有限观测，被污染的窗口仍会被计算。观测少于 window 个时返回空的有类型帧。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::roll_beta(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个窗口末端的滚动 OLS beta。

beta 不进行年化，因此忽略 period 和 annualization。窗口由公共时间戳构建，并连同 risk_free 交给 beta。每个完整窗口产生一行，以对齐后的窗口末端为索引；对齐观测少于 window 个时返回空的有类型帧。window 为零或列无效时抛出 input_error。

dataframe fincore::roll_down_capture(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, frequency period = frequency::daily, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个窗口末端的滚动下行捕获比率。

公共时间戳的每个完整窗口都连同 annualization_factor(period) 因子交给 down_capture，因此 period 是唯一的年化控制项。对齐观测少于 window 个时返回空的有类型帧。window 为零或频率未知时抛出 input_error。

dataframe fincore::roll_max_drawdown(const dataframe &returns, std::size_t window = 252U, std::string_view column = returns_column)

返回每个窗口末端的最大回撤。

每个窗口的财富都从 1 重新开始，NaN 观测从不更新滚动峰值或结果，因此未见任何有限回撤的被污染窗口报告 0.0。每个完整窗口产生一行，以其最后一个时间戳为索引；观测少于 window 个时返回空的有类型帧。window 为零时抛出 input_error。

dataframe fincore::roll_sharpe_ratio(const dataframe &returns, std::size_t window = 252U, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个窗口末端的滚动夏普比率。

由 window 个观测组成的每个完整窗口产生一行，以其最后一个时间戳为索引；观测少于 window 个时返回空的有类型帧。因子为 annualization_factor(period, annualization)，NaN 值由 sharpe_ratio 丢弃。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::roll_sortino_ratio(const dataframe &returns, std::size_t window, double required_return = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个窗口末端的滚动年化索提诺比率。

每个完整窗口都连同 required_return 和 annualization_factor(period, annualization) 交给 sortino_ratio；NaN 值由该标量指标丢弃。观测少于 window 个时返回空的有类型帧。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::roll_up_capture(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, frequency period = frequency::daily, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个窗口末端的滚动上行捕获比率。

公共时间戳的每个完整窗口都连同 annualization_factor(period) 因子交给 up_capture，因此 period 是唯一的年化控制项。对齐观测少于 window 个时返回空的有类型帧。window 为零或频率未知时抛出 input_error。

dataframe fincore::roll_up_down_capture(const dataframe &returns, const dataframe &benchmark, std::size_t window = 252U, frequency period = frequency::daily, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回每个窗口末端的滚动上下行捕获比率。

公共时间戳的每个完整窗口都连同 annualization_factor(period) 因子交给 up_down_capture，因此 period 是唯一的年化控制项。对齐观测少于 window 个时返回空的有类型帧。window 为零或频率未知时抛出 input_error。

dataframe fincore::rolling_beta(const dataframe &returns, const dataframe &factor_returns, std::size_t rolling_window = 126U, std::string_view returns_column_name = returns_column, std::string_view factor_column_name = benchmark_column)

返回 returns 相对单个因子列的滚动 beta。

结果保留对齐后的公共索引；首个完整窗口之前的行均为 NaN，任何含非有限值或因子方差为零的窗口也为 NaN。beta 为协方差除以因子方差，不做无风险调整。rolling_window 为零或列无效时抛出 input_error。

dataframe fincore::rolling_beta(const dataframe &returns, const dataframe &factor_returns, std::span<const std::string_view> factor_column_names, std::size_t rolling_window = 126U, std::string_view returns_column_name = returns_column)

为每个因子返回一个滚动 beta 列，列名取自因子列。

每个因子都单独与 returns 对齐，并遵循与单因子重载相同的预热和无效窗口规则。因子名称必须非空、唯一且作为 double 列存在；否则抛出 input_error，rolling_window 为零时亦然。

dataframe fincore::rolling_regression(const dataframe &returns, const dataframe &benchmark, std::size_t rolling_window = 126U, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回滚动 OLS alpha 和 beta，存储在列 "alpha" 和 "beta" 中。

窗口由公共时间戳构建；beta 为协方差除以因子方差，alpha 为平均收益减去 beta 乘以平均基准收益，不做无风险调整。行以对齐后的窗口末端为索引，含非有限值、因子方差为零或系数非有限的窗口会被省略，因此索引可能稀疏。rolling_window 为零或列无效时抛出 input_error。

dataframe fincore::rolling_sharpe(const dataframe &returns, std::size_t window, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回与输入索引对齐的滚动夏普比率。

索引和预热形状与 rolling_volatility 一致，无风险利率为零，含 NaN 的窗口返回 NaN。因子为 annualization_factor(period, annualization)。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::rolling_volatility(const dataframe &returns, std::size_t window, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回与输入索引对齐的年化滚动波动率。

首个完整窗口之前的行均为 NaN，含 NaN 的窗口返回 NaN。每个窗口使用 annual_volatility 与 annualization_factor(period, annualization)。观测少于 window 个时所有值均为 NaN。window 为零，或未知频率且未显式指定 annualization 时抛出 input_error。

double fincore::safe_correlation(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回两个序列在公共有限时间戳上的 Pearson 相关系数。

对少于两个，或任一序列标准差接近零时返回 NaN。

double fincore::second_max_drawdown(const dataframe &returns, std::string_view column = returns_column)

返回第二深回撤，以负比例表示。

事件少于两个时返回 NaN。

double fincore::second_max_drawdown_days(const dataframe &returns, std::string_view column = returns_column)

返回从首个水下观测到第二深回撤谷底的 UTC 经过天数。

事件少于两个时返回 NaN。

double fincore::second_max_drawdown_recovery_days(const dataframe &returns, std::string_view column = returns_column)

返回从第二深回撤的谷底到恢复的 UTC 经过天数。

该事件尚未恢复或事件少于两个时返回 NaN。

double fincore::serial_correlation(const dataframe &returns, std::ptrdiff_t lag = 1, std::string_view column = returns_column)

返回 column 在滞后 lag 个观测处的 Pearson 自相关系数。

滞后之前先移除 NaN 值。lag 小于一或剩余值少于 lag + 2 时返回 NaN。

double fincore::sharpe_ratio(const dataframe &returns, double risk_free = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回 column 的年化夏普比率。

丢弃 NaN 观测；value - risk_free 的均值除以样本标准差（一个自由度）并乘以 sqrt(annualization)。可用观测少于两个时返回 NaN；零偏差不特殊处理，因此商遵循 IEEE 规则。

dataframe fincore::sharpe_ratio_by_year(const dataframe &returns, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回每个 UTC 日历年的夏普比率，存储在列 "sharpe_ratio" 中。

每年使用 sharpe_ratio 与 risk_free 以及 annualization_factor(period, annualization)。年份以 1 月 1 日为索引并按升序排序。空帧返回空的有类型帧；未知频率且未显式指定 annualization 时抛出 input_error。

dataframe fincore::simple_returns(const dataframe &prices, std::string_view price_column)

返回 price_column 的逐期简单收益率，丢弃第一个观测。

结果存储在 returns_column 下，并保留每对中较晚价格的时间戳。价格少于两个时返回空帧。

matrix fincore::simulate_paths(std::span<const double> in_sample_returns, std::size_t num_days, double starting_value = 1.0, std::size_t num_samples = 1000U, std::uint32_t random_seed = 0U)

从样本内收益率中抽取 num_samples x num_days 个 bootstrap 收益率。

RNG：与 NumPy 旧式 RandomState 兼容的 MT19937，使用显式的 32 位 random_seed（默认 0；源的默认值 None 未被复现）。整数抽取使用 NumPy 的掩码拒绝法（rk_interval），因此在 32 位种子下，播种序列与 np.random.RandomState(seed).randint(0, n, size=...) 完全一致。这并不构成对数组播种或源的非确定性 None 默认值的声明。

starting_value 为与源签名保持一致而接受但被忽略，与源中相同（_starting_value）。样本内 NaN 值按原样抽取；无穷值会抛出 input_error。总体为空但抽取形状非空时抛出 input_error（源 rng.randint(0, 0, ...) 会抛出 ValueError），形状无法表示以及总体大于 32 位抽取索引时亦然。

matrix fincore::simulate_paths(const dataframe &in_sample_returns, std::size_t num_days, double starting_value = 1.0, std::size_t num_samples = 1000U, std::uint32_t random_seed = 0U, std::string_view column = returns_column)

返回与范围重载相同的路径，选择一个 double 列。

具有多列的源 DataFrame 会使 NumPy 索引返回三维数组；该形状无法表示，因此调用方需选择要 bootstrap 的列。

double fincore::skewness(const dataframe &returns, std::string_view column = returns_column)

返回 column 的有偏（总体）偏度，忽略 NaN 值。

可用值少于三个或方差为零时返回 NaN。

double fincore::sortino_ratio(const dataframe &returns, double required_return = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回 column 的年化索提诺比率。

丢弃 NaN 观测；超过 required_return 的年化平均超额除以年化下行偏差，其中只有负超额值参与，平方偏差除以可用观测数。原始值少于两个或没有可用观测时返回 NaN；零下行偏差不特殊处理。

double fincore::stability_of_timeseries(const dataframe &returns, std::string_view column = returns_column)

返回累计对数收益对线性时间索引回归的 R 平方。

丢弃非有限值并对每个值应用 log1p；累计和对观测位置回归。可用值少于两个、对数收益非有限（例如小于等于 -1 的收益率）、累计和溢出，或解释方差为零时返回 NaN。

double fincore::sterling_ratio(const dataframe &returns, double risk_free = 0.0, double annualization = daily_annualization, std::string_view column = returns_column)

返回超过 risk_free 的年化收益除以平均回撤幅度。

平均回撤为所有回撤深度的绝对均值；没有回撤或全为零时，回退到负收益的绝对均值（若没有负收益，则使用所有可用值的绝对总体偏差）。年化收益按 annualization 复合。当分母低于 1e-10 且超额年化收益为正时返回正无穷，否则返回 NaN；原始值少于两个或没有可用值时也返回 NaN。column 中嵌入 NUL 会抛出 input_error。

double fincore::stutzer_index(const dataframe &returns, double target_return = 0.0, std::string_view column = returns_column)

返回 column 相对 target_return 的 Stutzer 指数。

忽略 NaN 值；可用值少于两个时返回 NaN。平均超额收益实际为零时返回 0。

dataframe fincore::summarize_paths(const matrix &samples, std::span<const double> cone_std = default_cone_standard_deviations, double starting_value = 1.0)

返回由抽样路径得到的均值/标准差锥。

samples 为行主序，每条路径一行，每天一列。源公式：每条路径的累计财富由 cumprod(1 + returns) 得到，NaN 收益率视为 0；对每个请求的宽度，边界为 mean + std * num_std 和 mean - std * num_std，使用样本标准差（ddof = 1）。starting_value == 0 时结果为 cumprod - 1；否则财富按 starting_value 缩放，与 cum_returns 一致。各列按每个宽度先上界后下界的顺序排列，命名为 cone_（例如 cone_1、cone_-1、cone_1.5）；Python 浮点标签以原生字符串表示，不声明二者完全相同。宽度重复时抛出 input_error。

空 cone_std 范围返回空帧；宽度非有限、starting_value 非有限，或抽样收益为无穷时抛出 input_error。

dataframe fincore::summarize_paths(const matrix &samples, double cone_std, double starting_value = 1.0)

返回单个标准差宽度的锥。

等价于使用单元素宽度列表的范围重载。

double fincore::tail_ratio(const dataframe &returns, std::string_view column = returns_column)

返回 column 中有限值绝对第 95 百分位与绝对第 5 百分位之比。

输入为空或下尾为零时返回 NaN。

double fincore::third_max_drawdown(const dataframe &returns, std::string_view column = returns_column)

返回第三深回撤，以负比例表示。

事件少于三个时返回 NaN。

double fincore::third_max_drawdown_days(const dataframe &returns, std::string_view column = returns_column)

返回从首个水下观测到第三深回撤谷底的 UTC 经过天数。

事件少于三个时返回 NaN。

double fincore::third_max_drawdown_recovery_days(const dataframe &returns, std::string_view column = returns_column)

返回从第三深回撤的谷底到恢复的 UTC 经过天数。

该事件尚未恢复或事件少于三个时返回 NaN。

dataframe fincore::to_dataframe(std::span<const double> values, std::string_view column = returns_column)

返回输入的帧表示，替代源的 to_pandas 路由。

源 to_pandas 路由的原生替代（该路由在台账中保留名称为 fincore.metrics.basic.to_pandas，实现名为 to_dataframe）。不声明与 pandas/NumPy 完全相同。

一维输入变为带位置索引 0..n-1 的单列帧（RangeIndex 的原生对应物）；二维输入变为每个矩阵列一个 double 列，命名为 "_0"、"_1"、...，并使用相同的位置索引。已有的帧以拥有数据的副本返回。维度超过二维的输入无法由 matrix 表示，因此源的 ValueError 分支没有原生对应。

dataframe fincore::to_dataframe(const matrix &values, std::string_view column_prefix = "column"): 返回一个帧，每个矩阵列对应一个 double 列，命名为 "<column_prefix>_0"、"<column_prefix>_1"、...，并使用位置索引。

dataframe fincore::to_dataframe(const dataframe &frame): 返回 frame 的拥有数据的副本。

double fincore::tracking_difference(const dataframe &returns, const dataframe &benchmark, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回在公共有限时间戳上累计策略收益减去累计基准收益。

不存在公共有限对时返回 NaN。

double fincore::tracking_error(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回公共有限时间戳上主动收益（策略减基准）的年化样本标准差。

对少于两个、annualization 非有限/为负，或方差非有限时返回 NaN。

double fincore::trading_value_at_risk(const dataframe &returns, double sigma = 2.0, std::string_view column = returns_column)

返回 column 的 mean - sigma * sample_standard_deviation。

至少需要两个值；NaN 观测会传播到结果。

double fincore::treynor_mazuy_timing(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 Treynor-Mazuy 择时系数。

在公共时间戳上用普通最小二乘拟合 excess_return = a + b * excess_market + c * excess_market^2 并返回 c。只使用有限对，两个序列都减去 risk_free。可用对少于十个、risk_free 非有限、设计矩阵奇异或系数非有限时返回 NaN。

std::pair<double, double> fincore::up_alpha_beta(const dataframe &returns, const dataframe &benchmark, double risk_free = 0.0, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

仅使用基准收益率严格为正的日期返回 {alpha, beta}。

其余情况遵循 alpha_beta。

double fincore::up_capture(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回基准收益率严格为正的日期上的捕获比率。

在选定的公共有限对上遵循 capture。没有符合条件的日期或比率非有限时返回 NaN。

double fincore::up_capture_return(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回基准收益率严格为正的日期上 returns 的年化几何收益。

仅考虑公共时间戳。复合时选中的 NaN 收益率视为零。没有符合条件的日期时返回 NaN，复合财富非正时返回 -1。任一列名中嵌入 NUL 会抛出 input_error。

double fincore::up_down_capture(const dataframe &returns, const dataframe &benchmark, double annualization = daily_annualization, std::string_view returns_column_name = returns_column, std::string_view benchmark_column_name = benchmark_column)

返回 up_capture 除以 down_capture。

两个分量都使用公共有限对。任一分量非有限或下行捕获为零时返回 NaN。

double fincore::var_cov_var_normal(double portfolio_value, double confidence, double mean = 0.0, double standard_deviation = 1.0)

返回正态假设下的方差-协方差风险价值：portfolio_value * (z(confidence) * standard_deviation - mean)。

不进行年化。confidence 超出 [0, 1] 或 standard_deviation 非正时返回 NaN。

double fincore::var_excess_return(const dataframe &returns, double cutoff = 0.05, double risk_free = 0.0, frequency period = frequency::daily, std::optional<double> annualization = std::nullopt, std::string_view column = returns_column)

返回超过 risk_free 的年化收益除以 cutoff 处的绝对历史风险价值。

收益按 annualization_factor(period,annualization) 年化。值少于两个、风险价值为零或 NaN，或年化收益为 NaN 时返回 NaN。

double fincore::win_rate(const dataframe &returns, std::string_view column = returns_column)

返回 column 中严格为正的可用观测占比。

忽略 NaN 值；输入为空时返回 NaN。

constexpr std::string_view fincore::attribution_common_returns_column{"common_returns"}: 归因列，保存有限因子贡献之和。

constexpr std::string_view fincore::attribution_factor_column = {"factor"}: 因子汇总帧中保存因子名称的列。

constexpr std::string_view fincore::attribution_specific_returns_column{"specific_returns"}: 归因列，保存残差收益（total - common）。

constexpr std::string_view fincore::attribution_symbol_column = {"symbol"}: 保存资产符号的默认因子载荷列。

constexpr std::string_view fincore::attribution_tilt_returns_column{"tilt_returns"}: 归因列，保存平均暴露倾斜贡献之和。

constexpr std::string_view fincore::attribution_timing_returns_column{"timing_returns"}: 归因列，保存择时收益（common - tilt）。

constexpr std::string_view fincore::attribution_total_returns_column{"total_returns"}: 归因列，保存总（输入）收益。

constexpr std::string_view fincore::bayesian_cone_percentile_1_column = {"percentile_1"}: 结果列，保存累计路径财富的第 1 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_25_column = {"percentile_25"}: 结果列，保存累计路径财富的第 25 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_50_column = {"percentile_50"}: 结果列，保存累计路径财富的第 50 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_5_column = {"percentile_5"}: 结果列，保存累计路径财富的第 5 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_75_column = {"percentile_75"}: 结果列，保存累计路径财富的第 75 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_95_column = {"percentile_95"}: 结果列，保存累计路径财富的第 95 百分位。

constexpr std::string_view fincore::bayesian_cone_percentile_99_column = {"percentile_99"}: 结果列，保存累计路径财富的第 99 百分位。

constexpr std::string_view fincore::benchmark_column = {"benchmark"}: 保存基准收益的列的默认名称。

constexpr double fincore::daily_annualization = 252.0: 日度观测的默认年化因子（每年 252 个周期）。

constexpr std::string_view fincore::daily_frequency_name = {"daily"}: 日度频率的规范源名称（"daily"）。

constexpr std::array<double, 3U> fincore::default_cone_standard_deviations{1.0, 1.5, 2.0}: 默认锥宽度（1.0、1.5 和 2.0 个标准差）。

constexpr std::string_view fincore::monthly_frequency_name = {"monthly"}: 月度频率的规范源名称（"monthly"）。

constexpr std::string_view fincore::quarterly_frequency_name = {"quarterly"}: 季度频率的规范源名称（"quarterly"）。

constexpr std::string_view fincore::return_aggregation_period_column = {"period"}: aggregate_returns 添加的年内整数 period 列的名称。

constexpr std::string_view fincore::return_aggregation_year_column = {"year"}: aggregate_returns 添加的整数日历年列的名称。

constexpr std::string_view fincore::returns_column = {"returns"}: 保存周期性简单收益率的列的默认名称。

constexpr std::string_view fincore::weekly_frequency_name = {"weekly"}: 周度频率的规范源名称（"weekly"）。

constexpr std::string_view fincore::yearly_frequency_name = {"yearly"}: 年度频率的规范源名称（"yearly"）。