factorModelEsDecomposition: Compute Factor Model ES Decomposition
In R-Finance/FactorAnalytics: factor analysis

Description Usage Arguments Details Value Author(s) References Examples

Compute the factor model factor expected shortfall (ES) decomposition for an asset based on Euler's theorem given historic or simulated data and factor model parameters. The partial derivative of ES with respect to factor beta is computed as the expected factor return given fund return is less than or equal to its value-at-risk (VaR). VaR is compute as the sample quantile of the historic or simulated data.

1
2
3

  factorModelEsDecomposition(Data, beta.vec, sig2.e,
    tail.prob = 0.05,
    VaR.method = c("modified", "gaussian", "historical", "kernel"))

`Data`	`B x (k+2)` matrix of historic or simulated data. The first column contains the fund returns, the second through `k+1`st columns contain the returns on the `k` factors, and the `(k+2)`nd column contain residuals scaled to have unit variance.
`beta.vec`	`k x 1` vector of factor betas.
`sig2.e`	scalar, residual variance from factor model.
`tail.prob`	scalar, tail probability for VaR quantile. Typically 0.01 or 0.05.
`VaR.method`	character, method for computing VaR. Valid choices are one of "modified","gaussian","historical", "kernel". computation is done with the `VaR` in the PerformanceAnalytics package.

The factor model has the form
R(t) = beta'F(t) + e(t) = beta.star'F.star(t)
where beta.star = (beta, sig.e)' and F.star(t) = (F(t)', z(t))' By Euler's theorem:
ES.fm = sum(cES.fm) = sum(beta.star*mES.fm)

A list with the following components:

VaR Scalar, nonparametric VaR value for fund reported as a positive number.
n.exceed Scalar, number of observations beyond VaR.
idx.exceed n.exceed x 1 vector giving index values of exceedences.
ES.fm Scalar. nonparametric ES value for fund reported as a positive number.
mES.fm (K+1) x 1 vector of factor marginal contributions to ES.
cES.fm (K+1) x 1 vector of factor component contributions to ES.
pcES.fm (K+1) x 1 vector of factor percentage component contributions to ES.

Eric Zviot and Yi-An Chen.

Hallerback (2003), "Decomposing Portfolio Value-at-Risk: A General Analysis", The Journal of Risk 5/2.
Yamai and Yoshiba (2002)."Comparative Analyses of Expected Shortfall and Value-at-Risk: Their Estimation Error, Decomposition, and Optimization Bank of Japan.
Meucci (2007). "Risk Contributions from Generic User-Defined Factors," Risk.
Epperlein and Smillie (2006) "Cracking VAR with Kernels," Risk.

data(managers.df)
fit.macro <- fitTimeSeriesFactorModel(assets.names=colnames(managers.df[,(1:6)]),
                                     factors.names=c("EDHEC.LS.EQ","SP500.TR"),
                                     data=managers.df,fit.method="OLS")
# risk factor contribution to ETL
# combine fund returns, factor returns and residual returns for HAM1
tmpData = cbind(managers.df[,1],managers.df[,c("EDHEC.LS.EQ","SP500.TR")] ,
residuals(fit.macro$asset.fit$HAM1)/sqrt(fit.macro$resid.variance[1]))
colnames(tmpData)[c(1,4)] = c("HAM1", "residual")
factor.es.decomp.HAM1 = factorModelEsDecomposition(tmpData, fit.macro$beta[1,],
                                                  fit.macro$resid.variance[1], tail.prob=0.05,
                                                  VaR.method="historical" )

# fundamental factor model
# try to find factor contribution to ES for STI
data(Stock.df)
fit.fund <- fitFundamentalFactorModel(exposure.names=c("BOOK2MARKET", "LOG.MARKETCAP")
                                      , data=stock,returnsvar = "RETURN",datevar = "DATE",
                                     assetvar = "TICKER",
                                      wls = TRUE, regression = "classic",
                                      covariance = "classic", full.resid.cov = FALSE)
 idx <- fit.fund$data[,fit.fund$assetvar]  == "STI"
asset.ret <- fit.fund$data[idx,fit.fund$returnsvar]
tmpData = cbind(asset.ret, fit.fund$factor.returns,
                fit.fund$residuals[,"STI"]/sqrt(fit.fund$resid.variance["STI"]) )
colnames(tmpData)[c(1,length(tmpData[1,]))] = c("STI", "residual")
factorModelEsDecomposition(tmpData,
                          fit.fund$beta["STI",],
                          fit.fund$resid.variance["STI"], tail.prob=0.05,VaR.method="historical")