arch.univariate.var_exceptions¶

Identify the exceptions of a VaR forecast.

Parameters:¶

returns: ndarray[tuple[int], dtype[float64]] | Series | list[float]¶: Realized returns, a 1-d array of finite numbers.
var: ndarray[tuple[int], dtype[float64]] | Series | list[float]¶: VaR forecasts, a 1-d array of finite numbers. VaR is a positive loss, so that a VaR of 2.5 forecasts that the return is below -2.5 with the probability that the VaR is designed for. If both returns and var are Series, they are aligned on the index and the observations that are in both are used, in the order of returns. Otherwise, they must have the same length and are matched by position.

Returns:¶

A bool array that is True where the return is an exception, that is where the loss exceeds the VaR, -returns > var. It is a Series named "exception" if returns or var is a pandas object, with the index of the observations that are used: the index of returns if it is a pandas object, and otherwise the index of var.

Return type:¶

{ndarray, Series}

Raises:¶

TypeError – If returns or var cannot be converted to numbers.
ValueError – If returns or var is not a 1-d array of finite numbers (NaN and inf raise), has no observations, has an index with duplicates that differs from the index of the other Series, or does not have the same length as the other input.

Notes

The sign convention is the same for all the functions of this module. VaR is reported as a positive loss, so that a 99% VaR of 2.5 is the loss that is exceeded with probability p=0.01, and an observation is an exception if \(-r_t > \mathrm{VaR}_t\). A quantile of the distribution of returns, which is negative for the lower tail, must be negated first. A loss that equals the VaR is not an exception.

Only two Series are aligned on the index. A DataFrame, an array, or a Series used with an array, is matched by position, so the VaR forecast for the return in position \(t\) must be in position \(t\). The forecasts of forecast() are indexed by the date of the forecast origin by default, so that the one-step forecast for day \(t\) has the label of day \(t-1\). Use forecast(..., align="target"), or shift the VaR forward by one observation, so that each VaR has the label of the return that it is a forecast of.