[Returnanalytics-commits] r1905 - pkg/PerformanceAnalytics/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Apr 21 21:23:14 CEST 2012
Author: braverock
Date: 2012-04-21 21:23:13 +0200 (Sat, 21 Apr 2012)
New Revision: 1905
Modified:
pkg/PerformanceAnalytics/R/CalmarRatio.R
pkg/PerformanceAnalytics/R/CoMoments.R
pkg/PerformanceAnalytics/R/DownsideDeviation.R
pkg/PerformanceAnalytics/R/ES.R
pkg/PerformanceAnalytics/R/Return.clean.R
pkg/PerformanceAnalytics/R/Return.portfolio.R
pkg/PerformanceAnalytics/R/SharpeRatio.R
pkg/PerformanceAnalytics/R/StdDev.R
pkg/PerformanceAnalytics/R/StdDev.annualized.R
pkg/PerformanceAnalytics/R/UpsidePotentialRatio.R
pkg/PerformanceAnalytics/R/VaR.R
pkg/PerformanceAnalytics/R/chart.Histogram.R
pkg/PerformanceAnalytics/R/expectedShortFallFunctions.r
pkg/PerformanceAnalytics/R/findDrawdowns.R
pkg/PerformanceAnalytics/R/maxDrawdown.R
pkg/PerformanceAnalytics/R/skewness.R
pkg/PerformanceAnalytics/R/sortDrawdowns.R
pkg/PerformanceAnalytics/R/table.Arbitrary.R
pkg/PerformanceAnalytics/R/table.MonthlyReturns.R
pkg/PerformanceAnalytics/R/table.RollingPeriods.R
pkg/PerformanceAnalytics/R/textplot.R
pkg/PerformanceAnalytics/R/zerofill.R
Log:
- additional movement towards converting PerfA to use roxygen2 for documentation
Modified: pkg/PerformanceAnalytics/R/CalmarRatio.R
===================================================================
--- pkg/PerformanceAnalytics/R/CalmarRatio.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/CalmarRatio.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -1,5 +1,7 @@
#' calculate a Calmar or Sterling reward/risk ratio
#'
+#' @aliases SterlingRatio
+#'
#' Calmar and Sterling Ratios are yet another method of creating a
#' risk-adjusted measure for ranking investments similar to the
#' \code{\link{SharpeRatio}}.
@@ -75,6 +77,8 @@
return(result)
}
+#' @export
+#' @rdname CalmarRatio
SterlingRatio <-
function (R, scale=NA, excess=.1)
{ # @author Brian G. Peterson
Modified: pkg/PerformanceAnalytics/R/CoMoments.R
===================================================================
--- pkg/PerformanceAnalytics/R/CoMoments.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/CoMoments.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -1,5 +1,62 @@
# Compute co-moment matrices
+
+
+#' calculate centered Returns
+#'
+#' the \eqn{n}-th centered moment is calculated as \deqn{ }{moment^n(R) =
+#' E[R-E(R)^n]}\deqn{ \mu^{(n)}(R) = E\lbrack(R-E(R))^n\rbrack }{moment^n(R) =
+#' E[R-E(R)^n]}
+#'
+#' These functions are used internally by PerformanceAnalytics to calculate
+#' centered moments for a multivariate distribution as well as the standardized
+#' moments of a portfolio distribution. They are exposed here for users who
+#' wish to use them directly, and we'll get more documentation written when we
+#' can.
+#'
+#' These functions were first utilized in Boudt, Peterson, and Croux (2008),
+#' and have been subsequently used in our other research.
+#'
+#' ~~ Additional Details will be added to documentation as soon as we have time
+#' to write them. Documentation Patches Welcome. ~~
+#'
+#' @aliases centeredcomoment centeredmoment Return.centered
+#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
+#' asset returns
+#' @param Ra an xts, vector, matrix, data frame, timeSeries or zoo object of
+#' asset returns
+#' @param Rb an xts, vector, matrix, data frame, timeSeries or zoo object of
+#' index, benchmark, portfolio, or secondary asset returns to compare against
+#' @param power power or moment to calculate
+#' @param p1 first power of the comoment
+#' @param p2 second power of the comoment
+#' @param normalize whether to standardize the calculation to agree with common
+#' usage, or leave the default mathematical meaning
+#' @param \dots any other passthru parameters
+#' @author Kris Boudt and Brian Peterson
+#' @references Boudt, Kris, Brian G. Peterson, and Christophe Croux. 2008.
+#' Estimation and Decomposition of Downside Risk for Portfolios with Non-Normal
+#' Returns. Journal of Risk. Winter.
+#'
+#' Martellini, Lionel, and Volker Ziemann. 2007. Improved Forecasts of
+#' Higher-Order Comoments and Implications for Portfolio Selection. EDHEC Risk
+#' and Asset Management Research Centre working paper.
+#'
+#' Ranaldo, Angelo, and Laurent Favre Sr. 2005. How to Price Hedge Funds: From
+#' Two- to Four-Moment CAPM. SSRN eLibrary.
+#'
+#' Scott, Robert C., and Philip A. Horvath. 1980. On the Direction of
+#' Preference for Moments of Higher Order than the Variance. Journal of Finance
+#' 35(4):915-919.
+#' @keywords ts multivariate distribution models
+#' @examples
+#'
+#'
+#' data(managers)
+#' Return.centered(managers[,1:3,drop=FALSE])
+#'
+#' @rdname centeredmoments
+#' @export
Return.centered <-
function (R,...)
{ # @author Peter Carl and Kris Boudt
@@ -279,4 +336,4 @@
#
# $Id$
#
-###############################################################################
\ No newline at end of file
+###############################################################################
Modified: pkg/PerformanceAnalytics/R/DownsideDeviation.R
===================================================================
--- pkg/PerformanceAnalytics/R/DownsideDeviation.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/DownsideDeviation.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -47,7 +47,7 @@
#' future, we'll add a fitted option to this function, and would be happy to
#' accept a contribution of this nature.
#'
-#' @aliases DownsideDeviation SemiDeviation SemiVariance
+#' @aliases DownsideDeviation SemiDeviation SemiVariance DownsidePotential
#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
#' asset returns
#' @param MAR Minimum Acceptable Return, in the same periodicity as your
@@ -55,6 +55,9 @@
#' @param method one of "full" or "subset", indicating whether to use the
#' length of the full series or the length of the subset of the series below
#' the MAR as the denominator, defaults to "subset"
+#' @param \dots any other passthru parameters
+#' @param potential if TRUE, calculate downside potential instead, default
+#' FALSE
#' @author Peter Carl, Brian G. Peterson
#' @references Sortino, F. and Price, L. Performance Measurement in a Downside
#' Risk Framework. \emph{Journal of Investing}. Fall 1994, 59-65. \cr
@@ -70,7 +73,7 @@
#' @examples
#'
#' data(managers)
-#' sd.xts(managers[,1:6], na.rm=TRUE)
+#' apply(managers[,1:6], 2, sd, na.rm=TRUE)
#' DownsideDeviation(managers[,1:6]) # MAR 0%
#' DownsideDeviation(managers[,1:6], MAR = .04/12) #MAR 4%
#' SemiDeviation(managers[,1,drop=FALSE])
Modified: pkg/PerformanceAnalytics/R/ES.R
===================================================================
--- pkg/PerformanceAnalytics/R/ES.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/ES.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -6,11 +6,13 @@
#' univariate and component, using a variety of analytical methods.
#'
#' Calculates Expected Shortfall(ES) (also known as) Conditional Value at
-#' Risk(CVaR) for univariate, component, and marginal cases using a variety of
-#' analytical methods.
+#' Risk(CVaR) or Expected Tail Loss (ETL) for univariate, component,
+#' and marginal cases using a variety of analytical methods.
#'
#'
+#' @export
#' @aliases ES CVaR ETL
+#' @rdname ES
#' @param R a vector, matrix, data frame, timeSeries or zoo object of asset
#' returns
#' @param p confidence level for calculation, default p=.95
Modified: pkg/PerformanceAnalytics/R/Return.clean.R
===================================================================
--- pkg/PerformanceAnalytics/R/Return.clean.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/Return.clean.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -93,6 +93,8 @@
+
+
#' clean extreme observations in a time series to to provide more robust risk
#' estimates
#'
@@ -119,8 +121,8 @@
#' \eqn{n}-dimensional vector time series of length \eqn{T}: \eqn{r_1,...,r_T}.
#' We clean this time series in three steps.
#'
-#' \describe{ \item{ Ranking the observations in function of their
-#' extremeness:}{Denote \eqn{\mu} and \eqn{\Sigma} the mean and covariance
+#' \enumerate{ \item \emph{ Ranking the observations in function of their
+#' extremeness. }Denote \eqn{\mu} and \eqn{\Sigma} the mean and covariance
#' matrix of the bulk of the data and let \eqn{\lfloor \cdot \rfloor}{floor()}
#' be the operator that takes the integer part of its argument. As a measure of
#' the extremeness of the return observation \eqn{r_t}, we use its squared
@@ -132,27 +134,29 @@
#' smallest. These estimates will be robust against the \eqn{\alpha} most
#' extreme returns. Let \eqn{d^2_{(1)},...,d^2_{(T)}} be the ordered sequence
#' of the estimated squared Mahalanobis distances such that \eqn{d^2_{(i)}\leq
-#' d^2_{(i+1)}}.}
+#' d^2_{(i+1)}}.
#'
-#' \item{Outlier identification:}{Return observations are qualified as outliers
-#' if their estimated squared Mahalanobis distance \eqn{d^2_t} is greater than
-#' the empirical \eqn{1-\alpha} quantile \eqn{d^2_{(\lfloor (1-\alpha)T
-#' \rfloor)}}{floor((1-\alpha)T)} and exceeds a very extreme quantile of the
-#' Chi squared distribution function with \eqn{n} degrees of freedom, which is
-#' the distribution function of \eqn{d^2_t} when the returns are normally
-#' distributed. In this application we take the 99.9% quantile, denoted
-#' \eqn{\chi^2_{n,0.999}}.}
+#' \item \emph{Outlier identification.} Return observations are qualified as
+#' outliers if their estimated squared Mahalanobis distance \eqn{d^2_t} is
+#' greater than the empirical \eqn{1-\alpha} quantile \eqn{d^2_{(\lfloor
+#' (1-\alpha)T \rfloor)}}{floor((1-\alpha)T)} and exceeds a very extreme
+#' quantile of the Chi squared distribution function with \eqn{n} degrees of
+#' freedom, which is the distribution function of \eqn{d^2_t} when the returns
+#' are normally distributed. In this application we take the 99.9% quantile,
+#' denoted \eqn{\chi^2_{n,0.999}}.
#'
-#' \item{Data cleaning:}{Similarly to Khan(2007) we only clean the returns that
-#' are identified as outliers in step 2 by replacing these returns \eqn{r_t}
-#' with \deqn{r_t\sqrt{\frac{\max(d^2_{(\lfloor }{r_t *
+#' \item \emph{Data cleaning. } Similarly to Khan(2007) we only clean the
+#' returns that are identified as outliers in step 2 by replacing these returns
+#' \eqn{r_t} with \deqn{r_t\sqrt{\frac{\max(d^2_{(\lfloor }{r_t *
#' sqrt(max(d^2_floor((1-\alpha)T),\chi^2_{n,0.999})/d^2_t)}\deqn{(1-\alpha)T)\rfloor},\chi^2_{n,0.999})}{d^2_t}}}{r_t
#' * sqrt(max(d^2_floor((1-\alpha)T),\chi^2_{n,0.999})/d^2_t)} The cleaned
#' return vector has the same orientation as the original return vector, but
#' its magnitude is smaller. Khan(2007) calls this procedure of limiting the
#' value of \eqn{d^2_t} to a quantile of the \eqn{\chi^2_n} distribution,
-#' ``multivariate Winsorization'.} }
+#' ``multivariate Winsorization'.
#'
+#' }
+#'
#' Note that the primary value of data cleaning lies in creating a more robust
#' and stable estimation of the distribution generating the large majority of
#' the return data. The increased robustness and stability of the estimated
Modified: pkg/PerformanceAnalytics/R/Return.portfolio.R
===================================================================
--- pkg/PerformanceAnalytics/R/Return.portfolio.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/Return.portfolio.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -43,6 +43,8 @@
# Return.portfolio
+
+
#' Calculates weighted returns for a portfolio of assets
#'
#' Calculates weighted returns for a portfolio of assets. If you have a single
Modified: pkg/PerformanceAnalytics/R/SharpeRatio.R
===================================================================
--- pkg/PerformanceAnalytics/R/SharpeRatio.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/SharpeRatio.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -37,7 +37,9 @@
#' @param Rf risk free rate, in same period as your returns
#' @param p confidence level for calculation, default p=.95
#' @param FUN one of "StdDev" or "VaR" or "ES" to use as the denominator
-#' @param weights portfolio weighting vector, default NULL
+#' @param weights portfolio weighting vector, default NULL, see Details in
+#' \code{\link{VaR}}
+#' @param annualize if TRUE, annualize the measure, default FALSE
#' @param \dots any other passthru parameters to the VaR or ES functions
#' @author Brian G. Peterson
#' @seealso \code{\link{SharpeRatio.annualized}} \cr
@@ -71,6 +73,10 @@
#' SharpeRatio(managers[,1:9], Rf = managers[,10,drop=FALSE])
#' SharpeRatio(edhec,Rf = .04/12)
#'
+#' @export
+#' @rdname SharpeRatio
+#'
+#'
SharpeRatio <-
function (R, Rf = 0, p = 0.95, FUN=c("StdDev", "VaR","ES"), weights=NULL, annualize = FALSE , ...)
{ # @author Brian G. Peterson
@@ -167,6 +173,8 @@
return (result)
}
+#' @export
+#' @rdname SharpeRatio
SharpeRatio.modified <-
function (R, Rf = 0, p = 0.95, FUN=c("StdDev", "VaR","ES"), weights=NULL, ...) {
.Deprecated("SharpeRatio", package="PerformanceAnalytics", "The SharpeRatio.modified function has been deprecated in favor of a newer SharpeRatio wrapper that will cover both the classic case and a larger suite of modified Sharpe Ratios. This deprecated function may be removed from future versions")
Modified: pkg/PerformanceAnalytics/R/StdDev.R
===================================================================
--- pkg/PerformanceAnalytics/R/StdDev.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/StdDev.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -4,6 +4,8 @@
+
+
#' calculates Standard Deviation for univariate and multivariate series, also
#' calculates component contribution to standard deviation of a portfolio
#'
@@ -45,6 +47,14 @@
#' @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 use an optional character string giving a method for computing
+#' covariances in the presence of missing values. This must be (an
+#' abbreviation of) one of the strings \code{"everything"}, \code{"all.obs"},
+#' \code{"complete.obs"}, \code{"na.or.complete"}, or
+#' \code{"pairwise.complete.obs"}.
+#' @param method a character string indicating which correlation coefficient
+#' (or covariance) is to be computed. One of \code{"pearson"} (default),
+#' \code{"kendall"}, or \code{"spearman"}, can be abbreviated.
#' @author Brian G. Peterson and Kris Boudt
#' @seealso \code{\link{Return.clean}} \code{sd}
#' @keywords ts multivariate distribution models
Modified: pkg/PerformanceAnalytics/R/StdDev.annualized.R
===================================================================
--- pkg/PerformanceAnalytics/R/StdDev.annualized.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/StdDev.annualized.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -29,6 +29,7 @@
#' asset returns
#' @param scale number of periods in a year (daily scale = 252, monthly scale =
#' 12, quarterly scale = 4)
+#' @param \dots any other passthru parameters
#' @author Brian G. Peterson
#' @seealso \code{\link[stats]{sd}} \cr
#' \url{http://wikipedia.org/wiki/inverse-square_law}
@@ -43,7 +44,9 @@
#' # now for three periods:
#' sd.multiperiod(edhec[,6,drop=FALSE],scale=3)
#'
-sd.multiperiod <-
+#' @export
+#' @rdname StdDev.annualized
+StdDev.annualized <- sd.annualized <- sd.multiperiod <-
function (x, scale = NA, ...)
{
if (is.vector(x)) {
@@ -73,18 +76,6 @@
}
}
-sd.annualized <-
-function (x, scale = NA, ...)
-{ # wrapper function for backwards compatibility
- sd.multiperiod(x, scale = scale)
-}
-
-StdDev.annualized <-
-function (R, scale = NA, ...)
-{ # wrapper function for backwards compatibility
- sd.multiperiod(R, scale = scale)
-}
-
###############################################################################
# R (http://r-project.org/) Econometrics for Performance and Risk Analysis
#
Modified: pkg/PerformanceAnalytics/R/UpsidePotentialRatio.R
===================================================================
--- pkg/PerformanceAnalytics/R/UpsidePotentialRatio.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/UpsidePotentialRatio.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -8,7 +8,19 @@
#' denominator of the ratio equation.
#'
+
+
+#' calculate Upside Potential Ratio of upside performance over downside risk
#'
+#' Sortino proposed an improvement on the Sharpe Ratio to better account for
+#' skill and excess performance by using only downside semivariance as the
+#' measure of risk. That measure is the \code{\link{SortinoRatio}}. This
+#' function, Upside Potential Ratio, was a further improvement, extending the
+#' measurement of only upside on the numerator, and only downside of the
+#' denominator of the ratio equation.
+#'
+
+#'
#' Sortino contends that risk should be measured in terms of not meeting the
#' investment goal. This gives rise to the notion of \dQuote{Minimum
#' Acceptable Return} or MAR. All of Sortino's proposed measures include the
Modified: pkg/PerformanceAnalytics/R/VaR.R
===================================================================
--- pkg/PerformanceAnalytics/R/VaR.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/VaR.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -4,6 +4,8 @@
+
+
#' calculate various Value at Risk (VaR) measures
#'
#' Calculates Value-at-Risk(VaR) for univariate, component, and marginal cases
@@ -45,7 +47,6 @@
#' The prototype of the univariate Cornish Fisher VaR function was completed by
#' Prof. Diethelm Wuertz. All corrections to the calculation and error
#' handling are the fault of Brian Peterson.
-#'
#' @section Background: This function provides several estimation methods for
#' the Value at Risk (typically written as VaR) of a return series and the
#' Component VaR of a portfolio. Take care to capitalize VaR in the commonly
Modified: pkg/PerformanceAnalytics/R/chart.Histogram.R
===================================================================
--- pkg/PerformanceAnalytics/R/chart.Histogram.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/chart.Histogram.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -20,12 +20,12 @@
#' the number of cells (see \sQuote{Details}), \item a function to compute the
#' number of cells. } In the last three cases the number is a suggestion only.
#' see \code{\link[graphics]{hist}} for details, default "FD"
-#' @param methods what to graph, one or more of: \describe{ \item{add.density}{
-#' to display the density plot} \item{add.normal}{ to display a fitted normal
-#' distibution line over the mean} \item{add.centered}{ to display a fitted
-#' normal line over zero} \item{add.rug}{ to display a rug of the observations}
-#' \item{add.risk}{ to display common risk metrics} \item{add.qqplot}{ to
-#' display a small qqplot in the upper corner of the histogram plot} }
+#' @param methods what to graph, one or more of: \itemize{ \itemadd.density to
+#' display the density plot \itemadd.normal to display a fitted normal
+#' distibution line over the mean \itemadd.centered to display a fitted normal
+#' line over zero \itemadd.rug to display a rug of the observations
+#' \itemadd.risk to display common risk metrics \itemadd.qqplot to display a
+#' small qqplot in the upper corner of the histogram plot }
#' @param p confidence level for calculation, default p=.99
#' @param probability logical; if TRUE, the histogram graphic is a
#' representation of frequencies, the counts component of the result; if FALSE,
Modified: pkg/PerformanceAnalytics/R/expectedShortFallFunctions.r
===================================================================
--- pkg/PerformanceAnalytics/R/expectedShortFallFunctions.r 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/expectedShortFallFunctions.r 2012-04-21 19:23:13 UTC (rev 1905)
@@ -54,6 +54,118 @@
if ( tail.prob < 0 || tail.prob > 1)
stop("tail.prob must be between 0 and 1")
+
+
+#' 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) for univariate, component, and marginal cases using a variety of
+#' analytical methods.
+#'
+#'
+#' @aliases ES CVaR ETL
+#' @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", "kernel", 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
+#' @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)
+#' orConditional 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 Brian G. Peterson and Kris Boudt
+#' @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)
+#'
+#' # first do normal ES calc
+#' ES(edhec, p=.95, method="historical")
+#'
+#' # now use Gaussian
+#' ES(edhec, p=.95, method="gaussian")
+#'
+#' # now use modified Cornish Fisher calc to take non-normal distribution into account
+#' ES(edhec, p=.95, method="modified")
+#'
+#' # now use p=.99
+#' ES(edhec, p=.99)
+#' # or the equivalent alpha=.01
+#' ES(edhec, p=.01)
+#'
+#' # now with outliers squished
+#' ES(edhec, clean="boudt")
+#'
+#' # add Component ES for the equal weighted portfolio
+#' ES(edhec, clean="boudt", portfolio_method="component")
+#'
ES = mu - sigma*dnorm(qnorm(tail.prob))/tail.prob
return(-ES)
}
Modified: pkg/PerformanceAnalytics/R/findDrawdowns.R
===================================================================
--- pkg/PerformanceAnalytics/R/findDrawdowns.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/findDrawdowns.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -8,9 +8,9 @@
#' \code{Drawdowns} will calculate the drawdown levels as percentages, for use
#' in \code{\link{chart.Drawdown}}.
#'
-#' Returns an unordered list: \cr \describe{ \item{return }{depth of drawdown}
-#' \item{from }{starting period} \item{to }{ending period} \item{length
-#' }{length in periods} }
+#' Returns an unordered list: \cr \itemize{ \itemreturn depth of drawdown
+#' \itemfrom starting period \itemto ending period \itemlength length in
+#' periods }
#'
#' @aliases findDrawdowns Drawdowns
#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
Modified: pkg/PerformanceAnalytics/R/maxDrawdown.R
===================================================================
--- pkg/PerformanceAnalytics/R/maxDrawdown.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/maxDrawdown.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -79,6 +79,8 @@
+
+
#' Calculate Uryasev's proposed Conditional Drawdown at Risk (CDD or CDaR)
#' measure
#'
Modified: pkg/PerformanceAnalytics/R/skewness.R
===================================================================
--- pkg/PerformanceAnalytics/R/skewness.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/skewness.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -3,7 +3,14 @@
#' compute skewness of a univariate distribution.
#'
+
+
+#' Skewness
#'
+#' compute skewness of a univariate distribution.
+#'
+
+#'
#' This function was ported from the RMetrics package fUtilities to eliminate a
#' dependency on fUtiltiies being loaded every time. The function is identical
#' except for the addition of \code{\link{checkData} and column support.}
Modified: pkg/PerformanceAnalytics/R/sortDrawdowns.R
===================================================================
--- pkg/PerformanceAnalytics/R/sortDrawdowns.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/sortDrawdowns.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -3,9 +3,8 @@
#' sortDrawdowns(findDrawdowns(R)) Gives the drawdowns in order of worst to
#' best
#'
-#' Returns a sorted list: \describe{ \item{return }{depth of drawdown}
-#' \item{from }{starting period} \item{to }{ending period} \item{length
-#' }{length in periods} }
+#' Returns a sorted list: \itemize{ \itemreturn depth of drawdown \itemfrom
+#' starting period \itemto ending period \itemlength length in periods }
#'
#' @param runs pass in runs array from findDrawdowns to be sorted
#' @author Peter Carl \cr modified with permission from prototype function by
Modified: pkg/PerformanceAnalytics/R/table.Arbitrary.R
===================================================================
--- pkg/PerformanceAnalytics/R/table.Arbitrary.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/table.Arbitrary.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -9,8 +9,8 @@
#'
#' The idea here is to be able to pass in sets of metrics and values, like:
#'
-#' metrics = c(DownsideDeviation(x,MAR=mean(x)), sd.xts(subset(x,x>0)),
-#' sd.xts(subset(x,x<0)), DownsideDeviation(x,MAR=MAR),
+#' metrics = c(DownsideDeviation(x,MAR=mean(x)), sd(subset(x,x>0)),
+#' sd(subset(x,x<0)), DownsideDeviation(x,MAR=MAR),
#' DownsideDeviation(x,MAR=Rf=0), DownsideDeviation(x,MAR=0),maxDrawdown(x))
#'
#' metricsNames = c("Semi Deviation", "Gain Deviation", "Loss Deviation",
Modified: pkg/PerformanceAnalytics/R/table.MonthlyReturns.R
===================================================================
--- pkg/PerformanceAnalytics/R/table.MonthlyReturns.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/table.MonthlyReturns.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -9,7 +9,7 @@
#' to missing data or unequal time series should be given when intepreting the
#' results.
#'
-#' @aliases table.MonthlyReturns table.Stats
+#' @aliases table.Stats table.MonthlyReturns
#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
#' asset returns
#' @param ci confidence interval, defaults to 95%
@@ -27,6 +27,8 @@
#' textplot(format.df(result, na.blank=TRUE, numeric.dollar=FALSE, cdec=c(rep(1,2),rep(3,14))), rmar = 0.8, cmar = 1.5, max.cex=.9, halign = "center", valign = "top", row.valign="center", wrap.rownames=10, wrap.colnames=10, mar = c(0,0,3,0)+0.1)
#' title(main="Statistics for EDHEC Indexes")
#'
+#' @rdname table.MonthlyReturns
+#' @export
table.Stats <-
function (R, ci = 0.95, digits = 4)
{# @author Peter Carl
Modified: pkg/PerformanceAnalytics/R/table.RollingPeriods.R
===================================================================
--- pkg/PerformanceAnalytics/R/table.RollingPeriods.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/table.RollingPeriods.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -4,6 +4,11 @@
#'
#'
#' @aliases table.TrailingPeriods table.TrailingPeriodsRel table.RollingPeriods
+#'
+#' @export
+#'
+#' @rdname table.RollingPeriods
+#'
#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
#' asset returns
#' @param Rb an xts, vector, matrix, data frame, timeSeries or zoo object of
Modified: pkg/PerformanceAnalytics/R/textplot.R
===================================================================
--- pkg/PerformanceAnalytics/R/textplot.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/textplot.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -6,6 +6,8 @@
+
+
#' Display text information in a graphics plot.
#'
#' This function displays text output in a graphics window. It is the
Modified: pkg/PerformanceAnalytics/R/zerofill.R
===================================================================
--- pkg/PerformanceAnalytics/R/zerofill.R 2012-04-21 16:58:17 UTC (rev 1904)
+++ pkg/PerformanceAnalytics/R/zerofill.R 2012-04-21 19:23:13 UTC (rev 1905)
@@ -12,6 +12,8 @@
+
+
#' zerofill
#'
#' Fill NA's with zeros in a time series to allow analysis when the matrix must
More information about the Returnanalytics-commits
mailing list