returns {PMwR}

Compute Returns

Description

Convert prices into returns.

Usage

returns(x, ...)

## Default S3 method:
returns(x, t = NULL, period = NULL, complete.first = TRUE,
        pad = NULL, position = NULL,
        weights = NULL, rebalance.when = NULL,
        lag = 1, na.rm = TRUE, ...)

## S3 method for class 'zoo'
returns(x, period = NULL, complete.first = TRUE,
        pad = NULL, position = NULL,
        weights = NULL, rebalance.when = NULL, lag = 1, na.rm = TRUE, ...)

## S3 method for class 'p_returns'
print(x, ..., year.rows = TRUE, month.names = NULL,
      zero.print = "0", plus = FALSE, digits = 1,
      na.print = NULL)

## S3 method for class 'p_returns'
toLatex(object, ...,
        year.rows = TRUE, ytd = "YTD", month.names = NULL,
        eol = "\\\\", stand.alone = FALSE)

## S3 method for class 'p_returns'
toHTML(x, ...,
       year.rows = TRUE, ytd = "YTD", month.names = NULL,
       stand.alone = TRUE, table.style = NULL, table.class = NULL,
       th.style = NULL, th.class = NULL,
       td.style = "text-align:right; padding:0.5em;",
       td.class = NULL, tr.style = NULL, tr.class = NULL,
       browse = FALSE)

.returns(x, pad = NULL, lag)

Arguments

x

for the default method, a numeric vector (possibly with a dim attribute; i.e. a matrix) of prices. returns also supports x of other classes, such as zoo or NAVseries. For time-series classes, argument t should be NULL.

For .returns, x must be numeric (for other classes, .returns may not work properly).

t

timestamps. See arguments period and rebalance.when.

period

Typically a string. Supported are "hour", "day", "month", "quarter", "year", "ann" (annualised), "ytd" (year-to-date), "mtd" (month-to-date), "itd" (inception-to-date) or a single year, such as "2012". Instead of "itd", "total" may also be used. The value of ‘period’ is used only when timestamp information is available: for instance, when t is not NULL or with zoo/xts objects. The exception is "itd", which can be computed without timestamp information. Holding period "ytd" produces a warning if the current year (as obtained from Sys.Date) differs from the latest timestamp of the series. Specifying period as "ytd!" suppresses the warning.

All returns are computed as simple returns. They will only be annualised with option "ann"; they will not be annualised when the length of the time series is less than one year. To force annualising in such a case, use "ann!". Annualisation can only work when the timestamp t can be coerced to class Date. The result will have an attribute is.annualised, which is a logical vector of length one.

complete.first

logical. For holding-period returns such an monthly or yearly, should the first period (if incomplete) be used.

pad

either NULL (no padding of initial lost observation) or a value used for padding (reasonable values might be NA or 0)

na.rm

logical; see Details

position

either a numeric vector of the same length as the number of assets (i.e. ncol(x)), or a numeric matrix whose dimensions match those of prices (i.e. dim(x) must equal dim(weights)), or a matrix with as many rows as rebalance.when has elements

weights

either a numeric vector of the same length as the number of assets (i.e. ncol(x)), or a numeric matrix whose dimensions match those of prices (i.e. dim(x) must equal dim(weights)), or a matrix with as many rows as rebalance.when has elements

rebalance.when

logical or numeric. If x is a time-series class (such as zoo), it may also be of the same class as the time index of x.

...

further arguments to be passed to methods

year.rows

logical. If TRUE (the default), print monthly returns with one row per year.

zero.print

character. How to print zero values.

na.print

character. How to print NA values. (Not supported yet.)

plus

logical. Add a ‘+’ before positive numbers? Default is FALSE.

lag

The lag for computing returns. A positive integer, defaults to one; ignored for time-weighted returns or if t is supplied.

object

an object of class p_returns (‘period returns’)

month.names

character: names of months. Default is an abbreviated month name as provided by the locale. That may cause trouble, notably with toLatex, if such names contain non-ASCII characters: a safe choice is either the numbers 1 to 12, or the character vector month.abb, which lives in the base package.

digits

number of digits in table

ytd

header for YTD

eol

character

stand.alone

logical or character

table.class

character

table.style

character

th.class

character

th.style

character

td.class

character

td.style

character

tr.class

character

tr.style

character

browse

logical: open table in browser?

Details

returns is a generic function. It computes simple returns: current values divided by prior values minus one. The default method works for numeric vectors/matrices. The function .returns does the actual computations and may be used when a ‘raw’ return computation is needed.

Holding-Period Returns

When a timestamp is available, returns can compute returns for specific calendar periods. See argument period.

Portfolio Returns

returns may compute returns for a portfolio specified in weights or position. The portfolio is rebalanced at rebalance.when; the default is every period. Weights need not sum to one. A zero-weight portfolio, or a portfolio that never rebalances (e.g. with rebalance.when set to FALSE), will result in a zero return.

rebalance.when may either be logical, integers or of the same class as a timestamp (e.g. Date).

Handling missing values

Removing missing values (i.e. setting na.rm to TRUE) only has effects when period is specified.

Value

If called as returns(x): a numeric vector or matrix, possibly with a class attribute (e.g. for a zoo series).

If called with a period argument: an object of class "p_returns" (period returns), which is a numeric vector of returns with attributes t (timestamp) and period. Main use is to have methods that pretty-print such period returns; currently, there are methods for toLatex and toHTML.

In some cases, additional attributes may be attached: when portfolio returns were computed (i.e. argument weights was specified), there are attributes holdings and contributions. For holding-period returns, there may be a logical attribute is.annualised, and an attribute from.to, which tells the start and end date of the holding period.

Author(s)

Enrico Schumann <[e-mail]>

References

Schumann, E. (2023) Portfolio Management with R. https://enricoschumann.net/R/packages/PMwR/; in particular, see
https://enricoschumann.net/R/packages/PMwR/manual/PMwR.html#computing-returns

See Also

btest, pl

Examples

x <- 101:105
returns(x)
returns(x, pad = NA)
returns(x, pad = NA, lag = 2)


## monthly returns
t <- seq(as.Date("2012-06-15"), as.Date("2012-12-31"), by = "1 day")
x <- seq_along(t) + 1000
returns(x, t = t, period = "month")
returns(x, t = t, period = "month", complete.first = FALSE)

### formatting
print(returns(x, t = t, period = "month"), plus = TRUE, digits = 0)

## returns per year (annualised returns)
returns(x, t = t, period = "ann")  ## less than one year, not annualised
returns(x, t = t, period = "ann!") ## less than one year, *but* annualised

is.ann <- function(x)
    attr(x, "is.annualised")

is.ann(returns(x, t = t, period = "ann"))   ## FALSE
is.ann(returns(x, t = t, period = "ann!"))  ## TRUE


## with weights and fixed rebalancing times
prices <- cbind(p1 = 101:105,
                p2 = rep(100, 5))
R <- returns(prices, weights = c(0.5, 0.5), rebalance.when = 1)
## ... => resulting weights
h <- attr(R, "holdings")
h*prices / rowSums(h*prices)
##             p1        p2
## [1,] 0.5000000 0.5000000  ## <== only initial weights are .5/.5
## [2,] 0.5024631 0.4975369
## [3,] 0.5049020 0.4950980
## [4,] 0.5073171 0.4926829
## [5,] 0.5097087 0.4902913