*! version 1.0.1 21aug2026

Title

gvar import -- read a GVAR Toolbox 2.0 data workbook into a long panel

Syntax

gvar import using filename [, options]

options

domestic(varlist) the domestic variables, one worksheet each.

global(varlist) the global variables, one worksheet each with a single data column.

unit(name) name for the unit identifier. Default country.

time(name) name for the time identifier. Default period.

sheets(string) var=sheet pairs, where a worksheet title differs from the variable name.

frequency(string) quarterly, monthly, yearly or none.

clear replace the data in memory.

nosummary suppress the report.

Description

gvar import reads a GVAR Toolbox workbook and turns it into the long
panel that gvar setup expects. It exists so that a Toolbox
dataset can be brought over without being retyped or reshaped by hand.

It is a data-preparation command. It does not declare a model; run
gvar setup afterwards, and the report tells you the exact
command to type.

The workbook layout

The Toolbox keeps its data one worksheet per variable, with countries
across the columns and dates down column A:

row 1 a header of country codes

column A the dates, from row 2 down

That is the transpose of what every Stata command wants, which is one row per
(unit, period). So each sheet is read, reshaped long, and merged on
(unit, period).

A global variable has one data column rather than one per country, since
it is the same series for every unit. Those sheets are merged m:1 on the
time identifier instead.

Options

domestic(varlist) names the domestic variables. Each becomes one
worksheet read and one variable in the result. Required in practice: with none
given there is nothing to read.

global(varlist) names the global variables -- oil and commodity prices in
the standard Toolbox setup. Each is expected to have a single data column.

unit(name) and time(name) name the two panel identifiers that get
created. The defaults, country and period, are what the shipped
examples use.

sheets(string) maps a variable name onto a worksheet title when the two
differ, as var=sheet pairs separated by spaces. Without it the worksheet
title must equal the variable name.

frequency(string) says how to read column A. quarterly parses the
Toolbox's own YYYYQn form, monthly parses YYYYMnn,
yearly reads a year, and none keeps the sheet's own row order as a
running index.

clear is required if there are unsaved data in memory, exactly as for
use.

Remarks

A partly parsed date column is refused, not patched. The Toolbox writes
column A in whatever form Excel handed it -- a real Excel serial number, a
string like 1979Q2, or a plain running index -- so each form is tried and
the one that parses every row wins. A column that parses for only some
rows would silently reorder the panel, which is far worse than an error, so it
exits instead and suggests frequency(none).

Missing values after the merge are counted and reported. A country
present in one sheet and absent from another leaves gaps once the sheets are
merged. That is precisely the case that goes on to estimate and solve without
complaint, so the report states how many gaps there are and in which
variables. A ragged panel is legal -- gvar setup accepts it
and gvar estimate works around it unit by unit -- but it
is something to check rather than discover later in the fit.

Sheets that could not be read are named. They are listed rather than
skipped quietly, with a reminder that sheets() exists for the case where
worksheet titles do not match variable names.

Verification. The import was checked against the shipped
gvar_demo26 data, which came from the same Toolbox workbook by a
different route: all nine series agree to 0.0000e+00 over the 3400 shared
rows. The 1088 import-only rows are the eight individual euro-area members,
and the 136 reference-only rows are the aggregate that replaces them -- which
is a difference in how the region is treated, not a discrepancy in the data.

Examples

The standard Toolbox workbook, quarterly, with three global variables:

. gvar import using "GVAR_Data.xls", domestic(y Dp eq ep r lr) global(poil pmat pmetal) frequency(quarterly) clear

. gvar setup y Dp eq ep r lr, unit(country) time(period) global(poil pmat pmetal)

Where two worksheet titles do not match the variable names:

. gvar import using "GVAR_Data.xls", domestic(y Dp eq) global(poil) sheets(Dp=inflation poil=oilprice) frequency(quarterly) clear

Keeping the sheet's own row order, when column A is not a date at all:

. gvar import using "mydata.xlsx", domestic(y Dp) frequency(none) clear

Stored results

gvar import stores the following in r():

r(nunits) units found

r(nperiods) periods spanned

r(nsheets) domestic sheets successfully read

r(nmissing) missing values left by the merge

r(units) the unit identifiers

r(notread) sheets that could not be read

Source

Toolbox gvar.m:191, the xlsread calls and the 'A2:A65536'
range that skips the header row.

Author

Dr Merwan Roudane

merwanroudane920@gmail.com

https://github.com/merwanroudane