{smcl}
{* *! version 1.0.0  18jul2026}{...}
{vieweralsosee "xtoutliers" "help xtoutliers"}{...}
{vieweralsosee "xtvsom" "help xtvsom"}{...}
{vieweralsosee "xtrobust" "help xtrobust"}{...}
{vieweralsosee "xtlossf" "help xtlossf"}{...}
{viewerjumpto "VSOM" "xtoutliers_methods##vsom"}{...}
{viewerjumpto "Robust (S / WLE)" "xtoutliers_methods##robust"}{...}
{viewerjumpto "Loss functions" "xtoutliers_methods##loss"}{...}
{viewerjumpto "Compatibility" "xtoutliers_methods##compat"}{...}
{viewerjumpto "Author" "xtoutliers_methods##author"}{...}
{title:Title}

{phang}
{bf:xtoutliers methods} {hline 2} Equations, derivations, and code{c 174}paper map

{pstd}
This page documents the mathematics behind the three commands and maps every
computational step to the equation it implements. It is the companion to the
{cmd:_COMPATIBILITY_MAP.md} shipped with the package.{p_end}


{marker vsom}{...}
{title:1. VSOM ({cmd:xtvsom})}

{pstd}
{it:Source:} Ismadyaliana, Setiawan & Purnomo, MethodsX 13 (2024) 102900;
Gumedze (2008); Thompson (1985).{p_end}

{pstd}{bf:Null model and standardized residual.} The within (FE) or pooled
design gives residuals {cmd:e}{sub:it} and variance
{cmd:{&sigma}}{c 94}{cmd:2 = e'e/(nT-p)}. With leverage
{cmd:v}{sub:it}{cmd: = } diagonal of the hat matrix (for FE, plus the
{cmd:1/T}{sub:i} mean-projection term),{p_end}

{p 12 12 2}{cmd:t}{c 94}{cmd:2}{sub:it}{cmd: = e}{sub:it}{c 94}{cmd:2 / [ {&sigma}}{c 94}{cmd:2 (1 - v}{sub:it}{cmd:) ]}.   (paper, boxed p.4){p_end}

{pstd}{bf:Cutoff.} Under the null there are no outliers, so the empirical
distribution of {cmd:max}{sub:i}{cmd: t}{c 94}{cmd:2}{sub:it} is generated by a
parametric bootstrap: draw {cmd:y* = X{&beta}{c 94}{cmd: + {&epsilon}*},
{&epsilon}* {&sim} N(0,{&sigma}}{c 94}{cmd:2)}, refit, recompute
{cmd:max t}{c 94}{cmd:2}. Because {cmd:(I-H)X = 0}, the standardized residual is
scale free, so {cmd:{&sigma}} cancels and the bootstrap needs no variance
estimate. The cutoff is the {cmd:(1-{&alpha})} quantile of the bootstrap maxima.{p_end}

{pstd}{bf:Variance-shift estimates} (Thompson 1985 REML, paper p.4, boxed), for
a flagged observation with {cmd:t}{c 94}{cmd:2 > 1}:{p_end}

{p 12 12 2}{cmd:{&psi}}{sub:it}{cmd: = (nT-p)(t}{c 94}{cmd:2-1) / [ (nT-p-t}{c 94}{cmd:2)(1-v}{sub:it}{cmd:) ]},{p_end}
{p 12 12 2}{cmd:{&sigma}}{c 94}{cmd:2}{sub:it}{cmd: = (nT-p-t}{c 94}{cmd:2)/(nT-p-1) {&times} {&sigma}}{c 94}{cmd:2}.{p_end}

{pstd}{bf:Key equivalence (VSOM = WLS).} The variance model is
{cmd:var(y) = {&sigma}}{c 94}{cmd:2 (D {&Psi} D' + I) = {&sigma}}{c 94}{cmd:2 P}.
Because {cmd:D} is a 0/1 indicator matrix selecting the outliers and
{cmd:{&Psi} = diag({&psi})}, the matrix {cmd:P} is {it:diagonal}, with
{cmd:P}{sub:ii}{cmd: = 1+{&psi}}{sub:i} for an outlier and 1 otherwise. Hence the
feasible-GLS refit{p_end}

{p 12 12 2}{cmd:{&beta}}{c 94}{cmd:}{sub:V}{cmd: = (X'P}{c 94}{cmd:-1}{cmd:X)}{c 94}{cmd:-1}{cmd:X'P}{c 94}{cmd:-1}{cmd:y}{p_end}

{pstd}
is exactly weighted least squares with weights
{cmd:w}{sub:i}{cmd: = 1/(1+{&psi}}{sub:i}{cmd:)}. This is what {cmd:xtvsom}
computes.{p_end}

{pstd}{bf:Residual shrinkage.} The fitted value carries the shift term
{cmd:{&theta}}{c 94}{cmd:}{sub:it}{cmd: = {&psi}}{sub:it}{cmd: d'P}{c 94}{cmd:-1}{cmd:(y-X{&beta}}{c 94}{cmd:}{sub:V}{cmd:)}.
Writing {cmd:r}{sub:it}{cmd: = y}{sub:it}{cmd:-x}{sub:it}{cmd:'{&beta}}{c 94}{cmd:}{sub:V}
(the WLS raw residual),{p_end}

{p 12 12 2}{cmd:y}{sub:it}{cmd: - x}{sub:it}{cmd:'{&beta}}{c 94}{cmd:}{sub:V}{cmd: - {&theta}}{c 94}{cmd:}{sub:it}{cmd: = r}{sub:it}{cmd: - [{&psi}/(1+{&psi})] r}{sub:it}{cmd: = r}{sub:it}{cmd:/(1+{&psi}}{sub:it}{cmd:) = w}{sub:it}{cmd: r}{sub:it}.{p_end}

{pstd}
So the reported VSOM residual is {cmd:w}{sub:it}{cmd: r}{sub:it}, which shrinks
toward zero at outliers {c 45} reproducing the residual columns of the source
paper (e.g. 0.5129 {c 45}{c 62} 0.0760, giving {cmd:w{&asymp}0.148},
{cmd:{&psi}{&asymp}5.8}).{p_end}

{pstd}{bf:Simultaneous (2SLS).} For the simultaneous model the second-stage
design is {cmd:X** = [Y{c 94}, X}{sub:exog}{cmd:, cons]}, with {cmd:Y{c 94}} the
first-stage fitted endogenous regressors (paper Eq. 10{c 45}13). Everything above
then applies with {cmd:X**} in place of {cmd:X}.{p_end}


{marker robust}{...}
{title:2. Robust S-estimator and WLE ({cmd:xtrobust})}

{pstd}
{it:Source:} Jaseem & Mohammad, Al-Nahrain J. Science 27(4) (2024) 40{c 45}46.{p_end}

{pstd}{bf:Transforms.} FE: within demeaning (paper Eq. 5{c 45}6). RE:
quasi-demeaning (Eq. 7)
{cmd:{&lambda}}{sub:i}{cmd: = 1 - [{&sigma}}{sub:{&epsilon}}{c 94}{cmd:2/({&sigma}}{sub:{&epsilon}}{c 94}{cmd:2 + T}{sub:i}{cmd:{&sigma}}{sub:v}{c 94}{cmd:2)]}{c 94}{cmd:(1/2)},
with {cmd:{&sigma}}{sub:{&epsilon}}{c 94}{cmd:2}, {cmd:{&sigma}}{sub:v}{c 94}{cmd:2}
from a preliminary {cmd:xtreg,re}.{p_end}

{pstd}{bf:S-estimator} (Eq. 10{c 45}13). Tukey biweight
{cmd:{&rho}(u) = u}{c 94}{cmd:2/2 - u}{c 94}{cmd:4/(2c}{c 94}{cmd:2) + u}{c 94}{cmd:6/(6c}{c 94}{cmd:4)}
for {cmd:|u|{&le}c}, else {cmd:c}{c 94}{cmd:2/6}, with {cmd:c=1.547}. The scale
{cmd:{&sigma}}{sub:S} solves {cmd:mean {&rho}(r}{sub:i}{cmd:/{&sigma}) = K},
{cmd:K = 0.199 = (c}{c 94}{cmd:2/6)/2}, giving a 50% breakdown point. The
estimator {cmd:{&beta}}{c 94}{cmd: = argmin {&sigma}}{sub:S} is minimised by
fast-S: {cmd:nsamp} elemental subsets, each refined by concentration steps,
retaining the smallest scale, then full IRLS.{p_end}

{pstd}{bf:WLE} (Eq. 14{c 45}17). With residual density
{cmd:f*(r}{sub:i}{cmd:)} (Gaussian kernel, bandwidth {cmd:h}) and smoothed model
density {cmd:m*(r}{sub:i}{cmd:) = N(0,{&sigma}}{sub:v}{c 94}{cmd:2+h}{c 94}{cmd:2)},
the Pearson residual is
{cmd:{&delta}}{sub:i}{cmd: = f*(r}{sub:i}{cmd:)/m*(r}{sub:i}{cmd:) - 1}, the RAF
is {cmd:A({&delta}) = 2[({&delta}+1)}{c 94}{cmd:(1/2) - 1]}, and the weight is
{cmd:w}{sub:i}{cmd: = min{c 123}1, [A({&delta}}{sub:i}{cmd:)+1]}{sub:+}{cmd:/({&delta}}{sub:i}{cmd:+1){c 125}}.
Iterating {cmd:{&beta} = (X'WX)}{c 94}{cmd:-1}{cmd:X'Wy} solves the weighted
likelihood equation (Eq. 14).{p_end}


{marker loss}{...}
{title:3. Loss functions ({cmd:xtlossf})}

{pstd}
{it:Source:} Coleman & Bryan, arXiv:2509.07014v2 (2025).{p_end}

{pstd}{bf:Part I (nonnegative).} From symmetry, monotonicity in the difference,
and decrease in the base, the simplest loss is Cobb{c 45}Douglas; a Lie symmetry
fixes the difference exponent to 1:{p_end}

{p 12 12 2}{cmd:L = |F-B| B}{c 94}{cmd:q}     (Eq. I.2),   signed {cmd:S = (F-B) B}{c 94}{cmd:q}   (Eq. I.7).{p_end}

{pstd}{cmd:q=0} is the absolute difference, {cmd:q=-1} the absolute relative
difference; {cmd:q=-1/2} is optimal for comparing two unbiased estimate sets with
variance proportional to the level (Eq. I.13{c 45}I.16). The time-invariant form
uses exponent {cmd:tq+t-1} (Eq. I.6), {cmd:t} rescaled so the last date is 1.
Calibration from a criteria table solves {cmd:log {&epsilon} = -q log B + K}
(Eq. I.19{c 45}I.20), {cmd:C = exp(K)} ({opt fit}).{p_end}

{pstd}{bf:Part II (mixed sign).} With {cmd:{&Sigma} = |F|+|B|},{p_end}

{p 12 12 2}{cmd:L = |F-B| {&Sigma}}{c 94}{cmd:q}     (Eq. II.5),   signed {cmd:S = (F-B) {&Sigma}}{c 94}{cmd:q}   (Eq. II.9),{p_end}

{pstd}
with {cmd:L(0,0)=0} (a continuity point when {cmd:p+q>0}, Thm II.1) and
{cmd:q=-1} the harmonic-mean average absolute relative difference (Eq. II.6). An
outlier is declared when {cmd:L > C}; {cmd:C} is empirical (a quantile or a Tukey
IQR fence) {c 45} there is no distributional significance test, by construction.{p_end}


{marker compat}{...}
{title:4. Compatibility}

{pstd}
Every step above is traced to a numbered equation, and the equivalences (VSOM =
WLS; residual = {cmd:w r}; {cmd:K = c}{c 94}{cmd:2/6/2}; smoothed model density =
{cmd:N(0,{&sigma}}{c 94}{cmd:2+h}{c 94}{cmd:2)}) are proved in
{cmd:_COMPATIBILITY_MAP.md}. Where a paper provides no quantity (RE-VSOM, a
significance test for a loss, a CI for the S scale) the command reports none and
the limitation is documented rather than invented.{p_end}


{marker author}{...}
{title:Author}

{pstd}Dr Merwan Roudane{break}
merwanroudane920@gmail.com{break}
{browse "https://github.com/merwanroudane":github.com/merwanroudane}{p_end}