Utility Functions

The har_caesar.utils module provides essential statistical testing and loss functions for model validation and comparison.

Loss Functions

The module includes implementations of elicitable loss functions for VaR and ES:

• Tick Loss: Quantile loss for VaR estimation

• Barrera Loss: Loss function for ES residual estimation

• Fissler-Ziegel Loss: Jointly consistent loss for (VaR, ES) pairs

Statistical Tests

VaR Backtests:

• kupiec_test(): Unconditional coverage test

• christoffersen_cc_test(): Conditional coverage test (UC + independence)

ES Backtests:

• mcneil_frey_test(): Bootstrap-based ES calibration test

• acerbi_szekely_test(): Z1 and Z2 tests for ES specification

Forecast Comparison:

• diebold_mariano_test(): HAC-robust test for comparing forecast accuracy

• bootstrap_loss_test(): One-sided test for forecast encompassing

API Documentation

class har_caesar.utils.AS14_test(one_side=False, n_boot=10000)

Bases: bootstrap_mean_test

Acerbi-Szekely test for assessing the goodness of the Expected Shortfall estimate

__call__(Q, E, Y, theta, test_type='Z1', seed=None)

Compute the test INPUT: - Q: numpy array,

the quantile estimates

• E: numpy array,

  the expected shortfall estimates

• Y: numpy array,

  the actual time series

• test_type: str,

  the type of test to perform. It must be either ‘Z1’ or ‘Z2’

• theta: float,

  the threshold for the test

• seed: int,

  the seed for the random number generator. Default is None

OUTPUT: - statistic: float,

the test statistic

• p_value: float,

  the p-value of the test

as14_transform(test_type, Q_, E_, Y_, theta)

Transform the data to compute the Acerbi-Szekely test INPUT: - test_type: str,

the type of test to perform. It must be either ‘Z1’ or ‘Z2’

• Q_: numpy array,

  the quantile estimates

• E_: numpy array,

  the expected shortfall estimates

• Y_: numpy array,

  the actual time series

• theta: float,

  the threshold for the test

OUTPUT: - output: numpy array,

the transformed data

class har_caesar.utils.DMtest(loss_func, h=1)

Bases: object

Diebold-Mariano test for the equality of forecast accuracy.

__call__(Q1, E1, Q2, E2, Y)

INPUT: - Q1: numpy array,

the first set of quantile predictions

• E1: numpy array,

  the first set of expected shortfall predictions

• Q2: numpy array,

  the second set of quantile predictions

• E2: numpy array,

  the second set of expected shortfall predictions

• Y: numpy array,

  the actual time series

OUTPUT: - stat: float,

the test statistic

• p_value: float,

  the p-value of the test

• mean_difference: float,

  the mean difference of the losses

autocovariance(Xi, T, k, Xs)

Compute the autocovariance of a time series INPUT: - Xi: numpy array,

the time series

• T: int,

  the length of the time series

• k: int,

  the lag

• Xs: float,

  the mean of the time series

OUTPUT: - autoCov: float,

the autocovariance

class har_caesar.utils.Encompassing_test(loss, n_boot=10000)

Bases: bootstrap_mean_test

Encompassing test to assess whenever the first sample of losses is statistically lower than the second.

__call__(Q_new, E_new, Q_bench, E_bench, Y, seed=None)

Compute the test INPUT: - Q_new: numpy array,

the first set of quantile predictions

• E_new: numpy array,

  the first set of expected shortfall predictions

• Q_bench: numpy array,

  the second set of quantile predictions

• E_bench: numpy array,

  the second set of expected shortfall predictions

• Y: numpy array,

  the actual time series

• seed: int,

  the seed for the random number generator. Default is None

OUTPUT: - statistic: float,

the test statistic

• p_value: float,

  the p-value of the test

en_transform(Q_new_, E_new_, Q_bench_, E_bench_, Y_)

Transform the data to compute the test INPUT: - Q_new_: numpy array,

the first set of quantile predictions

• E_new_: numpy array,

  the first set of expected shortfall predictions

• Q_bench_: numpy array,

  the second set of quantile predictions

• E_bench_: numpy array,

  the second set of expected shortfall predictions

• Y_: numpy array,

  the actual time series

OUTPUT: - output: numpy array,

the transformed data

class har_caesar.utils.LossDiff_test(loss, n_boot=10000)

Bases: bootstrap_mean_test

Encompassing test to assess whenever the first sample of losses is statistically lower than the second.

__call__(Q_new, E_new, Q_bench, E_bench, Y, seed=None)

Compute the test INPUT: - Q_new: numpy array,

the first set of quantile predictions

• E_new: numpy array,

  the first set of expected shortfall predictions

• Q_bench: numpy array,

  the second set of quantile predictions

• E_bench: numpy array,

  the second set of expected shortfall predictions

• Y: numpy array,

  the actual time series

• seed: int,

  the seed for the random number generator. Default is None

OUTPUT: - statistic: float,

the test statistic

• p_value: float,

  the p-value of the test

ld_transform(Q_new, E_new, Q_bench, E_bench, Y)

Transform the data to compute the test INPUT: - Q_new: numpy array,

the first set of quantile predictions

• E_new: numpy array,

  the first set of expected shortfall predictions

• Q_bench: numpy array,

  the second set of quantile predictions

• E_bench: numpy array,

  the second set of expected shortfall predictions

• Y: numpy array,

  the actual time series

OUTPUT: - output: numpy array,

the transformed data

class har_caesar.utils.McneilFrey_test(one_side=False, n_boot=10000)

Bases: bootstrap_mean_test

McNeil-Frey test for assessing the goodness of the Expected Shortfall estimate

__call__(Q, E, Y, seed=None)

Compute the test INPUT: - Q: numpy array,

the quantile estimates

• E: numpy array,

  the expected shortfall estimates

• Y: numpy array,

  the actual time series

• seed: int,

  the seed for the random number generator. Default is None

OUTPUT: - statistic: float,

the test statistic

• p_value: float,

  the p-value of the test

mnf_transform(Q_, E_, Y_)

Transform the data to compute the McNeil-Frey test INPUT: - Q_: numpy array,

the quantile estimates

• E_: numpy array,

  the expected shortfall estimates

• Y_: numpy array,

  the actual time series

OUTPUT: - output: numpy array,

the transformed data

class har_caesar.utils.PinballLoss(quantile)

Bases: object

Pinball or Quantile loss function

__call__(y_pred, y_true)

INPUT: - y_pred: numpy array,

the predicted values

• y_true: numpy array,

  the true values

OUTPUT: - loss: float,

the mean pinball loss

class har_caesar.utils.barrera_loss(theta, ret_mean=True)

Bases: object

Barrera loss function

__call__(v_, e_, y_)

INPUT: - v_: numpy array,

the quantile estimate

• e_: numpy array,

  the expected shortfall estimate

• y_: numpy array,

  the actual time series

OUTPUT: - loss: float,

the loss function mean value, if ret_mean is True. Otherwise, the loss for each observation

class har_caesar.utils.bootstrap_mean_test(mu_target, one_side=False, n_boot=10000)

Bases: object

Bootstrap test for the mean of a sample

__call__(data, seed=None)

Compute the test INPUT: - data: numpy array,

the original sample

• seed: int,

  the seed for the random number generator. Default is None

OUTPUT: - statistic: float,

the test statistic

• p_value: float,

  the p-value of the test

null_statistic(B_data)

Compute the null statistic for the bootstrap sample INPUT: - B_data: numpy array,

the bootstrap sample

OUTPUT: - stat: float,

the null statistic

statistic(data)

Compute the test statistic for the original sample INPUT: - data: numpy array,

the original sample

OUTPUT: - stat: float,

the test statistic

har_caesar.utils.christoffersen_cc_test(violations, theta)

Christoffersen (1998) conditional coverage test for VaR backtesting.

Tests both unconditional coverage (correct violation rate) and independence (no clustering of violations). The test statistic is LR_CC = LR_UC + LR_IND, distributed as chi-squared with 2 degrees of freedom under the null.

INPUT: - violations: numpy array,

binary array where 1 indicates a VaR violation at time t

• theta: float,

  the nominal coverage level (e.g., 0.025 for 2.5% VaR)

OUTPUT: - dict with keys:

• ‘LR_UC’: float, unconditional coverage test statistic

• ‘LR_IND’: float, independence test statistic

• ‘LR_CC’: float, conditional coverage test statistic

• ‘p_value_UC’: float, p-value for unconditional coverage

• ‘p_value_IND’: float, p-value for independence

• ‘p_value_CC’: float, p-value for conditional coverage

• ‘violation_rate’: float, observed violation rate

har_caesar.utils.cr_t_test(errorsA, errorsB, train_len, test_len)

Corrected resampled t-test for the equality of forecast accuracy. INPUT: - errorsA: numpy array,

the first set of forecast errors

• errorsB: numpy array,

  the second set of forecast errors

• train_len: int,

  the length of the training set

• test_len: int,

  the length of the test set

OUTPUT: - stat: float,

the test statistic

• p_val: float,

  the p-value of the test

har_caesar.utils.gaussian_tail_stats(theta, loc=0, scale=1)

Compute the Value at Risk and Expected Shortfall for a Gaussian distribution INPUT: - theta: float,

the quantile to compute the statistics

• loc: numpy array,

  the mean of the distribution

• scale: numpy array,

  the standard deviation of the distribution

OUTPUT: - var: numpy array,

the Value at Risk

• es: numpy array,

  the Expected Shortfall

class har_caesar.utils.patton_loss(theta, ret_mean=True)

Bases: object

Patton loss function

__call__(v_, e_, y_)

INPUT: - v_: numpy array,

the quantile estimate

• e_: numpy array,

  the expected shortfall estimate

• y_: numpy array,

  the actual time series

OUTPUT: - loss: float,

the loss function mean value, if ret_mean is True. Otherwise, the loss for each observation

har_caesar.utils.tstudent_tail_stats(theta, df, loc=0, scale=1)

Compute the Value at Risk and Expected Shortfall for a Student’s t distribution INPUT: - theta: float,

the quantile to compute the statistics

• df: int,

  the degrees of freedom of the distribution

• loc: numpy array,

  the mean of the distribution

• scale: numpy array,

  the standard deviation of the distribution

OUTPUT: - var: numpy array,

the Value at Risk

• es: numpy array,

  the Expected Shortfall