HAR-CAESar API
Core models
HAR-CAESar: Heterogeneous Autoregressive Conditional Autoregressive Expected Shortfall
This module implements the HAR-CAESar model, an extension of CAESar that incorporates heterogeneous autoregressive dynamics based on the Heterogeneous Market Hypothesis (Muller et al., 1997; Corsi, 2009).
The model includes daily, weekly (5-day), and monthly (22-day) return aggregates to capture long-memory effects in tail risk.
Author: MSc Thesis Implementation
- class har_caesar.models.har_caesar.HAR_CAESar(theta, lambdas={})[source]
Bases:
objectHAR-CAESar: Heterogeneous Autoregressive CAESar for joint VaR and ES estimation.
This model extends the standard CAESar (Gatta et al., 2024) by incorporating HAR-style dynamics that capture long-memory effects in tail risk.
- The VaR equation is:
- q_t = β₀ + β₁^(d) r_{t-1}^+ + β₂^(d) r_{t-1}^-
β₁^(w) r^(w)_{t-1}^+ + β₂^(w) r^(w)_{t-1}^-
β₁^(m) r^(m)_{t-1}^+ + β₂^(m) r^(m)_{t-1}^-
β_q q_{t-1} + β_e e_{t-1}
The ES equation has the same structure with γ coefficients.
Parameters per equation: 9 (intercept + 6 return coeffs + 2 AR terms) Total parameters: 18
- ESloss(beta, y, q, r0, har_features)[source]
Compute the Barrera loss for ES estimation.
- Parameters:
beta (ndarray) – Parameters for ES equation. Shape is (9,).
y (ndarray) – Target return series.
q (ndarray) – VaR forecast from Step 1.
r0 (float) – Initial value for r = e - q.
har_features (dict) – HAR features with keys ‘daily’, ‘weekly’, ‘monthly’.
- Returns:
Loss value.
- Return type:
float
- Joint_HARloop(beta, y, q0, e0, har_features, pred_mode=False)[source]
Recursive loop for joint VaR and ES estimation with HAR specification.
- Jointloss(beta, y, q0, e0, har_features)[source]
Compute the Fissler-Ziegel loss for joint estimation.
- Parameters:
beta (ndarray) – Parameters for both equations. Shape is (18,).
y (ndarray) – Target return series.
q0 (float) – Initial VaR.
e0 (float) – Initial ES.
har_features (dict) – HAR features.
- Returns:
Loss value.
- Return type:
float
- R_HARloop(beta, y, q, r0, har_features, pred_mode=False)[source]
Recursive loop for ES residual (r = e - q) estimation with HAR specification.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the HAR-CAESar model on a univariate return series.
- Parameters:
yi (ndarray) – Target return series.
seed (int, optional) – Random seed for reproducibility.
return_train (bool, optional) – If True, return in-sample predictions. Default is False.
q0 (list, optional) – Initial [VaR, ES]. If None, computed from data.
nV (int, optional) – Number of random initializations. Default is 102.
n_init (int, optional) – Number of best initializations to refine. Default is 3.
n_rep (int, optional) – Number of optimization repetitions. Default is 5.
- Returns:
Keys ‘qi’, ‘ei’, ‘beta’ when return_train=True, else None.
- Return type:
dict
- fit_predict(y, ti, seed=None, return_train=True, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the model on training data and predict on test data.
- Parameters:
y (ndarray) – Full return series.
ti (int) – Training set length.
seed (int, optional) – Random seed.
return_train (bool, optional) – Return training predictions. Default is True.
q0 (list, optional) – Initial [VaR, ES].
nV (int, optional) – Number of random initializations.
n_init (int, optional) – Number of best initializations to refine.
n_rep (int, optional) – Number of optimization repetitions.
- Returns:
Keys ‘qi’, ‘ei’, ‘qf’, ‘ef’, ‘beta’.
- Return type:
dict
- joint_loss(v, e, y)[source]
Compute the Fissler-Ziegel (Patton) loss function for joint estimation (Step 3).
- Parameters:
v (ndarray) – VaR forecast.
e (ndarray) – ES forecast.
y (ndarray) – Target return series.
- Returns:
Fissler-Ziegel loss value.
- Return type:
float
- loss_function(v, r, y)[source]
Compute the Barrera loss function for ES estimation (Step 2).
- Parameters:
v (ndarray) – Value at Risk forecast.
r (ndarray) – Difference between ES forecast and VaR (r = e - q).
y (ndarray) – Target return series.
- Returns:
Barrera loss value.
- Return type:
float
- har_caesar.models.har_caesar.HAR_CAESar_model(theta, lambdas={})[source]
Factory function for HAR-CAESar model.
- Parameters:
theta (float) – Quantile level.
lambdas (dict, optional) – Penalty weights.
- Returns:
Model instance.
- Return type:
- class har_caesar.models.caesar.CAESar_1_1(theta, spec='AS', lambdas={})[source]
Bases:
CAESar_baseCAESar for joint quantile and expected shortfall estimation - y lags=1, q lags=1.
- Joint_ASloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (10,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_GARCHloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_SAVloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- R_ASloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (5,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_GARCHloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_SAVloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the CAESar model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, the function returns the fitted values. Default is False.
- q0: list of float or None, optional
[initial quantile, initial expected shortfall]. If None, the initial quantile is computed as the empirical quantile in the first 10% of the training set; the initial expected shortfall as the tail mean in the same subset. Default is None.
- nV: int, optional
number of random initializations of the model coefficients. Default is 102.
- n_init: int, optional
number of best initializations to work with. Default is 3.
- n_rep: int, optional
number of repetitions for the optimization. Default is 5.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- beta: ndarray
optimized coefficients of the model. The shape is (2, self.n_parameters) (if return_train=True).
- class har_caesar.models.caesar.CAESar_1_2(theta, spec='AS', lambdas={})[source]
Bases:
CAESar_baseCAESar for joint quantile and expected shortfall estimation - y lags=1, q lags=2.
- Joint_ASloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (10,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_GARCHloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_SAVloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- R_ASloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (5,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_GARCHloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_SAVloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the CAESar model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, the function returns the fitted values. Default is False.
- q0: list of float or None, optional
[initial quantile, initial expected shortfall]. If None, the initial quantile is computed as the empirical quantile in the first 10% of the training set; the initial expected shortfall as the tail mean in the same subset. Default is None.
- nV: int, optional
number of random initializations of the model coefficients. Default is 102.
- n_init: int, optional
number of best initializations to work with. Default is 3.
- n_rep: int, optional
number of repetitions for the optimization. Default is 5.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- beta: ndarray
optimized coefficients of the model. The shape is (2, self.n_parameters) (if return_train=True).
- class har_caesar.models.caesar.CAESar_2_1(theta, spec='AS', lambdas={})[source]
Bases:
CAESar_baseCAESar for joint quantile and expected shortfall estimation - y lags=2, q lags=1.
- Joint_ASloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (10,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_GARCHloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_SAVloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- R_ASloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (5,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_GARCHloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_SAVloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the CAESar model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, the function returns the fitted values. Default is False.
- q0: list of float or None, optional
[initial quantile, initial expected shortfall]. If None, the initial quantile is computed as the empirical quantile in the first 10% of the training set; the initial expected shortfall as the tail mean in the same subset. Default is None.
- nV: int, optional
number of random initializations of the model coefficients. Default is 102.
- n_init: int, optional
number of best initializations to work with. Default is 3.
- n_rep: int, optional
number of repetitions for the optimization. Default is 5.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- beta: ndarray
optimized coefficients of the model. The shape is (2, self.n_parameters) (if return_train=True).
- class har_caesar.models.caesar.CAESar_2_2(theta, spec='AS', lambdas={})[source]
Bases:
CAESar_baseCAESar for joint quantile and expected shortfall estimation - y lags=2, q lags=2.
- Joint_ASloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (10,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_GARCHloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_SAVloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- R_ASloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (5,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_GARCHloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_SAVloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the CAESar model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, the function returns the fitted values. Default is False.
- q0: list of float or None, optional
[initial quantile, initial expected shortfall]. If None, the initial quantile is computed as the empirical quantile in the first 10% of the training set; the initial expected shortfall as the tail mean in the same subset. Default is None.
- nV: int, optional
number of random initializations of the model coefficients. Default is 102.
- n_init: int, optional
number of best initializations to work with. Default is 3.
- n_rep: int, optional
number of repetitions for the optimization. Default is 5.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- beta: ndarray
optimized coefficients of the model. The shape is (2, self.n_parameters) (if return_train=True).
- class har_caesar.models.caesar.CAESar_general(theta, spec='AS', lambdas={}, p=1, u=1)[source]
Bases:
CAESar_baseCAESar model for joint VaR and ES estimation.
Implements the Conditional Autoregressive Expected Shortfall (CAESar) model with flexible lag structure and multiple specifications (SAV, AS, GARCH).
- Parameters:
theta (float) – Quantile level (e.g., 0.025 for 2.5% VaR).
spec (str, optional) – Model specification - ‘SAV’, ‘AS’, or ‘GARCH’. Default is ‘AS’.
lambdas (dict, optional) – Penalty weights for soft constraints. Default is {‘r’:10, ‘q’:10, ‘e’:10}.
p (int, optional) – Number of return lags. Default is 1.
u (int, optional) – Number of VaR/ES lags. Default is 1.
- Joint_ASloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (10,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_GARCHloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- Joint_SAVloop(beta, y, q0, e0, pred_mode=False)[source]
Loop for the joint ^q and ^e estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (8,).
- y: ndarray
target time series.
- q0: float
if pred_mode=False, it contains ^q starting point. Otherwise, it is not used.
- e0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], e[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
Expected Shortfall forecast.
- R_ASloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via AS specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (5,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_GARCHloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via GARCH specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- R_SAVloop(beta, y, q, r0, pred_mode=False)[source]
Loop for the ^r estimation via SAV specification. INPUTS:
- beta: ndarray
parameters of the model. The shape is (4,).
- y: ndarray
target time series.
- q: ndarray
quantile forecast.
- r0: float or list of floats
if pred_mode=False, r0 is a float describing initial point for the ^r forecast. If pred_mode=True, r0 is a list of floats describing the last state of the system, that is r0=[y[-1], q[-1], ^r[-1]].
- pred_mode: bool, optional
if True, the loop is in prediction mode and r0 is assumed to contain the last state. Default is False.
- OUTPUTS:
- r: ndarray
difference between the Expected Shortfall forecast and the quantile.
- fit(yi, seed=None, return_train=False, q0=None, nV=102, n_init=3, n_rep=5)[source]
Fit the CAESar model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, the function returns the fitted values. Default is False.
- q0: list of float or None, optional
[initial quantile, initial expected shortfall]. If None, the initial quantile is computed as the empirical quantile in the first 10% of the training set; the initial expected shortfall as the tail mean in the same subset. Default is None.
- nV: int, optional
number of random initializations of the model coefficients. Default is 102.
- n_init: int, optional
number of best initializations to work with. Default is 3.
- n_rep: int, optional
number of repetitions for the optimization. Default is 5.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- beta: ndarray
optimized coefficients of the model. The shape is (2, self.n_parameters) (if return_train=True).
- har_caesar.models.caviar.CAViaR(theta, spec='AS', p=1, u=1)[source]
CAViaR model selection.
- Parameters:
theta (float) – Quantile level.
spec (str, optional) – Specification of the model (SAV, AS, GARCH). Default is ‘AS’.
p (int, optional) – Number of lags for the y variable. Default is 1.
u (int, optional) – Number of lags for the quantile. Default is 1.
- Returns:
Selected CAViaR model instance.
- Return type:
CAViaR model
- class har_caesar.models.gas.GAS1(theta)[source]
Bases:
objectGAS1 (Generalized Autoregressive Score) model for joint VaR and ES estimation.
Implements the GAS model with a single score-driven state variable.
- Parameters:
theta (float) – Quantile level (e.g., 0.025 for 2.5% VaR).
- GAS1_loop(beta, y, k0, pred_mode=False)[source]
Loop for the GAS1 model. INPUTS:
- beta: ndarray
model parameters.
- y: ndarray
target time series.
- k0: float
initial point for the state variable.
- pred_mode: bool, optional
prediction mode. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
expected shortfall forecast.
- k: ndarray
state variable.
- GASloss(beta, y, k0, tau=None)[source]
Compute the GAS1 loss. INPUTS:
- beta: ndarray
model parameters.
- y: ndarray
target time series.
- k0: float
initial point for the state variable.
- tau: float, optional
smoothing parameter. If None, the original loss is computed. Default is None.
- OUTPUTS:
- loss_val: float
GAS1 loss, either in its original form (when tau=None) or smoothed version.
- fit(yi, seed=None, return_train=False)[source]
Fit the GAS1 model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, return the fitted variables. Default is False.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall in the training set (if return_train=True).
- ki: ndarray
state variable in the training set (if return_train=True).
- beta: ndarray
optimized model parameters (if return_train=True).
- fit_core(yi, beta0, k0, tau=None)[source]
Core function for the GAS1 model. INPUTS:
- yi: ndarray
target time series.
- beta0: ndarray
initial model parameters.
- k0: float
initial point for the state variable.
- tau: float, optional
smoothing parameter. If None, the original loss is computed. Default is None.
- OUTPUTS:
- beta: ndarray
optimized model parameters if the optimization is successful, otherwise the initial parameters.
- fit_predict(y, ti, seed=None, return_train=False)[source]
Fit and predict the GAS1 model. INPUTS:
- y: ndarray
target time series.
- ti: int
train set length.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, return the fitted values in training set. Default is False.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- ki: ndarray
state variable in the training set (if return_train=True).
- qf: ndarray
quantile forecast in the test set.
- ef: ndarray
expected shortfall forecast in the test set.
- kf: ndarray
state variable in the test set.
- beta: ndarray
optimized model parameters.
- loss(v, e, y)[source]
Compute the GAS1 loss. INPUTS:
- v: float
quantile forecast.
- e: float
expected shortfall forecast.
- y: ndarray
target time series.
- OUTPUTS:
- loss_val: float
GAS1 loss.
- predict(yf=array([], dtype=float64))[source]
Predict the GAS1 model. INPUTS:
- yf: ndarray, optional
target time series. If yf is not empty, the internal state is updated with the last observation. Default is an empty list.
- OUTPUTS:
- qf: ndarray
quantile forecast in the test set.
- ef: ndarray
expected shortfall forecast in the test set.
- kf: ndarray
state variable in the test set.
- class har_caesar.models.gas.GAS2(theta)[source]
Bases:
objectGAS2 (Generalized Autoregressive Score) model for joint VaR and ES estimation.
Implements the GAS model with separate score-driven state variables for VaR and ES.
- Parameters:
theta (float) – Quantile level (e.g., 0.025 for 2.5% VaR).
- GAS2_loop(beta, y, k0, pred_mode=False)[source]
Loop for the GAS2 model. INPUTS:
- beta: ndarray
model parameters.
- y: ndarray
target time series.
- k0: float
initial point for the state variable.
- pred_mode: bool, optional
prediction mode. Default is False.
- OUTPUTS:
- q: ndarray
quantile forecast.
- e: ndarray
expected shortfall forecast.
- k: ndarray
state variable.
- GASloss(beta, y, k0, tau=None)[source]
Compute the GAS2 loss. INPUTS:
- beta: ndarray
model parameters.
- y: ndarray
target time series.
- k0: float
initial point for the state variable.
- tau: float, optional
smoothing parameter. If None, the original loss is computed. Default is None.
- OUTPUTS:
- loss_val: float
GAS2 loss, either in its original form (when tau=None) or smoothed version.
- fit(yi, seed=None, return_train=False)[source]
Fit the GAS2 model. INPUTS:
- yi: ndarray
target time series.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, return the fitted variables. Default is False.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall in the training set (if return_train=True).
- beta: ndarray
optimized model parameters (if return_train=True).
- fit_core(yi, beta0, k0, tau=None)[source]
Core function for the GAS2 model. INPUTS:
- yi: ndarray
target time series.
- beta0: ndarray
initial model parameters.
- k0: float
initial point for the state variable.
- tau: float, optional
smoothing parameter. If None, the original loss is computed. Default is None.
- OUTPUTS:
- beta: ndarray
optimized model parameters if the optimization is successful, otherwise the initial parameters.
- fit_predict(y, ti, seed=None, return_train=False)[source]
Fit and predict the GAS1 model. INPUTS:
- y: ndarray
target time series.
- ti: int
train set length.
- seed: int or None, optional
random seed. Default is None.
- return_train: bool, optional
if True, return the fitted values in training set. Default is False.
- OUTPUTS:
- qi: ndarray
quantile forecast in the training set (if return_train=True).
- ei: ndarray
expected shortfall forecast in the training set (if return_train=True).
- qf: ndarray
quantile forecast in the test set.
- ef: ndarray
expected shortfall forecast in the test set.
- beta: ndarray
optimized model parameters.
- loss(v, e, y)[source]
Compute the GAS2 loss. INPUTS:
- v: float
quantile forecast.
- e: float
expected shortfall forecast.
- y: ndarray
target time series.
- OUTPUTS:
- loss_val: float
GAS2 loss.
- predict(yf=array([], dtype=float64))[source]
Predict the GAS2 model. INPUTS:
- yf: ndarray, optional
target time series. If yf is not empty, the internal state is updated with the last observation. Default is an empty list.
- OUTPUTS:
- qf: ndarray
quantile forecast in the test set.
- ef: ndarray
expected shortfall forecast in the test set.