[Returnanalytics-commits] r3544 - pkg/PerformanceAnalytics/sandbox

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

Author: peter_carl
Date: 2014-10-15 15:10:23 +0200 (Wed, 15 Oct 2014)
New Revision: 3544

Modified:
   pkg/PerformanceAnalytics/sandbox/to.period.contributions.R
Log:
- added roxygen documentation

Modified: pkg/PerformanceAnalytics/sandbox/to.period.contributions.R
===================================================================
--- pkg/PerformanceAnalytics/sandbox/to.period.contributions.R	2014-10-15 11:27:35 UTC (rev 3543)
+++ pkg/PerformanceAnalytics/sandbox/to.period.contributions.R	2014-10-15 13:10:23 UTC (rev 3544)
@@ -1,3 +1,34 @@
+#' aggregate contributions through time
+#' 
+#' Higher frequency contributions provided as a time series are converted to a lower 
+#' frequency for a specified calendar period.
+#' 
+#' From the portfolio contributions of individual assets, such as those of a particular asset class 
+#' or manager, the multiperiod contribution is neither summable from nor the geometric compounding of
+#' single-period contributions.  Because the weights of the individual assets change through time as
+#' transactions occur, the capital base for the asset changes.
+#' 
+#' Instead, the asset's multiperiod contribution is the sum of the asset's dollar contributions from
+#' each period, as calculated from the wealth index of the total portfolio. Once contributions are
+#' expressed in cumulative terms, asset contributions then sum to the returns of the total portfolio for 
+#' the period.
+#' 
+#' Valid period character strings for period include: "weeks", "months", "quarters", and "years". 
+#' These are calculated internally via \code{\link{endpoints}}. See that function's help page for further details.
+#' 
+#' @param Contributions a time series of the per period contribution to portfolio return of each asset 
+#' @param period period to convert to. See details."years", "quarters", "months", "weeks"
+#' @param \dots any other passthru parameters
+#' @author Peter Carl, with thanks to Paolo Cavatore
+#' @seealso \code{\link{Return.portfolio}} \cr \code{\link{endpoints}} \cr
+#' @references Morningstar \emph{Total Portfolio Performance Attribution Methodology} p.36. Available at http://corporate.morningstar.com/US/documents/MethodologyDocuments/MethodologyPapers/TotalPortfolioPerformanceAttributionMethodology.pdf \cr
+#' @aliases to.monthly.contributions to.weekly.contributions to.quarterly.contributions to.yearly.contributions
+#' @examples
+#' data(managers)
+#' res_qtr_rebal = Return.portfolio(managers["2002::",1:5], weights=c(.05,.1,.3,.4,.15), rebalance_on = "quarters", verbose=TRUE)
+#' to.period.contributions(res_qtr_rebal$contribution, period="years")
+#' to.yearly.contributions(res_qtr_rebal$contribution)
+#' @export
 to.period.contributions <- function(Contributions, period = c("years", "quarters", "months", "weeks"), ...){
   C = checkData(Contributions)
   period = period[1] 
@@ -50,16 +81,19 @@
   return(period.contrib)
   
 }
-
+#' @export
 to.weekly.contributions <- function(contributions) {
   to.period.contributions(contributions = contributions, period = "weeks")
 }
+#' @export
 to.monthly.contributions <- function(contributions) {
   to.period.contributions(contributions = contributions, period = "months")
 }
+#' @export
 to.quarterly.contributions <- function(contributions) {
   to.period.contributions(contributions = contributions, period = "quarters")
 }
+#' @export
 to.yearly.contributions <- function(contributions) {
   to.period.contributions(contributions = contributions, period = "years")
 }