Risk

VaR/ES diagnostics, GARCH/EGARCH estimates, extreme-value models, backtesting, walk-forward validation and risk reports.

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

struct egarch_parameters

Parameters of an EGARCH(1,1) model.

Public Members

double omega

Log-variance intercept.

double alpha

Magnitude coefficient on the absolute standardized shock.

double gamma

Asymmetry (leverage) coefficient on the standardized shock.

double beta

Persistence coefficient on the previous log-variance.

struct egarch_result

Result of an EGARCH(1,1) fit.

Public Members

egarch_parameters params

Fitted parameters.

std::vector<double> conditional_variances

Variance path in return units squared, one value per cleaned observation.

std::vector<double> residuals

Standardized residuals aligned with conditional_variances.

double log_likelihood

Gaussian log-likelihood, excluding the first observation.

bool converged

Whether the optimizer and parameter, variance and stationarity checks passed.

struct extreme_risk_result

Combined value-at-risk and expected-shortfall estimate from an EVT model.

Public Members

double var

Value-at-risk estimate, signed by the tail.

double cvar

Conditional tail expectation, signed by the tail.

double tail_index

Fitted GPD or GEV shape parameter.

double threshold

GPD magnitude threshold; NaN for GEV fits.

std::size_t n_exceedances

GPD exceedance count; zero for GEV fits.

double alpha

Tail probability used for the estimates.

std::optional<double> location

GEV location; empty for GPD fits.

std::optional<double> scale

GEV scale; empty for GPD fits.

std::optional<std::size_t> n_blocks

GEV block count; empty for GPD.

struct garch11_parameters

Parameters of a GARCH(1,1) model.

Public Members

double mu

Constant mean; zero when the fit uses a zero mean.

double omega

Variance intercept in return-variance units; positive.

double alpha

ARCH coefficient on the previous squared shock.

double beta

GARCH coefficient on the previous variance.

struct garch11_result

Result of a GARCH(1,1) fit.

Public Members

garch11_parameters params

Fitted parameters.

std::vector<double> conditional_variances

Variance path in return units squared, one value per cleaned observation.

std::vector<double> residuals

Standardized residuals aligned with conditional_variances.

double log_likelihood

Gaussian log-likelihood, excluding the first observation.

bool converged

Whether the optimizer and parameter, variance and stationarity checks passed.

struct garch_conditional_estimate

GARCH-family VaR or ES estimate and the variance path used.

Public Members

double value

Signed risk estimate; negative for losses at lower-tail probabilities.

std::vector<double> conditional_variances

Variance forecast path in return units squared from forecast_volatility, one value per horizon step.

bool converged

Convergence flag of the fit that produced the path.

struct garch_forecast_result

Forecast and fit diagnostics returned by forecast_volatility.

Public Members

std::vector<double> forecasts

Variance forecasts in return units squared.

double log_likelihood

Log-likelihood of the fitted model.

bool converged

Convergence flag of the fitted model.

struct gev_parameters

Fitted generalized extreme-value distribution of block extremes.

Public Members

double xi

Shape parameter.

double mu

Location parameter in tail-magnitude units.

double sigma

Scale parameter in tail-magnitude units.

std::size_t n_blocks

Number of complete blocks used.

struct gjr_garch_parameters

Parameters of a GJR-GARCH(1,1) model.

Public Members

double omega

Variance intercept in return-variance units; positive.

double alpha

ARCH coefficient on the previous squared shock.

double gamma

Additional coefficient on squared negative shocks.

double beta

GARCH coefficient on the previous variance.

struct gjr_garch_result

Result of a GJR-GARCH(1,1) fit.

Public Members

gjr_garch_parameters params

Fitted parameters.

std::vector<double> conditional_variances

Variance path in return units squared, one value per cleaned observation.

std::vector<double> residuals

Standardized residuals aligned with conditional_variances.

double log_likelihood

Gaussian log-likelihood, excluding the first observation.

bool converged

Whether the optimizer and parameter, variance and stationarity checks passed.

struct gpd_parameters

Fitted generalized Pareto distribution for threshold exceedances.

Public Members

double xi

Shape parameter.

double beta

Scale parameter in magnitude units.

double threshold

Positive magnitude threshold used for the fit.

std::size_t n_exceed

Number of strict exceedances used.

struct hill_estimate

Hill tail-index estimate and the exceedances used.

Public Members

double xi

Hill tail-index estimate: mean log exceedance ratio.

std::vector<double> tail_observations

Strict exceedances in magnitude units, in input order.

struct refit_parameters

Parameters recorded for one walk-forward refit.

Public Members

timestamp date

Timestamp of the first forecast step from this refit.

double forecast

VaR forecast for the refit segment.

double mean

Mean of the estimation window.

double standard_deviation

Sample standard deviation (n - 1) of the estimation window.

std::size_t n_observations

Estimation window length.

struct risk_backtest_result

Result of a VaR or ES backtest, including coverage statistics and a deterministic input digest.

Public Members

risk_backtest_method method

Risk measure backtested.

double confidence_level

Confidence level used for the forecast.

std::size_t observations

Number of paired non-NaN observations.

std::size_t exceptions

VaR: realized below forecast; ES: realized below the tail threshold.

double expected_exceptions

observations * (1 - confidence_level).

double exception_rate

exceptions / observations; 0 when empty.

double kupiec_lr

Kupiec unconditional-coverage statistic; 0 for ES.

double kupiec_pvalue

Chi-square (df 1) p-value; 1 for ES.

double christoffersen_lr

Independence statistic; 0 for ES.

double christoffersen_pvalue

Chi-square (df 1) p-value; 1 for ES.

std::string inputs_digest

Lowercase SHA-256 over aligned timestamps and values; native form, not the Python CSV digest.

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

VaR adds significance and small_sample; ES adds realized_es, forecast_es, z_score, n_bootstrap and seed.

risk_backtest_status status

Backtest classification.

struct risk_estimate

Point risk estimate plus provenance and diagnostics.

Public Members

risk_forecast_method method = risk_forecast_method::historical

Estimation method.

double confidence_level = 0.95

Confidence level used for the estimate.

std::size_t horizon = 1U

Configured forecast horizon.

std::string sign_convention = {losses_negative_sign_convention}

Sign convention label; losses_negative.

double estimate = 0.0

Point estimate; negative for losses under losses_negative.

timestamp forecast_timestamp = 0

Timestamp of the last cleaned observation used by the estimate.

bool has_forecast_timestamp = false

Whether forecast_timestamp was populated.

std::string inputs_digest

Lowercase SHA-256 hex digest of the cleaned timestamps and values.

bool has_forecast = false

Whether a forward forecast path is populated; current point estimates leave it false.

std::vector<timestamp> forecast_index

Optional forecast timestamps; empty for point estimates.

std::vector<double> forecast_values

Optional forecast values; empty for point estimates.

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

Method-specific numeric diagnostics; keys depend on method.

std::string kernel

Backend kernel: empty for historical, evt_var/evt_cvar for EVT, and conditional_var/conditional_es for GARCH.

std::string note

Note populated when a GARCH fit does not converge; empty otherwise.

risk_estimate_status status = risk_estimate_status::ok

Estimate status.

struct risk_forecast_config

Settings for a point VaR or expected-shortfall estimate.

Public Members

risk_forecast_method method = risk_forecast_method::historical

Estimation method.

double confidence_level = 0.95

Confidence level in (0, 1); the tail probability is 1 - confidence_level.

std::size_t horizon = 1U

Forecast horizon in observations; used by the GARCH method and must be at least 1.

garch_model garch_kernel = garch_model::garch

GARCH family used when method is garch.

evt_model evt_kernel = evt_model::gpd

EVT model used when method is evt.

evt_tail tail = evt_tail::lower

EVT tail used when method is evt.

std::optional<double> threshold

GPD threshold in absolute magnitude units; empty selects the automatic threshold and GEV ignores it.

std::optional<std::size_t> block_size

GEV block size in observations; empty selects the automatic block size and GPD ignores it.

struct risk_forecast_event

One out-of-sample forecast event in a validation report.

Public Members

timestamp date

Forecast timestamp.

double forecast

VaR forecast at date.

double realized

Realized return at date.

bool exception

Whether realized is strictly below forecast.

bool refit

Whether date starts a refit segment.

struct risk_model_spec

Versioned model specification shared by walk-forward VaR and validation reports.

Public Members

risk_forecast_target forecast_target = risk_forecast_target::var

Forecast target; walk-forward VaR supports var only.

double confidence_level = 0.99

Confidence level; must be finite in (0, 1).

std::size_t horizon = 1U

Forecast horizon in observations; must be at least 1.

std::string distribution = "normal"

Distribution label; historical or normal.

risk_tail tail = risk_tail::lower

Tail used by the model; walk-forward VaR supports lower only.

std::string sign_convention = "losses_negative"

Sign convention label; only losses_negative is accepted.

std::size_t window = 252U

Estimation window length in observations; at least 2.

std::size_t refit_cadence = 1U

Number of forecast steps between refits; at least 1.

std::string model_version = "1.0"

Model version label; only 1.0 is accepted.

struct risk_refit_event

Parameters recorded for one refit in a validation report.

Public Members

timestamp date

Refit timestamp.

double forecast

VaR forecast produced by the refit.

double mean

Estimation-window mean.

double standard_deviation

Estimation-window sample standard deviation.

std::size_t n_observations

Estimation-window length.

struct risk_report_diagnostics

Diagnostic fields describing how a validation report was produced.

Public Members

std::string method

Distribution label from the specification.

std::string quantile_method

weibull for historical and normal_ppf for normal.

std::size_t window = 0U

Estimation window length.

std::size_t refit_cadence = 0U

Forecast steps per refit.

std::size_t forecast_count = 0U

Number of forecast events.

std::string backtest_status

Backtest status name (pass, fail, inconclusive, or experimental).

std::string reason

Reason for a non-ok status; empty for ok reports.

std::size_t n_observations = 0U

Input observation count; populated for insufficient-data reports.

struct risk_validation_report

Versioned validation report projected from a walk-forward VaR result.

Public Functions

risk_validation_report_dict to_dict() const

Returns a detached native dict representation of the report fields.

Throws:

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

Returns:

Dictionary with one field per native report field.

std::string to_json() const

Serializes the report to deterministic JSON text.

Keys are emitted in sorted order with two-space indentation, Python-compatible float text, and a trailing newline. Non-finite numbers and invalid UTF-8 are rejected.

Throws:

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

Returns:

JSON text ending with a newline.

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

Writes the deterministic JSON artifact to path and returns it.

Parent directories are not created, matching the source contract.

Parameters:

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

Throws:

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

Returns:

The same path after a successful write.

Public Members

walk_forward_status status = walk_forward_status::unsupported

Run status.

std::string inputs_digest

Lowercase SHA-256 hex digest from the result.

risk_model_spec specification

Specification echoed from the result.

std::vector<risk_forecast_event> forecast_events

Forecast events; empty for non-ok reports.

std::vector<risk_refit_event> refits

Refit parameters; empty for non-ok reports.

risk_report_diagnostics diagnostics

Report diagnostics.

bool has_backtest = false

Whether backtest holds a backtest.

risk_backtest_result backtest = {}

Backtest payload; meaningful only when has_backtest is true.

std::string traffic_light_zone

Basel zone; empty without a backtest.

std::optional<std::string> timestamp_index_name

Optional index label supplied to the builder.

std::optional<std::string> timestamp_timezone

Optional index timezone label; the native builder leaves it empty.

std::string disclosure = {basel_reference_disclosure}

Basel reference disclosure text.

int schema_version = risk_validation_report_schema_version

Report schema version.

struct risk_validation_report_dict

Native detached dictionary projection of risk_validation_report.

This is the C++ equivalent of the source’s JSON-compatible to_dict mapping: every native report field is represented exactly once. Python object identity and mapping subclassing are not claimed.

Public Members

int schema_version = risk_validation_report_schema_version

Report schema version.

std::string status

Status name: ok, insufficient_data, or unsupported.

std::string inputs_digest

Lowercase SHA-256 hex digest from the walk-forward result.

std::optional<std::string> timestamp_index_name

Optional index label.

std::optional<std::string> timestamp_timezone

Optional index timezone label; not populated by the native builder.

risk_model_spec specification

Specification echoed from the result.

std::vector<risk_forecast_event> forecast_events

Forecast events; empty for non-ok reports.

std::vector<risk_refit_event> refits

Refit parameters; empty for non-ok reports.

risk_report_diagnostics diagnostics

Report diagnostics.

std::optional<risk_backtest_result> backtest

Backtest payload; empty when the report has no backtest.

std::string traffic_light_zone

Basel zone; empty without a backtest.

std::string disclosure

Basel reference disclosure text.

struct walk_forward_var_result

Result of a walk-forward VaR run.

Public Members

risk_model_spec spec

Specification used to produce the result.

std::vector<timestamp> index

Out-of-sample timestamps; empty unless status is ok.

std::vector<double> forecast

VaR forecast path aligned with index; empty unless status is ok.

std::vector<double> realized

Realized returns aligned with index; empty unless status is ok.

std::vector<timestamp> refit_timestamps

Timestamps of all refits; the first equals index.front() when ok.

std::vector<refit_parameters> fits

Parameters recorded for each refit, one per refit_timestamps entry.

std::string inputs_digest

Lowercase SHA-256 hex digest of the input values and the confidence level, window, refit cadence, distribution and model version.

walk_forward_status status

Run status.

std::string unsupported_reason

Reason for an unsupported or insufficient_data result; empty for ok.

std::size_t n_observations = 0U

Number of input observations.

risk_backtest_result backtest

Out-of-sample VaR backtest; meaningful only when has_backtest is true.

bool has_backtest

Whether backtest was populated.

enum class fincore::evt_model

Extreme-value model used for a tail estimate.

Values:

enumerator gpd

Peaks-over-threshold generalized Pareto model.

enumerator gev

Block-maxima generalized extreme-value model.

enum class fincore::evt_tail

Tail of the return distribution used by an EVT model.

Values:

enumerator lower

Lower tail (losses).

enumerator upper

Upper tail (gains).

enum class fincore::garch_model

GARCH-family model selected by the convenience functions.

Values:

enumerator garch

GARCH(1,1) with a zero mean.

enumerator egarch

EGARCH(1,1).

enumerator gjr_garch

GJR-GARCH(1,1) with an asymmetric shock term.

enum class fincore::gpd_estimation_method

Estimation method for a generalized Pareto fit.

Values:

enumerator mle

Maximum-likelihood fit of the GPD.

enumerator pwm

Probability-weighted-moment fit using L-moments.

enum class fincore::risk_backtest_method

Risk measure exercised by a backtest.

Values:

enumerator var

Value-at-risk exception backtest.

enumerator es

Expected-shortfall backtest.

enum class fincore::risk_backtest_status

Classification of a VaR or ES backtest.

Values:

enumerator pass

Coverage tests do not reject the model and the sample is adequate.

enumerator fail

A coverage test rejects the model and the sample is adequate.

enumerator inconclusive

Fewer than three paired observations or fewer than five expected exceptions; the sample is too small to test.

enumerator experimental

Experimental backtest; used by the ES bootstrap path.

enum class fincore::risk_distribution

Distribution labels for walk-forward VaR.

Values:

enumerator historical

Empirical distribution using the Weibull quantile.

enumerator normal

Normal distribution using the mean and sample deviation.

enum class fincore::risk_estimate_status

Completion status of a risk estimate.

Values:

enumerator ok

At least two non-NaN observations were available and any GARCH fit converged.

enumerator insufficient_data

Fewer than two non-NaN observations were available.

enumerator failed

The GARCH fit did not converge or failed its stationarity checks.

enum class fincore::risk_forecast_method

Risk-estimation method used by forecast_var and forecast_es.

Values:

enumerator historical

Historical quantile and tail-mean estimate.

enumerator evt

Extreme-value estimate using the configured EVT kernel.

enumerator garch

GARCH-family conditional estimate.

enum class fincore::risk_forecast_target

Target risk measure produced by a forecast.

Values:

enumerator var

Value at risk.

enumerator es

Expected shortfall.

enumerator pair

Pair target label for cross-component metadata.

enum class fincore::risk_tail

Tail of the return distribution used by a risk model.

Values:

enumerator lower

Lower (loss) tail.

enumerator upper

Upper (gain) tail.

enum class fincore::walk_forward_status

Completion status of a walk-forward VaR run.

Values:

enumerator ok

Forecast path and backtest were produced.

enumerator insufficient_data

Fewer observations than one full window plus one.

enumerator unsupported

The specification combination is not supported.

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")

Runs an experimental bootstrap expected-shortfall backtest.

The realized tail contains realized values strictly below the linear 1 - confidence_level quantile; realized ES is the tail mean and forecast ES the aligned forecast mean. A seeded bootstrap of the tail supplies the standard deviation of resampled tail means used in the reported z-score. The status is always experimental, and the Kupiec and Christoffersen fields are neutral (0 and 1).

Parameters:

  • 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.

Throws:

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.

Returns:

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")

Runs a VaR exception backtest on aligned forecast and realized series.

Both frames are aligned on their common timestamps, and pairs with a NaN forecast or realized value are dropped. An exception is a realized value strictly below the forecast. The result is inconclusive when there are fewer than three paired observations or fewer than five expected exceptions; otherwise it is fail when either coverage p-value is below significance and pass otherwise.

Parameters:

  • 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.

Throws:

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.

Returns:

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)

Classifies an exception count into a Basel traffic-light zone.

Zones are determined from binomial quantiles at 95% (green/yellow boundary) and 99.99% (yellow/red boundary) for the expected exception probability. Returns green when observations is zero.

Parameters:

  • exceptions – Observed exception count.

  • observations – Number of observations.

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

Throws:

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

Returns:

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)

Builds a validation report from a walk-forward VaR result.

The result is revalidated before projection: the forecast, realized and index lengths must agree, refit timestamps must follow the specification cadence, fit parameters must reproduce their forecast segments, the digest must be lowercase SHA-256 hex, and the backtest must match a recomputation over the path. The report owns copies of all projected fields.

Parameters:

  • result – Walk-forward result to project.

  • timestamp_index_name – Optional index label copied into the report.

Throws:

input_error – If the result violates the validation contract.

Returns:

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

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

Returns the Christoffersen independence likelihood-ratio statistic.

Flags are treated as binary; non-zero entries count as exceptions. Returns zero when fewer than two flags are supplied.

Parameters:

exceptions – Exception flags in chronological order.

Returns:

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)

Computes a conditional normal expected shortfall from a GARCH-family variance forecast.

The fit is performed by forecast_volatility; the value is -sqrt(sum(forecast variances)) * pdf(z(alpha)) / alpha over the requested horizon.

Parameters:

  • 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.

Throws:

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

Returns:

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)

Computes a conditional normal VaR from a GARCH-family variance forecast.

The fit is performed by forecast_volatility; the value is z(alpha) * sqrt(sum(forecast variances)) over the requested horizon.

Parameters:

  • 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.

Throws:

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

Returns:

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)

Returns the relative realized-versus-forecast expected-shortfall score.

Realized ES is the mean of realized values at or below the linear 1 - confidence_level quantile, and is zero when that tail is empty. The score is (realized_es - forecast_es) / abs(forecast_es).

Parameters:

  • forecast_es – Forecast expected shortfall.

  • realized – Realized return observations.

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

Returns:

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)

Estimates the conditional tail expectation with an extreme-value model.

Uses the same fitting and threshold policy as evt_var, then reports the mean of the tail beyond VaR (CVaR/ES). The estimate is signed by tail and lies further into the selected tail than the corresponding VaR.

Parameters:

  • 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.

Throws:

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.

Returns:

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)

Estimates the value at risk with an extreme-value model.

alpha is the tail probability, not the confidence level: for example 0.05 targets the 95% tail. The GPD path fits a peaks-over-threshold model; when threshold is empty, a threshold is chosen to leave enough strict exceedances to cover alpha, starting from the 90th percentile of the selected tail. The GEV path uses block maxima and ignores threshold. The result is signed by tail, so lower-tail estimates are negative.

Parameters:

  • 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.

Throws:

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.

Returns:

Signed VaR estimate.

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

Returns the expected number of VaR exceptions.

The expected count is observations * (1 - confidence_level).

Parameters:

  • observations – Number of observations.

  • confidence_level – Model confidence level.

Returns:

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)

Estimates VaR, CVaR and fitted tail parameters with an extreme-value model.

Runs the same fit and threshold policy as evt_var and evt_cvar and returns both estimates. For GPD, threshold and n_exceedances describe the fit and the location, scale and block fields are empty. For GEV, the location, scale and block fields are set, while threshold is NaN and n_exceedances is zero.

Parameters:

  • 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.

Throws:

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.

Returns:

Signed VaR and CVaR with fitted tail parameters.

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

Fits an EGARCH(1,1) model by Gaussian maximum likelihood.

NaN observations are dropped; at least ten non-NaN observations with finite values and positive variance are required. The fit uses multi-start Nelder-Mead optimization.

Parameters:

  • returns – Frame containing decimal simple returns.

  • column – Column holding the return series.

Throws:

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.

Returns:

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)

Fits a GARCH(1,1) model by Gaussian maximum likelihood.

NaN observations are dropped; at least eleven non-NaN observations with finite values and positive variance are required. A zero mean is imposed unless constant_mean is true.

Parameters:

  • returns – Frame containing decimal simple returns.

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

  • column – Column holding the return series.

Throws:

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.

Returns:

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)

Fits a GJR-GARCH(1,1) model by Gaussian maximum likelihood.

NaN observations are dropped; at least ten non-NaN observations with finite values and positive variance are required. The fit uses multi-start Nelder-Mead optimization.

Parameters:

  • returns – Frame containing decimal simple returns.

  • column – Column holding the return series.

Throws:

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.

Returns:

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

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

Forecasts the conditional variance path of an EGARCH(1,1) fit.

The first step uses the last log-variance and standardized residual; later steps use a constant drift and the fitted beta persistence. A result without conditional variances yields a path of NaNs.

Parameters:

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

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

Throws:

input_error – If horizon is zero.

Returns:

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)

Estimates the expected shortfall of a return series.

NaN observations are dropped before estimation, and the index must be strictly ascending and duplicate-free. Historical and EVT methods return a single point estimate and do not use config.horizon; the GARCH method composes the conditional variance forecast over the configured horizon.

Parameters:

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

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

  • column – Column holding decimal simple returns.

Throws:

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.

Returns:

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)

Forecasts the conditional variance path of a GARCH(1,1) fit.

The first step uses the last conditional variance and residual; later steps use the fitted persistence alpha + beta. A result without conditional variances yields a path of NaNs.

Parameters:

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

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

Throws:

input_error – If horizon is zero.

Returns:

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)

Forecasts the conditional variance path of a GJR-GARCH(1,1) fit.

The first step uses the last conditional variance and signed residual; later steps use the fitted persistence alpha + 0.5 * gamma + beta. A result without conditional variances yields a path of NaNs.

Parameters:

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

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

Throws:

input_error – If horizon is zero.

Returns:

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)

Estimates the value at risk of a return series.

NaN observations are dropped before estimation, and the index must be strictly ascending and duplicate-free. Historical and EVT methods return a single point estimate and do not use config.horizon; the GARCH method composes the conditional variance forecast over the configured horizon.

Parameters:

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

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

  • column – Column holding decimal simple returns.

Throws:

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.

Returns:

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)

Fits a GARCH-family model and forecasts its variance path.

Parameters:

  • 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.

Throws:

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

Returns:

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)

Returns the Gaussian GARCH(1,1) log-likelihood for fixed parameters.

The first conditional variance is the population variance of eps and the likelihood sums over the remaining observations, so the first observation is a one-step burn-in.

Parameters:

  • eps – Zero-mean return shocks.

  • omega – Variance intercept.

  • alpha – ARCH coefficient.

  • beta – GARCH coefficient.

Returns:

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)

Fits a generalized extreme-value distribution to block extremes.

NaN values are dropped; each complete block contributes its maximum for upper or the negated minimum for lower, so the fitted location and scale are in tail-magnitude units. The default block size is the integer square root of the remaining observation count.

Parameters:

  • 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.

Throws:

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.

Returns:

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)

Fits a generalized Pareto distribution to tail exceedances.

Magnitudes are reflected losses for lower and gains for upper; the default threshold is the 90th linear percentile of those magnitudes. At least ten strict exceedances are required. The maximum-likelihood path reproduces the pinned source objective and bounds, which can drive xi to its upper bound. The PWM path uses L-moment formulas.

Parameters:

  • 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.

Throws:

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.

Returns:

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)

Estimates the Hill tail index from the selected tail magnitudes.

Magnitudes are reflected losses for lower and gains for upper; the default threshold is the 90th linear percentile of those magnitudes. Only strict exceedances are used, and at least ten are required.

Parameters:

  • 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.

Throws:

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.

Returns:

Hill tail index and the strict exceedances used.

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

Returns the Kupiec proportion-of-failures likelihood-ratio statistic.

The expected exception probability is 1 - confidence_level. The statistic is clamped at zero and is zero when observations is zero.

Parameters:

  • observations – Number of backtest observations.

  • exceptions – Number of observed exceptions.

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

Returns:

Non-negative likelihood-ratio statistic.

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

Returns the lowercase name of a backtest status.

Parameters:

status – Backtest status.

Returns:

pass, fail, inconclusive, or experimental.

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

Returns the lowercase name of a forecast target.

Parameters:

target – Forecast target.

Returns:

var, es, or pair.

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

Returns the lowercase name of a distribution tail.

Parameters:

tail – Distribution tail.

Returns:

lower or upper.

void fincore::validate_risk_model_spec(const risk_model_spec &spec)

Validates a model specification against the supported contract.

Parameters:

spec – Specification to validate.

Throws:

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)

Returns the lowercase name of a walk-forward status.

Parameters:

status – Walk-forward status.

Returns:

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)

Runs a rolling-window walk-forward VaR backtest.

The first forecast is produced for the observation after the initial spec.window; refits occur at that point and every spec.refit_cadence steps, each using exactly the preceding window. Normal forecasts use the mean plus the sample deviation times the normal quantile, falling back to the mean on zero deviation; historical forecasts use the type-6 (Weibull) quantile. The resulting path is backtested at a 0.05 significance level. A path requires forecast_target='var', tail='lower', sign_convention='losses_negative' and horizon=1; a horizon above 1, another target, tail or sign convention, or a historical rank (window + 1) * (1 - confidence_level) outside [1, window] up to floating-point tolerance returns unsupported with a reason.

Parameters:

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

  • spec – Model specification.

  • column – Column holding decimal simple returns.

Throws:

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.

Returns:

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"

Sign-convention label stating that losses are negative returns.

constexpr int fincore::risk_validation_report_schema_version = 1

Schema version emitted by risk validation reports.