R/ES_SE.R

In chenx26/EstimatorStandardError: Risk/Performance Measure Estimator Standard Error

###############################################################################
# $Id$
###############################################################################

#' Calculates Expected Shortfall(ES) (or Conditional Value-at-Risk(CVaR) for
#' univariate and component, using a variety of analytical methods.
#'
#' Calculates Expected Shortfall(ES) (also known as) Conditional Value at
#' Risk(CVaR) or Expected Tail Loss (ETL) for univariate, component,
#' and marginal cases using a variety of analytical methods.
#' The standard error of the estimates can also be computed by supplying the
#' \code{se.method} parameter.
#' This function builds upon the same function in PerformanceAnalytics package by
#' adding functionalities to compute the standard errors of the point estimates.
#' The documentation involving computing the point estimate is due to corresponding
#' authors of the PerformanceAnalytics package.
#'
#'
#' @export
#' @aliases ES.SE CVaR.SE ETL.SE
#' @rdname ES.SE
#' @param R a vector, matrix, data frame, timeSeries or zoo object of asset
#' returns
#' @param p confidence level for calculation, default p=.95
#' @param method one of "modified","gaussian","historical", see
#' Details.
#' @param clean method for data cleaning through \code{\link{Return.clean}}.
#' Current options are "none", "boudt", or "geltner".
#' @param portfolio_method one of "single","component","marginal" defining
#' whether to do univariate, component, or marginal calc, see Details.
#' @param weights portfolio weighting vector, default NULL, see Details
#' @param mu If univariate, mu is the mean of the series. Otherwise mu is the
#' vector of means of the return series , default NULL, , see Details
#' @param sigma If univariate, sigma is the variance of the series. Otherwise
#' sigma is the covariance matrix of the return series , default NULL, see
#' Details
#' @param m3 If univariate, m3 is the skewness of the series. Otherwise m3 is
#' the coskewness matrix of the returns series, default NULL, see Details
#' @param m4 If univariate, m4 is the excess kurtosis of the series. Otherwise
#' m4 is the cokurtosis matrix of the return series, default NULL, see Details
#' @param invert TRUE/FALSE whether to invert the VaR measure.  see Details.
#' @param operational TRUE/FALSE, default TRUE, see Details.
#' @param \dots any other passthru parameters. This include two types of parameters.
#' The first type is parameters associated with the risk/performance measure, such as tail
#' probability for VaR and ES. The second type is the parameters associated with the metohd
#' used to compute the standard error. See \code{\link{SE.IF.iid}}, \code{\link{SE.IF.cor}},
#' \code{\link{SE.BOOT.iid}}, \code{\link{SE.BOOT.cor}} for details.
#' @param se.method a character string indicating which method should be used to compute
#' the standard error of the estimated standard deviation. One of \code{"none"} (default),
#' \code{"IFiid"}, \code{"IFcor"}, \code{"BOOTiid"}, \code{"BOOTcor"}. Currently, it works
#' only when \code{method="historical"} and \code{portfolio_method="single"}.
#' @note The option to \code{invert} the ES measure should appease both
#' academics and practitioners.  The mathematical definition of ES as the
#' negative value of extreme losses will (usually) produce a positive number.
#' Practitioners will argue that ES denotes a loss, and should be internally
#' consistent with the quantile (a negative number).  For tables and charts,
#' different preferences may apply for clarity and compactness.  As such, we
#' provide the option, and set the default to TRUE to keep the return
#' consistent with prior versions of PerformanceAnalytics, but make no value
#' judgement on which approach is preferable.
#' @section Background: This function provides several estimation methods for
#' the Expected Shortfall (ES) (also called Expected Tail Loss (ETL)
#' or Conditional Value at Risk (CVaR)) of a return series and the Component ES
#' (ETL/CVaR) of a portfolio.
#'
#' At a preset probability level denoted \eqn{c}, which typically is between 1
#' and 5 per cent, the ES of a return series is the negative value of the
#' expected value of the return when the return is less than its
#' \eqn{c}-quantile.  Unlike value-at-risk, conditional value-at-risk has all
#' the properties a risk measure should have to be coherent and is a convex
#' function of the portfolio weights (Pflug, 2000).  With a sufficiently large
#' data set, you may choose to estimate ES with the sample average of all
#' returns that are below the \eqn{c} empirical quantile. More efficient
#' estimates of VaR are obtained if a (correct) assumption is made on the
#' return distribution, such as the normal distribution. If your return series
#' is skewed and/or has excess kurtosis, Cornish-Fisher estimates of ES can be
#' more appropriate. For the ES of a portfolio, it is also of interest to
#' decompose total portfolio ES into the risk contributions of each of the
#' portfolio components. For the above mentioned ES estimators, such a
#' decomposition is possible in a financially meaningful way.
#' @author Xin Chen, \email{chenx26@uw.edu}
#' @seealso \code{\link{VaR}} \cr \code{\link{SharpeRatio.modified}} \cr
#' \code{\link{chart.VaRSensitivity}} \cr \code{\link{Return.clean}}
#'
#' @references Boudt, Kris, Peterson, Brian, and Christophe Croux. 2008.
#' Estimation and decomposition of downside risk for portfolios with non-normal
#' returns. 2008. The Journal of Risk, vol. 11, 79-103.
#'
#' Cont, Rama, Deguest, Romain and Giacomo Scandolo. Robustness and sensitivity
#' analysis of risk measurement procedures. Financial Engineering Report No.
#' 2007-06, Columbia University Center for Financial Engineering.
#'
#' Laurent Favre and Jose-Antonio Galeano. Mean-Modified Value-at-Risk
#' Optimization with Hedge Funds. Journal of Alternative Investment, Fall 2002,
#' v 5.
#'
#' Martellini, Lionel, and Volker Ziemann.  Improved Forecasts of Higher-Order
#' Comoments and Implications for Portfolio Selection. 2007. EDHEC Risk and
#' Asset Management Research Centre working paper.
#'
#' Pflug, G. Ch.  Some remarks on the value-at-risk and the conditional
#' value-at-risk. In S. Uryasev, ed., Probabilistic Constrained Optimization:
#' Methodology and Applications, Dordrecht: Kluwer, 2000, 272-281.
#'
#' Scaillet, Olivier. Nonparametric estimation and sensitivity analysis of
#' expected shortfall. Mathematical Finance, 2002, vol. 14, 74-86.
###keywords ts multivariate distribution models
#' @examples
#'
#'     data(edhec)
#'     ############### NEW USAGE: Computing Point Estimate and Standard Error at the same time
#'     # use more than one method at the same time
#'     res=ES.SE(edhec, p=.95, method="historical",
#'     se.method = c("IFiid","IFcor","BOOTiid","BOOTcor"))
#'     printSE(res)
#'
#'     ############### OLD USAGE: Computing Point Estimate Onlt
#'
#'     # now use Gaussian
#'     ES.SE(edhec, p=.95, method="gaussian")
#'
#'     # now use modified Cornish Fisher calc to take non-normal distribution into account
#'     ES.SE(edhec, p=.95, method="modified")
#'
#'     # now use p=.99
#'     ES.SE(edhec, p=.99)
#'     # or the equivalent alpha=.01
#'     ES.SE(edhec, p=.01)
#'
#'     # now with outliers squished
#'     ES.SE(edhec, clean="boudt")
#'
#'     # add Component ES for the equal weighted portfolio
#'     ES.SE(edhec, clean="boudt", portfolio_method="component")
#' @export ES.SE ETL.SE CVaR.SE
ES.SE <- CVaR.SE <- ETL.SE <- function (R=NULL , p=0.95, ...,
                               method=c("modified","gaussian","historical"),
                               clean=c("none","boudt", "geltner"),
                               portfolio_method=c("single","component"),
                               weights=NULL, mu=NULL, sigma=NULL, m3=NULL, m4=NULL,
                               invert=TRUE, operational=TRUE,
                               se.method="none")
{ # @author Brian G. Peterson and Xin Chen

  # Descripion:

  # wrapper for univariate and multivariate ES functions.

  # Setup:
  #if(exists(modified)({if( modified == TRUE) { method="modified" }}
  #if(method == TRUE or is.null(method) ) { method="modified" }
  myES=ES(R=R , p=p, ...,
          method=method,
          clean=clean,
          portfolio_method=portfolio_method,
          weights=weights, mu=mu, sigma=sigma, m3=m3, m4=m4,
          invert=invert, operational=operational)

  # se.method=se.method[1]
  # SE=NULL
  method = method[1]
  clean = clean[1]
  portfolio_method = portfolio_method[1]
  if(portfolio_method == "single" & is.null(weights) & method == "historical"){
    if(!is.null(R)){
      R <- checkData(R, method="xts", ...)
      columns=colnames(R)
      if (!is.null(weights) & portfolio_method != "single") {
        if ( length(weights) != ncol(R)) {
          stop("number of items in weights not equal to number of columns in R")
        }
      }
      # weights = checkData(weights, method="matrix", ...) #is this necessary?
      # TODO check for date overlap with R and weights
      if(clean!="none" & is.null(mu)){ # the assumption here is that if you've passed in any moments, we'll leave R alone
        R = as.matrix(Return.clean(R, method=clean))
      }
      if(portfolio_method != "single"){
        # get the moments ready
        if (is.null(mu)) { mu =  apply(R,2,'mean' ) }
        if (is.null(sigma)) { sigma = cov(R) }
        if(method=="modified"){
          if (is.null(m3)) {m3 = M3.MM(R,mu=mu)}
          if (is.null(m4)) {m4 = M4.MM(R,mu=mu)}
        }
      }
    } else {
      #R is null, check for moments
      if(is.null(mu)) stop("Nothing to do! You must pass either R or the moments mu, sigma, etc.")
      if ( length(weights) != length(mu)) {
        stop("number of items in weights not equal to number of items in the mean vector")
      }
    }
    if(se.method[1] == "none" & length(se.method)==1){
      return(myES)
    } else {
      res=list(ES=myES)
      # for each of the method specified in se.method, compute the standard error
      for(mymethod in se.method){
        res[[mymethod]]=EstimatorSE(R, ..., estimator.fun = "ES", se.method = mymethod, alpha.ES = 1-p)
      }
      return(res)
    }
  }
} # end ES.SE wrapper function

###############################################################################
# R (http://r-project.org/) Econometrics for Performance and Risk Analysis
#
# Copyright (c) 2004-2015 Peter Carl and Brian G. Peterson
#
# This R package is distributed under the terms of the GNU Public License (GPL)
# for full details see the file COPYING
#
# $Id$
#
###############################################################################