skfolio.measures.value_at_risk

skfolio.measures.value_at_risk(returns, beta=0.95, sample_weight=None)

Compute the historical value at risk (VaR).

The VaR is the smallest loss exceeded with probability at most \(1 - \beta\). It is the lower \(\beta\)-quantile of the empirical loss distribution \(F_L\):

\[\mathrm{VaR}_{\beta} = \inf\{\ell \in \mathbb{R} : F_L(\ell) \geq \beta\}\]

With sample_weight, \(F_L\) is the weighted empirical distribution function.

Parameters:

returnsndarray of shape (n_observations,) or (n_observations, n_assets)

Array of return values.

betafloat, default=0.95

The VaR confidence level. Must be between 0 and 1. The endpoints select the best and worst usable returns, respectively; zero-weight observations are excluded.

sample_weightndarray of shape (n_observations,), optional

Sample weights for each observation. If None, equal weights are assumed.

Returns:

valuefloat or ndarray of shape (n_assets,)

Value at Risk. If returns is a 1D-array, the result is a float. If returns is a 2D-array, the result is a ndarray of shape (n_assets,).

Notes

With \(n\) equally weighted observations and an integer \(k = (1 - \beta) n\), the VaR is the \((k+1)\)-th largest loss and the CVaR is the mean of the \(k\) largest losses. For example, with 100 observations and beta=0.95, the VaR is the sixth largest loss.

NaN handling: NaN returns are excluded from each column’s calculation. Remaining sample weights are rescaled to sum to one. The result is NaN if no observations or no positive weight remain.

References

[1]

“Conditional value-at-risk for general loss distributions”, Journal of Banking & Finance, Rockafellar & Uryasev (2002)

[2]

“Quantitative Risk Management: Concepts, Techniques and Tools”, Princeton University Press, McNeil, Frey & Embrechts (2015)