风险

VaR/ES 诊断、GARCH/EGARCH 估计、极值模型、回测、滚动前向验证与风险报告。

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

struct egarch_parameters

EGARCH(1,1) 模型的参数。

公共成员

double omega

对数方差截距。

double alpha

绝对标准化冲击项的幅度系数。

double gamma

标准化冲击项的非对称（杠杆）系数。

double beta

上一期对数方差的持续项系数。

struct egarch_result

EGARCH(1,1) 拟合的结果。

公共成员

egarch_parameters params

拟合得到的参数。

std::vector<double> conditional_variances

以收益率平方单位的方差路径，每个清洗后的观测一个值。

std::vector<double> residuals

与 conditional_variances 对齐的标准化残差。

double log_likelihood

高斯对数似然，不含第一个观测。

bool converged

优化器以及参数、方差与平稳性检查是否通过。

struct extreme_risk_result

由 EVT 模型同时给出的 VaR 与期望损失估计。

公共成员

double var

按尾部符号表示的 VaR 估计。

double cvar

按尾部符号表示的条件尾部期望。

double tail_index

拟合的 GPD 或 GEV 形状参数。

double threshold

GPD 的幅值阈值；GEV 拟合时为 NaN。

std::size_t n_exceedances

GPD 超出次数；GEV 拟合时为零。

double alpha

估计所使用的尾部概率。

std::optional<double> location

GEV 位置参数；GPD 拟合时为空。

std::optional<double> scale

GEV 尺度参数；GPD 拟合时为空。

std::optional<std::size_t> n_blocks

GEV 分块数量；GPD 时为空。

struct garch11_parameters

GARCH(1,1) 模型的参数。

公共成员

double mu

常数均值；拟合使用零均值时为零。

double omega

以收益率方差为单位的方差截距；必须为正。

double alpha

上期平方冲击项的 ARCH 系数。

double beta

上期方差项的 GARCH 系数。

struct garch11_result

GARCH(1,1) 拟合的结果。

公共成员

garch11_parameters params

拟合得到的参数。

std::vector<double> conditional_variances

以收益率平方单位的方差路径，每个清洗后的观测一个值。

std::vector<double> residuals

与 conditional_variances 对齐的标准化残差。

double log_likelihood

高斯对数似然，不含第一个观测。

bool converged

优化器以及参数、方差与平稳性检查是否通过。

struct garch_conditional_estimate

GARCH 家族的 VaR 或 ES 估计及其使用的方差路径。

公共成员

double value

带符号的风险估计；在下尾概率下亏损为负。

std::vector<double> conditional_variances

来自 forecast_volatility 的方差预测路径，单位为收益率平方，每个预测步一个值。

bool converged

产生该路径的拟合收敛标志。

struct garch_forecast_result

forecast_volatility 返回的预测与拟合诊断。

公共成员

std::vector<double> forecasts

以收益率平方为单位的方差预测。

double log_likelihood

拟合模型的对数似然。

bool converged

拟合模型的收敛标志。

struct gev_parameters

对分块极值拟合的推广极值分布。

公共成员

double xi

形状参数。

double mu

以尾部幅值为单位的位置参数。

double sigma

以尾部幅值为单位的尺度参数。

std::size_t n_blocks

使用的完整分块数量。

struct gjr_garch_parameters

GJR-GARCH(1,1) 模型的参数。

公共成员

double omega

以收益率方差为单位的方差截距；必须为正。

double alpha

上期平方冲击项的 ARCH 系数。

double gamma

负向平方冲击项的额外系数。

double beta

上期方差项的 GARCH 系数。

struct gjr_garch_result

GJR-GARCH(1,1) 拟合的结果。

公共成员

gjr_garch_parameters params

拟合得到的参数。

std::vector<double> conditional_variances

以收益率平方单位的方差路径，每个清洗后的观测一个值。

std::vector<double> residuals

与 conditional_variances 对齐的标准化残差。

double log_likelihood

高斯对数似然，不含第一个观测。

bool converged

优化器以及参数、方差与平稳性检查是否通过。

struct gpd_parameters

对阈值超出值拟合的推广 Pareto 分布。

公共成员

double xi

形状参数。

double beta

以幅值为单位的尺度参数。

double threshold

拟合使用的正幅值阈值。

std::size_t n_exceed

使用的严格超出值数量。

struct hill_estimate

Hill 尾部指数估计及其使用的超出值。

公共成员

double xi

Hill 尾部指数估计：超出值对数比的均值。

std::vector<double> tail_observations

以幅值为单位的严格超出值，按输入顺序排列。

struct refit_parameters

一次滚动前向重新拟合记录的参数。

公共成员

timestamp date

该次重新拟合的第一个预测步的时间戳。

double forecast

该重新拟合区段的 VaR 预测。

double mean

估计窗口均值。

double standard_deviation

估计窗口的样本标准差（n - 1）。

std::size_t n_observations

估计窗口长度。

struct risk_backtest_result

VaR 或 ES 回测结果，包含覆盖率统计量与确定性的输入摘要。

公共成员

risk_backtest_method method

被回测的风险度量。

double confidence_level

预测使用的置信水平。

std::size_t observations

配对的非 NaN 观测数量。

std::size_t exceptions

VaR：实现值低于预测；ES：实现值低于尾部阈值。

double expected_exceptions

observations * (1 - confidence_level)。

double exception_rate

exceptions / observations；为空时为 0。

double kupiec_lr

Kupiec 无条件覆盖率统计量；ES 时为 0。

double kupiec_pvalue

卡方（自由度 1）p 值；ES 时为 1。

double christoffersen_lr

独立性统计量；ES 时为 0。

double christoffersen_pvalue

卡方（自由度 1）p 值；ES 时为 1。

std::string inputs_digest

在对齐的时间戳与取值上计算的小写 SHA-256；为原生形式，不是 Python 的 CSV 摘要。

std::map<std::string, double> diagnostics

VaR 额外包含 significance 与 small_sample；ES 额外包含 realized_es、forecast_es、z_score、n_bootstrap 与 seed。

risk_backtest_status status

回测分类。

struct risk_estimate

点风险估计以及来源信息与诊断。

公共成员

risk_forecast_method method = risk_forecast_method::historical

估计方法。

double confidence_level = 0.95

估计使用的置信水平。

std::size_t horizon = 1U

配置的预测期。

std::string sign_convention = {losses_negative_sign_convention}

符号约定标签；losses_negative。

double estimate = 0.0

点估计；在 losses_negative 约定下亏损为负。

timestamp forecast_timestamp = 0

估计所使用的最后一个清洗后观测的时间戳。

bool has_forecast_timestamp = false

forecast_timestamp 是否被填充。

std::string inputs_digest

清洗后的时间戳与取值的小写 SHA-256 十六进制摘要。

bool has_forecast = false

是否填充了向前预测路径；当前的点估计保持为 false。

std::vector<timestamp> forecast_index

可选的预测时间戳；点估计为空。

std::vector<double> forecast_values

可选的预测值；点估计为空。

std::map<std::string, double> diagnostics

与方法相关的数值诊断；键取决于方法。

std::string kernel

后端内核：historical 为空，EVT 为 evt_var/evt_cvar，GARCH 为 conditional_var/conditional_es。

std::string note

GARCH 拟合未收敛时填充的说明；其他情况为空。

risk_estimate_status status = risk_estimate_status::ok

估计状态。

struct risk_forecast_config

点 VaR 或期望损失估计的设置。

公共成员

risk_forecast_method method = risk_forecast_method::historical

估计方法。

double confidence_level = 0.95

置信水平位于 (0, 1)；尾部概率为 1 - confidence_level。

std::size_t horizon = 1U

以观测数计的预测期；由 GARCH 方法使用，必须不小于 1。

garch_model garch_kernel = garch_model::garch

method 为 garch 时使用的 GARCH 家族。

evt_model evt_kernel = evt_model::gpd

method 为 evt 时使用的 EVT 模型。

evt_tail tail = evt_tail::lower

method 为 evt 时使用的 EVT 尾部。

std::optional<double> threshold

以绝对幅值为单位的 GPD 阈值；为空表示自动选择阈值，GEV 会忽略它。

std::optional<std::size_t> block_size

以观测数计的 GEV 分块大小；为空表示自动选择分块大小，GPD 会忽略它。

struct risk_forecast_event

验证报告中的一次样本外预测事件。

公共成员

timestamp date

预测时间戳。

double forecast

该日期的 VaR 预测。

double realized

该日期的实现收益率。

bool exception

实现值是否严格低于预测值。

bool refit

该日期是否为重新拟合区段的起点。

struct risk_model_spec

由滚动前向 VaR 与验证报告共享的带版本模型设定。

公共成员

risk_forecast_target forecast_target = risk_forecast_target::var

预测目标；滚动前向 VaR 仅支持 var。

double confidence_level = 0.99

置信水平；必须是 (0, 1) 内的有限值。

std::size_t horizon = 1U

以观测数计的预测期；必须不小于 1。

std::string distribution = "normal"

分布标签；historical 或 normal。

risk_tail tail = risk_tail::lower

模型使用的尾部；滚动前向 VaR 仅支持 lower。

std::string sign_convention = "losses_negative"

符号约定标签；仅接受 losses_negative。

std::size_t window = 252U

以观测数计的估计窗口长度；至少 2。

std::size_t refit_cadence = 1U

两次重新拟合之间的预测步数；至少 1。

std::string model_version = "1.0"

模型版本标签；仅接受 1.0。

struct risk_refit_event

验证报告中一次重新拟合记录的参数。

公共成员

timestamp date

重新拟合时间戳。

double forecast

该次重新拟合产生的 VaR 预测。

double mean

估计窗口均值。

double standard_deviation

估计窗口的样本标准差。

std::size_t n_observations

估计窗口长度。

struct risk_report_diagnostics

描述验证报告生成方式的诊断字段。

公共成员

std::string method

来自设定的分布标签。

std::string quantile_method

historical 对应 weibull，normal 对应 normal_ppf。

std::size_t window = 0U

估计窗口长度。

std::size_t refit_cadence = 0U

每次重新拟合的预测步数。

std::size_t forecast_count = 0U

预测事件数量。

std::string backtest_status

回测状态名称（pass、fail、inconclusive 或 experimental）。

std::string reason

非 ok 状态的原因；ok 报告为空。

std::size_t n_observations = 0U

输入观测数量；数据不足的报告会填充该字段。

struct risk_validation_report

由滚动前向 VaR 结果投影出的带版本验证报告。

公共函数

risk_validation_report_dict to_dict() const

返回报告字段的独立原生字典表示。

抛出:

fincore_error -- If forecast events, refits, or a present backtest contain non-finite values.

返回:

Dictionary with one field per native report field.

std::string to_json() const

将报告序列化为确定性 JSON 文本。

键按排序顺序输出，使用两空格缩进、与 Python 兼容的浮点文本，并以换行符结尾。拒绝非有限数值与非法 UTF-8。

抛出:

input_error -- If the specification is invalid, a numeric field is not finite, or a text field is not valid UTF-8.

返回:

JSON text ending with a newline.

std::filesystem::path write_json(const std::filesystem::path &path) const

将确定性 JSON 产物写入 path 并返回它。

不创建父目录，与源实现契约一致。

参数:

path -- Destination path; the file is created or truncated.

抛出:

fincore_error -- If report fields violate the serialization contract or the file cannot be opened or written.

返回:

The same path after a successful write.

公共成员

walk_forward_status status = walk_forward_status::unsupported

运行状态。

std::string inputs_digest

来自结果的小写 SHA-256 十六进制摘要。

risk_model_spec specification

从结果回显的模型设定。

std::vector<risk_forecast_event> forecast_events

预测事件；非 ok 报告为空。

std::vector<risk_refit_event> refits

重新拟合参数；非 ok 报告为空。

risk_report_diagnostics diagnostics

报告诊断信息。

bool has_backtest = false

backtest 字段是否包含回测结果。

risk_backtest_result backtest = {}

回测载荷；仅当 has_backtest 为 true 时有意义。

std::string traffic_light_zone

巴塞尔分区；没有回测时为空。

std::optional<std::string> timestamp_index_name

传给构建器的可选索引标签。

std::optional<std::string> timestamp_timezone

可选的索引时区标签；原生构建器保持其为空。

std::string disclosure = {basel_reference_disclosure}

巴塞尔参考披露文本。

int schema_version = risk_validation_report_schema_version

报告模式版本。

struct risk_validation_report_dict

risk_validation_report 的原生独立字典投影。

这是源实现中与 JSON 兼容的 to_dict 映射在 C++ 中的等价物：每个原生报告字段都恰好出现一次。不声称具备 Python 的对象身份或 mapping 子类化。

公共成员

int schema_version = risk_validation_report_schema_version

报告模式版本。

std::string status

状态名称：ok、insufficient_data 或 unsupported。

std::string inputs_digest

来自滚动前向结果的小写 SHA-256 十六进制摘要。

std::optional<std::string> timestamp_index_name

可选的索引标签。

std::optional<std::string> timestamp_timezone

可选的索引时区标签；原生构建器不会填充。

risk_model_spec specification

从结果回显的模型设定。

std::vector<risk_forecast_event> forecast_events

预测事件；非 ok 报告为空。

std::vector<risk_refit_event> refits

重新拟合参数；非 ok 报告为空。

risk_report_diagnostics diagnostics

报告诊断信息。

std::optional<risk_backtest_result> backtest

回测载荷；报告没有回测时为空。

std::string traffic_light_zone

巴塞尔分区；没有回测时为空。

std::string disclosure

巴塞尔参考披露文本。

struct walk_forward_var_result

一次滚动前向 VaR 运行的结果。

公共成员

risk_model_spec spec

产生该结果所使用的模型设定。

std::vector<timestamp> index

样本外时间戳；除非状态为 ok 否则为空。

std::vector<double> forecast

与 index 对齐的 VaR 预测路径；除非状态为 ok 否则为空。

std::vector<double> realized

与 index 对齐的实现收益率；除非状态为 ok 否则为空。

std::vector<timestamp> refit_timestamps

所有重新拟合的时间戳；状态为 ok 时第一个等于 index.front()。

std::vector<refit_parameters> fits

为每次重新拟合记录的参数，与 refit_timestamps 的条目一一对应。

std::string inputs_digest

输入取值以及置信水平、窗口、重新拟合节奏、分布与模型版本的小写 SHA-256 十六进制摘要。

walk_forward_status status

运行状态。

std::string unsupported_reason

unsupported 或 insufficient_data 结果的原因；ok 时为空。

std::size_t n_observations = 0U

输入观测数量。

risk_backtest_result backtest

样本外 VaR 回测；仅当 has_backtest 为 true 时有意义。

bool has_backtest

backtest 是否被填充。

enum class fincore::evt_model

用于尾部估计的极值模型。

取值：

enumerator gpd

超阈值 Peaks-over-threshold 推广 Pareto 模型。

enumerator gev

分块极大值推广极值模型。

enum class fincore::evt_tail

EVT 模型使用的收益率分布尾部。

取值：

enumerator lower

下尾（亏损）。

enumerator upper

上尾（盈利）。

enum class fincore::garch_model

便捷函数所选用的 GARCH 家族模型。

取值：

enumerator garch

零均值的 GARCH(1,1)。

enumerator egarch

EGARCH(1,1)。

enumerator gjr_garch

带非对称冲击项的 GJR-GARCH(1,1)。

enum class fincore::gpd_estimation_method

推广 Pareto 拟合的估计方法。

取值：

enumerator mle

GPD 的极大似然拟合。

enumerator pwm

使用 L 矩的概率加权矩拟合。

enum class fincore::risk_backtest_method

回测所检验的风险度量。

取值：

enumerator var

VaR 突破回测。

enumerator es

期望损失回测。

enum class fincore::risk_backtest_status

VaR 或 ES 回测的分类结果。

取值：

enumerator pass

覆盖率检验不拒绝模型，且样本量充足。

enumerator fail

某项覆盖率检验拒绝模型，且样本量充足。

enumerator inconclusive

配对观测少于三个，或预期突破数少于五；样本过小无法检验。

enumerator experimental

实验性回测；ES 自助法路径使用。

enum class fincore::risk_distribution

滚动前向 VaR 的分布标签。

取值：

enumerator historical

使用 Weibull 分位数的经验分布。

enumerator normal

使用均值与样本标准差的正态分布。

enum class fincore::risk_estimate_status

风险估计的完成状态。

取值：

enumerator ok

至少有两个非 NaN 观测可用，且任何 GARCH 拟合都已收敛。

enumerator insufficient_data

可用的非 NaN 观测少于两个。

enumerator failed

GARCH 拟合未收敛或未通过平稳性检查。

enum class fincore::risk_forecast_method

forecast_var 与 forecast_es 使用的风险估计方法。

取值：

enumerator historical

历史分位数与尾部均值估计。

enumerator evt

使用所配置 EVT 内核的极值估计。

enumerator garch

GARCH 家族的条件估计。

enum class fincore::risk_forecast_target

预测所生成的目标风险度量。

取值：

enumerator var

在险价值。

enumerator es

期望损失。

enumerator pair

跨组件元数据使用的配对目标标签。

enum class fincore::risk_tail

风险模型使用的收益率分布尾部。

取值：

enumerator lower

下尾（亏损）。

enumerator upper

上尾（盈利）。

enum class fincore::walk_forward_status

滚动前向 VaR 运行的完成状态。

取值：

enumerator ok

已生成预测路径与回测。

enumerator insufficient_data

观测数不足一个完整窗口加一。

enumerator unsupported

该设定组合不受支持。

risk_backtest_result fincore::backtest_es(const dataframe &forecast, const dataframe &realized, double confidence_level = 0.975, std::size_t n_bootstrap = 1000U, std::uint64_t seed = 20260817U, std::string_view forecast_column = "forecast", std::string_view realized_column = "realized")

运行实验性的自助法期望损失回测。

实现尾部包含严格低于线性 1 - confidence_level 分位数的实现值；realized ES 为尾部均值，forecast ES 为对齐的预测均值。带种子的尾部自助法给出重抽样尾部均值的样本标准差，用于所报告的 z 值。状态始终为 experimental，Kupiec 与 Christoffersen 字段取中性值（0 与 1）。

参数:

• forecast -- Frame containing ES forecasts.

• realized -- Frame containing realized returns.

• confidence_level -- Confidence level in (0, 1).

• n_bootstrap -- Number of bootstrap resamples of the realized tail.

• seed -- Seed for the native std::mt19937_64 bootstrap.

• forecast_column -- Forecast column name.

• realized_column -- Realized column name.

抛出:

input_error -- If confidence_level is not in (0, 1); a column is missing, not a double column, or contains an embedded NUL; or the frames share no timestamps.

返回:

ES backtest diagnostics, digest and experimental status.

risk_backtest_result fincore::backtest_var(const dataframe &forecast, const dataframe &realized, double confidence_level = 0.99, double significance = 0.05, std::string_view forecast_column = "forecast", std::string_view realized_column = "realized")

在对齐的预测与实现序列上运行 VaR 突破回测。

两个帧按共同时间戳对齐，预测或实现值为 NaN 的配对被丢弃。突破指实现值严格低于预测值。当配对观测少于三个或预期突破数少于五时结果为 inconclusive；否则任一覆盖率 p 值低于 significance 时为 fail，其余为 pass。

参数:

• forecast -- Frame containing VaR forecasts.

• realized -- Frame containing realized returns.

• confidence_level -- Confidence level in (0, 1).

• significance -- P-value threshold for rejecting coverage or independence.

• forecast_column -- Forecast column name.

• realized_column -- Realized column name.

抛出:

input_error -- If confidence_level is not in (0, 1); a column is missing, not a double column, or contains an embedded NUL; or the frames share no timestamps.

返回:

Backtest statistics, diagnostics, digest and status.

std::string fincore::basel_traffic_light(std::size_t exceptions, std::size_t observations, double confidence_level = 0.99)

将突破次数划分到巴塞尔红绿灯分区。

分区依据预期突破概率下二项分布的 95% 分位（绿/黄边界）与 99.99% 分位（黄/红边界）确定。observations 为零时返回 green。

参数:

• exceptions -- Observed exception count.

• observations -- Number of observations.

• confidence_level -- Model confidence level in (0, 1).

抛出:

input_error -- If observations is non-zero and confidence_level is not finite in (0, 1).

返回:

green, yellow, or red.

risk_validation_report fincore::build_risk_validation_report(const walk_forward_var_result &result, std::optional<std::string> timestamp_index_name = std::nullopt)

由滚动前向 VaR 结果构建验证报告。

投影之前会重新校验结果：预测、实现与索引的长度必须一致，重新拟合时间戳必须符合设定的节奏，拟合参数必须能复现其预测区段，摘要必须为小写 SHA-256 十六进制，且回测必须与在路径上的重新计算结果一致。报告持有所投影字段的全部副本。

参数:

• result -- Walk-forward result to project.

• timestamp_index_name -- Optional index label copied into the report.

抛出:

input_error -- If the result violates the validation contract.

返回:

Validation report with specification echo, events, refits, diagnostics, optional backtest and traffic-light zone.

double fincore::christoffersen_lr(std::span<const int> exceptions)

返回 Christoffersen 独立性似然比统计量。

标志按二值处理；非零项计为突破。提供的标志少于两个时返回零。

参数:

exceptions -- Exception flags in chronological order.

返回:

Independence likelihood-ratio statistic.

garch_conditional_estimate fincore::conditional_es(const dataframe &returns, garch_model model, double alpha = 0.05, std::size_t horizon = 1U, std::string_view column = returns_column)

由 GARCH 家族方差预测计算条件正态期望损失。

拟合由 forecast_volatility 完成；数值为在请求的预测期上 -sqrt(sum(forecast variances)) * pdf(z(alpha)) / alpha。

参数:

• returns -- Frame containing decimal simple returns.

• model -- GARCH family to fit.

• alpha -- Tail probability in (0, 1); values outside yield NaN.

• horizon -- Number of variance steps; must be at least 1.

• column -- Column holding the return series.

抛出:

input_error -- If horizon is zero or the selected fit rejects its input.

返回:

Signed expected-shortfall estimate, the variance forecast path and the fit convergence flag.

garch_conditional_estimate fincore::conditional_var(const dataframe &returns, garch_model model, double alpha = 0.05, std::size_t horizon = 1U, std::string_view column = returns_column)

由 GARCH 家族方差预测计算条件正态 VaR。

拟合由 forecast_volatility 完成；数值为在请求的预测期上 z(alpha) * sqrt(sum(forecast variances))。

参数:

• returns -- Frame containing decimal simple returns.

• model -- GARCH family to fit.

• alpha -- Tail probability in (0, 1); values outside yield NaN.

• horizon -- Number of variance steps; must be at least 1.

• column -- Column holding the return series.

抛出:

input_error -- If horizon is zero or the selected fit rejects its input.

返回:

Signed VaR estimate, the variance forecast path and the fit convergence flag.

double fincore::es_calibration_score(double forecast_es, std::span<const double> realized, double confidence_level)

返回实现与预测期望损失的相对差值度量。

realized ES 为不高于线性 1 - confidence_level 分位数的实现值均值，该尾部为空时取零。度量为 (realized_es - forecast_es) / abs(forecast_es)。

参数:

• forecast_es -- Forecast expected shortfall.

• realized -- Realized return observations.

• confidence_level -- Confidence level used to select the realized tail.

返回:

Relative calibration score, or NaN when abs(forecast_es) is below 1e-15.

double fincore::evt_cvar(const dataframe &data, double alpha = 0.05, evt_model model = evt_model::gpd, evt_tail tail = evt_tail::lower, std::optional<double> threshold = std::nullopt, std::optional<std::size_t> block_size = std::nullopt, std::string_view column = returns_column)

用极值模型估计条件尾部期望。

使用与 evt_var 相同的拟合与阈值策略，随后报告超出 VaR 的尾部均值（CVaR/ES）。估计值按尾部符号表示，且比对应的 VaR 更靠近所选尾部。

参数:

• data -- Frame containing the return series.

• alpha -- Tail probability in (0, 1).

• model -- EVT model.

• tail -- Tail to estimate.

• threshold -- Positive GPD magnitude threshold; empty selects the automatic threshold.

• block_size -- GEV block size in observations; empty selects the automatic block size.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If alpha is not finite in (0, 1), a GPD threshold leaves an exceedance probability below alpha, a fit is not finite, xi is at least 1 (infinite CVaR), or the column is missing or contains an embedded NUL.

返回:

Signed CVaR estimate.

double fincore::evt_var(const dataframe &data, double alpha = 0.05, evt_model model = evt_model::gpd, evt_tail tail = evt_tail::lower, std::optional<double> threshold = std::nullopt, std::optional<std::size_t> block_size = std::nullopt, std::string_view column = returns_column)

用极值模型估计在险价值。

alpha 是尾部概率而非置信水平：例如 0.05 对应 95% 的尾部。GPD 路径拟合 Peaks-over-threshold 模型；threshold 为空时，从所选尾部的第 90 百分位开始选择一个能提供足够严格超出值以覆盖 alpha 的阈值。GEV 路径使用分块极大值并忽略 threshold。结果按尾部符号表示，因此下尾估计为负。

参数:

• data -- Frame containing the return series.

• alpha -- Tail probability in (0, 1).

• model -- EVT model.

• tail -- Tail to estimate.

• threshold -- Positive GPD magnitude threshold; empty selects the automatic threshold.

• block_size -- GEV block size in observations; empty selects the automatic block size.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If alpha is not finite in (0, 1), a GPD threshold leaves an exceedance probability below alpha, a fit or VaR is not finite, or the column is missing or contains an embedded NUL.

返回:

Signed VaR estimate.

double fincore::expected_exception_count(std::size_t observations, double confidence_level)

返回预期的 VaR 突破次数。

预期次数为 observations * (1 - confidence_level)。

参数:

• observations -- Number of observations.

• confidence_level -- Model confidence level.

返回:

Expected exception count.

extreme_risk_result fincore::extreme_risk(const dataframe &returns, double alpha = 0.05, evt_tail tail = evt_tail::lower, evt_model model = evt_model::gpd, std::optional<double> threshold = std::nullopt, std::optional<std::size_t> block_size = std::nullopt, std::string_view column = returns_column)

用极值模型估计 VaR、CVaR 及拟合的尾部参数。

运行与 evt_var 和 evt_cvar 相同的拟合与阈值策略并返回两个估计。对 GPD，threshold 与 n_exceedances 描述拟合，而 location、scale 与 block 字段为空。对 GEV，location、scale 与 block 字段被设置，而 threshold 为 NaN、n_exceedances 为零。

参数:

• returns -- Frame containing the return series.

• alpha -- Tail probability in (0, 1).

• tail -- Tail to estimate.

• model -- EVT model.

• threshold -- Positive GPD magnitude threshold; ignored for GEV.

• block_size -- GEV block size in observations; empty selects the automatic block size.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If alpha is not finite in (0, 1), a fit is not finite, xi is at least 1 (infinite CVaR), or the column is missing or contains an embedded NUL.

返回:

Signed VaR and CVaR with fitted tail parameters.

egarch_result fincore::fit_egarch(const dataframe &returns, std::string_view column = returns_column)

用高斯极大似然拟合 EGARCH(1,1) 模型。

丢弃 NaN 观测；至少需要十个取值有限且方差为正的 non-NaN 观测。拟合使用多起点 Nelder-Mead 优化。

参数:

• returns -- Frame containing decimal simple returns.

• column -- Column holding the return series.

抛出:

input_error -- If fewer than ten non-NaN observations remain, a non-finite value remains, the series has zero variance, or the column is missing or contains an embedded NUL.

返回:

Fitted parameters, conditional variances, residuals, likelihood and convergence flag.

garch11_result fincore::fit_garch11(const dataframe &returns, bool constant_mean = false, std::string_view column = returns_column)

用高斯极大似然拟合 GARCH(1,1) 模型。

丢弃 NaN 观测；至少需要十一个取值有限且方差为正的 non-NaN 观测。除非 constant_mean 为 true，否则强制零均值。

参数:

• returns -- Frame containing decimal simple returns.

• constant_mean -- Estimate a constant mean instead of fixing it at zero.

• column -- Column holding the return series.

抛出:

input_error -- If fewer than eleven non-NaN observations remain, a non-finite value remains, the series has zero variance, or the column is missing or contains an embedded NUL.

返回:

Fitted parameters, conditional variances, residuals, likelihood and convergence flag. A failed convergence is reported through converged, not by throwing.

gjr_garch_result fincore::fit_gjr_garch(const dataframe &returns, std::string_view column = returns_column)

用高斯极大似然拟合 GJR-GARCH(1,1) 模型。

丢弃 NaN 观测；至少需要十个取值有限且方差为正的 non-NaN 观测。拟合使用多起点 Nelder-Mead 优化。

参数:

• returns -- Frame containing decimal simple returns.

• column -- Column holding the return series.

抛出:

input_error -- If fewer than ten non-NaN observations remain, a non-finite value remains, the series has zero variance, or the column is missing or contains an embedded NUL.

返回:

Fitted parameters, conditional variances, residuals, likelihood and convergence flag.

std::vector<double> fincore::forecast_egarch(const egarch_result &result, std::size_t horizon = 1U)

预测 EGARCH(1,1) 拟合的条件方差路径。

第一步使用最后一个对数方差与标准化残差；后续步骤使用常数漂移与拟合的 beta 持续性。没有条件方差的结果会产生全 NaN 的路径。

参数:

• result -- Fitted EGARCH(1,1) result.

• horizon -- Number of variance steps; must be at least 1.

抛出:

input_error -- If horizon is zero.

返回:

Variance forecasts in return units squared, one per step.

risk_estimate fincore::forecast_es(const dataframe &returns, const risk_forecast_config &config = {}, std::string_view column = returns_column)

估计收益率序列的期望损失。

估计之前丢弃 NaN 观测，且索引必须严格升序且无重复。historical 与 EVT 方法返回单个点估计并且不使用 config.horizon；GARCH 方法在配置的预测期上复合条件方差预测。

参数:

• returns -- Return series with ascending, duplicate-free timestamps.

• config -- Estimation method, confidence level and method settings.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If the configuration is invalid; the column is missing, not a double column, or contains an embedded NUL; the index is duplicated or unsorted; no non-NaN observation remains; or the selected EVT or GARCH kernel rejects the data.

返回:

Point expected-shortfall estimate, diagnostics, digest and status. The estimate is negative for losses under the losses_negative convention.

std::vector<double> fincore::forecast_garch11(const garch11_result &result, std::size_t horizon = 1U)

预测 GARCH(1,1) 拟合的条件方差路径。

第一步使用最后一个条件方差与残差；后续步骤使用拟合的持续性 alpha + beta。没有条件方差的结果会产生全 NaN 的路径。

参数:

• result -- Fitted GARCH(1,1) result.

• horizon -- Number of variance steps; must be at least 1.

抛出:

input_error -- If horizon is zero.

返回:

Variance forecasts in return units squared, one per step.

std::vector<double> fincore::forecast_gjr_garch(const gjr_garch_result &result, std::size_t horizon = 1U)

预测 GJR-GARCH(1,1) 拟合的条件方差路径。

第一步使用最后一个条件方差与带符号残差；后续步骤使用拟合的持续性 alpha + 0.5 * gamma + beta。没有条件方差的结果会产生全 NaN 的路径。

参数:

• result -- Fitted GJR-GARCH(1,1) result.

• horizon -- Number of variance steps; must be at least 1.

抛出:

input_error -- If horizon is zero.

返回:

Variance forecasts in return units squared, one per step.

risk_estimate fincore::forecast_var(const dataframe &returns, const risk_forecast_config &config = {}, std::string_view column = returns_column)

估计收益率序列的在险价值。

估计之前丢弃 NaN 观测，且索引必须严格升序且无重复。historical 与 EVT 方法返回单个点估计并且不使用 config.horizon；GARCH 方法在配置的预测期上复合条件方差预测。

参数:

• returns -- Return series with ascending, duplicate-free timestamps.

• config -- Estimation method, confidence level and method settings.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If the configuration is invalid; the column is missing, not a double column, or contains an embedded NUL; the index is duplicated or unsorted; no non-NaN observation remains; or the selected EVT or GARCH kernel rejects the data.

返回:

Point VaR estimate, diagnostics, digest and status. The estimate is negative for losses under the losses_negative convention.

garch_forecast_result fincore::forecast_volatility(const dataframe &returns, garch_model model, std::size_t horizon = 1U, std::string_view column = returns_column)

拟合 GARCH 家族模型并预测其方差路径。

参数:

• returns -- Frame containing decimal simple returns.

• model -- GARCH family to fit.

• horizon -- Number of variance steps; must be at least 1.

• column -- Column holding the return series.

抛出:

input_error -- If horizon is zero or the selected fit rejects its input.

返回:

Variance forecasts with the fitted likelihood and convergence flag.

double fincore::garch11_log_likelihood(std::span<const double> eps, double omega, double alpha, double beta)

返回给定参数下的高斯 GARCH(1,1) 对数似然。

首个条件方差取 eps 的总体方差，似然在其余观测上累加，因此第一个观测作为一步预热被舍弃。

参数:

• eps -- Zero-mean return shocks.

• omega -- Variance intercept.

• alpha -- ARCH coefficient.

• beta -- GARCH coefficient.

返回:

Log-likelihood; NaN when fewer than two shocks are supplied, or negative infinity when a conditional variance is not positive and finite.

gev_parameters fincore::gev_fit(const dataframe &data, std::optional<std::size_t> block_size = std::nullopt, evt_tail tail = evt_tail::lower, std::string_view column = returns_column)

对分块极值拟合推广极值分布。

丢弃 NaN 值；每个完整分块对 upper 贡献其最大值、对 lower 贡献其最小值取负，因此拟合的位置与尺度以尾部幅值为单位。默认分块大小为剩余观测数的整数平方根。

参数:

• data -- Frame containing the return series.

• block_size -- Positive number of consecutive observations per block; empty selects floor(sqrt(n)).

• tail -- Tail whose block extremes are fitted.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If no observation remains, block_size is zero or leaves no complete block, the block extremes have no positive finite variation, the fit does not reach a finite likelihood, a fitted parameter is non-finite or the scale is not positive, or the column is missing or contains an embedded NUL.

返回:

Fitted shape, location, scale and block count.

gpd_parameters fincore::gpd_fit(const dataframe &data, std::optional<double> threshold = std::nullopt, gpd_estimation_method method = gpd_estimation_method::mle, evt_tail tail = evt_tail::lower, std::string_view column = returns_column)

对尾部超出值拟合推广 Pareto 分布。

lower 幅值为亏损取反，upper 幅值为收益；默认阈值为这些幅值的第 90 线性百分位。至少需要十个严格超出值。极大似然路径复现固定版本源实现的目标函数与边界，可能把 xi 推到其上界。PWM 路径使用 L 矩公式。

参数:

• data -- Frame containing the return series.

• threshold -- Positive magnitude threshold; empty selects the 90th percentile of the tail magnitudes.

• method -- Estimation method.

• tail -- Tail to fit.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If the selected tail has no observations, the threshold is not finite and positive, fewer than ten exceedances remain, a PWM moment is invalid, or the column is missing or contains an embedded NUL.

返回:

Fitted shape, scale, threshold and exceedance count.

hill_estimate fincore::hill_estimator(const dataframe &data, std::optional<double> threshold = std::nullopt, evt_tail tail = evt_tail::upper, std::string_view column = returns_column)

由所选尾部幅值估计 Hill 尾部指数。

lower 幅值为亏损取反，upper 幅值为收益；默认阈值为这些幅值的第 90 线性百分位。只使用严格超出值，且至少需要十个。

参数:

• data -- Frame containing the return series.

• threshold -- Positive magnitude threshold; empty selects the 90th percentile of the tail magnitudes.

• tail -- Tail to estimate.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If the threshold is not finite and positive, fewer than ten exceedances remain, or the column is missing or contains an embedded NUL.

返回:

Hill tail index and the strict exceedances used.

double fincore::kupiec_lr(std::size_t observations, std::size_t exceptions, double confidence_level)

返回 Kupiec 失败比例似然比统计量。

预期突破概率为 1 - confidence_level。统计量下限截断为零，observations 为零时结果为零。

参数:

• observations -- Number of backtest observations.

• exceptions -- Number of observed exceptions.

• confidence_level -- Model confidence level; the expected exception probability is 1 - confidence_level.

返回:

Non-negative likelihood-ratio statistic.

std::string_view fincore::risk_backtest_status_name(risk_backtest_status status)

返回回测状态的小写名称。

参数:

status -- Backtest status.

返回:

pass, fail, inconclusive, or experimental.

std::string_view fincore::risk_forecast_target_name(risk_forecast_target target)

返回预测目标的小写名称。

参数:

target -- Forecast target.

返回:

var, es, or pair.

std::string_view fincore::risk_tail_name(risk_tail tail)

返回分布尾部的小写名称。

参数:

tail -- Distribution tail.

返回:

lower or upper.

void fincore::validate_risk_model_spec(const risk_model_spec &spec)

依据受支持的契约校验模型设定。

参数:

spec -- Specification to validate.

抛出:

input_error -- If confidence_level is not finite in (0, 1), horizon is below 1, distribution is not historical or normal, sign_convention is not losses_negative, window is below 2, refit_cadence is below 1, or model_version is not 1.0.

std::string_view fincore::walk_forward_status_name(walk_forward_status status)

返回滚动前向状态的小写名称。

参数:

status -- Walk-forward status.

返回:

ok, insufficient_data, or unsupported.

walk_forward_var_result fincore::walk_forward_var(const dataframe &returns, const risk_model_spec &spec, std::string_view column = returns_column)

运行滚动窗口的滚动前向 VaR 回测。

第一个预测针对初始 spec.window 之后的观测产生；此后每 spec.refit_cadence 步重新拟合并恰好使用前一个窗口。normal 预测使用均值加样本标准差乘以正态分位数，偏差为零时回退为均值；historical 预测使用第 6 类（Weibull）分位数。得到的路径按 0.05 显著性水平回测。路径要求 forecast_target='var'、tail='lower'、sign_convention='losses_negative' 且 horizon=1；若 horizon 大于 1、目标/尾部/符号约定不符，或在浮点容差内历史秩 (window + 1) * (1 - confidence_level) 落在 [1, window] 之外，则返回带原因的 unsupported。

参数:

• returns -- Return series with strictly increasing, duplicate-free timestamps and finite values.

• spec -- Model specification.

• column -- Column holding decimal simple returns.

抛出:

input_error -- If the specification is invalid, the index is not strictly increasing, a value is not finite, or the column is missing or contains an embedded NUL.

返回:

Forecast path, refit parameters, backtest and status. Unsupported and insufficient-data results carry an empty path and a reason.

constexpr std::string_view fincore::losses_negative_sign_convention = "losses_negative"

表示亏损为负收益率的符号约定标签。

constexpr int fincore::risk_validation_report_schema_version = 1

风险验证报告输出的模式版本。