PMwR (version 0.11-0)

returns: Compute Returns

Description

Convert prices into returns.

Usage

returns(x, …)
# S3 method for default
returns(x, t = NULL, period = NULL, complete.first = TRUE,
        pad = NULL, position = NULL, 
        weights = NULL, rebalance.when = NULL,
        lag = 1, …)
# S3 method for zoo
returns(x, period = NULL, complete.first = TRUE,
        pad = NULL, position = NULL,
        weights = NULL, rebalance.when = NULL, lag = 1, …)
# S3 method for p_returns
print(x, …, year.rows = TRUE, month.names = NULL,
      zero.print = "0", plus = FALSE, digits = 1,
      na.print = NULL)
# S3 method for p_returns
toLatex(object, …,
        year.rows = TRUE, ytd = "YTD", month.names = NULL, 
        eol = "\\\\", stand.alone = FALSE)
# S3 method for 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 character; 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". The value of ‘period’ is used only when timestamp information is available: for instance, when t is not NULL or with zoo/xts objects.

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)

position

numeric; the same length/dimension as x. This argument is currently ignored.

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))

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?

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.

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. The portfolio is rebalanced at rebalance.when; the default is every period.

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

See Also

btest, pl

Examples

# NOT RUN {
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)
# }