*! version 1.0.1 21aug2026

Title

gvar hd -- historical decomposition

Syntax

gvar hd , variables(unit:var) [options]

options

variables(unit:var) the series decomposed. One at a time.

shocks(spec) name the shocks to show instead of ranking them.

top(#) how many leading contributors to show. Default 6.

periods(numlist) print the contributions in these periods.

first(units) which units lead the ordering. For type(sgirf) this is the identifying assumption, and the block size is derived from it.

vorder(spec) the variable order inside each leading unit, one block per unit separated by ;.

vcov(string) sample keeps the estimated covariance; blockdiag zeroes every cross-unit covariance; blockdiag unit does the same but leaves one unit's cross-covariances free.

shrink shrink the correlation matrix towards the identity, intensity chosen internally.

lambda(#) set the shrinkage intensity by hand, between 0 and 1.

bgvar reproduce BGVAR's hd.R exactly, including its unscaled trend.

graph plot the contributions.

name(name) graph name.

nosummary suppress the tables.

saving(name) save the decomposition.

Description

gvar hd splits one observed series into the cumulated contribution of
every structural shock, plus the constant, the trend, the initial condition
and a leftover slice.

A historical decomposition attributes each movement in the data to one shock,
so it requires orthogonal shocks. The source refuses to do this under
generalized identification and so does this command.

Options

variables(unitvariable) the series to decompose. It must select exactly
one element -- a historical decomposition is read one series at a time.

shocks(spec) restricts which shocks are shown, and top(#) keeps only
the largest contributors. Default 6, which is what fits legibly in a stacked bar
chart.

periods(spec) restricts the sample window shown, for zooming on an episode.

full shows the deterministic and initial-condition blocks as well as the
shock contributions. By default they are netted out.

That default is deliberate. On data in levels the deterministic and initial-value
terms account for the overwhelming majority of the height of every bar -- around
85% on the shipped demo -- so a chart including them is technically complete and
tells you nothing about the shocks. full is there when you want to verify
that the pieces add back to the data.

lines draws lines instead of stacked bars, which is easier to read when
you care about one contributor's path rather than the composition.

vcov(spec), shrink and lambda(#) as in
gvar irf. A historical decomposition is orthogonalised, so it
needs a Cholesky factor and will refuse on the shipped demo without
shrink -- under either estimator, since Sigma_zeta is 136 x 136 from
134 quarters.

bgvar reproduces hd.R's own arithmetic, which feeds the trend
coefficient in unscaled and starts the initial-condition block one application of
the companion matrix short. Both are hidden by its trailing residual slice, which
is defined as data minus everything else. Corrected, the leftover falls from 48.7
to 9.4e-13 on a series whose level is 4.8. See gvar methods.

graph, name(), saving() and nosummary as elsewhere.

Remarks

Why it needs an orthogonal scheme. Generalized shocks are correlated by
construction, so the attributions would double count and the pieces would not
add back to the data. Use first() and vorder() to set a Cholesky
ordering, and shrink if the covariance is singular.

Do not validate this by checking that the pieces sum to the data. The
leftover slice is defined as the data minus everything else, so that
identity holds however wrong the other blocks are. The quantity to read is the
size of the leftover itself, reported in the header. Correctly computed it is
at machine zero; the demo gives 9e-13 against a series whose level is 4.8.

On bgvar. The reference implementation feeds the trend coefficient into
the companion recursion unscaled and starts its initial-condition block one
step short. Both defects are hidden by its residual slice. bgvar
reproduces that behaviour for replication; the default corrects it, and the
correction changes which shock is the largest contributor.

Examples

. gvar hd, variables(usa:y) shrink
. gvar hd, variables(usa:y) shrink first(usa) ///
vorder(poil pmat pmetal y Dp eq r lr) periods(40 80 120)
. gvar hd, variables(euro:y) shrink graph

Stored results

gvar hd stores the following in r():

r(hd) the decomposition, stacked blocks by period

r(strshock) the recovered structural shocks

r(contrib) mean absolute contribution of each shock

r(leftover) the largest leftover, which should be at machine zero

r(nblocks) number of blocks returned

Source

BGVAR hd.R.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

https://github.com/merwanroudane