*! version 1.0.0 March 2026

Title

xtpretest -- Comprehensive Panel Data Pre-Testing Suite

Syntax

xtpretest depvar indepvars [if] [in], [options]

Test Selection
all run all available tests (default if no specific module selected)

hsiao Hsiao (2014) ANCOVA homogeneity tests (standard F-tests)

robust Hsiao robust HC1 heteroscedasticity-consistent Wald tests

summary panel summary statistics (xtsum-style decomposition)

heterogeneity coefficient heterogeneity analysis with Swamy (1970) test

slopehomogeneity slope homogeneity tests via xthst and xtbhst

csd cross-sectional dependence tests via xtcd2 and built-in CD

breaks structural break test via xtbreak

Output Control
graph generate comprehensive diagnostic graphs (up to 15 graph types)

notable suppress table output (stored results still available)

Bootstrap Options
reps(#) number of bootstrap replications for xtbhst; default is reps(200)

seed(#) random number seed for reproducibility of bootstrap results

Data must be xtset before using xtpretest. The panel must be
strongly balanced with no gaps.

Description

xtpretest provides a comprehensive suite of panel data pre-tests in a single
command, covering eight modules of diagnostic analysis. It combines homogeneity
testing, summary statistics, coefficient heterogeneity analysis, slope homogeneity
tests, cross-sectional dependence diagnostics, structural break detection, and
diagnostic visualisation into one unified framework.

The command helps researchers determine the appropriate panel estimator before
estimation by systematically testing for:

(i) Poolability — whether data can be pooled across panels (Modules 2, 3)

(ii) Slope heterogeneity — whether coefficients vary across panels (Modules 4, 5)

(iii) Cross-sectional dependence — whether residuals are correlated across panels (Module 6)

(iv) Structural breaks — whether parameters are stable over time (Module 7)

The command integrates methods from Hsiao (2014), Pesaran and Yamagata (2008),
Blomquist and Westerlund (2015), Pesaran (2004, 2015, 2021), Swamy (1970),
Okui and Yanagi (2019), Breusch and Pagan (1979), Karavias, Narayan, and
Westerlund (2021), and Bai and Perron (1998, 2003). It auto-detects which
companion packages are installed and runs them when available.

After running all selected modules, xtpretest produces an Overall Pre-Test
Summary with a decision-tree-based estimator recommendation (see
Recommendation Logic).

Options

Test Selection

all runs all available modules (1 through 7). This is the default if no
specific module option is specified.

hsiao runs Module 2: Hsiao (2014) standard ANCOVA F-tests for poolability,
including F1 (overall homogeneity), F2 (slope homogeneity), and F3 (intercept
homogeneity conditional on equal slopes).

robust runs Module 3: Hsiao robust heteroscedasticity-consistent (HC1)
Wald tests. These provide valid inference under heteroscedasticity and also
report Breusch-Pagan (1979) diagnostics.

summary runs Module 1: Panel summary statistics with Overall/Between/Within
variance decomposition for each variable.

heterogeneity runs Module 4: Individual-level coefficient analysis,
heterogeneity statistics, variance decomposition, and the Swamy (1970) test
for parameter heterogeneity.

slopehomogeneity runs Module 5: Pesaran and Yamagata (2008) Delta test
via xthst and Blomquist and Westerlund (2015) bootstrap Delta test via
xtbhst, if installed.

csd runs Module 6: Cross-sectional dependence tests. Uses xtcd2 for
the Pesaran (2015, 2021) CD/CDw/CD* tests and also computes a built-in
Pesaran (2004) CD test on fixed-effects residuals.

breaks runs Module 7: Structural break detection using xtbreak test
(Karavias, Narayan and Westerlund 2021; Bai and Perron 1998, 2003), if installed.
Tests for one structural break under hypothesis H1 (supF test).

Output Control

graph generates up to 15 diagnostic graphs covering variation decomposition,
distributions, box plots, scatter plots, residual diagnostics, coefficient
distributions, radar charts, and heterogeneity plotmeans. See
Diagnostic Graphs.

notable suppresses all tabular output. Stored results in r() remain
available for programmatic use.

Bootstrap Options

reps(#) specifies the number of bootstrap replications used by xtbhst
in Module 5. Default is 200.

seed(#) sets the random number seed for bootstrap reproducibility. If not
specified or set to -1, Stata's current random state is used.

Modules

Module 1: Panel Summary Statistics

Produces an xtsum-style decomposition table showing Overall,
Between (cross-panel), and Within (time) variation for each variable
in the model. Reports Mean, Std.Dev, Min, and Max for each component.

Also produces a Pairwise Correlation Matrix with color-coded coefficients
(|r| >= 0.7 in red, |r| >= 0.4 in yellow) and a separate P-values table.

A Missing Data Analysis table reports Total Obs, Non-Missing, Missing
count, Missing %, and a status classification (Complete, Low < 5%, Moderate
5-20%, High >= 20%) for each variable. High missingness is flagged in red.

An Outlier Detection table uses the IQR method to identify observations
outside [Q1 - 1.5*IQR, Q3 + 1.5*IQR]. Reports Q1, Q3, IQR, outlier count,
and outlier % for each variable. High outlier rates (>= 10%) are flagged
in red; moderate (>= 5%) in yellow.

This decomposition is useful for assessing how much variation exists across
panels versus within panels over time, which informs the choice between
between-effects, fixed-effects, and random-effects estimators.

Module 2: Hsiao Standard Homogeneity Tests (ANCOVA)

Implements the three sequential F-tests from Hsiao (2014, Ch.2) using the
classical ANCOVA approach with three nested models:

Model 1 — Unrestricted: Individual OLS regressions per panel unit
(RSS = S1, df = N(T-K-1)).

Model 2 — Fixed Effects: Common slopes with different intercepts
(RSS = S2, df = N(T-1)-K).

Model 3 — Fully Pooled: Common slopes and intercepts
(RSS = S3, df = NT-(K+1)).

Three F-tests are computed:

F1 (Overall homogeneity): H0: slopes and intercepts are equal
across all panels. Compares S3 to S1. Rejection suggests panel-specific
parameters are needed.

F2 (Slope homogeneity): H0: slope coefficients are equal across
panels, allowing intercepts to differ. Compares S2 to S1. Rejection suggests
heterogeneous slope estimators (MG, PMG, CCE).

F3 (Intercept homogeneity | equal slopes): Conditional on equal
slopes, H0: intercepts are equal. Compares S3 to S2. Rejection suggests
fixed-effects (FE) specification.

Follows the three-step decision procedure of Kuh (1963):

Step 1: Test F1. If accepted, use Pooled OLS.

Step 2: If F1 rejected, test F2. If rejected, use MG/PMG/CCE.

Step 3: If F2 accepted, test F3. If rejected, use FE. If accepted, use Pooled OLS.

Displays an ANCOVA table (RSS, df, Mean Squares), hypothesis test results,
and a structured decision summary.

Module 3: Hsiao Robust HC Tests

Same three hypotheses as Module 2 but using HC1-robust (White, 1980) standard
errors via Stata's vce(robust). Uses interaction-based Wald tests:

Robust F1: Tests joint significance of all panel dummies and
slope interactions (overall homogeneity).

Robust F2: Tests joint significance of slope interaction terms
only (slope homogeneity).

Robust F3: Tests joint significance of panel dummies with common
slopes (intercept homogeneity).

These tests are valid under heteroscedasticity and provide a robust alternative
to the classical F-tests in Module 2.

Also reports the Breusch-Pagan (1979) test for heteroscedasticity in the
pooled model, informing whether robust standard errors are necessary.

Module 4: Coefficient Heterogeneity Analysis

Runs individual OLS regressions for each panel unit and produces three tables:

Table 1 — Individual Panel Coefficients: Full N x (K+1) table of
panel-specific intercept and slope estimates.

Table 2 — Heterogeneity Statistics: Distribution summary of each
coefficient across panels — Mean, Median, Std.Dev, IQR, Skewness, Kurtosis,
Min, Max. Provides a measure of how dispersed coefficients are.

Table 3 — Variance Decomposition: Decomposes total coefficient
variance into Between-panel variance (true heterogeneity) and Within-panel
variance (estimation noise from each panel's SE). Reports the signal ratio
(Between/Total) with classification: High (>= 0.8), Moderate (>= 0.5),
or Low (< 0.5).

Also computes the Swamy (1970) chi-squared test for parameter heterogeneity,
which tests whether individual slope coefficients significantly differ from the
pooled fixed-effects estimator. The test statistic is:

chi2 = sum_i (b_i - b_FE)' * V_i^(-1) * (b_i - b_FE)

where b_i is the individual OLS estimate for panel i, b_FE is the pooled FE
estimate, and V_i is the variance of b_i. Under H0 of homogeneous slopes,
the statistic is chi-squared with K*(N-1) degrees of freedom.

Module 5: Slope Homogeneity Tests

Auto-runs two complementary slope homogeneity tests if their packages are
installed:

5.1 Pesaran and Yamagata (2008) — xthst: Reports the Delta and
adjusted Delta statistics with asymptotic p-values. The Delta test is based on
the standardised dispersion of individual slope estimates around the pooled
estimator. The adjusted version corrects for small-sample bias.

5.2 Blomquist and Westerlund (2015) — xtbhst: A bootstrap version
of the Delta test that provides more reliable inference in small samples,
particularly when T is small relative to N. Uses block bootstrap for proper
handling of temporal dependence. The number of bootstrap replications is
controlled by reps(#).

Both tests share H0: slope coefficients are homogeneous across panels.
Rejection indicates the need for heterogeneous-coefficient estimators.

Module 6: Cross-Sectional Dependence

Tests for cross-sectional dependence in both the raw model variables and
the regression residuals:

6.1 Pesaran (2015, 2021) CD Test for Variables — xtcd2: Runs
xtcd2 on all variables in the model (dependent and independent) to test
for cross-sectional dependence in the raw data. Reports CD, CDw, CDw+, and
CD* statistics for each variable. This reveals whether the variables themselves
exhibit strong cross-sectional dependence that could affect estimation.

6.2 Pesaran (2015, 2021) CD Test for FE Residuals — xtcd2: Runs
xtcd2 on fixed-effects residuals. Cross-sectional dependence in the
residuals implies that an unobserved common factor structure is present, which
invalidates standard FE or pooled inference.

6.3 Built-in Pesaran (2004) CD Test — Residuals: Computes the CD
test statistic from fixed-effects residuals using the formula:

CD = sqrt(2T / (N(N-1))) * sum_ rho_

where rho_ is the pairwise sample correlation of residuals between panels
i and j. Also reports the average absolute pairwise correlation |rho_ij|.
Under H0 of cross-sectional independence, CD ~ N(0,1).

If cross-sectional dependence is detected, estimators that account for common
factors are recommended: CCEMG (Pesaran 2006), CCE (Chudik and Pesaran 2015),
or FE with Driscoll-Kraay (1998) standard errors.

Module 7: Structural Breaks

Tests for structural breaks in the panel regression relationship using
xtbreak test (Ditzen, Karavias and Westerlund 2024).

Runs xtbreak test depvar indepvars, hypothesis(1) breaks(1)
which tests H0: no structural breaks vs H1: one structural break using the
supF statistic. Critical values from Bai and Perron (1998, 2003) are reported
at the 1%, 5%, and 10% significance levels.

If a break is detected, the estimated break date is reported. Trimming is
automatically adjusted if necessary (default 15%, increased to 20% when the
minimal segment length is shorter than the number of regressors).

Note: The xtbreak package may display harmless "Unknown #command"
warnings during loading on some systems — these come from Python comment lines
in xtbreak_auxiliary.ado and do not affect results.

Recommendation Logic

After executing all selected modules, xtpretest produces an Overall
Pre-Test Summary and an automatic estimator recommendation based on the
following decision tree:

1. Start with Pooled OLS as the baseline.

2. If Hsiao F2 (slopes) is significant (p < 0.05), recommend
Mean Group (MG) / CCEMG.

3. Else if Hsiao F3 (intercepts) is significant, recommend
Fixed Effects (FE).

4. Override with robust results: if Robust F2 is significant and not
already MG, switch to MG / CCEMG. If Robust F3 is significant and still
Pooled OLS, switch to FE.

5. Override with Swamy: if Swamy test is significant and still Pooled
OLS, switch to FE.

6. Adjust for cross-sectional dependence: If CD test is significant:

— If current recommendation is MG → switch to CCEMG (with CSD)

— If current recommendation is FE → switch to FE with Driscoll-Kraay SE

The recommendation is stored in r(recommendation) for programmatic use.

Diagnostic Graphs

When graph is specified, xtpretest generates up to 15 diagnostic
graphs. Each graph is created as a named Stata graph object and can be
redisplayed using graph display name.

Graph Description

xtpre_variation Between vs Within variation bar chart — shows the standard
deviation decomposition for each variable

xtpre_distributions Variable distributions with kernel density overlays
and mean reference lines (combined, up to 6 variables)

xtpre_boxplots Cross-panel box plots by panel unit for each
variable

xtpre_timeseries Time series line plots by panel (separate
panel lines via by())

xtpre_scatter Scatter plots of depvar vs each with
linear and quadratic fit lines overlaid

xtpre_corrmatrix Pairwise scatter matrix of all variables in
the model

xtpre_residuals Residual diagnostics panel: residuals vs fitted
values, residual histogram with kernel density, and residual box plots by panel
(using pooled OLS residuals)

xtpre_csdisp Cross-sectional dispersion over time — panel SD
and mean of each variable by time period

xtpre_coefdist Coefficient distribution kernel densities —
shows the distribution of each individual slope estimate across panels
(requires heterogeneity or all)

xtpre_hsiao Hsiao F-test summary bar chart — F1, F2, F3 with
5% critical value line (requires hsiao or all)

xtpre_panelmeans Mean of dependent variable by panel — bar chart
(requires summary or all)

xtpre_radar Coefficient heterogeneity radar chart — grouped bar
chart showing Mean, Std.Dev, Min, Max of individual coefficients across panels
(requires heterogeneity or all)

xtpre_plotmeans Panel means with 95% confidence intervals — bar
chart with error bars highlighting mean-level heterogeneity

xtpre_plotmeans_panel Heterogeneity across panels — R-style
connected line plot with confidence intervals (plotmeans-style)

xtpre_plotmeans_time Heterogeneity across time periods — R-style
connected line plot with confidence intervals (plotmeans-style)

Use graph display name to redisplay any graph, or
graph export name.png, name(name) replace to save.

Stored results

xtpretest stores the following in r():

Scalars

r(N) number of panels

r(T) number of time periods

Module 1 — Summary Statistics

r(xtsum_overall_mean) overall mean of dependent variable

r(xtsum_overall_sd) overall standard deviation of dependent variable

Module 2 — Hsiao Standard F-Tests

r(F1) F1 statistic (overall homogeneity: slopes + intercepts)

r(F1_p) p-value for F1

r(F1_df1) numerator degrees of freedom for F1

r(F1_df2) denominator degrees of freedom for F1

r(F2) F2 statistic (slope homogeneity)

r(F2_p) p-value for F2

r(F2_df1) numerator degrees of freedom for F2

r(F2_df2) denominator degrees of freedom for F2

r(F3) F3 statistic (intercept homogeneity given equal slopes)

r(F3_p) p-value for F3

r(F3_df1) numerator degrees of freedom for F3

r(F3_df2) denominator degrees of freedom for F3

r(S1) unrestricted RSS (sum of individual panel regressions)

r(S2) fixed-effects model RSS

r(S3) pooled OLS model RSS

Module 3 — Hsiao Robust HC Tests

r(rF1) Robust F1 statistic (overall homogeneity)

r(rF1_p) p-value for robust F1

r(rF2) Robust F2 statistic (slope homogeneity)

r(rF2_p) p-value for robust F2

r(rF3) Robust F3 statistic (intercept homogeneity)

r(rF3_p) p-value for robust F3

r(bp_chi2) Breusch-Pagan chi-squared statistic

r(bp_p) Breusch-Pagan p-value

Module 4 — Coefficient Heterogeneity

r(swamy_chi2) Swamy (1970) test chi-squared statistic

r(swamy_df) Swamy test degrees of freedom = K*(N-1)

r(swamy_p) Swamy test p-value

Module 5 — Slope Homogeneity (if xthst installed)

r(delta_xthst) Delta statistic from xthst

r(delta_adj_xthst) adjusted Delta statistic from xthst

r(delta_p_xthst) p-value for Delta from xthst

r(delta_adj_p_xthst) p-value for adjusted Delta from xthst

Module 5 — Slope Homogeneity (if xtbhst installed)

r(delta_xtbhst) Delta statistic from xtbhst

r(delta_adj_xtbhst) adjusted Delta statistic from xtbhst

r(delta_p_xtbhst) bootstrap p-value for Delta from xtbhst

r(delta_adj_p_xtbhst) bootstrap p-value for adjusted Delta

Module 6 — Cross-Sectional Dependence (if xtcd2 installed)

r(cd) CD statistic from xtcd2

r(cd_p) CD p-value from xtcd2

r(cd_rho) average correlation from xtcd2

Module 6 — Cross-Sectional Dependence (built-in)

r(cd_builtin) built-in Pesaran (2004) CD test statistic

r(cd_builtin_p) built-in CD test p-value

r(avg_rho) average absolute pairwise correlation |rho_ij|

Macros

r(depvar) dependent variable name

r(indepvars) independent variable names

r(recommendation) recommended estimator based on test results

Matrices

r(indiv_b) N x (K+1) matrix of individual panel coefficients (from Module 4)

Dependencies

xtpretest requires Stata 14.0 or later. The following companion packages
are optional — the command auto-detects their availability and skips
any module whose dependency is not installed:

Package Used in / Purpose

xthst Module 5: Pesaran and Yamagata (2008) Delta test for slope
homogeneity

ssc install xthst

xtbhst Module 5: Blomquist and Westerlund (2015) bootstrap
Delta test

ssc install xtbhst

xtcd2 Module 6: Pesaran (2015, 2021) and related CSD tests

ssc install xtcd2

xtbreak Module 7: Structural break testing (Ditzen, Karavias and
Westerlund 2024). Requires moremata.

ssc install xtbreak

ssc install moremata

Install all optional dependencies at once:

. ssc install xthst

. ssc install xtbhst

. ssc install xtcd2

. ssc install moremata

. ssc install xtbreak

Examples

Basic usage — run all pre-tests:

. webuse grunfeld, clear

. xtset company year

. xtpretest invest mvalue kstock

Only Hsiao homogeneity tests:

. xtpretest invest mvalue kstock, hsiao

Hsiao standard + robust with diagnostic graphs:

. xtpretest invest mvalue kstock, hsiao robust graph

Panel summary statistics only:

. xtpretest invest mvalue kstock, summary

Coefficient heterogeneity with radar chart and plotmeans:

. xtpretest invest mvalue kstock, heterogeneity graph

Slope homogeneity tests with 500 bootstrap reps:

. xtpretest invest mvalue kstock, slopehomogeneity reps(500) seed(12345)

Cross-sectional dependence only:

. xtpretest invest mvalue kstock, csd

Structural break test only:

. xtpretest invest mvalue kstock, breaks

All tests with full diagnostic graphs:

. xtpretest invest mvalue kstock, all graph

Check stored results after running:

. return list

. di "F1=" r(F1) " F2=" r(F2) " F3=" r(F3)

. di "Recommended: " r(recommendation)

Suppress tables, keep only stored results:

. xtpretest invest mvalue kstock, notable

. return list

Using with custom data:

. use mydata, clear

. xtset country year

. xtpretest gdp fdi inflation unemployment

References

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

Bai, J. and Perron, P. (2003). Computation and analysis of multiple structural
change models. Journal of Applied Econometrics 18(1), pp 1-22.

Blomquist, J. and Westerlund, J. (2015). Panel bootstrap tests of slope
homogeneity. Empirical Economics 48, pp 1643-1660.

Breusch, T.S. and Pagan, A.R. (1979). A simple test for heteroscedasticity
and random coefficient variation. Econometrica 47(5), pp 1287-1294.

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), pp 393-420.

Ditzen, J., Karavias, Y. and Westerlund, J. (2024). Testing and estimating
structural breaks in time series and panel data in Stata.
arXiv:2110.14550.

Driscoll, J.C. and Kraay, A.C. (1998). Consistent covariance matrix estimation
with spatially dependent panel data. Review of Economics and Statistics
80(4), pp 549-560.

Fan, J., Liao, Y. and Yao, J. (2015). Power enhancement in high-dimensional
cross-sectional tests. Econometrica 83(4), pp 1497-1541.

Hsiao, C. (2014). Analysis of Panel Data. 3rd edition. Cambridge
University Press. Chapter 2.

Juodis, A. and Reese, S. (2021). The incidental parameters problem in testing
for remaining cross-section correlation. Journal of Business and Economic
Statistics 40(3), pp 1191-1203.

Karavias, Y., Narayan, P.K. and Westerlund, J. (2021). Structural breaks in
interactive effects panels and the stock market reaction to COVID-19.
Journal of Business and Economic Statistics 41(3), pp 653-666.

Kuh, E. (1963). Capital Stock Growth: A Micro-Econometric Approach.
North-Holland.

Okui, R. and Yanagi, T. (2019). Panel data analysis with heterogeneous
dynamics. Journal of Econometrics 212(2), pp 451-475.

Pesaran, M.H. (2004). General diagnostic tests for cross-section dependence
in panels. CESifo Working Paper No. 1229.

Pesaran, M.H. (2006). Estimation and inference in large heterogeneous panels
with a multifactor error structure. Econometrica 74(4), pp 967-1012.

Pesaran, M.H. (2015). Testing weak cross-sectional dependence in large
panels. Econometric Reviews 34(6-10), pp 1089-1117.

Pesaran, M.H. (2021). General diagnostic tests for cross-sectional dependence
in panels. Empirical Economics 60, pp 13-50.

Pesaran, M.H. and Xie, T. (2021). A bias-corrected CD test for error
cross-sectional dependence in panel data models with latent factors.
Cambridge Working Papers in Economics 2158.

Pesaran, M.H. and Yamagata, T. (2008). Testing slope homogeneity in large
panels. Journal of Econometrics 142(1), pp 50-93.

Swamy, P.A.V.B. (1970). Efficient inference in a random coefficient
regression model. Econometrica 38(2), pp 311-323.

White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator
and a direct test for heteroskedasticity. Econometrica 48(4),
pp 817-838.

Author

Dr. Merwan Roudane

Email: merwanroudane920@gmail.com

xtpretest v1.0.0, March 2026.