diff --git a/.Rbuildignore b/.Rbuildignore index cd5125e..3e6fff7 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -5,3 +5,7 @@ ^doc$ ^Meta$ ^\.github$ +^CRAN-SUBMISSION$ +^_pkgdown\.yml$ +^docs$ +^pkgdown$ diff --git a/.gitignore b/.gitignore index 311da47..f729723 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ inst/doc .Rprofile /doc/ /Meta/ +docs diff --git a/CRAN-SUBMISSION b/CRAN-SUBMISSION new file mode 100644 index 0000000..e321a82 --- /dev/null +++ b/CRAN-SUBMISSION @@ -0,0 +1,3 @@ +Version: 1.0.0 +Date: 2026-02-17 20:27:31 UTC +SHA: 9ff062df4af4e5572f66abfeca5e27fa2f7b3886 diff --git a/DESCRIPTION b/DESCRIPTION index dbdc4bf..5089572 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,10 @@ Package: csdm Title: Cross-Sectional Dependence Models -Version: 1.0.0 +Version: 1.0.1 Depends: R (>= 4.0.0) -Imports: MASS +Imports: MASS, + Rdpack +RdMacros: Rdpack Suggests: testthat (>= 3.0.0), knitr, @@ -14,7 +16,10 @@ Authors@R: person(given = c("Joao", "Claudio"), family = "Macosso", email = "joaoclaudiomacosso@gmail.com", - role = c("aut", "cre")) + role = c("aut", "cre"), + comment = c(ORCID = "0009-0006-5051-9312")) +URL: https://github.com/Macosso/csdm +BugReports: https://github.com/Macosso/csdm/issues Description: Provides estimators and utilities for large panel-data models with cross-sectional dependence, including mean group (MG), common correlated effects (CCE) and dynamic CCE (DCCE) estimators, and cross-sectionally augmented ARDL (CS-ARDL) specifications, plus related inference and diagnostics. License: GPL-3 Encoding: UTF-8 diff --git a/NAMESPACE b/NAMESPACE index 0ded606..f1c4642 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -22,6 +22,7 @@ export(get_residuals) export(pooled_vcov) export(prepare_cd_input) export(sandwich_vcov) +importFrom(Rdpack,reprompt) importFrom(stats,aggregate) importFrom(stats,cor) importFrom(stats,model.matrix.lm) diff --git a/NEWS.md b/NEWS.md index 01ec072..a5beb02 100644 --- a/NEWS.md +++ b/NEWS.md @@ -11,3 +11,16 @@ ### Inference and diagnostics - Cross-sectional dependence (CD) tests - Summary and printing methods + + +# csdm 1.0.1 + +## Documentation and References enhancement + +### References +- Added references for the implemented estimators and methods, including key papers and textbooks in the field + +### Documentation +- Improved documentation for all functions, including detailed descriptions of the estimators, their assumptions, and +- Ensured consistency in the documentation style across different documents +- Added link for reporting bugs diff --git a/R/csdm.R b/R/csdm.R index 38cd9bd..5333e0f 100644 --- a/R/csdm.R +++ b/R/csdm.R @@ -1,12 +1,13 @@ # csdm.R -#' Panel Model Estimation with Cross Section Dependence +#' Panel Model Estimation with Cross-Sectional Dependence #' -#' Estimate panel data models that allow for cross-sectional dependence and -#' heterogeneous slopes. The interface supports Mean Group (MG), Common -#' Correlated Effects (CCE), Dynamic CCE (DCCE), and Cross-Sectionally -#' Augmented ARDL (CS-ARDL) estimators with consistent handling of -#' cross-sectional averages, dynamic structure, and robust inference. +#' Estimate heterogeneous panel data models with optional cross-sectional +#' augmentation and dynamic structure. The interface supports Mean Group (MG), +#' Common Correlated Effects (CCE), Dynamic CCE (DCCE), and +#' Cross-Sectionally Augmented ARDL (CS-ARDL) estimators with a consistent +#' specification workflow for cross-sectional averages, lag structure, and +#' variance-covariance estimation. #' #' @param formula Model formula of the form \code{y ~ x1 + x2}. #' @param data A \code{data.frame} (or \code{plm::pdata.frame}) containing the @@ -29,59 +30,120 @@ #' #' @return An object of class \code{csdm_fit} containing estimated coefficients, #' residuals, variance-covariance estimates, model metadata, and diagnostics. -#' Use \code{summary()}, \code{coef()}, \code{residuals()}, \code{vcov()}, and -#' \code{cd_test()} to access standard outputs. +#' Use [summary()], [coef()], [residuals()], [vcov()], and +#' [cd_test()] to access standard outputs. #' #' @details -#' ## Model equations -#' -#' \describe{ -#' \item{MG (Pesaran and Smith, 1995)}{ -#' \deqn{y_{it} = x_{it}^\top \beta_i + u_{it}} -#' } -#' \item{CCE (Pesaran, 2006)}{ -#' \deqn{y_{it} = x_{it}^\top \beta_i + \lambda_i^\top F_t + u_{it}} -#' } -#' \item{DCCE (Chudik and Pesaran, 2015)}{ -#' \deqn{\Delta y_{it} = \Delta x_{it}^\top \beta_i + \lambda_i^\top \Delta F_t + u_{it}} -#' } -#' \item{CS-ARDL (Chudik and Pesaran, 2015)}{ -#' \deqn{y_{it} = \phi_i y_{it-1} + x_{it}^\top \theta_i + \lambda_i^\top F_t + u_{it}} -#' } -#' } -#' -#' ## Estimation, identification, and assumptions -#' -#' \describe{ -#' \item{MG}{Unit-by-unit estimation with heterogeneous slopes. The reported -#' coefficients are cross-sectional averages of unit estimates. Requires -#' sufficient time series per unit and weak serial dependence in errors.} -#' \item{CCE}{Augments regressions with cross-sectional averages (CSA) to proxy -#' unobserved common factors. Identification relies on large N and T, weak -#' dependence in idiosyncratic errors after CSA, and weak exogeneity of -#' regressors.} -#' \item{DCCE}{Extends CCE to dynamic settings with lagged dependent variables -#' and CSA lags. Identification relies on weak exogeneity, adequate time length -#' for dynamic lags, and a stable factor structure.} -#' \item{CS-ARDL}{Specifies dynamic distributed lags with CSA terms. Estimation -#' follows ARDL-style dynamics in each unit and aggregates to panel averages. -#' Assumes weak exogeneity and sufficient time length for lag structure.} -#' } +#' Let \eqn{i = 1, \ldots, N} index cross-sectional units and +#' \eqn{t = 1, \ldots, T} index time. A baseline heterogeneous panel model is #' -#' @references -#' Pesaran, M.H. and Smith, R. (1995). "Estimating long-run relationships from -#' dynamic heterogeneous panels." Journal of Econometrics, 68(1), 79-113. +#' \deqn{y_{it} = \alpha_i + \beta_i^T x_{it} + u_{it}.} +#' +#' Here \eqn{\alpha_i} is a unit-specific intercept, \eqn{x_{it}} is a vector +#' of regressors, \eqn{\beta_i} is a vector of unit-specific slopes, and +#' \eqn{u_{it}} is an error term that may exhibit cross-sectional dependence. +#' +#' Cross-sectional averages are specified through [csdm_csa()] and dynamic or +#' long-run structure is specified through [csdm_lr()]. This keeps the model +#' interface consistent across estimators while allowing the degree of +#' cross-sectional augmentation and lag structure to vary by application. +#' +#' \strong{Implemented estimators} +#' +#' \strong{MG (Pesaran and Smith, 1995)} +#' +#' The Mean Group estimator fits separate regressions for each unit and averages +#' the resulting coefficients: +#' +#' \deqn{\hat{\beta}_{MG} = \frac{1}{N}\sum_{i=1}^N \hat{\beta}_i.} +#' +#' This estimator accommodates slope heterogeneity but does not explicitly model +#' cross-sectional dependence. +#' +#' \strong{CCE (Pesaran, 2006)} +#' +#' Regressions are augmented with cross-sectional averages to proxy unobserved +#' common factors: +#' +#' \deqn{y_{it} = \alpha_i + \beta_i^T x_{it} + \gamma_i^T \bar{z}_{t} + v_{it}.} +#' +#' A common choice is +#' +#' \deqn{\bar{z}_t = (\bar{y}_t, \bar{x}_t),} +#' +#' with +#' +#' \deqn{\bar{x}_t = \frac{1}{N}\sum_{i=1}^N x_{it}, \qquad +#' \bar{y}_t = \frac{1}{N}\sum_{i=1}^N y_{it}.} +#' +#' More generally, \eqn{\bar{z}_t} collects the cross-sectional averages +#' specified in \code{csa}. +#' +#' \strong{DCCE (Chudik and Pesaran, 2015)} #' -#' Pesaran, M.H. (2006). "Estimation and inference in large heterogeneous panels -#' with multifactor error structure." Econometrica, 74(4), 967-1012. +#' Dynamic CCE extends CCE by allowing lagged dependent variables and lagged +#' cross-sectional averages: +#' +#' \deqn{y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} +#' + \beta_i^T x_{it} +#' + \sum_{q=0}^{Q} \delta_{iq}^T \bar{z}_{t-q} +#' + e_{it}.} +#' +#' In the package implementation, lagged dependent variables and distributed +#' lags of regressors are controlled through \code{lr}, while contemporaneous +#' and lagged cross-sectional averages are controlled through \code{csa}. +#' +#' \strong{CS-ARDL (Chudik and Pesaran, 2015)} +#' +#' In the package implementation, \code{model = "cs_ardl"} is obtained by first +#' estimating a cross-sectionally augmented ARDL-style regression in levels, +#' using the same dynamic specification as \code{model = "dcce"}, and then +#' transforming the unit-specific coefficients into adjustment and long-run +#' parameters. +#' +#' The underlying unit-level regression is of the form +#' +#' \deqn{y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} +#' + \sum_{q=0}^{Q} \beta_{iq}^T x_{i,t-q} +#' + \sum_{s=0}^{S} \omega_{is}^T \bar{z}_{t-s} +#' + e_{it}.} +#' +#' From this dynamic specification, the package recovers the implied +#' error-correction form +#' +#' \deqn{\Delta y_{it} = +#' \alpha_i + +#' \varphi_i \left(y_{i,t-1} - \theta_i^T x_{i,t-1}\right) +#' + \sum_{j=1}^{P-1} \lambda_{ij} \Delta y_{i,t-j} +#' + \sum_{j=0}^{Q-1} \psi_{ij}^T \Delta x_{i,t-j} +#' + \sum_{s=0}^{S} \tilde{\omega}_{is}^T \bar{z}_{t-s} +#' + e_{it},} +#' +#' where \eqn{\varphi_i} is the adjustment coefficient and \eqn{\theta_i} is +#' the implied long-run relationship. In the current implementation, these +#' quantities are computed from the estimated lag polynomials rather than from a +#' direct ECM regression. +#' +#' \strong{Identification and assumptions} +#' +#' MG requires sufficient time-series variation within each unit. +#' +#' CCE relies on cross-sectional averages acting as proxies for latent common +#' factors, together with adequate cross-sectional and time dimensions. +#' +#' DCCE additionally requires enough time periods to support lagged dependent +#' variables, distributed lags, and lagged cross-sectional averages. +#' +#' CS-ARDL requires sufficient time length for the distributed-lag structure and +#' is intended for applications where both short-run dynamics and long-run +#' relationships are of interest in the presence of common factors. +#' +#' @references +#' \insertRef{PesaranSmith1995}{csdm} #' -#' Chudik, A. and Pesaran, M.H. (2015). "Common correlated effects estimation of -#' heterogeneous dynamic panel data models with weakly exogenous regressors." -#' Journal of Econometrics, 188(2), 393-420. +#' \insertRef{Pesaran2006}{csdm} #' -#' Chudik, A. and Pesaran, M.H. (2015). "Large panel data models with -#' cross-sectional dependence: A survey." Annals of Economics and Finance, 16(1), -#' 53-78. +#' \insertRef{ChudikPesaran2015a}{csdm} #' #' @examples #' library(csdm) diff --git a/R/data.R b/R/data.R index 238a3b3..8c5d3c5 100644 --- a/R/data.R +++ b/R/data.R @@ -1,13 +1,13 @@ -#' Penn World Tables panel (93 countries, 1960–2007) +#' Penn World Tables panel (93 countries, 1960-2007) #' -#' A panel of 93 countries (unit id) observed annually over 1960–2007 (time/year), +#' A panel of 93 countries (unit id) observed annually over 1960-2007 (time/year), #' with the log-transformed variables used in #' xtdcce2-style examples. #' #' @format A data frame with 4464 rows and 6 variables: #' \describe{ #' \item{id}{Unit identifier (country id).} -#' \item{year}{Time identifier (year, 1960–2007).} +#' \item{year}{Time identifier (year, 1960-2007).} #' \item{log_rgdpo}{Log real GDP (output).} #' \item{log_hc}{Log human capital index.} #' \item{log_ck}{Log capital stock.} diff --git a/R/utils_cd.R b/R/utils_cd.R index fb7c8b1..ec66205 100644 --- a/R/utils_cd.R +++ b/R/utils_cd.R @@ -53,21 +53,15 @@ #' } #' #' @references -#' Pesaran, M.H. (2015). "Testing weak cross-sectional dependence in large panels." -#' \emph{Econometric Reviews}, 34(6-10), 1089-1117. +#' \insertRef{Pesaran2015}{csdm} #' -#' Pesaran, M.H. (2021). "General diagnostic tests for cross-sectional dependence -#' in panels." \emph{Empirical Economics}, 60, 13-50. +#' \insertRef{Pesaran2021}{csdm} #' -#' Juodis, A., & Reese, S. (2021). "The incidental parameters problem in testing for -#' remaining cross-sectional correlation." \emph{Journal of Business and Economic Statistics}, -#' 40(3), 1193-1203. +#' \insertRef{JuodisReese2021}{csdm} #' -#' Fan, J., Liao, Y., & Yao, J. (2015). "Power Enhancement in High-Dimensional -#' Cross-Sectional Tests." \emph{Econometric Reviews}, 34(6-10), 742-779. +#' \insertRef{FanLiaoYao2015}{csdm} #' -#' Pesaran, M.H., & Xie, Y. (2021). "A bias-corrected CD test for error cross-sectional -#' dependence in panel models." \emph{Econometric Reviews}, 41(6), 649-677. +#' \insertRef{PesaranXie2021}{csdm} #' #' @examples #' # Simulate independent and dependent panels diff --git a/R/zzz_imports.R b/R/zzz_imports.R index ea29b6e..53dc5a4 100644 --- a/R/zzz_imports.R +++ b/R/zzz_imports.R @@ -1,2 +1,3 @@ #' @importFrom stats aggregate cor model.matrix.lm pt residuals sd setNames symnum terms +#' @importFrom Rdpack reprompt NULL diff --git a/README.md b/README.md index 06fd09a..d4c1e16 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +# csdm [![R-CMD-check](https://github.com/Macosso/csdm/workflows/R-CMD-check/badge.svg)](https://github.com/Macosso/csdm/actions) @@ -6,74 +7,171 @@ The `csdm` package implements econometric methods for panel data with cross-sectional dependence (CSD). In many applications, observations across units (e.g., countries, firms, regions) are not independent—macroeconomic shocks, trade relationships, or spillovers create correlation across cross-sectional units. The `csdm` package provides robust estimators that account for this dependence structure, plus diagnostic tests to detect and characterize it. -This vignette demonstrates four core estimation methods and related inference tools on real panel data from the Penn World Table (PWT). - ## Methodology: Four Estimators - ### Model Specification -Consider a panel model with $T$ time periods and $N$ cross-sectional units (e.g., countries): +The `csdm()` interface estimates heterogeneous panel data models with optional cross-sectional augmentation and dynamic structure. A baseline heterogeneous panel model is: -$$y_{it} = \alpha_i + \beta_i x_{it} + u_{it}, \quad i = 1, \ldots, N; \quad t = 1, \ldots, T$$ +$$ +y_{it} = \alpha_i + \beta_i' x_{it} + u_{it}, +\qquad i = 1, \ldots, N\; t = 1, \ldots, T +$$ where: -- $y_{it}$ is the outcome variable for unit $i$ at time $t$ + +- $y_{it}$ is the outcome variable for unit \(i\) at time \(t\) - $\alpha_i$ is a unit-specific intercept -- $\beta_i$ is a unit-specific slope (heterogeneous across units) -- $x_{it}$ is explanatory variable(s) -- $u_{it}$ is the idiosyncratic error term +- $\beta_i$ is a \((k \times 1)\) vector of unit-specific slopes +- $x_{it}$ is a \((k \times 1)\) vector of explanatory variables +- $u_{it}$ is the error term, which may exhibit cross-sectional dependence -The key feature is **heterogeneity in slopes** ($\beta_i$ varies by unit), which allows each unit to have its own relationship between $x$ and $y$. Four estimators are available to fit this model under different assumptions about cross-sectional dependence. +The inner product $\beta_i' x_{it}$ is scalar-valued. Heterogeneous slopes allow each unit to respond differently to the regressors. In many applications, cross-sectional dependence arises because the error term contains unobserved common factors. The estimators implemented in `csdm()` differ in how they handle this dependence and whether they allow for dynamic adjustment. + +--- ### 1. Mean Group (MG) Estimator -The Mean Group (MG) estimator fits unit-specific regressions separately and averages the results: +The Mean Group estimator fits separate regressions for each unit and averages the resulting coefficients: + +$$ +\hat{\beta}_{MG} = \frac{1}{N}\sum_{i=1}^N \hat{\beta}_i +$$ -$$\hat{\beta}_{MG} = \frac{1}{N} \sum_{i=1}^{N} \hat{\beta}_i$$ +**Key idea**: Estimation is performed unit by unit, with no pooling of slope coefficients across cross-sectional units. -**Interpretation**: The MG coefficient is the simple average of individual unit slopes. It is consistent under mild regularity conditions and allows arbitrary cross-sectional dependence in errors $u_{it}$. +**Interpretation**: -**Use case**: When dependence is present but you only care about average effects. MG is robust to forms of CSD that would break other methods. +- $\hat{\beta}_{MG}$ is the cross-sectional average of the unit-specific estimates +- all slope coefficients are allowed to differ across units + +**Properties**: + +- accommodates slope heterogeneity +- requires sufficient time-series information within each unit +- does not explicitly model cross-sectional dependence + +**Use case**: A natural benchmark when the main concern is heterogeneous slopes and no explicit factor structure is imposed. + +--- ### 2. Common Correlated Effects (CCE) Estimator -The Common Correlated Effects (CCE) estimator augments the model with cross-sectional averages of regressors $\bar{x}_t = \frac{1}{N} \sum_{i=1}^{N} x_{it}$: +The CCE estimator augments each unit regression with cross-sectional averages to proxy unobserved common factors: + +$$ +y_{it} = \alpha_i + \beta_i' x_{it} + \gamma_i' \bar{z}_t + v_{it} +$$ -$$y_{it} = \alpha_i + \beta_i x_{it} + \gamma_i \bar{x}_t + \gamma_i \bar{y}_t + v_{it}$$ +where \(\bar{z}_t\) collects the cross-sectional averages specified through `csdm_csa()`, for example -By including these cross-sectional mean terms, the estimator **controls for common factors** (unobserved shocks that affect all units similarly). The CCE approach is more efficient than MG when common factor structure is strong, while retaining robustness to CSD. +$$ +\bar{z}_t = (\bar{y}_t, \bar{x}_t), +\qquad +\bar{x}_t = \frac{1}{N}\sum_{i=1}^N x_{it}, +\qquad +\bar{y}_t = \frac{1}{N}\sum_{i=1}^N y_{it}. +$$ -**Interpretation**: After accounting for common shocks, the $\beta_i$ coefficients represent unit-specific sensitivities net of factor loadings $\gamma_i$. +**Key idea**: Cross-sectional averages serve as proxies for latent common factors that induce dependence across units. -**Use case**: When cross-sectional dependence arises primarily from common shocks or latent factors. +**Interpretation**: + +- $\beta_i$ measures the unit-specific effect conditional on the included cross-sectional averages. +- $\gamma_i$ captures unit-specific exposure to the common components with \(\bar{z}_t\) as a proxy. + +**Properties**: + +- allows heterogeneous slopes +- augments the regression with cross-sectional averages supplied through `csa` +- suitable when cross-sectional dependence is driven by latent common shocks + +**Use case**: When dependence across units is believed to reflect common unobserved factors. + +--- ### 3. Dynamic CCE (DCCE) Estimator -The Dynamic Common Correlated Effects (DCCE) estimator extends CCE to include lagged dependent variable: +The DCCE estimator extends CCE to dynamic settings by including lagged dependent variables, optional distributed lags of regressors, and lagged cross-sectional averages: + +$$ y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} + \sum_{q=0}^{Q} \beta_{iq}' x_{i,t-q} + \sum_{s=0}^{S} \delta_{is}' \bar{z}_{t-s} + e_{it} $$ + +where the dynamic structure is controlled through `csdm_lr()` and the cross-sectional averages and their lags are controlled through `csdm_csa()`. + +**Key idea**: Dynamics are introduced directly in the unit equation, while lagged cross-sectional averages help absorb common factor dependence over time. + +**Interpretation**: + +- $\phi_{ip}$ captures unit-specific persistence +- $\beta_{iq}$ captures contemporaneous and lagged effects of regressors +- $\delta_{is}$ captures the effect of contemporaneous and lagged common components -$$y_{it} = \alpha_i + \lambda_i y_{it-1} + \beta_i x_{it} + \gamma_i \bar{x}_t + \gamma_i \bar{y}_t + v_{it}$$ +**Properties**: -where $\lambda_i$ is the unit-specific autoregressive coefficient. DCCE is ideal for dynamic panel models (e.g., when studying persistence of outcomes over time). +- allows heterogeneous dynamic adjustment across units +- combines lagged dependent variables, optional distributed lags, and cross-sectional augmentation +- requires enough time periods to support the chosen lag structure -**Interpretation**: $\lambda_i$ captures dynamic adjustment within units, $\beta_i$ measures the long-run effect after accounting for dynamics, and $\gamma_i$ adjusts for common factors. +**Use case**: When the outcome is persistent over time and cross-sectional dependence remains important. -**Use case**: When the outcome has substantial persistence (lagged effects) and cross-sectional dependence is suspected. +--- ### 4. Cross-Sectionally Augmented ARDL (CS-ARDL) -The CS-ARDL model extends the ARDL framework with cross-sectional augmentation: +In the current `csdm()` implementation, `model = "cs_ardl"` is obtained by first estimating a cross-sectionally augmented ARDL-style regression in levels, using the same dynamic specification as `model = "dcce"`, and then transforming the estimated unit-specific coefficients into adjustment and long-run parameters. -$$\Delta y_{it} = \alpha_i + \lambda_i (y_{it-1} - \theta_i x_{it-1}) + \beta_i \Delta x_{it} + \hat{\gamma}_i \Delta \bar{x}_t + v_{it}$$ +The underlying unit-level regression is -This model combines **autoregressive and distributed lag** dynamics. It separates short-run effects ($\beta_i$) from long-run cointegrating relationships ($\theta_i$), all while controlling for common factors. +$$ +y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} + \sum_{q=0}^{Q} \beta_{iq}' x_{i,t-q} + \sum_{s=0}^{S} \omega_{is}' \bar{z}_{t-s} + e_{it} +$$ -**Interpretation**: -- $\theta_i$ is the long-run equilibrium relationship (cointegrating coefficient) -- $\beta_i$ is the short-run adjustment to shocks -- $\lambda_i$ governs speed of reversion to equilibrium +From this dynamic specification, the implied error-correction form is -**Use case**: When studying long-run relationships in non-stationary panels with complex short-run dynamics. +$$ +\Delta y_{it} = \alpha_i + \varphi_i \left( y_{i,t-1} - \theta_i' x_{i,t-1} \right) + \sum_{j=1}^{P-1} \lambda_{ij} \Delta y_{i,t-j} + \sum_{j=0}^{Q-1} \psi_{ij}' \Delta x_{i,t-j} + \sum_{s=0}^{S} \tilde{\omega}_{is}' \bar{z}_{t-s} + e_{it} +$$ + +where the dynamic structure is controlled through `csdm_lr()` and the cross-sectional averages are supplied through `csdm_csa()`. + +**Key idea**: `cs_ardl` reports the implied short-run and long-run quantities from a cross-sectionally augmented ARDL fit. + +**Interpretation**: + +- $\theta_i$ is the unit-specific long-run relationship +- $\varphi_i$ is the implied speed of adjustment back toward equilibrium +- $\psi_{ij}$ captures short-run effects of changes in regressors +- $\tilde{\omega}_{is}$ captures the role of common cross-sectional components + +**Properties**: + +- supports heterogeneous short-run and long-run dynamics +- combines ARDL-style dynamics with cross-sectional augmentation +- recovers adjustment and long-run coefficients from estimated lag polynomials rather than fitting a separate ECM directly + +**Use case**: When the objective is to study long-run relationships together with heterogeneous short-run adjustment in panels affected by common factors. + +--- + +### Cross-Sectional Averages and Dynamic Structure + +Two helper specifications control the main extensions in `csdm()`: + +- `csdm_csa()` defines which variables enter as cross-sectional averages and how many lags of those averages are included +- `csdm_lr()` defines the dynamic or long-run structure, such as lagged dependent variables and distributed lags + +This design keeps the estimation interface consistent across the four estimators while allowing the model specification to vary by application. + +--- + +### Summary + +| Estimator | Heterogeneous Slopes | Cross-Sectional Averages | Dynamics | Long-Run Structure | +|-----------|----------------------|--------------------------|----------|--------------------| +| MG | Yes | No | No | No | +| CCE | Yes | Yes | No | No | +| DCCE | Yes | Yes | Yes | No | +| CS-ARDL | Yes | Yes | Yes | Yes | ## Package installation To install the `csdm` package from CRAN, run: @@ -239,15 +337,24 @@ In practice, models that do not account for cross-sectional dependence (like MG ## References -Chudik, A., & Pesaran, M. H. (2013). Common correlated effects estimation of heterogeneous dynamic panel data models with weakly exogenous regressors. *Journal of Business and Economic Statistics*, 33(2), 232–247. +Chudik, A., & Pesaran, M. H. (2013). Large panel data models with cross-sectional dependence: A survey [Globalization Institute Working Papers]. Federal Reserve Bank of Dallas, (153). + +Chudik, A., & Pesaran, M. H. (2015). Common correlated effects estimation of heterogeneous dynamic panel data models with weakly exogenous regressors. Journal of Econometrics, 188(2), 393–420. + +Ditzen, J. (2018). Estimating dynamic common-correlated effects in STATA. The STATA Journal, 18(3), 585–617. https://doi.org/10.1177/1536867X1801800306 + +Fan, J., Liao, Y., & Yao, J. (2015). Power enhancement in high-dimensional cross-section tests. Econometrica, 83(4), 1497–1541. + +Juodis, A., & Reese, S. (2021). The incidental parameters problem in testing for remaining cross-sectional correlation. Journal of Business and Economic Statistics, 40(3), 1191–1203. -Ditzen, J. (2021). Estimating dynamic common-correlated effects in Stata. *The Stata Journal*, 21(1), 39–59. +Pesaran, M. H. (2006). Estimation and inference in large heterogeneous panels with multifactor error structure. Econometrica, 74(4), 967–1012. -Fan, J., Liao, Y., & Yao, J. (2015). Power-enhanced simultaneous test for high-dimensional covariance matrix. *Journal of the American Statistical Association*, 110(510), 325–337. +Pesaran, M. H. (2007). A simple unit root test in the presence of cross-section dependence. Journal of Applied Econometrics, 22(2), 265–312. -Juodis, A., & Reese, S. (2022). The role of the *N/T* ratio in large N, large T panel time-series models. *Econometric Reviews*, 41(2), 221–261. +Pesaran, M. H. (2015). Testing weak cross-sectional dependence in large panels. Econometric Reviews, 34(6-10), 1089–1117. -Pesaran, M. H. (2007). A simple unit root test in the presence of cross-section dependence. *Journal of Applied Econometrics*, 22(2), 265–312. +Pesaran, M. H. (2021). General diagnostic tests for cross-sectional dependence in panels. Empirical Economics, 60(1), 13–50. -Pesaran, M. H., & Xie, Y. (2021). A bias-adjusted LM test of error cross-section independence. *Econometric Reviews*, 40(1), 7–24. +Pesaran, M. H., & Smith, R. (1995). Estimating long-run relationships from dynamic heterogeneous panels. Journal of Econometrics, 68(1), 79–113. +Pesaran, M. H., & Xie, Y. (2021). A bias-corrected CD test for error cross-sectional dependence in panel models. Econometric Reviews, 41(6), 649–677. diff --git a/_pkgdown.yml b/_pkgdown.yml new file mode 100644 index 0000000..20b8eaf --- /dev/null +++ b/_pkgdown.yml @@ -0,0 +1,22 @@ +template: + bootstrap: 5 + bootswatch: flatly + bslib: + primary: "#0b1f3b" + secondary: "#1f3c88" + success: "#2c7fb8" + info: "#d0d8e8" + base_font: + google: "Inter" + heading_font: + google: "Inter" + code_font: + google: "Fira Code" + +footer: + structure: + left: developed_by + right: built_with + components: + developed_by: "Developed by Joao Claudio Macosso" + built_with: "Built with pkgdown" diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib new file mode 100644 index 0000000..e4c7d8a --- /dev/null +++ b/inst/REFERENCES.bib @@ -0,0 +1,109 @@ +@article{PesaranSmith1995, + author = {Pesaran, M. Hashem and Smith, Ron}, + title = {Estimating long-run relationships from dynamic heterogeneous panels}, + journal = {Journal of Econometrics}, + year = {1995}, + volume = {68}, + number = {1}, + pages = {79--113} +} + +@article{Pesaran2006, + author = {Pesaran, M. Hashem}, + title = {Estimation and inference in large heterogeneous panels with multifactor error structure}, + journal = {Econometrica}, + year = {2006}, + volume = {74}, + number = {4}, + pages = {967--1012} +} + +@article{ChudikPesaran2015a, + author = {Chudik, Alexander and Pesaran, M. Hashem}, + title = {Common correlated effects estimation of heterogeneous dynamic panel data models with weakly exogenous regressors}, + journal = {Journal of Econometrics}, + year = {2015}, + volume = {188}, + number = {2}, + pages = {393--420} +} + +@article{ChudikPesaran2013, + author = {Chudik, Alexander and Pesaran, M. Hashem}, + title = {Large panel data models with cross-sectional dependence: A survey}, + journal = {Federal Reserve Bank of Dallas}, + type = {Globalization Institute Working Papers}, + number = {153}, + year = {2013} +} + +@article{Ditzen2018, + author = {Ditzen, Jan}, + title = {Estimating dynamic common-correlated effects in STATA}, + journal = {The STATA Journal}, + year = {2018}, + volume = {18}, + number = {3}, + pages = {585--617}, + doi = {10.1177/1536867X1801800306} +} + +@article{FanLiaoYao2015, + author = {Fan, Jianqing and Liao, Yuan and Yao, Jianfeng}, + title = {Power Enhancement in High-Dimensional Cross-Section Tests}, + journal = {Econometrica}, + year = {2015}, + volume = {83}, + number = {4}, + pages = {1497--1541} +} + +@article{Pesaran2007, + author = {Pesaran, M. Hashem}, + title = {A simple unit root test in the presence of cross-section dependence}, + journal = {Journal of Applied Econometrics}, + year = {2007}, + volume = {22}, + number = {2}, + pages = {265--312} +} + +@article{Pesaran2015, + author = {Pesaran, M. Hashem}, + title = {Testing weak cross-sectional dependence in large panels}, + journal = {Econometric Reviews}, + year = {2015}, + volume = {34}, + number = {6-10}, + pages = {1089--1117} +} + +@article{Pesaran2021, + author = {Pesaran, M. Hashem}, + title = {General diagnostic tests for cross-sectional dependence in panels}, + journal = {Empirical Economics}, + year = {2021}, + volume = {60}, + number = {1}, + pages = {13--50} +} + +@article{JuodisReese2021, + author = {Juodis, Artūras and Reese, Søren}, + title = {The incidental parameters problem in testing for remaining cross-sectional correlation}, + journal = {Journal of Business and Economic Statistics}, + year = {2021}, + volume = {40}, + number = {3}, + pages = {1191--1203} +} + +@article{PesaranXie2021, + author = {Pesaran, M. Hashem and Xie, Yue}, + title = {A bias-corrected CD test for error cross-sectional dependence in panel models}, + journal = {Econometric Reviews}, + year = {2021}, + volume = {41}, + number = {6}, + pages = {649--677} +} diff --git a/inst/WORDLIST b/inst/WORDLIST index 277410b..2aa5563 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -44,3 +44,7 @@ sectionally vcov wpn xtdcce +varphi +ip +iq +qquad diff --git a/inst/apa.csl b/inst/apa.csl new file mode 100644 index 0000000..9bc45ef --- /dev/null +++ b/inst/apa.csl @@ -0,0 +1,2273 @@ + + diff --git a/man/PWT_60_07.Rd b/man/PWT_60_07.Rd index 2ada3cc..4b18e9c 100644 --- a/man/PWT_60_07.Rd +++ b/man/PWT_60_07.Rd @@ -3,12 +3,12 @@ \docType{data} \name{PWT_60_07} \alias{PWT_60_07} -\title{Penn World Tables panel (93 countries, 1960–2007)} +\title{Penn World Tables panel (93 countries, 1960-2007)} \format{ A data frame with 4464 rows and 6 variables: \describe{ \item{id}{Unit identifier (country id).} -\item{year}{Time identifier (year, 1960–2007).} +\item{year}{Time identifier (year, 1960-2007).} \item{log_rgdpo}{Log real GDP (output).} \item{log_hc}{Log human capital index.} \item{log_ck}{Log capital stock.} @@ -23,7 +23,7 @@ panel for examples and tests. PWT_60_07 } \description{ -A panel of 93 countries (unit id) observed annually over 1960–2007 (time/year), +A panel of 93 countries (unit id) observed annually over 1960-2007 (time/year), with the log-transformed variables used in xtdcce2-style examples. } diff --git a/man/cd_test.Rd b/man/cd_test.Rd index 9e1f508..263b444 100644 --- a/man/cd_test.Rd +++ b/man/cd_test.Rd @@ -136,19 +136,13 @@ cd_test(fit, type = "all") } \references{ -Pesaran, M.H. (2015). "Testing weak cross-sectional dependence in large panels." -\emph{Econometric Reviews}, 34(6-10), 1089-1117. +\insertRef{Pesaran2015}{csdm} -Pesaran, M.H. (2021). "General diagnostic tests for cross-sectional dependence -in panels." \emph{Empirical Economics}, 60, 13-50. +\insertRef{Pesaran2021}{csdm} -Juodis, A., & Reese, S. (2021). "The incidental parameters problem in testing for -remaining cross-sectional correlation." \emph{Journal of Business and Economic Statistics}, -40(3), 1193-1203. +\insertRef{JuodisReese2021}{csdm} -Fan, J., Liao, Y., & Yao, J. (2015). "Power Enhancement in High-Dimensional -Cross-Sectional Tests." \emph{Econometric Reviews}, 34(6-10), 742-779. +\insertRef{FanLiaoYao2015}{csdm} -Pesaran, M.H., & Xie, Y. (2021). "A bias-corrected CD test for error cross-sectional -dependence in panel models." \emph{Econometric Reviews}, 41(6), 649-677. +\insertRef{PesaranXie2021}{csdm} } diff --git a/man/csdm.Rd b/man/csdm.Rd index 8e838bc..4afeaec 100644 --- a/man/csdm.Rd +++ b/man/csdm.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/csdm.R \name{csdm} \alias{csdm} -\title{Panel Model Estimation with Cross Section Dependence} +\title{Panel Model Estimation with Cross-Sectional Dependence} \usage{ csdm( formula, @@ -54,53 +54,121 @@ provided values are ignored.} \value{ An object of class \code{csdm_fit} containing estimated coefficients, residuals, variance-covariance estimates, model metadata, and diagnostics. -Use \code{summary()}, \code{coef()}, \code{residuals()}, \code{vcov()}, and -\code{cd_test()} to access standard outputs. +Use \code{\link[=summary]{summary()}}, \code{\link[=coef]{coef()}}, \code{\link[=residuals]{residuals()}}, \code{\link[=vcov]{vcov()}}, and +\code{\link[=cd_test]{cd_test()}} to access standard outputs. } \description{ -Estimate panel data models that allow for cross-sectional dependence and -heterogeneous slopes. The interface supports Mean Group (MG), Common -Correlated Effects (CCE), Dynamic CCE (DCCE), and Cross-Sectionally -Augmented ARDL (CS-ARDL) estimators with consistent handling of -cross-sectional averages, dynamic structure, and robust inference. +Estimate heterogeneous panel data models with optional cross-sectional +augmentation and dynamic structure. The interface supports Mean Group (MG), +Common Correlated Effects (CCE), Dynamic CCE (DCCE), and +Cross-Sectionally Augmented ARDL (CS-ARDL) estimators with a consistent +specification workflow for cross-sectional averages, lag structure, and +variance-covariance estimation. } \details{ -\subsection{Model equations}{ +Let \eqn{i = 1, \ldots, N} index cross-sectional units and +\eqn{t = 1, \ldots, T} index time. A baseline heterogeneous panel model is -\describe{ -\item{MG (Pesaran and Smith, 1995)}{ -\deqn{y_{it} = x_{it}^\top \beta_i + u_{it}} -} -\item{CCE (Pesaran, 2006)}{ -\deqn{y_{it} = x_{it}^\top \beta_i + \lambda_i^\top F_t + u_{it}} -} -\item{DCCE (Chudik and Pesaran, 2015)}{ -\deqn{\Delta y_{it} = \Delta x_{it}^\top \beta_i + \lambda_i^\top \Delta F_t + u_{it}} -} -\item{CS-ARDL (Chudik and Pesaran, 2015)}{ -\deqn{y_{it} = \phi_i y_{it-1} + x_{it}^\top \theta_i + \lambda_i^\top F_t + u_{it}} -} -} -} +\deqn{y_{it} = \alpha_i + \beta_i^T x_{it} + u_{it}.} -\subsection{Estimation, identification, and assumptions}{ - -\describe{ -\item{MG}{Unit-by-unit estimation with heterogeneous slopes. The reported -coefficients are cross-sectional averages of unit estimates. Requires -sufficient time series per unit and weak serial dependence in errors.} -\item{CCE}{Augments regressions with cross-sectional averages (CSA) to proxy -unobserved common factors. Identification relies on large N and T, weak -dependence in idiosyncratic errors after CSA, and weak exogeneity of -regressors.} -\item{DCCE}{Extends CCE to dynamic settings with lagged dependent variables -and CSA lags. Identification relies on weak exogeneity, adequate time length -for dynamic lags, and a stable factor structure.} -\item{CS-ARDL}{Specifies dynamic distributed lags with CSA terms. Estimation -follows ARDL-style dynamics in each unit and aggregates to panel averages. -Assumes weak exogeneity and sufficient time length for lag structure.} -} -} +Here \eqn{\alpha_i} is a unit-specific intercept, \eqn{x_{it}} is a vector +of regressors, \eqn{\beta_i} is a vector of unit-specific slopes, and +\eqn{u_{it}} is an error term that may exhibit cross-sectional dependence. + +Cross-sectional averages are specified through \code{\link[=csdm_csa]{csdm_csa()}} and dynamic or +long-run structure is specified through \code{\link[=csdm_lr]{csdm_lr()}}. This keeps the model +interface consistent across estimators while allowing the degree of +cross-sectional augmentation and lag structure to vary by application. + +\strong{Implemented estimators} + +\strong{MG (Pesaran and Smith, 1995)} + +The Mean Group estimator fits separate regressions for each unit and averages +the resulting coefficients: + +\deqn{\hat{\beta}_{MG} = \frac{1}{N}\sum_{i=1}^N \hat{\beta}_i.} + +This estimator accommodates slope heterogeneity but does not explicitly model +cross-sectional dependence. + +\strong{CCE (Pesaran, 2006)} + +Regressions are augmented with cross-sectional averages to proxy unobserved +common factors: + +\deqn{y_{it} = \alpha_i + \beta_i^T x_{it} + \gamma_i^T \bar{z}_{t} + v_{it}.} + +A common choice is + +\deqn{\bar{z}_t = (\bar{y}_t, \bar{x}_t),} + +with + +\deqn{\bar{x}_t = \frac{1}{N}\sum_{i=1}^N x_{it}, \qquad +\bar{y}_t = \frac{1}{N}\sum_{i=1}^N y_{it}.} + +More generally, \eqn{\bar{z}_t} collects the cross-sectional averages +specified in \code{csa}. + +\strong{DCCE (Chudik and Pesaran, 2015)} + +Dynamic CCE extends CCE by allowing lagged dependent variables and lagged +cross-sectional averages: + +\deqn{y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} ++ \beta_i^T x_{it} ++ \sum_{q=0}^{Q} \delta_{iq}^T \bar{z}_{t-q} ++ e_{it}.} + +In the package implementation, lagged dependent variables and distributed +lags of regressors are controlled through \code{lr}, while contemporaneous +and lagged cross-sectional averages are controlled through \code{csa}. + +\strong{CS-ARDL (Chudik and Pesaran, 2015)} + +In the package implementation, \code{model = "cs_ardl"} is obtained by first +estimating a cross-sectionally augmented ARDL-style regression in levels, +using the same dynamic specification as \code{model = "dcce"}, and then +transforming the unit-specific coefficients into adjustment and long-run +parameters. + +The underlying unit-level regression is of the form + +\deqn{y_{it} = \alpha_i + \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} ++ \sum_{q=0}^{Q} \beta_{iq}^T x_{i,t-q} ++ \sum_{s=0}^{S} \omega_{is}^T \bar{z}_{t-s} ++ e_{it}.} + +From this dynamic specification, the package recovers the implied +error-correction form + +\deqn{\Delta y_{it} = +\alpha_i + +\varphi_i \left(y_{i,t-1} - \theta_i^T x_{i,t-1}\right) ++ \sum_{j=1}^{P-1} \lambda_{ij} \Delta y_{i,t-j} ++ \sum_{j=0}^{Q-1} \psi_{ij}^T \Delta x_{i,t-j} ++ \sum_{s=0}^{S} \tilde{\omega}_{is}^T \bar{z}_{t-s} ++ e_{it},} + +where \eqn{\varphi_i} is the adjustment coefficient and \eqn{\theta_i} is +the implied long-run relationship. In the current implementation, these +quantities are computed from the estimated lag polynomials rather than from a +direct ECM regression. + +\strong{Identification and assumptions} + +MG requires sufficient time-series variation within each unit. + +CCE relies on cross-sectional averages acting as proxies for latent common +factors, together with adequate cross-sectional and time dimensions. + +DCCE additionally requires enough time periods to support lagged dependent +variables, distributed lags, and lagged cross-sectional averages. + +CS-ARDL requires sufficient time length for the distributed-lag structure and +is intended for applications where both short-run dynamics and long-run +relationships are of interest in the presence of common factors. } \examples{ library(csdm) @@ -145,17 +213,9 @@ cs_ardl <- csdm( summary(cs_ardl) } \references{ -Pesaran, M.H. and Smith, R. (1995). "Estimating long-run relationships from -dynamic heterogeneous panels." Journal of Econometrics, 68(1), 79-113. - -Pesaran, M.H. (2006). "Estimation and inference in large heterogeneous panels -with multifactor error structure." Econometrica, 74(4), 967-1012. +\insertRef{PesaranSmith1995}{csdm} -Chudik, A. and Pesaran, M.H. (2015). "Common correlated effects estimation of -heterogeneous dynamic panel data models with weakly exogenous regressors." -Journal of Econometrics, 188(2), 393-420. +\insertRef{Pesaran2006}{csdm} -Chudik, A. and Pesaran, M.H. (2015). "Large panel data models with -cross-sectional dependence: A survey." Annals of Economics and Finance, 16(1), -53-78. +\insertRef{ChudikPesaran2015a}{csdm} } diff --git a/man/figures/logo.svg b/man/figures/logo.svg new file mode 100644 index 0000000..6bc16b8 --- /dev/null +++ b/man/figures/logo.svg @@ -0,0 +1,109 @@ + + + + + + + + + cs-ardl + cce + dcce + ccemg + cs-ardl + ccemg + dcce + + + + + + + + + + + + + + + + + + + + + + + + + csdm + + + + + + + + + + + + + + + + + + + + + + id + t + y + x + + + 1 + 1960 + + y(1,1960) + + + x(1,1960) + + + + 2 + 1980 + + y(2,1980) + + + x(2,1980) + + + + ... + ... + ... + ... + + + N + T + + y(N,T) + + + x(N,T) + + + + + + cross-sectional dependence modelling + + + \ No newline at end of file diff --git a/pkgdown/favicon/apple-touch-icon.png b/pkgdown/favicon/apple-touch-icon.png new file mode 100644 index 0000000..d92ba32 Binary files /dev/null and b/pkgdown/favicon/apple-touch-icon.png differ diff --git a/pkgdown/favicon/favicon-96x96.png b/pkgdown/favicon/favicon-96x96.png new file mode 100644 index 0000000..df73d23 Binary files /dev/null and b/pkgdown/favicon/favicon-96x96.png differ diff --git a/pkgdown/favicon/favicon.ico b/pkgdown/favicon/favicon.ico new file mode 100644 index 0000000..00d6ebb Binary files /dev/null and b/pkgdown/favicon/favicon.ico differ diff --git a/pkgdown/favicon/favicon.svg b/pkgdown/favicon/favicon.svg new file mode 100644 index 0000000..50bb121 --- /dev/null +++ b/pkgdown/favicon/favicon.svg @@ -0,0 +1,108 @@ + + + + + + + + cs-ardl + cce + dcce + ccemg + cs-ardl + ccemg + dcce + + + + + + + + + + + + + + + + + + + + + + + + + csdm + + + + + + + + + + + + + + + + + + + + + + id + t + y + x + + + 1 + 1960 + + y(1,1960) + + + x(1,1960) + + + + 2 + 1980 + + y(2,1980) + + + x(2,1980) + + + + ... + ... + ... + ... + + + N + T + + y(N,T) + + + x(N,T) + + + + + + cross-sectional dependence modelling + + + \ No newline at end of file diff --git a/pkgdown/favicon/site.webmanifest b/pkgdown/favicon/site.webmanifest new file mode 100644 index 0000000..4ebda26 --- /dev/null +++ b/pkgdown/favicon/site.webmanifest @@ -0,0 +1,21 @@ +{ + "name": "", + "short_name": "", + "icons": [ + { + "src": "/web-app-manifest-192x192.png", + "sizes": "192x192", + "type": "image/png", + "purpose": "maskable" + }, + { + "src": "/web-app-manifest-512x512.png", + "sizes": "512x512", + "type": "image/png", + "purpose": "maskable" + } + ], + "theme_color": "#ffffff", + "background_color": "#ffffff", + "display": "standalone" +} \ No newline at end of file diff --git a/pkgdown/favicon/web-app-manifest-192x192.png b/pkgdown/favicon/web-app-manifest-192x192.png new file mode 100644 index 0000000..a2ce71f Binary files /dev/null and b/pkgdown/favicon/web-app-manifest-192x192.png differ diff --git a/pkgdown/favicon/web-app-manifest-512x512.png b/pkgdown/favicon/web-app-manifest-512x512.png new file mode 100644 index 0000000..2a6162b Binary files /dev/null and b/pkgdown/favicon/web-app-manifest-512x512.png differ diff --git a/vignettes/introduction_to_csdm.Rmd b/vignettes/introduction_to_csdm.Rmd index ac62a98..4e086d6 100644 --- a/vignettes/introduction_to_csdm.Rmd +++ b/vignettes/introduction_to_csdm.Rmd @@ -2,13 +2,19 @@ title: "Introduction to csdm: Panel Data Models with Cross-Sectional Dependence" author: "Joao Claudio Macosso" date: "`r Sys.Date()`" -output: rmarkdown::html_vignette +output: + rmarkdown::html_vignette +bibliography: "`r system.file('REFERENCES.bib', package = 'csdm')`" +csl: "`r system.file('apa.csl', package = 'csdm')`" +nocite: | + @* vignette: > %\VignetteIndexEntry{Introduction to csdm} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- + ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, @@ -16,9 +22,14 @@ knitr::opts_chunk$set( warning = FALSE, message = FALSE ) + library(csdm) ``` + + +--- + ## Overview The `csdm` package implements econometric methods for panel data with cross-sectional dependence (CSD). In many applications, observations across units (e.g., countries, firms, regions) are not independent—macroeconomic shocks, trade relationships, or spillovers create correlation across cross-sectional units. The `csdm` package provides robust estimators that account for this dependence structure, plus diagnostic tests to detect and characterize it. @@ -27,70 +38,190 @@ This vignette demonstrates four core estimation methods and related inference to ## Methodology: Four Estimators - ### Model Specification -Consider a panel model with $T$ time periods and $N$ cross-sectional units (e.g., countries): +The `csdm()` interface estimates heterogeneous panel data models with optional cross-sectional augmentation and dynamic structure. Let \(i = 1, \ldots, N\) index cross-sectional units and \(t = 1, \ldots, T\) index time. A baseline heterogeneous panel model is -$$y_{it} = \alpha_i + \beta_i x_{it} + u_{it}, \quad i = 1, \ldots, N; \quad t = 1, \ldots, T$$ +$$ +y_{it} = \alpha_i + \beta_i' x_{it} + u_{it}, +\qquad i = 1, \ldots, N,\; t = 1, \ldots, T +$$ where: -- $y_{it}$ is the outcome variable for unit $i$ at time $t$ -- $\alpha_i$ is a unit-specific intercept -- $\beta_i$ is a unit-specific slope (heterogeneous across units) -- $x_{it}$ is explanatory variable(s) -- $u_{it}$ is the idiosyncratic error term -The key feature is **heterogeneity in slopes** ($\beta_i$ varies by unit), which allows each unit to have its own relationship between $x$ and $y$. Four estimators are available to fit this model under different assumptions about cross-sectional dependence. +- \(y_{it}\) is the outcome variable for unit \(i\) at time \(t\) +- \(\alpha_i\) is a unit-specific intercept +- \(\beta_i\) is a \((k \times 1)\) vector of unit-specific slopes +- \(x_{it}\) is a \((k \times 1)\) vector of explanatory variables +- \(u_{it}\) is the error term, which may exhibit cross-sectional dependence + +The inner product \(\beta_i' x_{it}\) is scalar-valued. Heterogeneous slopes allow each unit to respond differently to the regressors. In many applications, cross-sectional dependence arises because the error term contains unobserved common factors. The estimators implemented in `csdm()` differ in how they handle this dependence and whether they allow for dynamic adjustment. + +--- ### 1. Mean Group (MG) Estimator -The Mean Group (MG) estimator fits unit-specific regressions separately and averages the results: +The Mean Group estimator fits separate regressions for each unit and averages the resulting coefficients: + +$$ +\hat{\beta}_{MG} = \frac{1}{N}\sum_{i=1}^N \hat{\beta}_i +$$ + +**Key idea**: Estimation is performed unit by unit, with no pooling of slope coefficients across cross-sectional units. + +**Interpretation**: + +- \(\hat{\beta}_{MG}\) is the cross-sectional average of the unit-specific estimates +- all slope coefficients are allowed to differ across units -$$\hat{\beta}_{MG} = \frac{1}{N} \sum_{i=1}^{N} \hat{\beta}_i$$ +**Properties**: -**Interpretation**: The MG coefficient is the simple average of individual unit slopes. It is consistent under mild regularity conditions and allows arbitrary cross-sectional dependence in errors $u_{it}$. +- accommodates slope heterogeneity +- requires sufficient time-series information within each unit +- does not explicitly model cross-sectional dependence -**Use case**: When dependence is present but you only care about average effects. MG is robust to forms of CSD that would break other methods. +**Use case**: A natural benchmark when the main concern is heterogeneous slopes and no explicit factor structure is imposed. + +--- ### 2. Common Correlated Effects (CCE) Estimator -The Common Correlated Effects (CCE) estimator augments the model with cross-sectional averages of regressors $\bar{x}_t = N^{-1} \sum_{i=1}^{N} x_{it}$: +The CCE estimator augments each unit regression with cross-sectional averages to proxy unobserved common factors: + +$$ +y_{it} = \alpha_i + \beta_i' x_{it} + \gamma_i' \bar{z}_t + v_{it} +$$ + +where \(\bar{z}_t\) collects the cross-sectional averages specified through `csdm_csa()`, for example + +$$ +\bar{z}_t = (\bar{y}_t, \bar{x}_t), +\qquad +\bar{x}_t = \frac{1}{N}\sum_{i=1}^N x_{it}, +\qquad +\bar{y}_t = \frac{1}{N}\sum_{i=1}^N y_{it}. +$$ + +**Key idea**: Cross-sectional averages serve as proxies for latent common factors that induce dependence across units. + +**Interpretation**: -$$y_{it} = \alpha_i + \beta_i x_{it} + \gamma_i \bar{x}_t + \gamma_i \bar{y}_t + v_{it}$$ +- \(\beta_i\) measures the unit-specific effect conditional on the included cross-sectional averages +- \(\gamma_i\) captures unit-specific exposure to the common components with \(\bar{z}_t\) as a proxy. -By including these cross-sectional mean terms, the estimator **controls for common factors** (unobserved shocks that affect all units similarly). The CCE approach is more efficient than MG when common factor structure is strong, while retaining robustness to CSD. +**Properties**: -**Interpretation**: After accounting for common shocks, the $\beta_i$ coefficients represent unit-specific sensitivities net of factor loadings $\gamma_i$. +- allows heterogeneous slopes +- augments the regression with cross-sectional averages supplied through `csa` +- suitable when cross-sectional dependence is driven by latent common shocks -**Use case**: When cross-sectional dependence arises primarily from common shocks or latent factors. +**Use case**: When dependence across units is believed to reflect common unobserved factors. + +--- ### 3. Dynamic CCE (DCCE) Estimator -The Dynamic Common Correlated Effects (DCCE) estimator extends CCE to include lagged dependent variable: +The DCCE estimator extends CCE to dynamic settings by including lagged dependent variables, optional distributed lags of regressors, and lagged cross-sectional averages: + +$$ +y_{it} += +\alpha_i ++ \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} ++ \sum_{q=0}^{Q} \beta_{iq}' x_{i,t-q} ++ \sum_{s=0}^{S} \delta_{is}' \bar{z}_{t-s} ++ e_{it} +$$ + +where the dynamic structure is controlled through `csdm_lr()` and the cross-sectional averages and their lags are controlled through `csdm_csa()`. + +**Key idea**: Dynamics are introduced directly in the unit equation, while lagged cross-sectional averages help absorb common factor dependence over time. + +**Interpretation**: -$$y_{it} = \alpha_i + \lambda_i y_{it-1} + \beta_i x_{it} + \gamma_i \bar{x}_t + \gamma_i \bar{y}_t + v_{it}$$ +- \(\phi_{ip}\) captures unit-specific persistence +- \(\beta_{iq}\) captures contemporaneous and lagged effects of regressors +- \(\delta_{is}\) captures the effect of contemporaneous and lagged common components -where $\lambda_i$ is the unit-specific autoregressive coefficient. DCCE is ideal for dynamic panel models (e.g., when studying persistence of outcomes over time). +**Properties**: -**Interpretation**: $\lambda_i$ captures dynamic adjustment within units, $\beta_i$ measures the long-run effect after accounting for dynamics, and $\gamma_i$ adjusts for common factors. +- allows heterogeneous dynamic adjustment across units +- combines lagged dependent variables, optional distributed lags, and cross-sectional augmentation +- requires enough time periods to support the chosen lag structure -**Use case**: When the outcome has substantial persistence (lagged effects) and cross-sectional dependence is suspected. +**Use case**: When the outcome is persistent over time and cross-sectional dependence remains important. + +--- ### 4. Cross-Sectionally Augmented ARDL (CS-ARDL) -The CS-ARDL model extends the ARDL framework with cross-sectional augmentation: +In the current `csdm()` implementation, `model = "cs_ardl"` is obtained by first estimating a cross-sectionally augmented ARDL-style regression in levels, using the same dynamic specification as `model = "dcce"`, and then transforming the estimated unit-specific coefficients into adjustment and long-run parameters. + +The underlying unit-level regression is + +$$ +y_{it} += +\alpha_i ++ \sum_{p=1}^{P} \phi_{ip} y_{i,t-p} ++ \sum_{q=0}^{Q} \beta_{iq}' x_{i,t-q} ++ \sum_{s=0}^{S} \omega_{is}' \bar{z}_{t-s} ++ e_{it} +$$ + +From this dynamic specification, the implied error-correction form is + +$$ +\Delta y_{it} += +\alpha_i ++ \varphi_i \left( y_{i,t-1} - \theta_i' x_{i,t-1} \right) ++ \sum_{j=1}^{P-1} \lambda_{ij} \Delta y_{i,t-j} ++ \sum_{j=0}^{Q-1} \psi_{ij}' \Delta x_{i,t-j} ++ \sum_{s=0}^{S} \tilde{\omega}_{is}' \bar{z}_{t-s} ++ e_{it} +$$ + +where the dynamic structure is controlled through `csdm_lr()` and the cross-sectional averages are supplied through `csdm_csa()`. -$$\Delta y_{it} = \alpha_i + \lambda_i (y_{it-1} - \theta_i x_{it-1}) + \beta_i \Delta x_{it} + \hat{\gamma}_i \Delta \bar{x}_t + v_{it}$$ +**Key idea**: `cs_ardl` reports the implied short-run and long-run quantities from a cross-sectionally augmented ARDL fit. -This model combines **autoregressive and distributed lag** dynamics. It separates short-run effects ($\beta_i$) from long-run cointegrating relationships ($\theta_i$), all while controlling for common factors. +**Interpretation**: + +- \(\theta_i\) is the unit-specific long-run relationship +- \(\varphi_i\) is the implied speed of adjustment back toward equilibrium +- \(\psi_{ij}\) captures short-run effects of changes in regressors +- \(\tilde{\omega}_{is}\) captures the role of common cross-sectional components + +**Properties**: + +- supports heterogeneous short-run and long-run dynamics +- combines ARDL-style dynamics with cross-sectional augmentation +- recovers adjustment and long-run coefficients from estimated lag polynomials rather than fitting a separate ECM directly + +**Use case**: When the objective is to study long-run relationships together with heterogeneous short-run adjustment in panels affected by common factors. + +--- -**Interpretation**: -- $\theta_i$ is the long-run equilibrium relationship (cointegrating coefficient) -- $\beta_i$ is the short-run adjustment to shocks -- $\lambda_i$ governs speed of reversion to equilibrium +### Cross-Sectional Averages and Dynamic Structure -**Use case**: When studying long-run relationships in non-stationary panels with complex short-run dynamics. +Two helper specifications control the main extensions in `csdm()`: + +- `csdm_csa()` defines which variables enter as cross-sectional averages and how many lags of those averages are included +- `csdm_lr()` defines the dynamic or long-run structure, such as lagged dependent variables and distributed lags + +This design keeps the estimation interface consistent across the four estimators while allowing the model specification to vary by application. + +--- + +### Summary + +| Estimator | Heterogeneous Slopes | Cross-Sectional Averages | Dynamics | Long-Run Structure | +|-----------|----------------------|--------------------------|----------|--------------------| +| MG | Yes | No | No | No | +| CCE | Yes | Yes | No | No | +| DCCE | Yes | Yes | Yes | No | +| CS-ARDL | Yes | Yes | Yes | Yes | ## Data: Penn World Table Subset @@ -209,7 +340,7 @@ fit_csardl <- csdm( vars = c("log_rgdpo", "log_hc", "log_ck", "log_ngd"), lags = 3 ), - lr = csdm_lr(type = "ardl", ylags = 1, xdlags = 1) + lr = csdm_lr(type = "ardl", ylags = 1, xdlags = 0) ) print(fit_csardl) @@ -295,17 +426,8 @@ In practice, models that do not account for cross-sectional dependence (like MG ## References -Chudik, A., & Pesaran, M. H. (2013). Common correlated effects estimation of heterogeneous dynamic panel data models with weakly exogenous regressors. *Journal of Business and Economic Statistics*, 33(2), 232–247. - -Ditzen, J. (2021). Estimating dynamic common-correlated effects in Stata. *The Stata Journal*, 21(1), 39–59. - -Fan, J., Liao, Y., & Yao, J. (2015). Power-enhanced simultaneous test for high-dimensional covariance matrix. *Journal of the American Statistical Association*, 110(510), 325–337. - -Juodis, A., & Reese, S. (2022). The role of the *N/T* ratio in large N, large T panel time-series models. *Econometric Reviews*, 41(2), 221–261. - -Pesaran, M. H. (2007). A simple unit root test in the presence of cross-section dependence. *Journal of Applied Econometrics*, 22(2), 265–312. - -Pesaran, M. H., & Xie, Y. (2021). A bias-adjusted LM test of error cross-section independence. *Econometric Reviews*, 40(1), 7–24. +::: {#refs} +::: ---