ES {cvar}

Compute expected shortfall (ES) of distributions

Description

Compute the expected shortfall for a distribution.

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(),
  x
)

## S3 method for class 'numeric'
ES(
  dist,
  p_loss = 0.05,
  dist.type = "qf",
  qf,
  ...,
  intercept = 0,
  slope = 1,
  control = list(),
  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, see 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.

x

deprecated and will soon be removed. x was renamed to p_loss, please use the latter.

Details

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.

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 x 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).

Value

a numeric vector

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)