*! version 1.0.1 21aug2026

Title

gvar setup -- declare the panel and the model specification

Syntax

gvar setup varlist [if] [in] , unit(varname) time(varname) [options]

options

unit(varname) the cross-section identifier. Required.

time(varname) the time identifier. Required.

global(varlist) variables common to every unit, such as commodity prices.

gendog(spec) make a global variable endogenous to one unit, as gendog(poil=usa). This is the Dees-di Mauro-Pesaran-Smith device of attaching the oil price to the United States.

foreign(spec) override which variables enter a unit's foreign block.

noforeign(spec) suppress the foreign counterpart of a variable.

exclude(spec) drop a variable from a unit's domestic block.

case(spec) deterministic case 2, 3 or 4, globally or per unit.

wtype(spec) which weight matrix each variable uses.

psc(#) order of the serial-correlation F test carried through to gvar diag. Default psc(4).

spec(filename) read the whole specification grid from a dataset.

nosummary suppress the report.

Description

gvar setup reads a balanced long panel and declares which variable
belongs to which unit, which variables are global, and how each country model
is specified. Nothing else in the package works until it has run.

A variable that is entirely missing for a unit is treated as absent for
that unit, exactly as the Toolbox's dvflag does. Missing is the encoding
for "this unit does not have this series", not a gap to be filled. The command
reports which series are absent and which are only partially observed, so a
data problem cannot pass silently as a specification.

Options

unit(varname) and time(varname) identify the panel. If both are
omitted the data must already be xtset, and the xtset identifiers
are used. unit may be a string, a numeric with a value label, or a plain
numeric; the unit names in every later table come from whichever it is, so a
labelled numeric or a string gives readable output and a bare numeric gives
integers.

global(varlist) names variables that are common to every unit -- an oil
price, a commodity index. They are not any one country's variables and are
carried once rather than per unit.

gendog(spec) attaches a global variable to one unit's block as an
endogenous variable, as var=unit, e.g. gendog(poil=usa). That
gives the oil price the US model's dynamics and puts a US-specific shock on it.
Contrast dominant().

dominant(varlist) instead gives the global variables their own block,
estimated by gvar dominant. Use this when the variable is
nobody's domestic variable: it then has its own dynamics and its own shock, and
feeds back from the world with a lag rather than being driven by one country
contemporaneously. The two options answer the same question differently and
should not be used for the same variable.

foreign(spec) and noforeign(spec) control which domestic variables
get a foreign-specific counterpart. By default every domestic variable does.
noforeign() is how you say that a variable has no meaningful star
version for a unit -- and it changes the model, since a star variable that
should not be there is a weakly exogenous regressor that does not belong.

exclude(spec) drops individual (unit, variable) pairs from the model, for
the case where a country genuinely does not have a series. Note that a
missing series already encodes this: gvar setup does not mark out
observations on the domestic varlist, because doing so would delete the whole
unit. Use exclude() when the data are present but should not be used.

case(spec) sets the deterministic specification, 2, 3 or 4 in
Pesaran-Shin-Smith's numbering, either globally or per unit. Case 4 -- restricted
trend -- is the default and the Toolbox's. This choice propagates: it sets the
critical values gvar coint uses and the deterministic terms
recovered by gvar estimate.

wtype(#) selects which of the weight types loaded by
gvar weights builds the star variables, when more than one
is available.

psc(#) is the number of principal components used in the cross-section
augmentation. Default 4.

spec(filename) reads the per-unit lag orders, ranks and deterministic
cases from a dataset instead of setting them by hand -- which is how the shipped
gvar_demospec reproduces the Toolbox's published specification exactly.
gvar datasets describes its layout.

nosummary suppresses the report. Read it at least once per dataset.
It is where partially observed series are named, and a series that is present for
only part of the window is dropped from its unit -- which changes the model
silently if you never look.

Remarks

On spec(). The grid is one row per unit and variable with columns
dv, fv, gv, p, q, case and rank. It
fixes, per unit, which variables are endogenous, which have foreign
counterparts, the lag orders, the deterministic case and the cointegrating
rank. This is the equivalent of the Toolbox's interface workbook and the only
reliable way to reproduce a published model: without it, ranks come from
gvar coint and lag orders from
gvar lags, which will not in general agree with someone
else's choices.

Read the report before continuing. It lists each unit's domestic block,
weakly exogenous block and lag orders. An unexpected blank almost always means
a variable name did not match, not that the unit lacks the series. The counts
of absent and partially observed series at the foot are there for the same
reason.

On the sample. Only the unit and time identifiers are used to define the
estimation sample. Casewise deletion on the domestic variables would drop
whole units, because in a GVAR a missing series is a specification fact
rather than a missing observation.

Examples

. use gvar_demo26
. gvar setup y Dp eq ep r lr, unit(country) time(quarter) ///
global(poil pmat pmetal) gendog(poil=usa pmat=usa pmetal=usa) ///
spec(gvar_demospec.dta)

Without a grid, giving every unit case 3:

. gvar setup y Dp r, unit(country) time(quarter) case(3)

Stored results

gvar setup stores the following in r():

r(N) units

r(K) total endogenous variables in x(t)

r(T) periods

r(V) distinct domestic variables

r(G) global variables

r(units) unit names

r(domestic) domestic variable names

r(global) global variable names

r(unitvar) the unit identifier

r(timevar) the time identifier

r(absent) series absent for at least one unit

r(partial) series only partially observed

Source

Toolbox gvar.m data-loading block; the dvflag, fvflag and
gvflag grid.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

https://github.com/merwanroudane