ES: Compute expected shortfall (ES)

In cvar: Compute Expected Shortfall and Value at Risk for Continuous Distributions

Compute expected shortfall (ES)

Description

Compute expected shortfall (ES).

Usage

ES(dist, p_loss = 0.05, ...)

## Default S3 method:
ES(
  dist,
  p_loss = 0.05,
  dist.type = "qf",
  qf,
  ...,
  intercept = 0,
  slope = 1,
  control = list(),
  transf = FALSE,
  x
)

## S3 method for class 'numeric'
ES(dist, p_loss = 0.05, ..., intercept = 0, slope = 1, transf = FALSE, x)

## S3 method for class 'matrix'
ES(dist, p_loss = 0.05, ..., intercept = 0, slope = 1, transf = FALSE, x)

Arguments

dist	specifies the distribution whose ES is computed, usually a function or a name of a function computing quantiles, cdf, pdf, or a random number generator. Can also be a numeric vector or matrix, representing data, see section ‘Details’.
p_loss	level, default is 0.05.
...	passed on to dist.
dist.type	a character string specifying what is computed by dist, such as "qf" or "cdf".
qf	quantile function, only used if dist.type = "pdf".
intercept, slope	compute ES for the linear transformation intercept + slope*X, where X has distribution specified by dist, see Details.
control	additional control parameters for the numerical integration routine.
transf	use only if "dist" represents log-returns. If TRUE, give the result for the returns (not log-returns), see section ‘Details’.
x	deprecated and will soon be removed. x was renamed to p_loss, please use the latter.

Details

ES is a generic function for computation of expected shortfall. The default method computes ES corresponding to a distribution, usually fitted or implied by a fitted model. There are also methods for data (numeric or matrix).

Alternative terms for ES include CVaR (conditional value at risk), AVaR (average value at risk), and ETL (expected tail loss).

The default method of ES computes the expected shortfall for distributions specified by the arguments. dist is typically a function (or the name of one). What dist computes is determined by dist.type, whose default setting is "qf" (the quantile function). Other possible settings of dist.type include "cdf" and "pdf". Additional arguments for dist can be given with the "..." arguments.

Argument dist can also be a numeric vector. In that case the ES is computed, effectively, for the empirical cumulative distribution function (ecdf) of the vector. The ecdf is not created explicitly and the quantile function is used instead for the computation of VaR. Arguments in "..." are passed eventually to quantile() and can be used, for example, to select a non-defult method for the computation of quantiles.

If dist is a matrix, the numeric method is applied to each of its columns.

Except for the exceptions discussed below, a function computing VaR for the specified distribution is constructed and the expected shortfall is computed by numerically integrating it. The numerical integration can be fine-tuned with argument control, which should be a named list, see integrate for the available options.

If dist.type is "pdf", VaR is not computed, Instead, the partial expectation of the lower tail is computed by numerical integration of x * pdf(x). Currently the quantile function is required anyway, via argument qf, to compute the upper limit of the integral. So, this case is mainly for testing and comparison purposes.

A bunch of expected shortfalls is computed if argument p_loss or any of the arguments in "..." are of length greater than one. They are recycled to equal length, if necessary, using the normal R recycling rules.

intercept and slope can be used to compute the expected shortfall for the location-scale transformation Y = intercept + slope * X, where the distribution of X is as specified by the other parameters and Y is the variable of interest. The expected shortfall of X is calculated and then transformed to that of Y. Note that the distribution of X doesn't need to be standardised, although it typically will.

The intercept and the slope can be vectors. Using them may be particularly useful for cheap calculations in, for example, forecasting, where the predictive distributions are often from the same family, but with different location and scale parameters. Conceptually, the described treatment of intercept and slope is equivalent to recycling them along with the other arguments, but more efficiently.

The names, intercept and slope, for the location and scale parameters were chosen for their expressiveness and to minimise the possibility for a clash with parameters of dist (e.g., the Gamma distribution has parameter scale).

When argument dist represents log-returns, ES is for the log-returns. Use transf = TRUE to return its value for the returns. Note that the ES of the returns cannot be obtained by exponentiating the ES for the log-returns.

Value

a numeric vector or matrix

See Also

VaR for VaR,

predict for examples with fitted models

Examples

ES(qnorm)

## Gaussian
ES(qnorm, dist.type = "qf")
ES(pnorm, dist.type = "cdf")

## t-dist
ES(qt, dist.type = "qf", df = 4)
ES(pt, dist.type = "cdf", df = 4)

ES(pnorm, 0.95, dist.type = "cdf")
ES(qnorm, 0.95, dist.type = "qf")
## - VaRES::esnormal(0.95, 0, 1)
## - PerformanceAnalytics::ETL(p=0.05, method = "gaussian", mu = 0,
##                             sigma = 1, weights = 1)             # same

cvar::ES(pnorm, dist.type = "cdf")
cvar::ES(qnorm, dist.type = "qf")
cvar::ES(pnorm, 0.05, dist.type = "cdf")
cvar::ES(qnorm, 0.05, dist.type = "qf")

## this uses "pdf"
cvar::ES(dnorm, 0.05, dist.type = "pdf", qf = qnorm)


## this gives warning (it does more than simply computing ES):
## PerformanceAnalytics::ETL(p=0.95, method = "gaussian", mu = 0, sigma = 1, weights = 1)

## run this if VaRRES is present
## Not run: 
x <- seq(0.01, 0.99, length = 100)
y <- sapply(x, function(p) cvar::ES(qnorm, p, dist.type = "qf"))
yS <- sapply(x, function(p) - VaRES::esnormal(p))
plot(x, y)
lines(x, yS, col = "blue")

## End(Not run)

cvar documentation built on Dec. 17, 2025, 9:07 a.m.