*! version 1.0.0 18jul2026

Title

xtvsom -- Variance Shift Outlier Model (VSOM) for panel data

Syntax

Postestimation (after xtreg,fe / regress / ivregress 2sls):

xtvsom [if] [in] [, options]

Standalone:

xtvsom depvar indepvars [if] [in], fe|ols [options]

Model
fe fixed-effects (within) design; default when data are xtset

ols pooled OLS design (constant included)

iv simultaneous / 2SLS design (postestimation after ivregress 2sls)

Detection
alpha(#) family-wise significance for the cutoff; default alpha(0.05)

reps(#) parametric-bootstrap replications for the cutoff; default reps(2000)

seed(#) random-number seed for the bootstrap

cutoff(#) use a fixed cutoff instead of bootstrapping

Reporting
level(#) confidence level; default level(95)

graph draw the four VSOM diagnostic figures

name(string) stub for the graph names; default name(xtvsom)

nolabel show numeric panel codes instead of value labels

Description

xtvsom implements the Variance Shift Outlier Model (VSOM) of Gumedze
(2008) as adapted to panel data by Ismadyaliana, Setiawan and Purnomo (2024).
VSOM is a compromise between case deletion and robust estimation: rather than
dropping a suspected outlier, it shifts (inflates) that observation's
variance, which is algebraically equivalent to down-weighting it. The
command:

1. fits a null model (fixed-effects within, pooled OLS, or 2SLS);

2. forms the squared standardized residual t^2 of each observation;

3. builds an empirical cutoff for max t^2 by a parametric bootstrap under the null;

4. flags observations exceeding the cutoff;

5. estimates each flagged unit's variance-shift {&psi} and refits by feasible GLS (= WLS).

Used as postestimation, xtvsom reuses the model in memory: fit
xtreg with fe, or regress, or ivregress 2sls
(the simultaneous case), then type xtvsom. The estimation sample and the
estimator are read from e(), and e() is restored on exit. See
xtvsom postestimation.

Options

Model

fe uses the within (fixed-effects) design: depvar and
indepvars are demeaned by panel, no constant, and the leverage carries the
1/T mean-projection term of the LSDV hat matrix. This is the default when
the data are xtset and no model is given in postestimation.

ols uses the pooled design with a constant.

iv treats the fit as a 2SLS structural equation. It is available
only as postestimation after ivregress 2sls (or xtivreg); the
first-stage fitted endogenous regressors are reconstructed from e(instd)
and e(insts), and VSOM is applied to the second-stage residuals, exactly
as in the simultaneous-equation VSOM of the source paper. After
xtivreg,fe the fixed effects are absorbed (LSDV first stage plus a within
second stage), so the VSOM null slopes reproduce the xtivreg,fe
coefficients; after ivregress 2sls a pooled 2SLS design is used.

Detection

alpha(#) sets the (family-wise) tail probability used to read the
cutoff off the bootstrap distribution of max t^2. Smaller
alpha flags fewer observations.

reps(#) is the number of parametric-bootstrap replications used to
build the null distribution of max t^2. Larger is more stable.

cutoff(#) bypasses the bootstrap and uses the supplied value as the
t^2 cutoff (e.g. to reuse a previously computed threshold).

Method

Full derivations and the code®paper equation map are in
xtoutliers methods. In brief, with squared
standardized residual t^2it = eit^2 / [{&sigma}^2 (1-vit)],
the REML variance-shift estimate is

{&psi}it = (nT-p)(t^2-1) / [(nT-p-t^2)(1-vit)]

and, because the shift matrix P = D{&Psi}D'+I is diagonal, the VSOM
generalized-least-squares refit reduces to weighted least squares with weights
wit = 1/(1+{&psi}it). The reported VSOM residual is
wit {&times} rit, reproducing the residual shrinkage of
the source paper.

Interpreting the output

o cutoff - the t^2 threshold; observations
above it are outliers.

o Coefficient comparison - null vs VSOM slopes with standard
errors; signs should be stable and VSOM standard errors typically smaller.

o SSR null / SSR VSOM - the sum of squared residuals falls under
VSOM, confirming the outliers were accommodated.

o Detected outliers - per-unit t^2, {&psi},
and the null vs VSOM residuals.

o graph - four figures matching the source paper: (a) t^2
with the cutoff line; (b) residuals null vs VSOM; (c) the variance-shift
{&psi}; (d) the variance estimate {&sigma}^2.

Examples

Fixed-effects postestimation with figures:

. webuse nlswork

. xtreg ln_wage age tenure hours, fe

. xtvsom, alpha(0.05) reps(2000) seed(12345) graph

Pooled OLS, standalone:

. xtvsom ln_wage age tenure hours, ols

Simultaneous (2SLS) VSOM:

. ivregress 2sls y (w = z1 z2) x1 x2, fe

. xtvsom, iv graph

Stored results

xtvsom stores the following in r():

Scalars

r(N) number of observations

r(p) number of model parameters

r(nout) number of detected outliers

r(cutoff) t^2 cutoff

r(alpha) significance used

r(sigma2) null-model variance

r(sigma2v) VSOM variance

r(ssr0) null SSR

r(ssrv) VSOM SSR

Macros

r(model) model type (fe/ols/iv)

r(depvar) dependent variable

Matrices

r(b_null) null coefficients

r(V_null) null variance matrix

r(b_vsom) VSOM coefficients

r(V_vsom) VSOM variance matrix

r(outliers) outlier table (obs, id, time, t^2, {&psi}, {&sigma}^2, resid0, residVSOM, weight)

References

Gumedze, F.N. 2008. A Variance Shift Model for Outlier Detection and
Estimation in Linear and Linear Mixed Models. University of Cape Town.

Ismadyaliana, S., Setiawan, and J.D.T. Purnomo. 2024. Panel data
modeling: Identifying and handling outliers with the VSOM approach.
MethodsX 13: 102900.

Thompson, R. 1985. A note on restricted maximum likelihood estimation
with an alternative outlier model. JRSS B 47: 53-55.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

github.com/merwanroudane