*! version 1.0.0 09aug2026
help xtasymVersion 1.0.0 9 August 2026

Title

xtasym -- Directional asymmetry with panel data: partial sums,
diagnostics and graphics

Syntax

xtasym varlist [if] [in]
[, options]

Construction
threshold(#) size of the dead band around zero; default
threshold(0)

convention(rule) shin (default) or allison; sets the
sign of the negative arm

prefix(string) prefix for every variable created

nogenerate do not create partial sums; treat varlist as partial
sums already built

fdm also create the undifferenced first-difference-method
components

replace overwrite variables of the same name

Tables
frequency directional frequency table of the first
differences

summary overall, within and between dispersion of the partial
sums

csd Pesaran (2015) CD test for cross-sectional dependence

csdopt(string) options passed to xtcse2 for the exponent
alpha

cips(# #) Pesaran (2007) CIPS panel unit-root test; maximum lags
and Lagrange-multiplier order

cipsopt(string) options passed to xtcips

all shorthand for frequency summary csd graph

Graphics
graph shorthand for grsum grfre grdist

grsum accumulated-change paths, cross-panel mean with
interquartile band

grfre directional composition bar chart

grdist distribution of the first differences, split at the
threshold

scheme(name) parula (default), viridis,
journal or mono

name(stub) stub for the names of the graphs in memory

saving(stub) stub for .gph files written to disk

nodraw build the graphs but do not display them

combine also produce a combined figure of everything drawn

You must xtset your data, with both a panel and a time variable,
before using xtasym.

xtasym has no compulsory dependencies. xtcse2 (from
xtdcce2) is used, if it is installed, to add the exponent of
cross-sectional dependence to the csd table. xtcips is required
only by the cips() option.

Description

xtasym builds, describes and draws the partial sums used to model
directional asymmetry with panel data: the idea, going back to Lieberson
(1985), that an increase in x need not have an effect equal and opposite to
that of a decrease in x.

For each variable in varlist the command forms the first difference, splits
it into an increase and a decrease around a symmetric dead band of half-width
threshold(), and accumulates each part over time within panel. The two
new series appear as var_p and var_n. They are ordinary
variables: put them on the right-hand side of xtreg, xtdcce2,
clogit or anything else, and test asymmetry with test.

xtasym then reports what you need in order to choose an estimator for
those series — how many changes there actually are in each direction, how much
within variation the partial sums carry, whether they are cross-sectionally
dependent, and whether they are stationary — and draws them.

The construction follows Shin, Yu and Greenwood-Nimmo (2014) as used by Thombs,
Huang and Fitzgerald (2022), or Allison (2019), at your choice; see
Conventions below and
help xtasym methods for the algebra.

Options

Construction

threshold(#) sets the half-width c of a symmetric dead band. A
first difference counts as an increase when it exceeds +c, as a decrease
when it falls below -c, and as no change when it lies in
[-c, +c]. The default threshold(0) reproduces the definitions
in Allison (2019) and Thombs et al. (2022) exactly. Raising c is useful when a
series moves by a trivial amount every period, so that almost nothing is
classified as "no change" and the two arms are nearly collinear.

convention(rule) chooses the sign of the negative arm.
convention(shin), the default, follows Shin, Yu and Greenwood-Nimmo
(2014) and Thombs et al. (2022): the negative partial sum accumulates
min(dx, 0), so it is negative-valued and the symmetry restriction is
b+ = b-. convention(allison) follows Allison (2019): the
negative arm accumulates -min(dx, 0), so it is non-negative and the
symmetry restriction is b+ = -b-. The header of every run states
which restriction applies. See Conventions.

prefix(string) prepends string to every variable the command
creates. Use it to keep several thresholds or conventions side by side, for
example prefix(t5_).

nogenerate suppresses variable creation and takes varlist to be
partial sums that already exist. Use it to run the diagnostic tables on series
you built earlier. It may not be combined with threshold() or fdm,
and the grsum graph is skipped.

fdm additionally creates var_pfd and
var_nfd: the period-by-period positive and negative components,
not accumulated. These are the regressors of the first-difference method of
York and Light (2017) and Allison (2019, sec. 3), for a model whose dependent
variable is also first differenced. They obey the same convention().

replace allows the command to overwrite variables of the same
name. Without it, an existing name is an error.

Tables

frequency reports, per variable, how many first differences are
increases, decreases and no-change, with percentages of the changes actually
observed. This is the table that tells you whether an asymmetric model is
identified at all: an arm supported by a handful of movements will not carry a
coefficient.

summary reports the mean and the overall, within and between
standard deviations of every partial sum, through xtsum. The within
standard deviation is the one that matters: fixed-effects and
common-correlated-effects estimators identify from within variation only.

csd reports the Pesaran (2015) CD test for weak cross-sectional
dependence of each partial sum, together with the mean and mean absolute
pairwise correlation. The statistic is computed internally, so no other package
is needed. If xtcse2 is installed, the exponent of cross-sectional
dependence alpha (Bailey, Kapetanios and Pesaran 2016) is added to the table;
csdopt() passes options through to it.

cips(# #) reports the Pesaran (2007) CIPS panel unit-root test,
robust to cross-sectional dependence, for each partial sum. The first integer
is the maximum lag order, the second the autocorrelation order of the Lagrange
multiplier test. This option is a wrapper for xtcips, which must be
installed; cipsopt() passes options through to it.

all is shorthand for frequency summary csd graph.

Graphics

grsum draws, for each variable, the cross-panel mean of the two
partial sums against time, with the interquartile range across panels shaded.
Unlike a per-panel line plot this stays readable with many panels: it is the
picture of accumulated directional change.

grfre draws a single horizontal stacked bar per variable giving
the share of increases, no-change and decreases.

grdist draws, for each variable, the distribution of the first
differences with increases and decreases shaded separately. Both halves share
one bin grid and are plotted as counts, so the two sides are directly
comparable; the dead band, when one is set, is marked by dashed vertical lines
at -c and +c.

scheme(name) selects the colour ramp. parula (default)
reproduces the MATLAB R2014b Parula ramp; viridis is the matplotlib
ramp; journal is the Okabe-Ito colour-blind-safe set; mono is
greyscale for print. Increases always take the warm end of the ramp and
decreases the cool end.

name(stub), saving(stub), nodraw and combine
control where the graphs go. Names are formed as stub_composition,
stub_dist_var and stub_path_var; the default
stub is xtasym.

Conventions

Two sign conventions circulate in this literature and they are easy to confuse.
Write dx for the first difference of x.

Shin et al. (2014) x+ = sum of max(dx, 0)

x- = sum of min(dx, 0) (negative-valued)

symmetry: b+ = b-

used by Thombs, Huang and Fitzgerald (2022) and by xtasysum

Allison (2019) Z+ = sum of max(dx, 0)

Z- = sum of -min(dx, 0) (non-negative)

symmetry: b+ = -b-

The two are the same object with a flipped sign on one arm: x- =
-Z-. The coefficients therefore also differ by a sign, and so does the
restriction you must test. Getting this wrong reverses the sign of the reported
"effect of a decrease" and tests the wrong hypothesis. xtasym prints the
applicable restriction in its header on every run.

Note that under the Shin convention a positive coefficient on x-
means that a decrease in x lowers y. This is the reading behind the note to
Table 5 of Thombs et al. (2022).

Interpreting the output

Header. Confirms the panel and time variables, the number of panels and
observations entering the calculation, the threshold, the convention, and the
symmetry restriction implied by that convention.

Directional decomposition. Counts are of first differences, so the first
period of every panel and any gap in the time variable contribute nothing. If
one arm has very few movements, its coefficient will be imprecise however you
estimate it; Thombs et al. (2022, note 10) suggest a non-zero threshold when
within variation is scarce.

Summary statistics. A partial sum with a large between and a tiny within
standard deviation is nearly a fixed effect and will be absorbed by the panel
dummies.

CD table. CD is standard normal under the null of weak cross-sectional
dependence. Rejection, especially with a large mean absolute correlation, is
the case for a common-correlated-effects estimator instead of two-way fixed
effects. Pairs of panels with fewer than three overlapping periods are dropped
from the average, and the count of usable pairs is reported when alpha is not
available.

CIPS table. The test is left-tailed: a statistic more negative than the
critical value rejects the null of a homogeneous unit root. Partial sums of a
non-stationary series are themselves typically non-stationary, which is
expected rather than alarming; it is one reason Thombs et al. (2022) work with
an autoregressive distributed lag specification.

Using the partial sums in a model

xtasym builds and describes the regressors; the model is yours. The
specifications compared by Thombs et al. (2022) are, in the notation of the
variables this command creates:

1. Static fixed effects (York and Light 2017; Allison 2019). Biased when
the process is autoregressive, which it usually is with large T:

. xtasym lngdp

. xtreg lco2 lngdp_p lngdp_n i.year, fe cluster(id)

. test lngdp_p = lngdp_n

2. Dynamic fixed effects in ARDL form (their eq. 18). Consistent
short-run effects, but unstable long-run effects under slope heterogeneity:

. xtreg lco2 L.lco2 lngdp_p lngdp_n L.lngdp_p L.lngdp_n i.year, fe cluster(id)

. nlcom (lr_p: (_b[lngdp_p]+_b[L.lngdp_p])/(1-_b[L.lco2]))

3. Mean group or common correlated effects (their eq. 19), through
xtdcce2, when the slope-heterogeneity and CD pre-tests reject:

. xtdcce2 lco2 lngdp_p lngdp_n, lr(L.lco2 L.lngdp_p L.lngdp_n) lr_options(ardl) crosssectional(lco2) cr_lags(3)

4. Asymmetric conditional logit (Allison 2019, sec. 7) for a binary
outcome, which requires the Allison convention:

. xtasym spouse hours, convention(allison)

. clogit pov mother spouse_p spouse_n hours_p hours_n i.year, group(id) robust

. test spouse_p = -spouse_n

Note the restriction changes with the convention. Test slope heterogeneity with
xthst before settling on 2 versus 3.

Remarks and practical guidance

o Partial sums are accumulated within panel in time order and are set to
missing outside the estimation sample and wherever the source variable is
missing. A gap in the time variable produces no first difference for that
period, so nothing is accumulated across the gap.

o With threshold() greater than zero, changes inside the dead band
contribute nothing to either arm. The contribution of a change outside the band
is the whole first difference, not the excess over c, which is the
definition used in this literature.

o The command never changes the sort order of your data on exit and
never touches e().

o With few panels or a short T the CD statistic is unreliable; Pesaran
(2015) is a large-N result.

o Comparability with xtasysum (Thombs 2022): with
threshold(0) and the default convention, xtasym produces the same
_p and _n series as xtasysum, and fdm produces the same
_pfd and _nfd series. The results differ only when a non-zero
threshold is used: xtasym applies the threshold symmetrically as a dead
band, so that a small positive change is never counted as a decrease.

Stored results

xtasym stores the following in r():

Scalars

r(threshold) the dead-band half-width c

r(k) number of variables in varlist

Macros

r(varlist) the variables supplied

r(partialsums) the partial sums created or used

r(fdmvars) the first-difference-method components created

r(convention) shin or allison

r(panelvar) the panel variable

r(timevar) the time variable

r(graphs) names of the graphs produced

Matrices

r(frequency) counts and percentages by direction, one row per
variable

r(summary) mean and overall, within, between dispersion of each
partial sum

r(csd) CD, p-value, mean rho, mean |rho|, alpha, pairs, n,
T-bar

r(cips) CIPS statistic, critical values and the stationarity
verdict

Examples

Setup

. webuse grunfeld, clear

. xtset company year

Create the partial sums of mvalue

. xtasym mvalue

Everything at once, with graphs

. xtasym mvalue kstock, all

A dead band, so that trivial movements are not counted as changes

. xtasym mvalue, threshold(50) frequency prefix(b_)

Allison's convention, for a model in first differences or a
clogit

. xtasym mvalue, convention(allison) fdm replace

Diagnostics only, on partial sums that already exist

. xtasym mvalue_p mvalue_n, nogenerate summary csd

A publication figure in colour-blind-safe colours, saved to disk

. xtasym mvalue kstock, graph scheme(journal) saving(fig1) combine nodraw

Use them

. xtasym mvalue, replace

. xtreg invest mvalue_p mvalue_n kstock i.year, fe cluster(company)

. test mvalue_p = mvalue_n

A complete worked run on simulated data with a known asymmetry is in
xtasym_example.do, retrieved with net get xtasym.

References

Allison, Paul D. 2019. "Asymmetric Fixed-Effects Models for Panel
Data." Socius 5: 1-12.

Bailey, Natalia, George Kapetanios, and M. Hashem Pesaran. 2016.
"Exponent of Cross-Sectional Dependence: Estimation and Inference."
Journal of Applied Econometrics 31: 929-960.

Burdisso, Tamara, and Maximo Sangiacomo. 2016. "Panel Time Series:
Review of the Methodological Evolution." The Stata Journal 16(2): 424-442.

Chudik, Alexander, and M. Hashem Pesaran. 2015. "Common Correlated
Effects Estimation of Heterogeneous Dynamic Panel Data Models with Weakly
Exogenous Regressors." Journal of Econometrics 188(2): 393-420.

Ditzen, Jan. 2021. "Estimating Long-Run Effects and the Exponent of
Cross-Sectional Dependence: An Update to xtdcce2." The Stata Journal
21(3): 687-707.

Lieberson, Stanley. 1985. Making It Count: The Improvement of
Social Research and Theory. Berkeley: University of California Press.

Pesaran, M. Hashem. 2006. "Estimation and Inference in Large
Heterogeneous Panels with a Multifactor Error Structure." Econometrica
74(4): 967-1012.

Pesaran, M. Hashem. 2007. "A Simple Panel Unit Root Test in the
Presence of Cross-Section Dependence." Journal of Applied Econometrics
22(2): 265-312.

Pesaran, M. Hashem. 2015. "Testing Weak Cross-Sectional Dependence in
Large Panels." Econometric Reviews 34(6-10): 1089-1117.

Pesaran, M. Hashem, and Ron Smith. 1995. "Estimating Long-Run
Relationships from Dynamic Heterogeneous Panels." Journal of Econometrics
68(1): 79-113.

Shin, Yongcheol, Byungchul Yu, and Matthew Greenwood-Nimmo. 2014.
"Modelling Asymmetric Cointegration and Dynamic Multipliers in a Nonlinear ARDL
Framework." Pp. 281-314 in Festschrift in Honor of Peter Schmidt, edited
by R. Sickles and W. C. Horrace. New York: Springer.

Thombs, Ryan P., Xiaorui Huang, and Jared B. Fitzgerald. 2022. "What
Goes Up Might Not Come Down: Modeling Directional Asymmetry with Large-N,
Large-T Data." Sociological Methodology 52(1): 1-29.

York, Richard, and Ryan Light. 2017. "Directional Asymmetry in
Sociological Analyses." Socius 3: 1-13.

Author

Dr Merwan Roudane

Email: merwanroudane920@gmail.com

GitHub: github.com/merwanroudane

Also see

Manual: xtset, xtsum, xtreg

Help: xtasym methods

If installed: xtdcce2, xtcse2, xtcips,
xthst