% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/structural_break.R
\name{structural_break_test}
\alias{structural_break_test}
\title{Structural Break Tests for Panels with Cross-Sectional Dependence}
\usage{
structural_break_test(
  data,
  unit_index,
  time_index,
  formula,
  model = "cce",
  type = c("unknown", "known"),
  break_date = NULL,
  trim = 0.15,
  n_breaks = 1L,
  test_terms = NULL,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{data}{A panel data.frame.}

\item{unit_index}{Character: unit identifier column.}

\item{time_index}{Character: time identifier column.}

\item{formula}{Two-sided formula passed through to \code{dcce()}.}

\item{model}{Character: base estimator (default \code{"cce"}).}

\item{type}{Character: \code{"known"} for a Chow test at a specific
break date, \code{"unknown"} for a sup-Wald test over a trimmed
window. Default \code{"unknown"}.}

\item{break_date}{Required when \code{type = "known"}. Must match the
time-index type.}

\item{trim}{Numeric: trimming fraction at each end of the sample for
the unknown-break-date search. Default \code{0.15} (standard
Andrews 1993 choice).}

\item{n_breaks}{Integer: maximum number of breaks to search for using
the sequential Bai-Perron procedure. Default \code{1L}.}

\item{test_terms}{Character vector: which coefficients to include in
the Wald statistic. Default \code{NULL} tests all slope coefficients
(excluding the intercept).}

\item{verbose}{Logical: print progress during the candidate search.
Default \code{FALSE}.}

\item{...}{Additional arguments passed to \code{dcce()}
(e.g. \code{cross_section_vars}, \code{cross_section_lags}).}
}
\value{
An object of class \code{dcce_break} with elements:
\describe{
\item{type}{\code{"known"} or \code{"unknown"}.}
\item{statistic}{The Wald (or sup-Wald) test statistic.}
\item{p_value}{Approximate p-value.}
\item{df}{Degrees of freedom of the Wald statistic.}
\item{break_date}{Known or estimated break date.}
\item{candidates}{For \code{type = "unknown"}: a tibble with one
row per candidate date (\code{date}, \code{wald}).}
\item{break_dates}{Vector of break dates when \code{n_breaks > 1L}.}
\item{fit_pre}{\code{dcce_fit} object from the pre-break sub-sample.}
\item{fit_post}{\code{dcce_fit} object from the post-break sub-sample.}
\item{call}{The original call.}
}
}
\description{
Tests for and estimates structural breaks in heterogeneous panel data
models with cross-sectional dependence. Implements a Wald-type Chow
test at a known break date, a sup-Wald test for an unknown break date
(with trimmed candidate set), and a sequential procedure for multiple
breaks following Bai & Perron (1998) adapted to panel CCE settings.
}
\details{
For each candidate break date \eqn{\tau} the function computes
\deqn{W_N(\tau) = (\hat\beta_1(\tau) - \hat\beta_2(\tau))'
  [V_1(\tau) + V_2(\tau)]^{-1}
  (\hat\beta_1(\tau) - \hat\beta_2(\tau))}
where \eqn{\hat\beta_1} and \eqn{\hat\beta_2} are the Mean Group
coefficients from running the base estimator on the pre-break and
post-break sub-samples respectively, and \eqn{V_1}, \eqn{V_2} are
the corresponding MG variances. Under the null of no break the
statistic is distributed \eqn{\chi^2_k} where \eqn{k} is the number
of tested coefficients.

The unknown-break-date sup-Wald test reports
\eqn{\sup_{\tau \in [\tau_1, \tau_2]} W_N(\tau)}, where
\eqn{[\tau_1, \tau_2]} is the interior of the sample after applying
the trimming parameter. Approximate p-values use the Andrews (1993)
large-sample distribution.
}
\examples{
data(pwt8)
brk <- structural_break_test(
  data       = pwt8,
  unit_index = "country",
  time_index = "year",
  formula    = d_log_rgdpo ~ log_hc + log_ck + log_ngd,
  model      = "mg",
  cross_section_vars = NULL,
  type       = "unknown",
  trim       = 0.20
)
print(brk)
}
\references{
Andrews, D. W. K. (1993). Tests for parameter instability and
structural change with unknown change point. \emph{Econometrica},
61(4), 821-856.

Bai, J., & Perron, P. (1998). Estimating and testing linear models
with multiple structural changes. \emph{Econometrica}, 66(1), 47-78.

Ditzen, J., Karavias, Y., & Westerlund, J. (2024). Multiple
structural breaks in interactive effects panel data models.
\emph{Journal of Applied Econometrics}.
}
