calculate_historical_returns: Calculate Historical Time-series Returns

In gothic-hedge-society/FinancieR: Tools for Financial Data Analysis and Manipulation

Calculate Historical Time-series Returns

Description

Calculate period-over-period historical returns for a list of assets. calculate_historical_returns() takes dividends and splits into account. Because calculate_historical_returns is intended for use in calculating correlations, averages, and volatility of returns it does not take taxes or transaction fees into account.

Usage

calculate_historical_returns(
  assets,
  date_range_xts = paste0("2012/", as.character(Sys.Date())),
  buy_at = "Close",
  sell_at = "Close",
  returns_method = "ln",
  silent = FALSE
)

Arguments

assets	a list of sub-lists named and corresponding to a given asset, for example, "AAPL". Each sublist contains split, dividend, and aggregated prices data as xts objects. An example of an object that may be passed as asset_data is stock_data.
date_range_xts	A string that specifies the date range for which calculate_daily_returns() will calculate returns. Use xts subsetting notation to specify the date range; see examples in xts. If missing or NULL, then the full date range of OHLCV prices is used.
buy_at	Character: Specifies the 'initial price' to be used for calculating returns. Must be one of "open", "high", "low", "close", or "price", defaults to "Close". Not case sensitive.
sell_at	Character: Specifies the 'final price' to be used for calculating returns. Must be One of "open", "high", "low", "close", or "price", defaults to "Close". Not case sensitive.
returns_method	Character vector specifying how the returns should be calculated, defaults to "ln. Choices are: "ln": Log return; ln(sell_price / buy_price) where ln() denotes the natural logarithm (base e). "log2": Log return; log(sell_price / buy_price) where log() denotes the logarithm to base 2. "log10": Log return; log(sell_price / buy_price) where log() denotes the logarithm to base 10. "pct_diff": Percent difference; (sell_price - buy_price)/buy_price. NOT multiplied by 100. "multiple": Price multiple; sell_price / buy_price.
silent	Boolean. If FALSE (Default), messages will be displayed for special cases that might produce unexpected behavior; e.g., if no data is available for the date range specified. If TRUE, these messages will not be displayed.

Value

An xts object. Each element is the return observed on the date given by the xts's index with respect to the previous period, taking into account any splits or dividends that may have occurred in between, for the asset specified by the element's column name.

Examples

# Calculate daily natural log returns of Apple (AAPL) and AT&T (T) for 2014, a
# year in which Apple had a major stock split.
aapl_att_returns <- calculate_historical_returns(
  assets         = stock_data[c("AAPL", "T")],
  date_range_xts = "2014"
)

# Print the first 10 rows:
head(aapl_att_returns, 10)

# Let's check this result in a few key places. 

# 1) Normal trading day
#      Because we didn't specify otherwise, calculate_historical_returns() will
#      use its default behavior and will calculate period-over-period
#      natural-log returns using Close prices. Let's pick Monday, 21 July 2014,
#      which was a normal trading day (no dividend, no split) for AT&T. The
#      previous trading day was Friday, 18 Jul 2014:
stock_data$T$prices["2014-07-18/2014-07-21"]

#      The natural log return using Close prices (calculate_historical_returns()
#      default) as calculated by hand should be:
log(
  as.numeric(stock_data$T$prices$Close["2014-07-21"]) /
    as.numeric(stock_data$T$prices$Close["2014-07-18"])
)

#      This return was realized on 2014-07-21, so it should appear at that date
#      index in the results returned by calculate_historical_returns():
aapl_att_returns["2014-07-21", "T"]

# 2) AT&T's dividend
#      AT&T paid several dividends in 2014:
stock_data$T$dividends["2014"]

#     If you had bought a share of AT&T stock on 07 July 2014 and sold it at the
#     Close price the next day after the dividend went ex-div, you would have
#     collected the closing price from the sale plus the dividend amount, 
#     meaning that your total earned return would have been:
log(
  (
    as.numeric(stock_data$T$prices$Close["2014-07-08"]) + 
      as.numeric(stock_data$T$dividends$DividendAmount["2014-07-08"])
  ) / as.numeric(stock_data$T$prices$Close["2014-07-07"])
)

#      This return was realized on 2014-07-08, so it should appear at that date
#      index in the results returned by calculate_historical_returns():
aapl_att_returns["2014-07-08", "T"]
# --> In this case, the stock closed at the same price as the previous day once
#     the dividend was taken into account, so return = 0.

# 3) AAPL's split
#      Apple underwent a major split on a Monday in June of 2014:
stock_data$AAPL$splits

#     If you had bought a share of AAPL at Close price on Friday, you would have
#     woken up on Monday morning with 7 shares... each one of which worth about
#     1/7th what they were worth previously. If you sold those shares at Close
#     price on Monday, your total return would be:
log(
  (
    as.numeric(stock_data$AAPL$prices$Close["2014-06-09"]) *
      as.numeric(stock_data$AAPL$splits$Denominator["2014-06-09"])
  ) / as.numeric(stock_data$AAPL$prices$Close["2014-06-06"])
)

#      This return was realized on 2014-06-09, so it should appear at that date
#      index in the results returned by calculate_historical_returns():
aapl_att_returns["2014-06-09", "AAPL"]

gothic-hedge-society/FinancieR documentation built on June 18, 2022, 4:55 a.m.