1#' relative performance chart between multiple return series
2#'
3#' Plots a time series chart that shows the ratio of the cumulative performance
4#' for two assets at each point in time and makes periods of under- or
5#' out-performance easier to see.
6#'
7#' To show under- and out-performance through different periods of time, a time
8#' series view is more helpful. The value of the chart is less important than
9#' the slope of the line. If the slope is positive, the first asset (numerator)
10#' is outperforming the second, and vice versa. May be used to look at the
11#' returns of a fund relative to each member of the peer group and the peer
12#' group index. Alternatively, it might be used to assess the peers
13#' individually against an asset class or peer group index.
14#'
15#' @param Ra an xts, vector, matrix, data frame, timeSeries or zoo object of
16#' asset returns
17#' @param Rb return vector of the benchmark asset
18#' @param main set the chart title, same as in \code{plot}
19#' @param xaxis if true, draws the x axis
20#' @param colorset color palette to use, set by default to rational choices
21#' @param elementcolor provides the color for drawing less-important chart
22#' elements, such as the box lines, axis lines, etc. replaces \code{darken}
23#' @param legend.loc places a legend into one of nine locations on the chart:
24#' bottomright, bottom, bottomleft, left, topleft, top, topright, right, or
25#' center.
26#' @param ylog TRUE/FALSE set the y-axis to logarithmic scale, similar to
27#' \code{\link{plot}}, default FALSE
28#' @param cex.legend the magnification to be used for sizing the legend
29#' relative to the current setting of 'cex'.
30#' @param lty set the line type, same as in \code{\link{plot}}
31#' @param \dots any other passthru parameters
32#' @author Peter Carl
33#' @seealso \code{\link{Return.relative}}
34###keywords ts multivariate distribution models hplot
35#' @examples
36#'
37#' data(managers)
38#' chart.RelativePerformance(managers[, 1:6, drop=FALSE],
39#' 		managers[, 8, drop=FALSE],
40#' 		colorset=rich8equal, legend.loc="bottomright",
41#' 		main="Relative Performance to S&P")
42#'
43#' @export
44chart.RelativePerformance <-
45function (Ra, Rb, main = "Relative Performance", xaxis = TRUE, colorset = (1:12), legend.loc = NULL, ylog = FALSE, elementcolor = "darkgray", lty = 1, cex.legend=.7, ...)
46{ # @author Peter Carl
47
48    # DESCRIPTION:
49    # A wrapper to create a chart of relative returns through time
50
51    # Inputs:
52    # R: a matrix, data frame, or timeSeries of returns
53    # Rb: a matrix, data frame, or timeSeries of returns for a benchmark
54
55    # Outputs:
56    # A timeseries line chart of the calculated series
57
58    # FUNCTION:
59
60    # Transform input data to a matrix
61    Ra = checkData(Ra)
62    Rb = checkData(Rb)
63
64    # Get dimensions and labels
65    columns.a = ncol(Ra)
66    columns.b = ncol(Rb)
67    columnnames.a = colnames(Ra)
68    columnnames.b = colnames(Rb)
69
70    # Calculate
71    for(column.a in 1:columns.a) { # for each asset passed in as R
72        for(column.b in 1:columns.b) { # against each asset passed in as Rb
73            merged.columns = merge(Ra[, column.a, drop = FALSE], Rb[, column.b, drop = FALSE])
74            cumulative = cumprod(1+na.omit(merged.columns))
75            column.calc = cumulative[,1,drop=FALSE]/cumulative[,2,drop=FALSE]
76            colnames(column.calc) = paste(columnnames.a[column.a], columnnames.b[column.b], sep = "/")
77            if(column.a == 1 & column.b == 1)
78                Result.calc = column.calc
79            else
80                Result.calc = merge(Result.calc,column.calc)
81        }
82    }
83columnnames = colnames(Result.calc)
84    p <- chart.TimeSeries(Result.calc, xaxis = xaxis, main = main, colorset = colorset, ylog = ylog, lty = lty, ...)
85    p$Env$elementcolor <- elementcolor
86    p <- addSeries(xts(rep(1, nrow(Result.calc)), time(Result.calc)), col = elementcolor, on = 1)
87    if(!is.null(legend.loc)){
88      # There's no good place to put this automatically, except under the graph.
89      # That requires a different solution, but here's the quick fix
90      p$Env$cex.legend <- cex.legend
91      p$Env$colorset <- colorset
92      p$Env$columnnames <- columnnames
93      p <- addLegend(legend.loc, columnnames, inset = 0.02, col = colorset, cex = cex.legend, lty = lty, lwd = 2, bg = "white")
94    }
95    return(p)
96}
97
98###############################################################################
99# R (http://r-project.org/) Econometrics for Performance and Risk Analysis
100#
101# Copyright (c) 2004-2020 Peter Carl and Brian G. Peterson
102#
103# This R package is distributed under the terms of the GNU Public License (GPL)
104# for full details see the file COPYING
105#
106# $Id$
107#
108###############################################################################
109