[Returnanalytics-commits] r1989 - pkg/PerformanceAnalytics/R

[noreply at r-forge.r-project.org]

Author: matthieu_lestel
Date: 2012-06-06 20:18:50 +0200 (Wed, 06 Jun 2012)
New Revision: 1989

Modified:
   pkg/PerformanceAnalytics/R/DownsideDeviation.R
Log:
Documentation of DownsideDeviation and DownsidePotential updated

Modified: pkg/PerformanceAnalytics/R/DownsideDeviation.R
===================================================================
--- pkg/PerformanceAnalytics/R/DownsideDeviation.R	2012-06-06 16:54:44 UTC (rev 1988)
+++ pkg/PerformanceAnalytics/R/DownsideDeviation.R	2012-06-06 18:18:50 UTC (rev 1989)
@@ -6,16 +6,23 @@
 #' Downside deviation, similar to semi deviation, eliminates positive returns
 #' when calculating risk.  Instead of using the mean return or zero, it uses
 #' the Minimum Acceptable Return as proposed by Sharpe (which may be the mean
-#' historical return or zero).
+#' historical return or zero). It measures the the variability of underperformance
+#' below a minimum targer rate. The downside variance is the square of the downside
+#' potential.
 #' 
 #' To calculate it, we take the subset of returns that are less than the target
 #' (or Minimum Acceptable Returns (MAR)) returns and take the differences of
 #' those to the target.  We sum the squares and divide by the total number of
 #' returns to get a below-target semi-variance.
 #' 
-#' \deqn{ DownsideDeviation(R , MAR)= \delta_{MAR} = \sqrt{
-#' \frac{\sum^{n}_{t=1}(R_{t} - MAR)^{2}}{n} } }
-#' 
+#'
+#' \deqn{ DownsideDeviation(R , MAR)= \delta_{MAR} = \sqrt{\sum^{n}_{t=1}\frac{
+#' min[(R_{t} - MAR), 0]^2}{n}}}
+#'
+#' \deqn{ DownsideVariance(R, MAR) = \sum^{n}_{t=1}\frac{min[(R_{t} - MAR), 0]^2} {n}}
+#'
+#' \deqn{DownsidePotential(R, MAR) = \sum^{n}_{t=1}\frac{min[(R_{t} - MAR), 0]} {n}}
+#'
 #' where \eqn{n} is either the number of observations of the entire series or
 #' the number of observations in the subset of the series falling below the
 #' MAR.
@@ -58,9 +65,11 @@
 #' @param \dots any other passthru parameters
 #' @param potential if TRUE, calculate downside potential instead, default
 #' FALSE
-#' @author Peter Carl, Brian G. Peterson
+#' @author Peter Carl, Brian G. Peterson, Matthieu Lestel
 #' @references Sortino, F. and Price, L. Performance Measurement in a Downside
-#' Risk Framework. \emph{Journal of Investing}. Fall 1994, 59-65. \cr
+#' Risk Framework. \emph{Journal of Investing}. Fall 1994, 59-65. \cr 
+#' Carl Bacon, \emph{Practical portfolio performance measurement and attribution}, 
+#' second edition 2008
 #' 
 #' Plantinga, A., van der Meer, R. and Sortino, F. The Impact of Downside Risk
 #' on Risk-Adjusted Performance of Mutual Funds in the Euronext Markets. July
@@ -71,7 +80,16 @@
 #' \url{http://en.wikipedia.org/wiki/Semivariance}
 #' @keywords ts multivariate distribution models
 #' @examples
+#'
+#' #with data used in Bacon 2008
+#'
+#' portfolio_return <- c(0.3,2.6,1.1,-1.0,1.5,2.5,1.6,6.7,-1.4,4.0,-0.5,8.1,4.0,-3.7,-6.1,1.7,-4.9,-2.2,7.0,5.8,-6.5,2.4,-0.5,-0.9)
+#' MAR = 0.5
+#' DownsideDeviation(portfolio_return, MAR) #expected 2.55
+#' DownsidePotential(portfolio_return, MAR) #expected 1.37
 #' 
+#' #with data of managers
+#'
 #' data(managers)
 #' apply(managers[,1:6], 2, sd, na.rm=TRUE)
 #' DownsideDeviation(managers[,1:6])  # MAR 0%
@@ -80,7 +98,9 @@
 #' SemiDeviation(managers[,1:6])
 #' SemiVariance (managers[,1,drop=FALSE])
 #' SemiVariance (managers[,1:6]) #calculated using method="subset"
-#' 
+#'
+#' @export 
+
 DownsideDeviation <-
 function (R, MAR = 0, method=c("full","subset"), ..., potential=FALSE)
 { # @author Peter Carl, Matthieu Lestel