Package 'tseffects'

Title: Dynamic Inferences from Time Series (with Interactions)
Description: Autoregressive distributed lag (A[R]DL) models (and their reparameterized equivalent, the Generalized Error-Correction Model [GECM]) are the workhorse models in uncovering dynamic inferences. ADL models are simple to estimate; this is what makes them attractive. Once these models are estimated, what is less clear is how to uncover a rich set of dynamic inferences from these models. We provide tools for recovering those inferences. These tools apply to traditional time-series quantities of interest and are built from the Impulse Response Function and Step Response Function (sometimes described as a pulse effect or a cumulative effect). They also allow for a variety of shock histories to be applied to the independent variable (beyond just a one-time, one-unit increase) as well as the recovery of inferences in levels for shocks applied to (in)dependent variables in differences (what we call the Generalized Dynamic Response Function). These effects are also available for the general conditional dynamic model advocated by Warner, Vande Kamp, and Jordan (2026 <doi:10.1017/psrm.2026.10087>). We also provide the formulae for these effects.
Authors: Soren Jordan [aut, cre, cph] (ORCID: <https://orcid.org/0000-0003-4201-1085>), Garrett N. Vande Kamp [aut], Reshi Rajan [aut]
Maintainer: Soren Jordan <[email protected]>
License: GPL (>=2)
Version: 0.3.1
Built: 2026-07-15 21:41:43 UTC
Source: https://github.com/sorenjordan/tseffects

Help Index

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for an autoregressive distributed lag (ADL) model, assuming the underlying model is in levels (d.x = d.y = 0) and the user wants a marginal effect (the untransformed GDRF). (This is just a wrapper for GDRF.adl.plot with simplifying assumptions)

Description

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for an autoregressive distributed lag (ADL) model, assuming the underlying model is in levels (d.x = d.y = 0) and the user wants a marginal effect (the untransformed GDRF). (This is just a wrapper for GDRF.adl.plot with simplifying assumptions)

Usage

adl.plot(
  model = NULL,
  x.vrbl = NULL,
  y.vrbl = NULL,
  shock.history = "pulse",
  dM.level = 0.95,
  s.limit = 20,
  se.type = "const",
  return.data = FALSE,
  return.plot = TRUE,
  return.formulae = FALSE,
  ...
)

Arguments

model

the lm model containing the ADL estimates
x.vrbl

a named numeric vector in which the names correspond to an independent variable and its lags and the numbers correspond to the specific lag order of each variable
y.vrbl

a named numeric vector in which the names correspond to lags of the dependent variable and the numbers correspond to the specific lag order of each variable. Can be NULL if the model has no lagged dependent variables
shock.history

the desired shock history. shock.history determines the shock history (h) (which can be expressed as an integer) that will be applied to the independent variable. -1 represents a pulse (Impulse Response Function). 0 represents a step (Step Response Function). These can also be specified via pulse and step. For others, see Vande Kamp, Jordan, and Rajan. The default is pulse
dM.level

a numeric significance level of the GDRF, calculated by the delta method. The default is 0.95
s.limit

an integer for the number of periods to determine the GDRF (beginning at s = 0)
se.type

a string for the type of standard error to extract from the model. The default is const, but any argument to vcovHC from the sandwich package is accepted
return.data

logical to return the raw calculated GDRFs as a list element under estimates. The default is FALSE
return.plot

logical to return the visualized GDRFs as a list element under plot. The default is TRUE
return.formulae

logical to return the formulae for the GDRFs as a list element under formulae (for the GDRFs) and binomials (for the shock history). The default is FALSE
...

other arguments to be passed to the call to plot

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# ADL(1,1)
# Use the toy data to run an ADL. No argument is made this is well specified; it is just expository
model.toydata <- lm(y ~ l_1_y + x + l_1_x, data = toy.ts.interaction.data)

# Since this is in levels, we can quickly look at the adl.plot
#  Pulse effect of x
adl.plot(model = model.toydata,
	x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_y" = 1),
	shock.history = "pulse",
	s.limit = 20)

Data on US Presidential Approval

Description

A dataset from: Cavari, Amnon. 2019. "Evaluating the President on Your Priorities: Issue Priorities, Policy Performance, and Presidential Approval, 1981–2016." Presidential Studies Quarterly 49(4): 798-826.

Usage

data(approval)

Format

A data frame with 140 rows and 14 variables:

APPROVE

Presidential approval

APPROVE_ECONOMY

Presidential approval: economy

APPROVE_FOREIGN

Presidential approval: foreign affairs

MIP_MACROECONOMICS

Salience (Most Important Problem): economy

MIP_FOREIGN

Salience (Most Important Problem): foreign affairs

PARTY_IN

Macropartisanship (in-party)

PARTY_OUT

Macropartisanship (out-party)

PRESIDENT

Numeric indicator for president

DIVIDEDGOV

Dummy variable for divided government

ELECTION

Dummy variable for election years

HONEYMOON

Dummy variable for honeymoon period

UMCSENT

Consumer sentiment

UNRATE

Unemployment rate

APPROVE_L1

Lagged presidential approval

Source

doi:10.1111/psq.12594

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for an autoregressive distributed lag (ADL) model

Description

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for an autoregressive distributed lag (ADL) model

Usage

GDRF.adl.plot(
  model = NULL,
  x.vrbl = NULL,
  y.vrbl = NULL,
  d.x = NULL,
  d.y = NULL,
  shock.history = "pulse",
  inferences.y = "levels",
  inferences.x = "levels",
  effect.type = "marginal",
  prediction.values = NULL,
  baseline.y = NULL,
  baseline.y.se = 0,
  shock.size = 1,
  dM.level = 0.95,
  s.limit = 20,
  se.type = "const",
  return.data = FALSE,
  return.plot = TRUE,
  return.formulae = FALSE,
  ...
)

Arguments

model

the lm model containing the ADL estimates
x.vrbl

a named numeric vector in which the names correspond to an independent variable and its lags and the numbers correspond to the specific lag order of each variable
y.vrbl

a named numeric vector in which the names correspond to lags of the dependent variable and the numbers correspond to the specific lag order of each variable. Can be NULL if the model has no lagged dependent variables
d.x

an integer describing how many times the independent variable was differenced before model estimation
d.y

an integer describing how many times the dependent variable was differenced before model estimation
shock.history

the desired shock history. shock.history determines the shock history (h) (which can be expressed as an integer) that will be applied to the independent variable. -1 represents a pulse (Impulse Response Function). 0 represents a step (Step Response Function). These can also be specified via pulse and step. For others, see Vande Kamp, Jordan, and Rajan. The default is pulse
inferences.y

does the user want resulting inferences about the dependent variable in levels or in differences? (For y variables where d.y is 0, this is automatically levels.) The default is levels
inferences.x

does the user want to apply the shock history to the independent variable in levels or in differences? (For x variables where d.x is 0, this is automatically levels.) The default is levels
effect.type

whether to return marginal effects or fitted values. marginal returns the GDRF as a marginal effect. fitted returns the GDRF as a fitted value, relative to a baseline value of y. The default is marginal
prediction.values

a named list of values for non-y variables in the model, used to calculate a steady-state baseline when effect.type = "fitted" and d.y = 0 and baseline.y is not supplied. This allows for the calculation of model-based uncertainty. If any differenced variables are included in the model, they should be set to 0. Ignored when d.y > 0
baseline.y

a user-supplied baseline value of y in levels. For d.y = 0, this overrides the steady-state calculation from prediction.values if provided. For d.y > 0 with inferences.y = "levels", this is required (otherwise it is just marginal effects). Only used when effect.type = "fitted"
baseline.y.se

a user-supplied standard error for the baseline value of y (to suggest uncertainty around predictions). If supplied, this is added in quadrature to the standard errors of the GDRF estimates. Only used when effect.type = "fitted" and inferences.y = "levels". The default is 0: in recognition that this is user-constructed uncertainty. Possible values would be the square root of the standard deviation of y (in levels)
shock.size

the size of the shock to x in the units of x. Only used when effect.type = "fitted"; marginal effects are not scaled. Defaults to 1 (a marginal effect)
dM.level

a numeric significance level of the GDRF, calculated by the delta method. The default is 0.95
s.limit

an integer for the number of periods to determine the GDRF (beginning at s = 0)
se.type

a string for the type of standard error to extract from the model. The default is const, but any argument to vcovHC from the sandwich package is accepted
return.data

logical to return the raw calculated GDRFs as a list element under estimates. The default is FALSE
return.plot

logical to return the visualized GDRFs as a list element under plot. The default is TRUE
return.formulae

logical to return the formulae for the GDRFs as a list element under formulae (for the GDRFs) and binomials (for the shock history). The default is FALSE
...

other arguments to be passed to the call to plot

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# ADL(1,1)
# Use the toy data to run an ADL. No argument is made this is well specified; it is just expository
model.toydata <- lm(y ~ l_1_y + x + l_1_x, data = toy.ts.interaction.data)

# Pulse effect of x
GDRF.adl.plot(model = model.toydata,
	x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_y" = 1),
	d.x = 0,
	d.y = 0,
	shock.history = "pulse",
	inferences.y = "levels",
	inferences.x = "levels",
	s.limit = 20)

# Step effect of x. You can store the data to draw your own plot,
#  if you prefer
test.cumulative <- GDRF.adl.plot(model = model.toydata,
	x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_y" = 1),
	d.x = 0,
	d.y = 0,
	shock.history = "step",
	inferences.y = "levels",
	inferences.x = "levels",
	s.limit = 20)
test.cumulative$plot

# Fitted values: steady state baseline from prediction.values
GDRF.adl.plot(model = model.toydata,
	x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_y" = 1),
	d.x = 0,
	d.y = 0,
	shock.history = "pulse",
	inferences.y = "levels",
	inferences.x = "levels",
	effect.type = "fitted",
	prediction.values = list("x" = 0, "l_1_x" = 0),
	s.limit = 20)

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for a Generalized Error Correction Model (GECM)

Description

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for a Generalized Error Correction Model (GECM)

Usage

GDRF.gecm.plot(
  model = NULL,
  x.vrbl = NULL,
  y.vrbl = NULL,
  x.vrbl.d.x = NULL,
  y.vrbl.d.y = NULL,
  x.d.vrbl = NULL,
  y.d.vrbl = NULL,
  x.d.vrbl.d.x = NULL,
  y.d.vrbl.d.y = NULL,
  shock.history = "pulse",
  inferences.y = "levels",
  inferences.x = "levels",
  effect.type = "marginal",
  prediction.values = NULL,
  baseline.y = NULL,
  baseline.y.se = 0,
  shock.size = 1,
  dM.level = 0.95,
  s.limit = 20,
  se.type = "const",
  return.data = FALSE,
  return.plot = TRUE,
  return.formulae = FALSE,
  ...
)

Arguments

model

the lm model containing the GECM estimates
x.vrbl

a named numeric vector of the x variables (of the lower level of differencing, usually in levels d = 0) and corresponding lag orders in the GECM model
y.vrbl

a named numeric vector of the (lagged) y variables (of the lower level of differencing, usually in levels d = 0) and corresponding lag orders in the GECM model
x.vrbl.d.x

the order of differencing of the x variable (of the lower level of differencing, usually in levels d = 0) in the GECM model
y.vrbl.d.y

the order of differencing of the y variable (of the lower level of differencing, usually in levels d = 0) in the GECM model
x.d.vrbl

a named numeric vector of the x variables (of the higher level of differencing, usually first differences d = 1) and corresponding lag orders in the GECM model
y.d.vrbl

a named numeric vector of the y variables (of the higher level of differencing, usually first differences d = 1) and corresponding lag orders in the GECM model. Can be NULL if the model has no lags of the differenced dependent variables
x.d.vrbl.d.x

the order of differencing of the x variable (of the higher level of differencing, usually first differences d = 1) in the GECM model
y.d.vrbl.d.y

the order of differencing of the y variable (of the higher level of differencing, usually first differences d = 1) in the GECM model
shock.history

the desired shock history. shock.history determines the shock history (h) that will be applied to the independent variable. -1 represents a pulse. 0 represents a step. These can also be specified via pulse and step. For others, see Vande Kamp, Jordan, and Rajan. The default is pulse
inferences.y

does the user want resulting inferences about the dependent variable in levels or in differences? The default is levels
inferences.x

does the user want to apply the shock history to the independent variable in levels or in differences? The default is levels
effect.type

whether to return marginal effects or fitted values. marginal returns the GDRF as a marginal effect. fitted returns the GDRF as a fitted value, relative to a baseline value of y. The default is marginal
prediction.values

a named list of values for non-y variables in the model, used to calculate a steady-state baseline when effect.type = "fitted" and d.y = 0 and baseline.y is not supplied. This allows for the calculation of model-based uncertainty. If any differenced variables are included in the model, they should be set to 0. Ignored when d.y > 0
baseline.y

a user-supplied baseline value of y in levels. For d.y = 0, this overrides the steady-state calculation from prediction.values if provided. For d.y > 0 with inferences.y = "levels", this is required (otherwise it is just marginal effects). Only used when effect.type = "fitted"
baseline.y.se

a user-supplied standard error for the baseline value of y (to suggest uncertainty around predictions). If supplied, this is added in quadrature to the standard errors of the GDRF estimates. Only used when effect.type = "fitted" and inferences.y = "levels". The default is 0: in recognition that this is user-constructed uncertainty. Possible values would be the square root of the standard deviation of y (in levels)
shock.size

the size of the shock to x in the units of x. Only used when effect.type = "fitted"; marginal effects are not scaled. Defaults to 1 (a marginal effect)
dM.level

a numeric significance level of the GDRF, calculated by the delta method. The default is 0.95
s.limit

an integer for the number of periods to determine the GDRF (beginning at s = 0)
se.type

a string for the type of standard error to extract from the model. The default is const, but any argument to vcovHC from the sandwich package is accepted
return.data

logical to return the raw calculated GDRFs as a list element under estimates. The default is FALSE
return.plot

logical to return the visualized GDRFs as a list element under plot. The default is TRUE
return.formulae

logical to return the formulae for the GDRFs as a list element under formulae (for the GDRFs) and binomials (for the shock history). The default is FALSE
...

other arguments to be passed to the call to plot

Details

We assume that the GECM model estimated is well specified, free of residual autocorrelation, balanced, and meets other standard time-series qualities. Given that, to obtain inferences for the specified shock history, the user only needs a named vector of the x and y variables, as well as the order of the differencing. Internally, the GECM to ADL equivalences are used to calculate the GDRFs from the GECM

Value

depending on return.data, return.plot, and return.formulae, a list of elements relating to the GDRF

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# GECM(1,1)
# Use the toy data to run a GECM. No argument is made this 
#  is well specified or even sensible; it is just expository
model <- lm(d_y ~ l_1_y + l_1_x + l_1_d_y + d_x + l_1_d_x, data = toy.ts.interaction.data)
test.pulse <- GDRF.gecm.plot(model = model,
                                  x.vrbl = c("l_1_x" = 1), 
                                  y.vrbl = c("l_1_y" = 1),
                                  x.vrbl.d.x = 0, 
                                  y.vrbl.d.y = 0,
                                  x.d.vrbl = c("d_x" = 0, "l_1_d_x" = 1),
                                  y.d.vrbl = c("l_1_d_y" = 1),
                                  x.d.vrbl.d.x = 1,
                                  y.d.vrbl.d.y = 1,
                                  shock.history = "pulse", 
                                  inferences.y = "levels", 
                                  inferences.x = "levels",
                                  s.limit = 10, 
                                  return.plot = TRUE, 
                                  return.formulae = TRUE)
names(test.pulse)

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for a GECM(1,1) model, assuming the underlying model is in first differences (x.vrbl.d.x = y.vrbl.d.y = 0 and x.d.vrbl.d.x = y.d.vrbl.d.y = 1) and the user wants a marginal effect (the untransformed GDRF) and inferences about y in levels to a treatment applied to x in levels. (This is just a wrapper for GDRF.gecm.plot with simplifying assumptions)

Description

Evaluate (and possibly plot) the General Dynamic Response Function (GDRF) for a GECM(1,1) model, assuming the underlying model is in first differences (x.vrbl.d.x = y.vrbl.d.y = 0 and x.d.vrbl.d.x = y.d.vrbl.d.y = 1) and the user wants a marginal effect (the untransformed GDRF) and inferences about y in levels to a treatment applied to x in levels. (This is just a wrapper for GDRF.gecm.plot with simplifying assumptions)

Usage

gecm.plot(
  model = NULL,
  x.vrbl = NULL,
  y.vrbl = NULL,
  x.d.vrbl = NULL,
  y.d.vrbl = NULL,
  shock.history = "pulse",
  dM.level = 0.95,
  s.limit = 20,
  se.type = "const",
  return.data = FALSE,
  return.plot = TRUE,
  return.formulae = FALSE,
  ...
)

Arguments

model

the lm model containing the GECM estimates
x.vrbl

a named numeric vector of the x variables (of the lower level of differencing, usually in levels d = 0) and corresponding lag orders in the GECM model
y.vrbl

a named numeric vector of the (lagged) y variables (of the lower level of differencing, usually in levels d = 0) and corresponding lag orders in the GECM model
x.d.vrbl

a named numeric vector of the x variables (of the higher level of differencing, usually first differences d = 1) and corresponding lag orders in the GECM model
y.d.vrbl

a named numeric vector of the y variables (of the higher level of differencing, usually first differences d = 1) and corresponding lag orders in the GECM model. Can be NULL if the model has no lags of the differenced dependent variables
shock.history

the desired shock history. shock.history determines the shock history (h) that will be applied to the independent variable. -1 represents a pulse. 0 represents a step. These can also be specified via pulse and step. For others, see Vande Kamp, Jordan, and Rajan. The default is pulse
dM.level

a numeric significance level of the GDRF, calculated by the delta method. The default is 0.95
s.limit

an integer for the number of periods to determine the GDRF (beginning at s = 0)
se.type

a string for the type of standard error to extract from the model. The default is const, but any argument to vcovHC from the sandwich package is accepted
return.data

logical to return the raw calculated GDRFs as a list element under estimates. The default is FALSE
return.plot

logical to return the visualized GDRFs as a list element under plot. The default is TRUE
return.formulae

logical to return the formulae for the GDRFs as a list element under formulae (for the GDRFs) and binomials (for the shock history). The default is FALSE
...

other arguments to be passed to the call to plot

Details

We assume that the GECM model estimated is well specified, free of residual autocorrelation, balanced, and meets other standard time-series qualities. Given that, to obtain inferences for the specified shock history, the user only needs a named vector of the x and y variables, as well as the order of the differencing. Internally, the GECM to ADL equivalences are used to calculate the GDRFs from the GECM

Value

depending on return.data, return.plot, and return.formulae, a list of elements relating to the GDRF

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# GECM(1,1). So we can use gecm.plot to quickly check dynamics
# Use the toy data to run a GECM. No argument is made this 
#  is well specified or even sensible; it is just expository
model <- lm(d_y ~ l_1_y + l_1_x + l_1_d_y + d_x + l_1_d_x, data = toy.ts.interaction.data)
test.pulse <- gecm.plot(model = model,
                                  x.vrbl = c("l_1_x" = 1), 
                                  y.vrbl = c("l_1_y" = 1),
                                  x.d.vrbl = c("d_x" = 0, "l_1_d_x" = 1),
                                  y.d.vrbl = c("l_1_d_y" = 1),
                                  shock.history = "pulse", 
                                  s.limit = 10, 
                                  return.plot = TRUE, 
                                  return.formulae = TRUE)
names(test.pulse)

Translate the coefficients from the General Error Correction Model (GECM) to the autoregressive distributed lag (ADL) model

Description

Translate the coefficients from the General Error Correction Model (GECM) to the autoregressive distributed lag (ADL) model

Usage

gecm.to.adl(x.vrbl, y.vrbl, x.d.vrbl, y.d.vrbl)

Arguments

x.vrbl

a named numeric vector in which the names correspond to an independent variable (of the lower level of differencing, usually in levels d = 0) and its lags and the numbers correspond to the specific lag order of each variable in the GECM model
y.vrbl

a named numeric vector in which the names correspond to lags of the dependent variable (of the lower level of differencing, usually in levels d = 0) and the numbers correspond to the specific lag order of each variable in the GECM model
x.d.vrbl

a named numeric vector in which the names correspond to an independent variable (of the higher level of differencing, usually in first differences d = 1) and its lags and the numbers correspond to the specific lag order of each variable in the GECM model
y.d.vrbl

a named numeric vector in which the names correspond to lags of the dependent variable (of the higher level of differencing, usually in first differences d = 1) and the numbers correspond to the specific lag order of each variable in the GECM model

Details

gecm.to.adl utilizes the mathematical equivalence between the GECM and ADL models to translate the coefficients from one to the other. This way, we can apply a single function using the ADL math to calculate effects

Value

a list of named vectors of translated ADL coefficients for the x and y variables of interest

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# GECM(1,1)
the.x.vrbl <- c("l_1_x" = 1) 
the.y.vrbl <- c("l_1_y" = 1) 
the.x.d.vrbl <- c("d_x" = 0, "l_1_d_x" = 1) 
the.y.d.vrbl <- c("l_1_d_y" = 1) 
adl.coef <- gecm.to.adl(x.vrbl = the.x.vrbl, y.vrbl = the.y.vrbl, 
			x.d.vrbl = the.x.d.vrbl, y.d.vrbl = the.y.d.vrbl)
adl.coef$x.vrbl.adl
adl.coef$y.vrbl.adl

Generate the generalized effect formulae for an autoregressive distributed lag (ADL) model, given pulse effects and shock history

Description

Generate the generalized effect formulae for an autoregressive distributed lag (ADL) model, given pulse effects and shock history

Usage

general.calculator(d.x, d.y, h, limit, pulses)

Arguments

d.x

an integer determining the order of differencing of the x variable before a shock is applied when parametrized as an ADL model. (Generally, this is the same x variable used in pulse.calculator)
d.y

an integer determining the order of differencing of the y variable when parametrized as an ADL model. (Generally, this is the same y variable used in pulse.calculator)
h

an integer determining the shock history applied to the independent variable in levels. -1 represents the Impulse Response Function. 0 represents a Step Response Function. For others, see Vande Kamp, Jordan, and Rajan
limit

an integer for the number of periods (s) to determine the generalized effect (beginning at 0)
pulses

a list comprising the formulae for Impulse Response Functions, typically generated using pulse.calculator

Details

general.calculator does no calculation. It generates a list of mpoly formulae that contain variable names that represent the generalized effect in each period. The expectation is that these will be evaluated using coefficients from an object containing an ADL model with corresponding variables. Note: mpoly does not allow variable names with a .; variables passed to general.calculator should not include this character

Value

a list of limit + 1 mpoly formulae containing the generalized effect formula in each period

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# ADL(1,1)
x.lags <- c("x" = 0, "l_1_x" = 1) # lags of x
y.lags <- c("l_1_y" = 1)
s <- 5
pulse.effects <- pulse.calculator(x.vrbl = x.lags, y.vrbl = y.lags, limit = s)
# Assume that both x and y are in levels and we want a pulse shock history
general.pulse.effects <- general.calculator(d.x = 0, d.y = 0, 
							h = -1, limit = s, pulses = pulse.effects)
general.pulse.effects
# Apply a step shock response function
general.step.effects <- general.calculator(d.x = 0, d.y = 0, 
							h = 0, limit = s, pulses = pulse.effects)
general.step.effects

Plot the interaction in a single-equation time series model estimated via lm.

Description

Plot the interaction in a single-equation time series model estimated via lm.

Usage

interact.adl.plot(
  model = NULL,
  x.vrbl = NULL,
  z.vrbl = NULL,
  x.z.vrbl = NULL,
  y.vrbl = NULL,
  shock.history = "impulse",
  plot.type = "lines",
  line.options = "z.lines",
  heatmap.options = "significant",
  line.colors = "okabe-ito",
  heatmap.colors = "Blue-Red",
  z.vals = NULL,
  s.vals = c(0, "LRM"),
  z.label.rounding = 3,
  z.vrbl.label = names(z.vrbl)[1],
  dM.level = 0.95,
  s.limit = 20,
  se.type = "const",
  return.data = FALSE,
  return.plot = TRUE,
  return.formulae = FALSE,
  ...
)

Arguments

model

the lm model containing the ADL estimates
x.vrbl

named numeric vector of the “main” x variables and corresponding lag orders in the ADL model
z.vrbl

named numeric vector of the “moderating” z variables and corresponding lag orders in the ADL model
x.z.vrbl

named numeric vector with the interaction variables and corresponding lag orders in the ADL model. IMPORTANT: enter the lag order that pertains to the “main” x variable. For instance, x_l_1_z (contemporaneous x times lagged z) would be 0 and l_1_x_z (lagged x times contemporaneous z) would be 1
y.vrbl

named numeric vector of the (lagged) y variables and corresponding lag orders in the ADL model. Can be NULL if the model has no lagged dependent variables
shock.history

whether impulse/pulse or cumulative/step effects should be calculated. impulse (or pulse) generates impulse effects (the Impulse Response Function), or short-run/instantaneous effects specific to each period. cumulative (or step: the Step Response Function) generates the accumulated, or long-run/cumulative effects up to each period (including the long-run multiplier). The default is impulse
plot.type

a string for whether to feature marginal effects at discrete values of s/z as lines, or across a range of values through a heatmap. The default is lines
line.options

if drawing lines, a string for whether the moderator should be values of z (z.lines) or values of s (s.lines). The default is z.lines
heatmap.options

if drawing a heatmap, a string for whether all marginal effects should be shown or just statistically significant ones. (Note: this just sets the insignificant effects to the numeric value of 0. If the middle value of your scale gradient is white, these will effectively “disappear.” If another gradient is used, they will take on the color assigned to 0 values.) The default is significant
line.colors

a string for what color lines would you like for line plots? This defaults to the color-safe Okabe-Ito (okabe-ito) colors. There is also a grayscale option through bw. Users can also include whatever colors they like. The number of colors must match the number of lines drawn. This is passed to scale_color_discrete
heatmap.colors

a string for what color scale would you like for the heatmap? The default is Blue-Red. Alternate colors must be one of hcl.pals(). For grayscale plots, use Grays. This is passed to scale_fill_gradientn
z.vals

numeric values for the moderating variable. If plot.type = lines, these are treated as discrete levels of z. If plot.type = heatmap, these are treated as a lower and upper level of a range of values of z. If none are provided, interact.adl.plot will pick
s.vals

numeric values for the time since the shock. This is only used if line.options = s.lines, meaning s is treated as the moderator. The default is 0 (short-run) and the LRM
z.label.rounding

number of digits to round to for the z labels in the legend (if those values are automatically calculated)
z.vrbl.label

the name of the moderating z variable, used in plotting
dM.level

significance level of the (cumulative) marginal effects, calculated by the delta method. The default is 0.95
s.limit

an integer for the number of periods to determine the (cumulative) marginal effects (beginning at s = 0)
se.type

the type of standard error to extract from the model. The default is const, but any argument to vcovHC from the sandwich package is accepted
return.data

logical to return the raw calculated (cumulative) marginal effects as a list element under estimates. The default is FALSE
return.plot

logical to return the visualized (cumulative) marginal effects as a list element under plot. The default is TRUE
return.formulae

logical to return the formulae for the (cumulative) marginal effects as a list element under formulae (for the (cumulative) marginal effects) and binomials (for the shock history). The default is FALSE
...

other arguments to be passed to the call to plot

Details

We assume that the ADL model estimated is well specified, free of residual autocorrelation, balanced, and meets other standard time-series qualities. It is imperative that you double-check you have referenced all x, y, z, and interaction terms through x.vrbl, y.vrbl, z.vrbl, and x.z.vrbl. You must also have their orders correctly entered. interact.adl.plot has no way of determining, from the variable list, which correspond with which

Value

depending on return.data, return.plot, and return.formulae, a list of elements relating to the interaction

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# Using Cavari's (2019) approval model
# Cavari's original model: APPROVE ~ APPROVE_ECONOMY + APPROVE_FOREIGN + MIP_MACROECONOMICS + 
#     MIP_FOREIGN + APPROVE_ECONOMY*MIP_MACROECONOMICS + APPROVE_FOREIGN*MIP_FOREIGN + 
#     APPROVE_L1 + PARTY_IN + PARTY_OUT + UNRATE + 
#     DIVIDEDGOV + ELECTION + HONEYMOON + as.factor(PRESIDENT)

approval$ECONAPP_ECONMIP <- approval$APPROVE_ECONOMY*approval$MIP_MACROECONOMICS
approval$FPAPP_ECONFP <- approval$APPROVE_FOREIGN*approval$MIP_FOREIGN

cavari.model <- lm(APPROVE ~ APPROVE_ECONOMY + APPROVE_FOREIGN + MIP_MACROECONOMICS + 
     MIP_FOREIGN + ECONAPP_ECONMIP + FPAPP_ECONFP + 
     APPROVE_L1 + PARTY_IN + PARTY_OUT + UNRATE + 
     DIVIDEDGOV + ELECTION + HONEYMOON + as.factor(PRESIDENT), data = approval)

# Now: marginal effect of X at different levels of Z
interact.adl.plot(model = cavari.model, 
	x.vrbl = c("APPROVE_ECONOMY" = 0), y.vrbl = c("APPROVE_L1" = 1),
		z.vrbl = c("MIP_MACROECONOMICS" = 0), x.z.vrbl = c("ECONAPP_ECONMIP" = 0),
	shock.history = "impulse", plot.type = "lines", line.options = "z.lines")

# Use well-behaved simulated data (included) for even more examples, 
#  using the Warner, Vande Kamp, and Jordan general model
model.toydata <- lm(y ~ l_1_y + x + l_1_x + z + l_1_z +
	x_z + z_l_1_x +
	x_l_1_z + l_1_x_l_1_z, data = toy.ts.interaction.data)

# Marginal effect of z (not run: computational time)
# Be sure to specify x.z.vrbl orders with respect to x term
## Not run: interact.adl.plot(model = model.toydata, x.vrbl = c("x" = 0, "l_1_x" = 1), 
				y.vrbl = c("l_1_y" = 1), z.vrbl = c("z" = 0, "l_1_z" = 1),
				x.z.vrbl = c("x_z" = 0, "z_l_1_x" = 1, 
					"x_l_1_z" = 0, "l_1_x_l_1_z" = 1),
				z.vals = -2:2,
				shock.history = "impulse", 
				plot.type = "lines", 
				line.options = "z.lines",
				s.limit = 20)

## End(Not run)

# Heatmap of marginal effects, since X and Z are actually continuous
#  (not run: computational time)
## Not run: interact.adl.plot(model = model.toydata, x.vrbl = c("x" = 0, "l_1_x" = 1), 
				y.vrbl = c("l_1_y" = 1), z.vrbl = c("z" = 0, "l_1_z" = 1),
				x.z.vrbl = c("x_z" = 0, "z_l_1_x" = 1, 
					"x_l_1_z" = 0, "l_1_x_l_1_z" = 1),
				z.vals = c(-2,2),
				shock.history = "impulse", 
				plot.type = "heatmap", 
				heatmap.options = "all",
				s.limit = 20)

## End(Not run)

Generate pulse effect formulae for a given autoregressive distributed lag (ADL) model

Description

Generate pulse effect formulae for a given autoregressive distributed lag (ADL) model

Usage

pulse.calculator(x.vrbl, y.vrbl = NULL, limit)

Arguments

x.vrbl

a named numeric vector in which the names correspond to an independent variable and its lags and the numbers correspond to the specific lag order of each variable
y.vrbl

a named numeric vector in which the names correspond to lags of the dependent variable and the numbers correspond to the specific lag order of each variable. Can be NULL if the model has no lagged dependent variables
limit

an integer representing the number of periods after the initial shock (s) to calculate the Impulse Response Function

Details

pulse.calculator does no calculation. It generates a list of mpoly formulae that contain variable names that represent the pulse effect in each period. The expectation is that these will be evaluated using coefficients from an object containing an ADL model with corresponding variables. Note: mpoly does not allow variable names with a .; variables passed to pulse.calculator should not include this character

Value

a list of limit + 1 mpoly formulae containing the pulse effect formula in each period

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# ADL(1,1)
x.lags <- c("x" = 0, "l_1_x" = 1) # lags of x
y.lags <- c("l_1_y" = 1)
s <- 5
pulses <- pulse.calculator(x.vrbl = x.lags, y.vrbl = y.lags, limit = s)
pulses
# Will also handle finite dynamics
x.lags <- c("x" = 0, "l_1_x" = 1) # lags of x
finite.pulses <- pulse.calculator(x.vrbl = x.lags, limit = s)

Simulated interactive time series data

Description

A simulated, well-behaved dataset of interactive time series data

Usage

data(toy.ts.interaction.data)

Format

A data frame with 50 rows and 23 variables:

time

Indicator for time period

x

Contemporaneous x

l_1_x

First lag of x

l_2_x

Second lag of x

l_3_x

Third lag of x

l_4_x

Fourth lag of x

l_5_x

Fifth lag of x

d_x

First difference of x

l_1_d_x

First lag of first difference of x

l_2_d_x

Second lag of first difference of x

l_3_d_x

Third lag of first difference of x

z

Contemporaneous z

l_1_z

First lag of z

l_2_z

Second lag of z

l_3_z

Third lag of z

l_4_z

Fourth lag of z

l_5_z

Fifth lag of z

y

Contemporaneous y

l_1_y

First lag of y

l_2_y

Second lag of y

l_3_y

Third lag of y

l_4_y

Fourth lag of y

l_5_y

Fifth lag of y

d_y

First difference of y

l_1_d_y

First lag of first difference of y

l_2_d_y

Second lag of first difference of y

d_2_y

Second difference of y

l_1_d_2_y

First lag of second difference of y

x_z

Interaction of contemporaneous x and z

x_l_1_z

Interaction of contemporaneous x and lagged z

z_l_1_x

Interaction of lagged x and contemporaneous z

l_1_x_l_1_z

Interaction of lagged x and lagged z

Transform the GDRF formulae to fitted value formulae

Description

Transform the GDRF formulae to fitted value formulae

Usage

yhat.calculator(
  formulae,
  d.y,
  model,
  the.coef,
  y.vrbl = NULL,
  inferences.y = NULL,
  prediction.values = NULL,
  baseline.y = NULL,
  shock.size = 1
)

Arguments

formulae

the list of formulae from general.calculator
d.y

an integer for the order of differencing of the y variable in the ADL model
model

the lm model containing the model estimates
the.coef

the coefficient vector from the estimated model
y.vrbl

a named vector of the (lagged) y variables and corresponding lag orders in the ADL model
inferences.y

whether the inferences for the dependent variable are in levels or differences. Must be one of levels or differences
prediction.values

a named list of values for non-y variables in the model, used to calculate a steady-state baseline when d.y = 0 and baseline.y is not supplied. If any differenced variables are included in the model, they should be set to 0. Ignored when d.y > 0
baseline.y

a user-supplied baseline value of y in levels. For d.y = 0, this overrides the steady-state calculation from prediction.values. For d.y > 0 with inferences.y = "levels", this is required. Optional uncertainty around this baseline can be supplied through baseline.y.se in the calling function
shock.size

the size of the shock to x in the units of x. Defaults to 1 (the marginal effect)

Details

yhat.calculator does no calculation. It transforms the formulae from general.calculator into fitted value formulae by prepending a baseline value of y. For d.y = 0, the baseline is either a user-supplied value or a model-implied steady-state prediction, the latter of which incorporates model-based uncertainty. For d.y > 0, the baseline must be user-supplied through baseline.y, as the model in differences contains no information about the level of y. Optional uncertainty around a user-supplied baseline can be added through baseline.y.se, it is added as a post-processing step in the calling function

Value

a list of limit + 1 formula strings containing the fitted value formula in each period, for evaluation by deltaMethod in the calling function

Author(s)

Soren Jordan, Garrett N. Vande Kamp, and Reshi Rajan

Examples

# ADL model with y in levels
model.levels <- lm(y ~ x + l_1_x + l_1_y, data = toy.ts.interaction.data)

# set up formulae
pulses.levels <- pulse.calculator(x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_y" = 1), limit = 5)
general.levels <- general.calculator(d.x = 0, d.y = 0, h = -1,
	limit = 5, pulses = pulses.levels)

# I(0) y: steady state from means (warns about differenced variables)
#  Note this would mean different values for x and l_1_x, which might be undesirable
yhat.calculator(formulae = general.levels$formulae, d.y = 0,
	model = model.levels, the.coef = coef(model.levels),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	prediction.values = NULL, baseline.y = 0, shock.size = 1)

# I(0) y: steady state from supplied prediction.values (same values for both x/l_1_x)
yhat.calculator(formulae = general.levels$formulae, d.y = 0,
	model = model.levels, the.coef = coef(model.levels),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	prediction.values = list("x" = 1, "l_1_x" = 1),
	baseline.y = NULL, shock.size = 1)

# I(0) y: user-supplied baseline.y overrides prediction.values
yhat.calculator(formulae = general.levels$formulae, d.y = 0,
	model = model.levels, the.coef = coef(model.levels),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	prediction.values = list("x" = 0, "l_1_x" = 1),
	baseline.y = 5, shock.size = 1)

# ADL model with differenced y
model.diffs <- lm(d_y ~ x + l_1_x + l_1_d_y, data = toy.ts.interaction.data)

# set up formulae
pulses.diffs <- pulse.calculator(x.vrbl = c("x" = 0, "l_1_x" = 1),
	y.vrbl = c("l_1_d_y" = 1), limit = 5)
general.diffs <- general.calculator(d.x = 0, d.y = 1, h = -1,
	limit = 5, pulses = pulses.diffs)

## Not run: 
# inferences in differences, baseline.y != 0. warn that this makes no sense (implies the
#  model is always changing) and change baseline.y to 0
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "differences",
	baseline.y = 3, shock.size = 1)
	
# inferences in differences, shock size of 1: identical to marginal effect (warns)
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "differences",
	baseline.y = NULL, shock.size = 1)

# inferences in differences, shock size of 2: scales the marginal effect
#  Since we're asking for inferences.y in differences, the baseline will automatically be 0
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "differences",
	baseline.y = NULL, shock.size = 2)

# inferences in levels with no baseline.y: stops with an error
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	baseline.y = NULL, shock.size = 2)

# inferences in levels with prediction.values but no baseline.y: warns and stops
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	prediction.values = list("x" = 1, "l_1_x" = 1),
	baseline.y = NULL, shock.size = 2)

## End(Not run)

# inferences in levels with a supplied baseline
yhat.calculator(formulae = general.diffs$formulae, d.y = 1,
	model = model.diffs, the.coef = coef(model.diffs),
	y.vrbl = c("l_1_y" = 1), inferences.y = "levels",
	prediction.values = list("x" = 1, "l_1_x" = 1),
	baseline.y = 5, shock.size = 2)