[Returnanalytics-commits] r2014 - pkg/PortfolioAnalytics/sandbox/attribution

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

Author: ababii
Date: 2012-06-14 17:28:02 +0200 (Thu, 14 Jun 2012)
New Revision: 2014

Modified:
   pkg/PortfolioAnalytics/sandbox/attribution/Attribution.geometric.R
   pkg/PortfolioAnalytics/sandbox/attribution/attribution.R
Log:
- documentation update

Modified: pkg/PortfolioAnalytics/sandbox/attribution/Attribution.geometric.R
===================================================================
--- pkg/PortfolioAnalytics/sandbox/attribution/Attribution.geometric.R	2012-06-14 10:49:01 UTC (rev 2013)
+++ pkg/PortfolioAnalytics/sandbox/attribution/Attribution.geometric.R	2012-06-14 15:28:02 UTC (rev 2014)
@@ -1,7 +1,64 @@
-# Geometric attribution
+#' performs geometric attribution 
+#' 
+#' Performance attribution of geometric excess returns. Calculates total 
+#' geometric attribution effects over multiple periods. Used internally by the 
+#' \code{\link{Attribution}} function. Geometric attribution effects in the
+#' conrast with arithmetic do naturally link over time multiplicatively:
+#' \deqn{\frac{(1+r)}{1+b}-1=\overset{n}{\underset{t=1}{\prod}}(1+A_{t}^{G})\times\overset{n}{\underset{t=1}{\prod}}(1+S{}_{t}^{G})-1}
+#' , where
+#' \deqn{A_{t}^{G}} - total allocation effect at time t
+#' \deqn{S_{t}^{G}} - total selection effect at time t
+#' \deqn{A_{t}^{G}=\frac{1+b_{s}}{1+b_{t}}-1}
+#' \deqn{S_{t}^{G}=\frac{1+r_{t}}{1+b_{s}}-1}
+#' \deqn{b_{s}=\overset{n}{\underset{i=1}{\sum}}wp_{i}\times rb_{i}}
+#' \deqn{b_{s}} - semi-notional fund
+#' \deqn{wp_{t}} - portfolio weights at time t
+#' \deqn{wb_{t}} - benchmark weights at time t
+#' \deqn{r_{t}} - portfolio returns at time t
+#' \deqn{b_{t}} - benchmark returns at time t
+#' \deqn{r} - total portfolio returns
+#' \deqn{b} - total benchmark returns
+#' \deqn{n} - number of periods
+#'
+#' @aliases Attribution.geometric
+#' @param Rp xts of portfolio returns
+#' @param wp xts of portfolio weights
+#' @param Rb xts of benchmark returns
+#' @param wb xts of benchmark weights
+#' @author Andrii Babii
+#' @seealso  \code{\link{Attribution}}
+#' @references Christopherson, Jon A., Carino, David R., Ferson, Wayne E.  
+#' \emph{Portfolio Performance Measurement and Benchmarking}. McGraw-Hill. 2009. 
+#' Chapter 18-19
+#' 
+#' Bacon, C. \emph{Practical Portfolio Performance Measurement and
+#' Attribution}. Wiley. 2004. Chapter 5, 8
+#' @keywords attribution, geometric attribution, geometric linking
+#' @examples
+#' 
+#' data(attrib)
+#' Attribution.geometric(Rp, wp, Rb, wb)
+#' 
+#' @export
 Attribution.geometric <-
 function(Rp, wp, Rb, wb)
-{
+{   # @author Andrii Babii
+  
+    # DESCRIPTION:
+    # Function to perform the geometric attribution analysis.
+  
+    # Inputs:
+    # Rp       xts, data frame or matrix of portfolio returns
+    # wp       vector, xts, data frame or matrix of portfolio weights
+    # Rb       xts, data frame or matrix of benchmark returns
+    # wb       vector, xts, data frame or matrix of benchmark weights
+  
+    # Outputs: 
+    # This function returns the list with attribution effects (allocation,
+    # selection and total effects) including total multi-period 
+    # attribution effects
+  
+    # FUNCTION:
     rp = reclass(rowSums(Rp * wp), Rp)  
     rb = reclass(rowSums(Rb * wb), Rb)  
     names(rp) = "Total"                    

Modified: pkg/PortfolioAnalytics/sandbox/attribution/attribution.R
===================================================================
--- pkg/PortfolioAnalytics/sandbox/attribution/attribution.R	2012-06-14 10:49:01 UTC (rev 2013)
+++ pkg/PortfolioAnalytics/sandbox/attribution/attribution.R	2012-06-14 15:28:02 UTC (rev 2014)
@@ -7,12 +7,47 @@
 #' on the sector-based approach to the attribution. The workhorse is the
 #' Brinson model that explains the arithmetic difference between portfolio and 
 #' benchmark returns. That is it breaks down the arithmetic excess returns at 
-#' one level. It also alows to break down the geometric excess returns. The 
-#' attribution effects can be computed for several periods. Different linking 
-#' methods allow to get the multi-period summary. Finally, it annualizes 
+#' one level. The attribution effects can be computed for several periods. 
+#' The multi-period summary is obtained using one of linking methods: Carino, 
+#' Menchero, GRAP, Frongello. It also allows to break down the geometric excess 
+#' returns, which link naturally over time. Finally, it annualizes 
 #' arithmetic and geometric excess returns similarly to the portfolio and/or 
-#' benchmark returns annualization.
-#'
+#' benchmark returns annualization. 
+#' 
+#' The arithmetic exess returns are decomposed into the sum of allocation, 
+#' selection and interaction effects across \deqn{n} sectors:
+#' \deqn{r-b=\overset{n}{\underset{i=1}{\sum}}\left(A_{i}+S_{i}+I_{i}\right)}
+#' The arithmetic attribtion effects for the category \deqn{i} are computed
+#' as suggested in the Brinson, Hood and Beebower (1986):
+#' \deqn{A_{i}=(wp_{i}-wb_{i})\times b_{i}} - allocation effect
+#' \deqn{S_{i}=wp_{i}\times(r_{i}-b_{i})} - selection effect
+#' \deqn{I_{i}=(wp_{i}-wb_{i})\times(r_{i}-b_{i})} - interaction effect
+#' \deqn{r} - total portfolio returns
+#' \deqn{b} - total benchmark returns
+#' \deqn{wp_{i}} - weights of the category \deqn{i} in the portfolio
+#' \deqn{wb_{i}} - weigths of the category \deqn{i} in the benchmark
+#' \deqn{r_{i}} - returns of the portfolio category \deqn{i}
+#' \deqn{b_{i}} - returns of the benchmark category \deqn{i}
+#' Depending on goals we can give priority to the allocation or to 
+#' the selection effects. If the priority is given to the sector allocation
+#' the interaction term will be combined with the security selection effect
+#' (top-down approach). If the priority is given to the security selection,
+#' the interaction term will be combined with the asset-allocation effect
+#' (bottom-up approach).
+#' Usually we have more then one period. In that case individual arithmetic 
+#' attribution effects should be adjusted using linking methods. Adjusted
+#' arithmetic attribution effects can be summed up over time to provide the
+#' multi-period summary: \deqn{r-b=\overset{T}{\underset{t=1}{\sum}}\left(A_{t}'+S_{t}'+I_{t}'\right)}
+#' , where \deqn{T} - number of periods; prime stands for the adjustment.
+#' The geometric attribution effects do not suffer from the linking problem.
+#' Moreover we don't have the interaction term. For more details about the 
+#' geometric attribution see the documentation to \code{link{Attribution.geometric}}
+#' Finally, arithmetic annualized excess returns are computed as the 
+#' arithmetic difference between annualised portfolio and benchmark returns:
+#' \deqn{AAER=r_{a}-b_{a}}; the geometric annualized excess returns are
+#' computed as the geometric difference between annualized portfolio
+#' and benchmark returns: \deqn{GAER=\frac{1+r_{a}}{1+b_{a}}-1}
+#' 
 #' @aliases Attribution
 #' @param Rp xts, data frame or matrix of portfolio returns
 #' @param wp vector, xts, data frame or matrix of portfolio weights