*! version 1.0.1 21aug2026

Title

gvar weights -- build or load the link weights

Syntax

gvar weights [using filename] [, options]

options

matrix(name) use a matrix already in memory, rows and columns in unit order.

type(#) which weight matrix this is, when variables use different ones. Default type(1).

flow(name) the flow variable in the using file.

source(name) the partner identifier in the using file.

destination(name) the home identifier in the using file.

year(name) the year variable in the using file.

years(numlist) average the flows over these years.

map(filename) crosswalk from flow-file names to model units.

wide the using file is already a wide matrix.

rowname(name) the row identifier in a wide file.

slice(name) which slice of a stacked time-varying file to use.

timevarying build one weight matrix per year.

window(#) moving-average window for time-varying weights. Default 3.

solyears(numlist) years whose weights are used when solving.

equal equal weights, 1/(N-1) off the diagonal.

list print the matrix.

graph heatmap of the weights.

name(name) graph name.

norebuild do not rebuild the foreign variables afterwards.

Description

gvar weights supplies the w_ij used to build each unit's foreign
variables. Weights may be computed from bilateral flows, taken from a matrix
in memory, read from a wide file, set equal, or allowed to vary over time.

Rows are normalised to sum to one with w_ii = 0. The command refuses an
all-zero column outright, because that would make a unit's foreign variables
identically zero and silently drive its cointegrating rank to zero.

Options

There are two ways to supply weights, and the options divide accordingly: give a
matrix that is already a weight matrix, or give flow data and let the
command build one.

From a matrix

matrix(name) names a Stata matrix holding W, and rowname(name)
and slice(name) identify its rows and, for a stack of matrices, which slice
to take. wide says the file is in wide rather than long layout.

From flow data

flow(name) is the variable holding the flow -- trade, financial claims --
with source(name) and destination(name) naming the two country
variables.

Get the direction right. W_i weights the other units from unit
i's point of view, so which of the two columns is the source and which the
destination determines whether you build W or W'. A transposed weight
matrix produces foreign variables that look entirely plausible and are wrong --
gvar foreign's list option exists for checking this,
and it is worth doing once per new dataset.

year(name) and years(numlist) select the years averaged over. Fixed
weights are the usual choice and the Toolbox averages a short window -- the demo
uses 2009 to 2011 -- rather than a single year, because annual bilateral flows are
noisy.

timevarying, window(#) and solyears(numlist) instead build a
weight matrix per period from a rolling window of # years, default 3, and
solyears() chooses which years the solved model uses.

equal builds equal weights, which is the null case worth running once: if
your conclusions are the same under trade weights and equal weights, the weights
are not doing the work you think they are.

Common

type(#) labels the weight type, so several can be loaded and
gvar setup's wtype() can choose between them per
variable -- trade weights for real variables, financial weights for the rest.

map(filename) supplies the aggregation map, which is how the eight euro-area
members become one unit. Aggregation happens before the weights are
normalised, so the map is not a post-processing step.

list prints the resulting matrix and nosummary suppresses the report.

Remarks

On map(). If any unit in your model is an aggregate of several entities
in the flow file, you must supply a crosswalk. In the shipped demo the euro
area is built from eight members; those members appear in the trade data under
their own names and the aggregate does not appear at all. Without
map() the euro column is identically zero, its foreign variables vanish
and its rank collapses. The command detects the all-zero column and stops.

On years(). The weights are an average over the chosen window, and
different windows give visibly different responses, so record which you used.
The Toolbox demo averages 2009-2011.

A sanity check worth doing. After building, list the matrix and
look at a row you know. In the demo the United States' three largest trade
weights are Canada 0.200, China 0.176 and Mexico 0.149, which is the right
real-world ranking. If the largest weights look implausible, the source and
destination variables are probably the wrong way round.

Examples

. gvar weights using gvar_flows.dta, flow(trade) source(partner) ///
destination(home) year(year) years(2009 2011) type(1) ///
map(gvar_demoagg.dta)

. gvar weights, equal
. gvar weights, matrix(Wtrade) list graph
. gvar weights using gvar_flows.dta, flow(trade) source(partner) ///
destination(home) year(year) timevarying window(3)

Stored results

gvar weights stores the following in r():

r(type) the weight-matrix type just built

r(units) unit names in row order

r(W) the weight matrix

Source

Toolbox build_wmat.m, weightmat.m, country_weights.m;
the crosswalk follows update_matrix.m.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

https://github.com/merwanroudane