westerlund_test: Westerlund ECM-Based Panel Cointegration Test

In Westerlund: Panel Cointegration Tests Based on Westerlund (2007)

Westerlund ECM-Based Panel Cointegration Test

Description

Implements the error-correction-based panel cointegration tests proposed by Westerlund (2007). The function computes both mean-group (G_t, G_a) and pooled (P_t, P_a) statistics based on unit-specific ECMs, with Stata-like input validation, time-continuity checks, and optional bootstrap p-values for the raw statistics.

Usage

westerlund_test(
  data,
  yvar,
  xvars,
  idvar,
  timevar,
  constant = FALSE,
  trend = FALSE,
  lags,
  leads = NULL,
  westerlund = FALSE,
  aic = TRUE,
  bootstrap = -1,
  indiv.ecm = FALSE,
  lrwindow = 2,
  verbose = FALSE
)

Arguments

data	A data.frame containing the panel data. Panels may be unbalanced, but each unit's time index must be continuous (no holes) after removing missing observations on model variables.
yvar	String. Name of the dependent variable.
xvars	Character vector. Names of regressors entering the long-run relationship. A maximum of 6 regressors is allowed. If westerlund=TRUE, at most one regressor may be included.
idvar	String. Column identifying cross-sectional units. Missing values are not allowed.
timevar	String. Column identifying time. Within each unit, the time index must be strictly increasing and continuous (differences of 1).
constant	Logical. Include an intercept in the cointegrating relationship.
trend	Logical. Include a linear trend in the cointegrating relationship. Setting trend=TRUE requires constant=TRUE.
lags	Integer or length-2 integer vector. Fixed lag order or range c(min,max) for the short-run lag length p. This option must be provided.
leads	Integer or length-2 integer vector, or NULL. Fixed lead order or range c(min,max) for the short-run lead length q. If NULL, defaults to 0.
westerlund	Logical. If TRUE, enforces additional restrictions: at least a constant must be included (constant and/or trend) and at most one regressor may be specified.
aic	Logical. If TRUE, uses AIC for lag/lead selection when ranges. If FALSE, uses BIC.
bootstrap	Integer. If bootstrap > 0, runs an internal bootstrap routine with bootstrap replications and returns bootstrap p-values for the raw statistics. If bootstrap <= 0 (default -1), no bootstrap is performed.
indiv.ecm	Logical. If TRUE, gets output of individual ECM regressions.
lrwindow	Integer. Window parameter used for long-run variance estimation in internal routines.
verbose	Logical. If TRUE, prints additional information.

Details

The test is based on estimating unit-specific error-correction models (ECMs) and testing the null hypothesis of no error correction for all cross-sectional units. Four statistics are reported:

• G_t: mean of individual t-ratios of the error-correction coefficient,

• G_a: mean of individually scaled error-correction coefficients,

• P_t: pooled t-type statistic based on a common error-correction coefficient,

• P_a: pooled statistic based on the scaled common coefficient.

Input validation and data checks. The function enforces several Stata-like guardrails:

• A maximum of 6 regressors can be specified in xvars.

• If trend=TRUE, then constant=TRUE is required.

• If westerlund=TRUE, at least a constant must be included and xvars must contain at most one regressor.

• The panel must be declared by specifying idvar and timevar, and idvar may not contain missing values.

• Rows with missing values are excluded, and continuity checks are applied to the resulting usable sample.

Inference. If bootstrap <= 0, the function returns standardized Z-scores and asymptotic (left-tail) p-values. If bootstrap > 0, it additionally produces bootstrap p-values for the raw statistics.

Value

A list containing the following components:

• test_stats: A numeric vector containing:

  • gt, ga, pt, pa: Raw test statistics.

  • gt_z, ga_z, pt_z, pa_z: Standardized Z-scores.

  • gt_pval, ga_pval, pt_pval, pa_pval: Asymptotic left-tail p-values.

• boot_pvals: A list containing gt_pvalboot, ga_pvalboot, pt_pvalboot, pa_pvalboot (only populated if bootstrap > 0).

• bootstrap_distributions: A matrix of the bootstrap replicates for each statistic.

• unit_data: A data.frame with unit-specific ECM results (alpha and beta estimates). indiv_data: A list of length equal to the number of cross-sectional units storing unit-specific results.

• mean_group: A list containing the Mean Group estimates (mg_alpha, mg_betas) and their respective standard errors.

• settings: A list of the lag/lead specifications and internal parameters used.

• mg_results: A data.frame summarizing the Mean Group estimation results.

Vignette

This section demonstrates how to use westerlund_test() and interprets common outputs.

What the test does

The test evaluates the null hypothesis of no error correction for all cross-sectional units. Rejection suggests that at least some units exhibit error-correcting behaviour.

Data requirements: unbalanced panels and time continuity

Unbalanced panels are permitted as long as each unit's time index is continuous after removing rows with missing values. If any unit has gaps (e.g., time jumps from 2001 to 2003), the function stops and reports the unit identifier.

Examples

## Plain (asymptotic) test
res_plain <- westerlund_test(
  data       = df,
  yvar       = "y",
  xvars      = c("x1","x2"),
  idvar      = "id",
  timevar    = "t",
  constant   = TRUE,
  trend      = FALSE,
  lags       = 1,
  leads      = 0,
  westerlund = FALSE,
  bootstrap  = -1,
  indiv.ecm  = FALSE,
  lrwindow   = 2
)

Interpreting common errors

• Continuous time-series are required: at least one unit has holes in the time index. Fix by ensuring the usable sample is continuous.

• At least ... observations are required: units are too short for the requested lag/lead orders.

• If a trend is included, a constant must be included: set constant=TRUE when trend=TRUE.

References

Westerlund, J. (2007). Testing for error correction in panel data. Oxford Bulletin of Economics and Statistics, 69(6), 709–748.

See Also

WesterlundPlain, WesterlundBootstrap, DisplayWesterlund

Westerlund documentation built on Feb. 7, 2026, 5:07 p.m.