Package 'xtbreakcoint' reference manual

Title:	Panel Cointegration Tests with Structural Breaks
Description:	Implements panel cointegration tests allowing for structural breaks and cross-section dependence following the methodology of Banerjee and Carrion-i-Silvestre (2015) <doi:10.1002/jae.2348>. The package provides iterative factor-break estimation, individual ADF tests on defactored residuals, standardized panel test statistics, and the Bai and Ng (2004) <doi:10.1111/j.1468-0262.2004.00528.x> MQ test for identifying common stochastic trends. Supports five model specifications with varying deterministic components and break structures.
Authors:	Muhammad Alkhalaf [aut, cre, cph] (ORCID: <https://orcid.org/0009-0002-2677-9246>), Anindya Banerjee [ctb] (Original GAUSS code), Josep Lluis Carrion-i-Silvestre [ctb] (Original GAUSS code)
Maintainer:	Muhammad Alkhalaf <[email protected]>
License:	GPL-3
Version:	1.0.4
Built:	2026-05-28 07:21:36 UTC
Source:	https://github.com/muhammedalkhalaf/xtbreakcoint

Panel Cointegration Tests with Structural Breaks

Description

Implements panel cointegration tests allowing for structural breaks and cross-section dependence following the methodology of Banerjee and Carrion-i-Silvestre (2015). The package provides iterative factor-break estimation, individual ADF tests on defactored residuals, standardized panel test statistics, and the Bai and Ng (2004) MQ test for identifying common stochastic trends.

Details

The main function is xtbreakcoint, which performs the panel cointegration test.

Key Features:

Accounts for cross-section dependence through common factors
Allows for structural breaks in the cointegrating relationship
Supports five model specifications with varying deterministic components
Provides individual and panel test statistics
Includes the Bai & Ng (2004) MQ test for stochastic trends

Model Specifications:

Model 1 (constant): Constant only
Model 2 (trend): Constant plus linear trend
Model 3 (levelshift): Constant plus level shift at break
Model 4 (trendshift): Constant, trend, plus level shift (default)
Model 5 (regimeshift): Constant, trend, level shift, plus slope shift

Author(s)

Muhammad Alkhalaf

References

Banerjee, A., & Carrion-i-Silvestre, J. L. (2015). Cointegration in panel data with structural breaks and cross-section dependence. Journal of Applied Econometrics, 30(1), 1-22. doi:10.1002/jae.2348

Bai, J., & Ng, S. (2004). A PANIC attack on unit roots and cointegration. Econometrica, 72(4), 1127-1177. doi:10.1111/j.1468-0262.2004.00528.x

Bai, J., & Ng, S. (2002). Determining the number of factors in approximate factor models. Econometrica, 70(1), 191-221. doi:10.1111/1468-0262.00273

Print Method for xtbreakcoint Objects

Description

Print method for objects of class "xtbreakcoint".

Usage

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

Arguments

x

An object of class "xtbreakcoint".

...

Additional arguments (ignored).

Value

Invisibly returns x.

Examples

# Generate example panel data
set.seed(42)
N <- 5
T <- 30

panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = rnorm(N * T),
  x = rnorm(N * T)
)

result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time",
                       max_factors = 0)
print(result)
# Generate example panel data
set.seed(42)
N <- 5
T <- 30

panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = rnorm(N * T),
  x = rnorm(N * T)
)

result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time",
                       max_factors = 0)
print(result)

Summary Method for xtbreakcoint Objects

Description

Summary method for objects of class "xtbreakcoint", providing detailed output including individual unit results.

Usage

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

Arguments

object

An object of class "xtbreakcoint".

...

Additional arguments (ignored).

Value

Invisibly returns object.

Examples

# Generate example panel data
set.seed(42)
N <- 5
T <- 30

panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = rnorm(N * T),
  x = rnorm(N * T)
)

result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time",
                       max_factors = 0)
summary(result)
# Generate example panel data
set.seed(42)
N <- 5
T <- 30

panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = rnorm(N * T),
  x = rnorm(N * T)
)

result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time",
                       max_factors = 0)
summary(result)

Panel Cointegration Test with Structural Breaks

Description

Implements the panel cointegration test of Banerjee and Carrion-i-Silvestre (2015), allowing for structural breaks and cross-section dependence through common factors.

Usage

xtbreakcoint(
  formula,
  data,
  id,

  time,
  model = "trendshift",
  max_factors = 5,
  max_lag = 4,

  lag_method = c("auto", "fixed"),
  trim = 0.15,
  max_iter = 20,
  tolerance = 0.001
)
xtbreakcoint(
  formula,
  data,
  id,

  time,
  model = "trendshift",
  max_factors = 5,
  max_lag = 4,

  lag_method = c("auto", "fixed"),
  trim = 0.15,
  max_iter = 20,
  tolerance = 0.001
)

Arguments

formula

A formula of the form y ~ x1 + x2 + ... specifying the cointegrating relationship.

data

A data frame containing panel data with columns for the panel identifier, time identifier, and all variables in the formula.

id

Character string naming the panel (cross-section) identifier.

time

Character string naming the time identifier.

model

Model specification for deterministic components. One of: "constant" (1), "trend" (2), "levelshift" (3), "trendshift" (4, default), or "regimeshift" (5). Can also specify as integer 1-5.

max_factors

Maximum number of common factors to estimate (default: 5). Set to 0 to skip factor estimation.

max_lag

Maximum lag order for ADF tests (default: 4).

lag_method

Method for selecting ADF lag order: "auto" for automatic selection via BIC (default) or "fixed" to use max_lag.

trim

Trimming parameter for break estimation, proportion of sample excluded from endpoints (default: 0.15). Must be in (0, 0.5).

max_iter

Maximum iterations for factor-break estimation (default: 20).

tolerance

Convergence tolerance for iterative estimation (default: 0.001).

Details

This function tests for panel cointegration in the presence of structural breaks and cross-sectional dependence. The methodology follows these steps:

Iterative Factor-Break Estimation: Jointly estimates common factors and individual break dates using an iterative procedure.
Individual ADF Tests: Applies ADF tests to the defactored (idiosyncratic) residuals for each cross-section unit.
Panel Test Statistic: Combines individual ADF statistics into a standardized panel statistic using Monte Carlo moments.
MQ Test: If factors are detected, tests whether they are stationary or represent stochastic trends (Bai & Ng, 2004).

Value

An object of class "xtbreakcoint" containing:

Z_t: Panel test statistic (standard normal under H0)
p_value: One-sided p-value for Z_t
tbar: Average of individual ADF t-statistics
mean_t: Expected value of t-statistic under H0
var_t: Variance of t-statistic under H0
N: Number of cross-section units
T: Number of time periods
n_factors: Number of estimated common factors
n_trends: Number of stochastic trends (from MQ test)
MQ_np: Non-parametric MQ test statistic
MQ_p: Parametric MQ test statistic
iterations: Number of iterations for factor-break convergence
reject_pct: Percentage of individual units rejecting H0 at 5%
adf_stats: Vector of individual ADF t-statistics
lag_orders: Vector of selected lag orders for each unit
breaks: Vector of estimated break dates (periods from start)
factors: Matrix of estimated common factors (T-1 x n_factors)
model: Model specification used
call: The matched call

Model Specifications

1 - constant: Constant only
2 - trend: Constant plus linear trend
3 - levelshift: Constant plus level shift at break
4 - trendshift: Constant, trend, plus level shift (default)
5 - regimeshift: Constant, trend, level shift, plus slope shift

Author(s)

Muhammad Alkhalaf

References

Bai, J., & Ng, S. (2004). A PANIC attack on unit roots and cointegration. Econometrica, 72(4), 1127-1177. doi:10.1111/j.1468-0262.2004.00528.x

Examples

# Generate example panel data
set.seed(42)
N <- 10  # panels
T <- 50  # time periods

# Create cointegrated data with a structural break
panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = NA,
  x = NA
)

for (i in 1:N) {
  idx <- panel_data$id == i
  x <- cumsum(rnorm(T))
  u <- rnorm(T, sd = 0.5)
  # Cointegrating relationship with break at t=25
  beta <- ifelse(1:T <= 25, 1, 1.5)
  y <- 1 + beta * x + u
  panel_data$x[idx] <- x
  panel_data$y[idx] <- y
}

# Test for cointegration
result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time")
print(result)
# Generate example panel data
set.seed(42)
N <- 10  # panels
T <- 50  # time periods

# Create cointegrated data with a structural break
panel_data <- data.frame(
  id = rep(1:N, each = T),
  time = rep(1:T, N),
  y = NA,
  x = NA
)

for (i in 1:N) {
  idx <- panel_data$id == i
  x <- cumsum(rnorm(T))
  u <- rnorm(T, sd = 0.5)
  # Cointegrating relationship with break at t=25
  beta <- ifelse(1:T <= 25, 1, 1.5)
  y <- 1 + beta * x + u
  panel_data$x[idx] <- x
  panel_data$y[idx] <- y
}

# Test for cointegration
result <- xtbreakcoint(y ~ x, data = panel_data, id = "id", time = "time")
print(result)

Package 'xtbreakcoint'

Help Index

Panel Cointegration Tests with Structural Breaks

Description

Details

Author(s)

References

Print Method for xtbreakcoint Objects

Description

Usage

Arguments

Value

See Also

Examples

Summary Method for xtbreakcoint Objects

Description

Usage

Arguments

Value

See Also

Examples

Panel Cointegration Test with Structural Breaks

Description

Usage

Arguments

Details

Value

Model Specifications

Author(s)

References

Examples