Convert prices into returns.
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, na.rm = TRUE, ...)
# S3 method for 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 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)
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
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.
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).
timestamps. See arguments period and
rebalance.when.
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.
logical. For holding-period returns such an monthly or yearly, should the first period (if incomplete) be used.
either NULL (no padding of initial lost
observation) or a value used for padding
(reasonable values might be NA or
0)
logical; see Details
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
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
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
logical. If TRUE (the default), print
monthly returns with one row per year.
character. How to print zero values.
character. How to print NA values. (Not
supported yet.)
logical. Add a ‘+’ before positive
numbers? Default is FALSE.
The lag for computing returns. A positive integer,
defaults to one; ignored for time-weighted returns
or if t is supplied.
an object of class p_returns (‘period
returns’)
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.
number of digits in table
header for YTD
character
logical or character
character
character
character
character
character
character
character
character
logical: open table in browser?
Enrico Schumann <es@enricoschumann.net>
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.
When a timestamp is available, returns can
compute returns for specific calendar periods. See
argument period.
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).
Removing missing values (i.e. setting na.rm to
TRUE) only has effects when period is
specified.
Schumann, E. (2023) Portfolio Management with R.
http://enricoschumann.net/R/packages/PMwR/;
in particular, see
http://enricoschumann.net/R/packages/PMwR/manual/PMwR.html#computing-returns
btest, pl
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
Run the code above in your browser using DataLab