1#' calculate a compounded (geometric) cumulative return
2#'
3#' This is a useful function for calculating cumulative return over a period of
4#' time, say a calendar year.  Can produce simple or geometric return.
5#'
6#' product of all the individual period returns
7#'
8#' \deqn{(1+r_{1})(1+r_{2})(1+r_{3})\ldots(1+r_{n})-1=prod(1+R)-1}{prod(1+R)-1}
9#'
10#' @param R an xts, vector, matrix, data frame, timeSeries or zoo object of
11#' asset returns
12#' @param geometric utilize geometric chaining (TRUE) or simple/arithmetic chaining (FALSE) to aggregate returns,
13#' default TRUE
14#' @author Peter Carl
15#' @seealso \code{\link{Return.annualized}}
16#' @references Bacon, Carl. \emph{Practical Portfolio Performance Measurement
17#' and Attribution}. Wiley. 2004. p. 6
18###keywords ts multivariate distribution models
19#' @examples
20#'
21#' data(managers)
22#' Return.cumulative(managers[,1,drop=FALSE])
23#' Return.cumulative(managers[,1:8])
24#' Return.cumulative(managers[,1:8],geometric=FALSE)
25#'
26#' @export
27Return.cumulative <-
28function (R, geometric = TRUE)
29{ # @author Peter Carl
30
31    # This is a useful function for calculating cumulative return over a period
32    # of time, say a calendar year.  Can produce simple or geometric return.
33
34    if (is.vector(R)) {
35        R = na.omit(R)
36        if (!geometric)
37            return(sum(R))
38        else {
39            return(prod(1+R)-1)
40        }
41    }
42    else {
43        R = checkData(R, method = "matrix")
44        result = apply(R, 2, Return.cumulative, geometric = geometric)
45        dim(result) = c(1,NCOL(R))
46        colnames(result) = colnames(R)
47        rownames(result) = "Cumulative Return"
48        return(result)
49    }
50}
51
52###############################################################################
53# R (http://r-project.org/) Econometrics for Performance and Risk Analysis
54#
55# Copyright (c) 2004-2020 Peter Carl and Brian G. Peterson
56#
57# This R package is distributed under the terms of the GNU Public License (GPL)
58# for full details see the file COPYING
59#
60# $Id$
61#
62###############################################################################
63