Package 'caustests'

Multiple Granger Causality Tests

Description

Performs various Granger causality tests including Toda-Yamamoto, Fourier-based tests (single and cumulative frequency), and quantile causality tests with bootstrap inference.

Usage

caustests(
  data,
  test,
  pmax = 8,
  ic = 1,
  nboot = 1000,
  kmax = 3,
  dmax = NULL,
  quantiles = seq(0.1, 0.9, 0.1),
  verbose = TRUE
)

Arguments

data	A data frame or matrix with time series variables (columns).
test	Integer 1-7 specifying the test type: 1: Toda-Yamamoto (1995) 2: Single Fourier Granger (Enders and Jones, 2016) 3: Single Fourier Toda-Yamamoto (Nazlioglu et al., 2016) 4: Cumulative Fourier Granger (Enders and Jones, 2019) 5: Cumulative Fourier Toda-Yamamoto (Nazlioglu et al., 2019) 6: Quantile Toda-Yamamoto (Cai et al., 2023) 7: Bootstrap Fourier Granger Causality in Quantiles (Cheng et al., 2021)
pmax	Maximum lag order for model selection (default: 8).
ic	Information criterion: 1 for AIC, 2 for SBC/BIC (default: 1).
nboot	Number of bootstrap replications (default: 1000).
kmax	Maximum Fourier frequency (default: 3, used for tests 2-5, 7).
dmax	Extra lags for Toda-Yamamoto augmentation. If NULL, automatically set to 0 for tests 2, 4 (differences) and 1 for tests 1, 3, 5, 6, 7 (levels).
quantiles	Numeric vector of quantiles for tests 6-7 (default: seq(0.1, 0.9, 0.1)).
verbose	Logical; print progress messages (default: TRUE).

Details

The package implements seven Granger causality tests:

Test 1: Toda-Yamamoto (1995) Standard Granger causality in levels using VAR with extra lags equal to the maximum integration order (dmax). This approach is robust to unknown integration and cointegration properties.

Tests 2-3: Single Fourier Frequency Incorporate a single Fourier frequency to capture smooth structural breaks. Test 2 uses first differences, Test 3 uses levels (Toda-Yamamoto style).

Tests 4-5: Cumulative Fourier Frequency Use cumulative Fourier frequencies (1 to k) for more flexible break patterns. Test 4 uses first differences, Test 5 uses levels.

Test 6: Quantile Toda-Yamamoto Extends Toda-Yamamoto to quantile regression, allowing causality analysis across different quantiles of the conditional distribution.

Test 7: Bootstrap Fourier Granger Causality in Quantiles (BFGC-Q) Combines Fourier flexibility with quantile regression for robust inference under structural breaks and across quantiles.

Value

An object of class "caustests" containing:

results	Data frame with test results for each direction
test	Test number used
test_name	Name of the test
pmax	Maximum lag considered
ic	Information criterion used
nboot	Number of bootstrap replications
kmax	Maximum Fourier frequency
dmax	Augmentation lags
quantiles	Quantiles used (for tests 6-7)
quantile_results	Detailed quantile results (for tests 6-7)
quantreg_warnings	For tests 6-7, a data frame with one row per direction and quantile giving the number of quantile regression fits (observed sample plus bootstrap replications) for which quantreg::summary.rq(se = "nid") reported "non-positive fis"; NULL for tests 1-5. The individual quantreg warnings are not shown; one summary warning is issued instead if any occurred.

References

Toda, H. Y. and Yamamoto, T. (1995). Statistical inference in vector autoregressions with possibly integrated processes. Journal of Econometrics, 66(1-2), 225-250. doi:10.1016/0304-4076(94)01616-8

Enders, W. and Jones, P. (2016). Grain prices, oil prices, and multiple smooth breaks in a VAR. Studies in Nonlinear Dynamics & Econometrics, 20(4), 399-419. doi:10.1515/snde-2014-0101

Nazlioglu, S., Gormus, N. A. and Soytas, U. (2016). Oil prices and real estate investment trusts (REITs): Gradual-shift causality and volatility transmission analysis. Energy Economics, 60, 168-175. doi:10.1016/j.eneco.2016.09.009

Nazlioglu, S., Soytas, U. and Gormus, N. A. (2019). Oil prices and monetary policy in emerging markets: Structural shifts in causal linkages. Emerging Markets Finance and Trade, 55(1), 105-117. doi:10.1080/1540496X.2018.1434072

Cai, Y., Chang, T., Xiang, Y. and Chang, H. L. (2023). Testing Granger causality in quantiles between the stock and the foreign exchange markets of Japan. Finance Research Letters, 58, 104327. doi:10.1016/j.frl.2023.104327

Cheng, S. C., Hsueh, H. P., Ranjbar, O., Wang, M. C. and Chang, T. (2021). Bootstrap Fourier Granger causality test in quantiles and the asymmetric causal relationship between CO2 emissions and economic growth. Letters in Spatial and Resource Sciences, 14, 31-49. doi:10.1007/s12076-020-00263-0

Examples

# Load example data
data(caustests_data)


# Test 1: Toda-Yamamoto test
result1 <- caustests(caustests_data, test = 1, nboot = 199)
print(result1)
summary(result1)

# Test 3: Single Fourier Toda-Yamamoto
result3 <- caustests(caustests_data, test = 3, kmax = 2, nboot = 199)
print(result3)

# Test 6: Quantile causality (fewer quantiles for speed)
result6 <- caustests(caustests_data, test = 6, 
                     quantiles = c(0.25, 0.50, 0.75), nboot = 199)
print(result6)

---

Example Time Series Dataset for Causality Tests

Description

A simulated dataset containing three time series variables for demonstrating Granger causality tests. The data includes one dependent variable (Y) and two potential causal variables (X1, X2) with known causal relationships.

Usage

caustests_data

Format

A data frame with 200 observations and 3 variables:

Y

Dependent variable, generated as AR(2) plus causal effects from X1

X1

First explanatory variable, AR(1) process

X2

Second explanatory variable, independent AR(1) process

Details

The data generating process is:

• X1 and X2 are independent AR(1) processes

• Y depends on its own lags plus lagged values of X1 (but not X2)

• This creates a true causal relationship from X1 to Y

• There is no true causality from X2 to Y or from Y to X1/X2

This allows users to verify that the causality tests correctly identify the causal direction X1 to Y while finding no significant causality in other directions (with appropriate sample sizes and test settings).

Source

Simulated data for package demonstration

Examples

data(caustests_data)
head(caustests_data)
summary(caustests_data)

# Check correlations
cor(caustests_data)

---

Example Panel Data for xtpcmg

Description

Returns the Grunfeld (1958) balanced panel dataset for examples.

Usage

grunfeld_cmg()

Value

A data frame with columns firm, year, invest, and mvalue.

Examples

dat <- grunfeld_cmg()
head(dat)

---

Example Panel Data for xtpcaus

Description

Returns a small balanced panel dataset (subset of Grunfeld 1958) for use in examples and testing.

Usage

grunfeld_panel()

Value

A data frame with columns firm, year, invest, and mvalue.

Examples

dat <- grunfeld_panel()
head(dat)

---

Plot Quantile Causality Results

Description

Creates diagnostic plots for quantile causality tests (tests 6-7).

Usage

## S3 method for class 'caustests'
plot(x, which = 1, type = "both", ...)

Arguments

x	An object of class "caustests" from test 6 or 7.
which	Which direction to plot (default: 1, first direction).
type	Plot type: "wald" for Wald statistics, "pval" for p-values, or "both" (default).
...	Additional arguments passed to plot.

Value

Invisibly returns the plotted data.

Examples

data(caustests_data)
result <- caustests(caustests_data, test = 6,
                    quantiles = c(0.25, 0.50, 0.75), nboot = 199)
plot(result)

---

Print Method for xtpcaus Objects

Description

Print Method for xtpcaus Objects

Usage

## S3 method for class 'xtpcaus'
print(x, ...)

Arguments

x	An object of class "xtpcaus".
...	Additional arguments (ignored).

Value

Invisibly returns x.

---

Print Method for xtpcmg Objects

Description

Print Method for xtpcmg Objects

Usage

## S3 method for class 'xtpcmg'
print(x, ...)

Arguments

x	An object of class "xtpcmg".
...	Additional arguments (ignored).

Value

Invisibly returns x.

---

Summary Method for xtpcaus Objects

Description

Summary Method for xtpcaus Objects

Usage

## S3 method for class 'xtpcaus'
summary(object, ...)

Arguments

object	An object of class "xtpcaus".
...	Additional arguments (ignored).

Value

Invisibly returns object.

---

Summary Method for xtpcmg Objects

Description

Summary Method for xtpcmg Objects

Usage

## S3 method for class 'xtpcmg'
summary(object, ...)

Arguments

object	An object of class "xtpcmg".
...	Additional arguments (ignored).

Value

Invisibly returns object.

---

Panel Granger Causality Tests

Description

Tests whether x Granger-causes y in a balanced panel using either the Panel Fourier Toda-Yamamoto (PFTY) test or the Panel Quantile Causality (PQC) test.

Usage

xtpcaus(
  data,
  y,
  x,
  panel_id,
  time_id,
  test = c("pfty", "pqc"),
  pmax = 4L,
  dmax = 1L,
  nboot = 499L,
  kmax = 3L,
  ic = c("aic", "bic"),
  quantiles = c(0.1, 0.25, 0.5, 0.75, 0.9),
  seed = -1L
)

Arguments

data	A data frame in long format.
y	Character. Name of the dependent (caused) variable.
x	Character. Name of the independent (causing) variable.
panel_id	Character. Name of the panel identifier variable.
time_id	Character. Name of the time variable.
test	Character. Test type: "pfty" for Panel Fourier Toda-Yamamoto or "pqc" for Panel Quantile Causality.
pmax	Integer. Maximum lag order for selection. Default is 4. Lag orders that leave fewer than 5 residual degrees of freedom are not considered (see Details).
dmax	Integer. Maximum integration order for Toda-Yamamoto augmentation. Default is 1. 0 omits the augmentation.
nboot	Integer. Number of bootstrap replications. Minimum 99. Default is 499.
kmax	Integer. Maximum Fourier frequency (PFTY only). Default is 3. 0 omits the Fourier terms.
ic	Character. Information criterion: "aic" or "bic". Default is "aic".
quantiles	Numeric vector. Quantile grid for PQC test (values strictly between 0 and 1). Default is c(0.1, 0.25, 0.50, 0.75, 0.90).
seed	Integer. Random seed for bootstrap. -1 means no seed. Default is -1. The global RNG state is restored on exit.

Details

PFTY specification. For each unit i the test regression is

$y_t = a + \sum_{k=1}^{p_i + dmax} g_k y_{t-k} + \sum_{k=1}^{p_i + dmax} b_k x_{t-k} + c_1 \sin(2 \pi f_i t / T) + c_2 \cos(2 \pi f_i t / T) + e_t,$

with p_i in 1..pmax and f_i in 1..kmax chosen jointly by the information criterion. The null hypothesis restricts the first p_i lags of x. The individual Wald statistic uses the residual variance RSS / n with n = T - p_i - dmax the effective sample (the normalisation of the Stata command caustests). kmax = 0 omits the Fourier terms; dmax = 0 omits the Toda-Yamamoto augmentation. With kmax = 0 and dmax = 0 the regression is the plain VAR(p) of Dumitrescu and Hurlin (2012, eq. 1) with a unit-specific lag order K_i = p_i.

Degrees of freedom. A lag order p is admissible only when the unrestricted regression keeps at least 5 residual degrees of freedom, T - (p + dmax) - k >= 5 with k = 2 (p + dmax) + 1 + 2 I(kmax > 0) regressors. Lag orders that violate this bound are not considered (a warning says so); if no lag order is admissible the function stops. This bound implies the condition T_i > 5 + 2 K_i of Dumitrescu and Hurlin (2012, eq. 10) for the existence of the second moments of the Wald statistic.

Dumitrescu and Hurlin (2012) statistics. Only for the plain specification (kmax = 0 and dmax = 0) the function reports the standardised statistics of Dumitrescu and Hurlin (2012). They are built from the individual Wald statistics with the unbiased residual variance RSS / (T_i - 2 K_i - 1) (the paper's main definition), where T_i = T - p_i is the effective sample of unit i: Z-bar is eq. (9) with the asymptotic moments K_i and 2 K_i, and Z-tilde is eq. (26) with the fixed-T moments of eq. (21) and (22),

$E(W_i) = K_i (T_i - 2 K_i - 1) / (T_i - 2 K_i - 3),$

$Var(W_i) = 2 K_i (T_i - 2 K_i - 1)^2 (T_i - K_i - 3) / ((T_i - 2 K_i - 3)^2 (T_i - 2 K_i - 5)).$

When the selected lag orders differ across units the moments are averaged over units: Z-bar uses the averaged asymptotic moments of eq. (11) of the paper (mean of K_i and of 2K_i), Z-tilde the averaged fixed-T moments of eq. (33). Both p-values are one-sided (upper tail), the decision rule of the paper. Z-tilde is the statistic to use at fixed T; Z-bar requires T to grow before N and is oversized in short panels (the paper's Table 1). For the Fourier or Toda-Yamamoto augmented specification the Wald statistics come from a different regression with a data-selected frequency, the moments of eq. (21) and (22) do not apply, and zbar, ztilde and their p-values are NA; inference then rests on the bootstrap Fisher p-value.

Bootstrap. The bootstrap is a residual bootstrap under the null built on Dumitrescu and Hurlin (2012, Section 6.2, steps 3 to 7). For each unit the model is re-estimated without the tested lags of x (restricted model) and its residuals are kept. In each replication a sequence of time indices is drawn with replacement from the periods common to all units and the same sequence is used for every unit (block of size 1 in time and size N in the cross-section), so that cross-sectional dependence of the residuals is preserved. A bootstrap series is generated recursively from the restricted model (intercept, autoregressive part, unrestricted lags of x, Fourier terms, resampled residuals; the observed first p_i + dmax values are the initial conditions), and the whole procedure, selection of the lag order and frequency included, is repeated on it. The paper's step 5 holds the lagged values of y fixed; the recursive construction is used here so that the selection step can be repeated, since the selection on the observed data inflates the Wald statistics in short panels. When there is a single candidate (pmax = 1 and kmax <= 1) the selection is skipped. The individual bootstrap p-values are combined by the Fisher statistic of Emirmahmutoglu and Kose (2011), -2 sum log p_i on 2 N degrees of freedom. For the plain specification the bootstrap distribution of Z-tilde is also recorded and ztilde_boot_pv is the one-sided bootstrap p-value. Bootstrap regressions that are singular or non-finite are dropped with a warning giving their number. In Monte Carlo experiments under the null with N = 10, pmax = 1, dmax = 1, kmax = 3 and nominal size 5 percent, the bootstrap Fisher test rejected about 12 percent at T = 20 and 9 percent at T = 50 (independent normal errors), while the plain specification was at nominal size; the selection of the Fourier frequency on short panels is absorbed only in part. For the Dumitrescu and Hurlin statistics use the plain specification.

Singular regressions. If the regressor matrix of a unit is singular for every admissible lag order (for example x constant or identical to y), its Wald statistic is NA, a warning names the unit and the unit is excluded from the panel statistics; N_used gives the number of units that enter them.

Input checks. Missing values in y, x, panel_id or time_id stop the function with the count and the row positions. Every unit must be observed at the same set of time values exactly once; duplicated or misaligned rows stop the function.

Random numbers. When seed >= 0 the bootstrap uses that seed in a local RNG scope: the state of the global random number generator is saved before and restored after the call.

Value

An object of class "xtpcaus" containing:

test

Character. "pfty" or "pqc".

N

Integer. Number of panel units.

TT

Integer. Number of time periods.

nboot

Integer. Number of bootstrap replications.

y

Character. Name of the y variable.

x

Character. Name of the x variable.

For PFTY:

fisher

Numeric. Fisher panel statistic, -2 sum log p_i over the bootstrap p-values of the units that enter the panel statistics.

fisher_df

Integer. Degrees of freedom (2 N_used).

fisher_pv

Numeric. Fisher p-value.

N_used

Integer. Number of units entering the panel statistics (units with a singular regression are excluded).

wbar

Numeric. Average individual Wald statistic (variance normalisation RSS / n).

wbar_dh

Numeric. Average individual Wald statistic with the unbiased variance RSS / (T_i - 2 K_i - 1) (Dumitrescu and Hurlin 2012, eq. 4). NA unless kmax = 0 and dmax = 0.

zbar

Numeric. Dumitrescu and Hurlin (2012) Z-bar statistic, eq. (9), with asymptotic moments. NA unless kmax = 0 and dmax = 0.

zbar_pv

Numeric. One-sided (upper tail) asymptotic p-value of zbar.

ztilde

Numeric. Dumitrescu and Hurlin (2012) Z-tilde statistic, eq. (26), with the fixed-T moments of eq. (21) and (22). NA unless kmax = 0 and dmax = 0.

ztilde_pv

Numeric. One-sided (upper tail) asymptotic p-value of ztilde.

ztilde_boot_pv

Numeric. One-sided bootstrap p-value of ztilde from the cross-sectional block bootstrap. NA unless kmax = 0 and dmax = 0.

ind_wald

Numeric vector. Individual Wald statistics (length N; NA for a unit with a singular regression).

ind_wald_dh

Numeric vector. Individual Wald statistics with the unbiased variance (length N). NA unless kmax = 0 and dmax = 0.

ind_pval_a

Numeric vector. Asymptotic chi-squared p-values of the individual Wald statistics (ind_wald) with ind_lags degrees of freedom (length N). Not used for the panel statistics; the bootstrap p-values are the basis of inference.

ind_freq

Integer vector. Selected Fourier frequencies (length N; 0 when kmax = 0).

ind_pval_b

Numeric vector. Bootstrap p-values (length N).

ind_lags

Integer vector. Selected lag orders (length N).

ind_df

Integer vector. Residual degrees of freedom of the unrestricted regressions (length N).

For PQC:

quantiles

Numeric vector. Quantiles tested.

wald_xy

Numeric vector. Wald statistics per quantile (x to y).

pval_xy

Numeric vector. Bootstrap p-values per quantile (x to y).

wald_yx

Numeric vector. Wald statistics per quantile (y to x).

pval_yx

Numeric vector. Bootstrap p-values per quantile (y to x).

supwald_xy

Numeric. Sup-Wald statistic for x to y.

supwald_yx

Numeric. Sup-Wald statistic for y to x.

p_opt

Integer. Selected optimal lag.

References

Chuang, C.C., Kuan, C.M. and Lin, H.Y. (2009). Causality in quantiles and dynamic stock return-volume relations. Journal of Banking and Finance, 33(7), 1351–1360. doi:10.1016/j.jbankfin.2009.02.013

Dumitrescu, E.I. and Hurlin, C. (2012). Testing for Granger non-causality in heterogeneous panels. Economic Modelling, 29(4), 1450–1460. doi:10.1016/j.econmod.2012.02.014

Emirmahmutoglu, F. and Kose, N. (2011). Testing for Granger causality in heterogeneous mixed panels. Economic Modelling, 28(3), 870–876. doi:10.1016/j.econmod.2010.10.018

Toda, H.Y. and Yamamoto, T. (1995). Statistical inference in vector autoregressions with possibly integrated processes. Journal of Econometrics, 66(1–2), 225–250. doi:10.1016/0304-4076(94)01616-8

Wang, K.M. and Nguyen, T.B. (2022). A quantile panel-type analysis of income inequality and healthcare expenditure. Economic Research, 35(1), 873–893. doi:10.1080/1331677X.2021.1948436

Yilanci, V. and Gorus, M.S. (2020). Does economic globalization have predictive power for ecological footprint. Environmental Science and Pollution Research, 27, 40552–40562. doi:10.1007/s11356-020-10092-9

Examples

dat <- grunfeld_panel()
# PFTY test (quick with few bootstrap reps)

res <- xtpcaus(dat, y = "invest", x = "mvalue",
               panel_id = "firm", time_id = "year",
               test = "pfty", pmax = 2L, dmax = 1L,
               nboot = 99L, kmax = 2L, seed = 42L)
print(res)

# Plain VAR(p) specification with the Dumitrescu and Hurlin (2012)
# Z-bar and Z-tilde statistics
res_dh <- xtpcaus(dat, y = "invest", x = "mvalue",
                  panel_id = "firm", time_id = "year",
                  test = "pfty", pmax = 2L, dmax = 0L,
                  nboot = 99L, kmax = 0L, seed = 42L)
print(res_dh)


# PQC test

res2 <- xtpcaus(dat, y = "invest", x = "mvalue",
                panel_id = "firm", time_id = "year",
                test = "pqc", pmax = 2L, nboot = 99L,
                quantiles = c(0.25, 0.50, 0.75), seed = 42L)
print(res2)

---

Panel Cointegrating Polynomial Regressions via FM-OLS

Description

Estimates a polynomial cointegrating regression in a panel using either Group-Mean FM-OLS (Wagner and Reichold 2023) or Pooled FM-OLS (de Jong & Wagner 2022). Models the long-run relationship:

Usage

xtpcmg(
  data,
  y,
  x,
  panel_id,
  time_id,
  model = c("mg", "pmg"),
  q = 2L,
  controls = NULL,
  trend = 1L,
  kernel = "ba",
  bw = "And91",
  effects = "oneway",
  corr_rob = FALSE
)

Arguments

data	A data frame in long format.
y	Character. Name of the dependent variable.
x	Character. Name of the polynomial (I(1)) regressor.
panel_id	Character. Name of the panel identifier variable.
time_id	Character. Name of the time variable.
model	Character. Estimator: "mg" for Group-Mean FM-OLS (default) or "pmg" for Pooled FM-OLS.
q	Integer. Polynomial degree: 2 (quadratic, default) or 3 (cubic).
controls	Character vector. Names of additional I(1) control variables. Default is NULL (no controls).
trend	Integer. Deterministic trend type: 1 for demeaning only (default), 2 for demeaning and detrending.
kernel	Character. HAC kernel: "ba" (Bartlett, default), "pa" (Parzen), "qs" (Quadratic Spectral), "tr" (truncated), "bo" (Bohman).
bw	Character or numeric. Bandwidth for HAC estimation. "And91" (default) uses Andrews (1991) automatic selection. A numeric value sets the bandwidth directly.
effects	Character. For Pooled FM-OLS: "oneway" (default) for one-way demeaning or "twoways" for two-way demeaning.
corr_rob	Logical. For Group-Mean FM-OLS: if TRUE, use cross-sectionally robust VCV. Default is FALSE.

Details

$y_{it} = \alpha_i + \beta_1 x_{it} + \beta_2 x_{it}^2 [+ \beta_3 x_{it}^3] [+ \gamma z_{it}] + u_{it}$

where $x_{it}$ and $z_{it}$ are I(1) processes.

Value

An object of class "xtpcmg" with elements: coefficients (named numeric vector), vcov (variance-covariance matrix), se (standard errors), tstat (t-statistics), pvalue (two-sided p-values), model (estimator type: mg or pmg), q (polynomial degree), N (number of panel units), TT (number of time periods), y (dependent variable name), x (polynomial variable name), tp (turning point estimate, quadratic models only), tp_se (delta-method SE for turning point), tp_lo and tp_hi (95% CI bounds), ind_coef (individual FM-OLS estimates, MG model), swamy_s and swamy_p (Swamy slope homogeneity test).

References

Andrews, D.W.K. (1991). Heteroskedasticity and autocorrelation consistent covariance matrix estimation. Econometrica, 59(3), 817–858. doi:10.2307/2938229

de Jong, R.M. and Wagner, M. (2022). Panel cointegrating polynomial regressions. Annals of Applied Statistics, 16(1), 416–442.

Wagner, M. and Reichold, K. (2023). Panel cointegrating polynomial regressions. Econometric Reviews, 42(9–10), 782–827. doi:10.1080/07474938.2023.2178141

Examples

dat <- grunfeld_cmg()

# Group-Mean FM-OLS (quadratic EKC-type model)
res <- xtpcmg(dat, y = "invest", x = "mvalue",
              panel_id = "firm", time_id = "year",
              model = "mg", q = 2L)
print(res)
summary(res)

# Pooled FM-OLS
res2 <- xtpcmg(dat, y = "invest", x = "mvalue",
               panel_id = "firm", time_id = "year",
               model = "pmg", q = 2L)
print(res2)

---