jubilee: A package to forecast long-term growth of the US stock market and business cycles

Description

The jubilee package provides the core class and functions to forecast long-term growth of the U.S. stock market. It also contains a module for business cycles, optimal interest rate, and recession forecasts. A tutorial is provided to demonstrate how to use this package and explain the relation between the mathematical notations and the functions and data columns in this package.

Author(s)

Stephen H-T. Lihn

References

Stephen H.T. Lihn, "Jubilee Tectonic Model: Forecasting Long-Term Growth and Mean Reversion in the U.S. Stock Market." Available at SSRN: https://ssrn.com/abstract=3156574 or via DOI: http://dx.doi.org/10.2139/ssrn.3156574

Stephen H.T. Lihn, "Business Cycles, Optimal Interest Rate, and Recession Forecast From Yield Curve, Unemployment, GDP, and Payrolls." Available at SSRN: https://ssrn.com/abstract=3422278

Converter from daily Date to fraction

Description

Utility to convert from daily Date (R's Date object) to fraction.

Usage

daily2fraction(d)

Arguments

Value

numeric, year in fraction convention

Author(s)

Stephen H. Lihn

Examples

  daily2fraction(as.Date("2017-01-15")) # 2017.038
  daily2fraction(as.Date("2017-02-14")) # 2017.122
  daily2fraction(as.Date("2017-07-15")) # 2017.538

Converter from fraction to daily Date

Description

Utility to convert from fraction to daily Date (R's Date object).

Usage

fraction2daily(fraction)

Arguments

Value

array of Date object

Author(s)

Stephen H. Lihn

Examples

  fraction2daily(2017.038) # 2017-01-15
  fraction2daily(2017.125) # 2017-02-15

Constructor of the jubilee class

Description

Construct an jubilee object which holds raw and derived data, channel regression results, and other derived analytical quantities. This object is the main object to perform various forecasts and analyses.

Usage

jubilee(dtb, lookback.channel = 45, fwd.rtn.duration = 20,
  force = TRUE)

Arguments

Value

an object of the jubilee class

Author(s)

Stephen H. Lihn

Examples

## Not run: 
  repo <- jubilee.repo(online=FALSE)
  ju <- jubilee(repo@ie, 45, 20)

## End(Not run)

The jubilee class

Description

This S4 class stores raw and derived data, channel regression settings and results.

Slots

call

the match.call slot.

lookback.channel

numeric, the look-back channel in years.

fwd.rtn.duration

numeric, the forward return duration in years.

reg.dtb

data.table, contains the regression data.

dtb

data.table, contains the consolidated market data.

rate.spread.mean

numeric, the mean of the yield spread, used to calculate rate.spread.norm column.

create.time

POSIXct, records the creation time of this object.

Adjust the time series by fault lines

Description

This utility is used to adjust the time series by the provided fault lines.

Usage

jubilee.adj_fault_line(fraction, ts, fl, months = 1)

Arguments

Value

numeric, ts adjusted by fault lines

Author(s)

Stephen H. Lihn

Examples

## Not run: 
  repo <- jubilee.repo(online=FALSE)
  dj <- jubilee(repo@ie, 45, 10)@reg.dtb
  dj$log.cape10.adj <- jubilee.adj_fault_line(dj$fraction, dj$log.cape10, "r_nom_f10_5ftr_4fl")

## End(Not run)

Internal utility to calculate n-year CAPE

Description

This CAPE calculator replicates the methodology of Shiller, so that one can calculate n-year CAPE, e.g. n=20. This utility has been calibrated by original 10-year CAPE data from Shiller.

Usage

jubilee.calc_cape(dtb, period, tol.frac = 1/6)

Arguments

Value

numeric, the same length as dtb$fraction.

Author(s)

Stephen H. Lihn

Examples

  ## Not run: 
    dtb <- jubilee.repo(online=FALSE)@ie
    cape10 <- jubilee.calc_cape(dtb, 10)
    cape20 <- jubilee.calc_cape(dtb, 20)
  
## End(Not run)

Internal utility to calculate OLS regression for log total return index

Description

Calculate the OLS regression for log total return index

Usage

jubilee.eqty_ols(dtb, end.frac, lookback.channel, tol.frac = 1/6)

Arguments

Value

two-element array c(a,R) if end.frac is length-one; data.table with end.frac as fraction column if end.frac is an array.

Author(s)

Stephen H. Lihn

Examples

  ## Not run: 
    dtb <- jubilee.repo(online=FALSE)@ie
    jubilee.eqty_ols(dtb, 1970, 50) # c(11.8671626, 0.1008371)
 
## End(Not run)

Internal utility to calculate annualized forward and backward (log) return

Description

These two internal utilities are intended to be used to calculate the annualized forward and backward log-return on the given time series. It is really calculating the speed of change, aka log-return, expecting the input to be in logrithmic scale. The forward return is typically the response variable in a forecast. The backward return is often used as explanatory variable in a regression.

Usage

jubilee.forward_rtn(fraction, ts, fwd.rtn.duration, tol.frac = 1/12)

jubilee.backward_rtn(fraction, ts, bwd.rtn.duration, tol.frac = 1/12)

Arguments

Value

numeric, the same length as fraction

Author(s)

Stephen H. Lihn

Examples

## Not run: 
  dtb <- jubilee.repo(online=FALSE)@ie
  dtb$fwd.logr.10 <- jubilee.forward_rtn(dtb$fraction, dtb$log.tri, 10)
  dtb$bwd.logr.10 <- jubilee.backward_rtn(dtb$fraction, dtb$log.tri, 10)
  head(subset(dtb, fraction >= 1990),1)$fwd.logr.10 # 1/1990+10y: 0.16745
  tail(subset(dtb, fraction <= 2000+1/12),1)$bwd.logr.10 # the same as above

## End(Not run)

Internal utility to download time series data from FRED

Description

This utility downloads time series from FRED. Many time series that this package uses are available on FRED. Therefore, this utility is used to provide daily or monthly updates by concatenating live data to the internal static data.

Usage

jubilee.fred_data(symbol, col_out = "Close", retry = 3)

Arguments

Value

The xts object for the time series

Examples

## Not run: 
   jubilee.fred_data("VIXCLS") # VIX

## End(Not run)

Internal utility to locate static file

Description

This utility returns the path to internal file

Usage

jubilee.locate_file(local_file, stop = TRUE)

Arguments

Value

The path to the file, or else, an empty string

Author(s)

Stephen H. Lihn

Examples

  jubilee.locate_file("UNRATE.csv")

Calculate the cost function of the macro model

Description

This utility calculates the cost function of the macro model according to the squared error sum with penaty parameter. This utility can be used to experiment more sophisticated optimization schemes.

Usage

jubilee.macro_cost(dtb, rs, penalty = c(1, 1, 1), new.tb3ms = NA,
  new.gs10 = NA)

Arguments

Value

The data table containing the "macro.cost" column

Author(s)

Stephen H. Lihn

The GUPTY macro model

Description

This utility contains the macro regression models, covering GUPTY: three types of GDP, UNRATE (unemployment rate), Payroll, and Treasury yield curve. TCU (total capacity utilization) is also covered in the model but less recommended. Given the in-sample time periods, it will perform model regressions and return a list storing relavant information about the result. The purpose of this method is to automate the regression and facilitate programatic cross validation.

Usage

jubilee.macro_fit(dtb, N, K, unrate.frac.start, gdp.frac.start, frac.end,
  cv.frac.end)

Arguments

Value

The list of data elements and their attributes.

Author(s)

Stephen H. Lihn

References

Stephen H.T. Lihn, "Business Cycles, Optimal Interest Rate, and Recession Forecast From Yield Curve, Unemployment, GDP, and Payrolls." Available at SSRN: https://ssrn.com/abstract=3422278

Examples

## Not run: 
  repo <- jubilee.repo()
  ju <- jubilee(repo@ie, 45, 20)
  N <- 4
  K <- 1.5
  rs <- jubilee.macro_fit(ju@reg.dtb, N, K, 1950, 1960, 2010, 2019)

## End(Not run)

Prediction from UNRATE and GDP models

Description

This utility performs the prediction from the linear models of UNRATE and GDP. The purpose of this method is to automate the prediction and to allow users experimenting optimization on the natural rate of interest.

Usage

jubilee.macro_predict(dtb, rs, new.tb3ms = NA, new.gs10 = NA)

Arguments

Value

The data table containing the predictions and all the required input columns

Author(s)

Stephen H. Lihn

Wrapper to calculate sapply using multi-core

Description

This utility calculates sapply using multi-core capability. It is a simple wrapper on simplify2array and parallel::mclapply. It is particularly convenient on Linux and Mac when parallelism saves significant amount of computing time.

Usage

jubilee.mcsapply(x, FUN, ...)

Arguments

Value

numeric

Author(s)

Stephen H. Lihn

Examples

   a <- seq(1,100)
   jubilee.mcsapply(a, function(x) x^2) # use multi-core!

Internal utility to calculate OLS regression

Description

Calculate the OLS regression for a given time series and fraction

Usage

jubilee.ols(fraction, ts, lookback.channel, tol.frac = 1/6)

Arguments

Value

data.table with columns of fraction, lm.a, lm.y, lm.r

Author(s)

Stephen H. Lihn

References

See Section 2.3 of Stephen H.T. Lihn, "Jubilee Tectonic Model: Forecasting Long-Term Growth and Mean Reversion in the U.S. Stock Market." Available at http://dx.doi.org/10.2139/ssrn.3156574

Examples

## Not run: 
  dtb <- jubilee.repo(online=FALSE)@ie
  df <- jubilee.ols(dtb$fraction, dtb$log.tri, 50)
  subset(df, fraction > 1970 & fraction < 1970.05)
  # fraction     lm.a      lm.r       lm.y
  # 1970.042 11.86401 0.1007617 0.02103105

## End(Not run)

Calculate the optimal TB3MS

Description

This utility calculates the optimal TB3MS using the analytic solution.

Usage

jubilee.optimal_tb3ms(dtb, rs, penalty = c(1, 1, 1))

Arguments

Value

The data table containing the "optimal.tb3ms" column

Author(s)

Stephen H. Lihn

Make prediction based on linear regression

Description

Make prediction based on the linear regression of the forward return. Refer to the tutorial for more detail.

Usage

jubilee.predict(object, lm, data)

jubilee.predict_real(object, lm, data)

Arguments

Value

data.table containing the prediction

Author(s)

Stephen H. Lihn

References

See Section 7 of Stephen H.T. Lihn, "Jubilee Tectonic Model: Forecasting Long-Term Growth and Mean Reversion in the U.S. Stock Market." Available at http://dx.doi.org/10.2139/ssrn.3156574

Internal utility to read FRED file

Description

This utility reads the internal static file, optionally amends with FRED online data, and returns the values of a given symbol.

Usage

jubilee.read_fred_file(fraction, local_file, symbol, online = FALSE,
  daily_symbol = NULL, period = "M")

Arguments

Value

The values of the symbol, numeric with the same length as fraction.

Author(s)

Stephen H. Lihn

Examples

## Not run: 
  repo <- jubilee.repo(online=FALSE)
  a <- jubilee.read_fred_file(repo@ie$fraction, "BAA.csv", "BAA")
  tail(a)

## End(Not run)

Constructor of jubilee.repo class

Description

Construct a jubilee.repo class by combining data from that of Robert Shiller since 1871, historical stock market data from 1802 to 1987 by William Schwert, 3-month Treasury bill rate, gold price, and several other economic time series from FRED. Optionally, this function can fetch more recent data from the website of Robert Shiller and Federal Reserve FRED website if the R session has connection to the internet.

Usage

jubilee.repo(online = TRUE, force = TRUE)

Arguments

Value

An object of jubilee.repo class

Author(s)

Stephen H. Lihn

Examples

## Not run: 
  repo <- jubilee.repo(online=FALSE)
  dtb <- repo@ie
  tail(dtb,1)

## End(Not run)

The jubilee repository class

Description

This S4 class stores the raw data for the jubilee package

Slots

call

The match.call slot

ie

data.table, contains the combined data from ie.raw, ws, and inflation.

yield.inversion

numeric, the fractions of yield curve inversion

raw.ie

data.table, contains the data from ie_data.xls of Robert Shiller

ws

data.table, contains the historical market return data from William Schwert

inflation

data.table, contains the historical inflation data from Minneapolis FED

comm.int

data.table, contains the historical commercial interest rate

tb3ms

data.table, contains the historical 3-month Treasury bill rate

gold

data.table, contains the historical monthly gold prices

gold2

data.table, contains the historical annual gold prices

create.time

POSIXct, records the creation time of this object.

Configuration of jubilee's data repository

Description

This utility stores the data configuration for the jubilee's data repository. This is used internally to provide proper abstraction to the data sources, such as file name, URL, FRED symbol, column name, decimal format, etc.

Usage

jubilee.repo.config()

Value

The list of data elements and their attributes.

Author(s)

Stephen H. Lihn

Examples

  c <- jubilee.repo.config()
  c$ie$url

Standard fault line data sets

Description

This method defines a collection of standard fault line data sets that have been analyzed and optimized in the research. It is intended for end users to produce standard regressions, forecasts, and charts quickly.

Usage

jubilee.std_fault_line(name)

Arguments

Value

numeric, pairs of fault lines, each is c(year, delta)

Author(s)

Stephen H. Lihn

Examples

  jubilee.std_fault_line("r_nom_f10_5ftr_4fl")
  jubilee.std_fault_line("r_nom_f20_5ftr_2fl")
  jubilee.std_fault_line("r_nom_f20_5ftr_2fl_ramp5y")

List of dates for yield curve inversion

Description

List of dates for yield curve inversion, generally compliant to the dating of business cycles after WWII in the U.S.. This data is also stored in the yield.inversion slot in the jubilee.repo object.

Usage

jubilee.yield_inversion()

Value

numeric, in the unit of fraction.

Author(s)

Stephen H. Lihn

Examples

  jubilee.yield_inversion()

Constructor of tri.wave class

Description

Construct an tri.wave object to simulate the triangular wave model.

Usage

tri.wave()

Value

an object of tri.wave class

Author(s)

Stephen H. Lihn

Examples

w <- tri.wave()

The triangular wave model class

Description

This S4 class defines the parameters in the triangular wave model.

Slots

call

the match.call slot.

a.t

numeric, the look-back channel in years

a0

numeric, the look-back channel in years

s1

numeric, the forward return duration in years

s2

numeric, the start fraction of in-sample training period

y.mean

numeric, the end fraction of in-sample training period

y.amp

numeric, the end fraction of in-sample training period

y.t

numeric, the end fraction of in-sample training period

y.p

numeric, the end fraction of in-sample training period

References

See Section 4 of Stephen H.T. Lihn, "Jubilee Tectonic Model: Forecasting Long-Term Growth and Mean Reversion in the U.S. Stock Market." Available at http://dx.doi.org/10.2139/ssrn.3156574

Methods of triangular wave model

Description

Methods of triangular wave model

Usage

triangle(t, p)

tri.wave.s(object, t)

tri.wave.a(object, t)

tri.wave.y(object, t)

tri.wave.x(object, t)

tri.wave.logr.y(object, t, p)

tri.wave.logr(object, t, p)

tri.wave.logr.semi(object, t)

tri.wave.logr.quarter(object, t)

Arguments

Value

numeric

Author(s)

Stephen H. Lihn

References

See Section 4 of Stephen H.T. Lihn, "Jubilee Tectonic Model: Forecasting Long-Term Growth and Mean Reversion in the U.S. Stock Market." Available at http://dx.doi.org/10.2139/ssrn.3156574

Examples

  w <- tri.wave()
  t <- seq(1900, 2000, by=1)
  tri.wave.y(w, t)