[Returnanalytics-commits] r2046 - in pkg/PerformanceAnalytics: R man

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

Author: matthieu_lestel
Date: 2012-06-21 18:38:02 +0200 (Thu, 21 Jun 2012)
New Revision: 2046

Added:
   pkg/PerformanceAnalytics/R/Kappa.R
   pkg/PerformanceAnalytics/man/Kappa.Rd
Modified:
   pkg/PerformanceAnalytics/man/DRatio.Rd
Log:
addition of kappa with examples and documentation

Added: pkg/PerformanceAnalytics/R/Kappa.R
===================================================================
--- pkg/PerformanceAnalytics/R/Kappa.R	                        (rev 0)
+++ pkg/PerformanceAnalytics/R/Kappa.R	2012-06-21 16:38:02 UTC (rev 2046)
@@ -0,0 +1,74 @@
+#' Kappa of the return distribution
+#'
+#' Introduced by Kaplan and Knowles (2004), Kappa is a generalized
+#' downside risk-adjusted performance measure.
+#'
+#' To calculate it, we take the difference of the mean of the distribution
+#' to the target and we divide it by the l-root of the lth lower partial
+#' moment. To calculate the lth lower partial moment we take the subset of
+#' returns below the target and we sum the differences of the target to
+#' these returns. We then return return this sum divided by the length of
+#' the whole distribution.
+#'
+#' \deqn{Kappa(R, MAR, l) = \frac{r_{p}-MAR}{\sqrt[l]{\frac{1}{n}*\sum^n_{t=1}
+#' max(MAR-R_{t}, 0)^l}}}{Kappa(R, MAR, l) = (rp - MAR)/(\sqrt[l](1/n*sum(t=1..n)
+#' (max(MAR-r(t),0)^l)))}
+#'
+#' For l=1 kappa is the Sharpe-omega ratio and for l=2 kappa
+#' is the sortino ratio.
+#'
+#' Kappa should only be used to rank portfolios as it is difficult to
+#' interpret the absolute differences between kappas. The higher the
+#' kappa is, the better.
+#'
+#'
+#' @aliases Kappa
+#' @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
+#' returns
+#' @param l the coefficient of the Kappa
+#' @param \dots any other passthru parameters
+#' @author Matthieu Lestel
+#' @references Carl Bacon, \emph{Practical portfolio performance measurement 
+#' and attribution}, second edition 2008 p.96
+#' 
+#' @keywords ts multivariate distribution models
+#'
+#' @examples
+#' l = 2
+#'
+#' data(portfolio_bacon)
+#' MAR = 0.5
+#' print(Kappa(portfolio_bacon, MAR, l)) #expected 0.157
+#'
+#' data(managers)
+#' MAR = 0
+#' print(Kappa(managers['1996'], MAR, l))
+#' print(Kappa(managers['1996',1], MAR, l)) #expected 1.493
+#'
+#' @export 
+
+Kappa <- function (R, MAR, l, ...)
+{
+    R0 <- R
+    R = checkData(R, method="matrix")
+
+    if (ncol(R)==1 || is.null(R) || is.vector(R)) {
+       R = na.omit(R)
+       r = subset(R, R<MAR)
+       n = length(R)
+       m = mean(R)
+       result = (m-MAR)/(((1/n)*sum((MAR - r)^l))^(1/l))
+       reclass(result, R0)
+       return(result)
+    }
+    else {
+        R = checkData(R)
+        result = apply(R, MARGIN = 2, Kappa, MAR=MAR, l=l, ...)
+        result<-t(result)
+        colnames(result) = colnames(R)
+        rownames(result) = paste("kappa (MAR = ",MAR,"%)", sep="")
+        return(result)
+    }
+}
\ No newline at end of file

Modified: pkg/PerformanceAnalytics/man/DRatio.Rd
===================================================================
--- pkg/PerformanceAnalytics/man/DRatio.Rd	2012-06-21 14:19:44 UTC (rev 2045)
+++ pkg/PerformanceAnalytics/man/DRatio.Rd	2012-06-21 16:38:02 UTC (rev 2046)
@@ -29,9 +29,9 @@
   (t=1..n)(max(-R(t),0)) / nu*sum(t=1..n)(max(R(t),0))}
 
   where \eqn{n} is the number of observations of the entire
-  series \\ \eqn{n_{d}} is the number of observations less
-  than zero \\ \eqn{n_{u}} is the number of observations
-  greater than zero \\
+  series, \eqn{n_{d}} is the number of observations less
+  than zero, \eqn{n_{u}} is the number of observations
+  greater than zero
 }
 \examples{
 data(portfolio_bacon)

Added: pkg/PerformanceAnalytics/man/Kappa.Rd
===================================================================
--- pkg/PerformanceAnalytics/man/Kappa.Rd	                        (rev 0)
+++ pkg/PerformanceAnalytics/man/Kappa.Rd	2012-06-21 16:38:02 UTC (rev 2046)
@@ -0,0 +1,66 @@
+\name{Kappa}
+\alias{Kappa}
+\title{Kappa of the return distribution}
+\usage{
+  Kappa(R, MAR, l, ...)
+}
+\arguments{
+  \item{R}{an xts, vector, matrix, data frame, timeSeries
+  or zoo object of asset returns}
+
+  \item{MAR}{Minimum Acceptable Return, in the same
+  periodicity as your returns}
+
+  \item{l}{the coefficient of the Kappa}
+
+  \item{\dots}{any other passthru parameters}
+}
+\description{
+  Introduced by Kaplan and Knowles (2004), Kappa is a
+  generalized downside risk-adjusted performance measure.
+}
+\details{
+  To calculate it, we take the difference of the mean of
+  the distribution to the target and we divide it by the
+  l-root of the lth lower partial moment. To calculate the
+  lth lower partial moment we take the subset of returns
+  below the target and we sum the differences of the target
+  to these returns. We then return return this sum divided
+  by the length of the whole distribution.
+
+  \deqn{Kappa(R, MAR, l) =
+  \frac{r_{p}-MAR}{\sqrt[l]{\frac{1}{n}*\sum^n_{t=1}
+  max(MAR-R_{t}, 0)^l}}}{Kappa(R, MAR, l) = (rp -
+  MAR)/(\sqrt[l](1/n*sum(t=1..n) (max(MAR-r(t),0)^l)))}
+
+  For l=1 kappa is the Sharpe-omega ratio and for l=2 kappa
+  is the sortino ratio.
+
+  Kappa should only be used to rank portfolios as it is
+  difficult to interpret the absolute differences between
+  kappas. The higher the kappa is, the better.
+}
+\examples{
+l = 2
+
+data(portfolio_bacon)
+MAR = 0.5
+print(Kappa(portfolio_bacon, MAR, l)) #expected 0.157
+
+data(managers)
+MAR = 0
+print(Kappa(managers['1996'], MAR, l))
+print(Kappa(managers['1996',1], MAR, l)) #expected 1.493
+}
+\author{
+  Matthieu Lestel
+}
+\references{
+  Carl Bacon, \emph{Practical portfolio performance
+  measurement and attribution}, second edition 2008 p.96
+}
+\keyword{distribution}
+\keyword{models}
+\keyword{multivariate}
+\keyword{ts}
+