The READ statement puts variables from a .gbk file (or other formats) into the first-position databank. A .gbk file is a Gekko-specific binary databank format that stores series, values, dates, strings, lists, maps, and matrices.

Before reading, the first-position databank is cleared, so after reading, the first-position databank will correspond to the file (this behavior may be altered with the <merge> option). After reading (optionally merging) data from the file into the first-position databank, the reference databank is always constructed as an exact copy of the first-position databank (a 'clone').

Because READ clears the first-position databank, it may often be practical to store variables in the Global databank. It can be practical to put general settings etc. in that bank, for instance default periods, often-used lists, etc. Variables in the Global databank will survive READ and CLEAR statements, and are in that sense long-lived.

When modelling using Gekko program files, it is advised to put a MODEL statement and an option freq = ... ; statement before the READ statement, so that READ knows the model and its frequency. When doing this, READ will auto-create technical model variables like add-factors etc. (D-, J-, and Z-type variables), and will also indicate if the lists of variables in the model and the databank are not matching (note: such auto-creation is not done for data mode).

READ is intended for .gbk files, and can be thought of as an enhanced version of IMPORT. In contrast to IMPORT, READ clears the first-position databank, reads all data regardless of the global time period (unless a time period or <respect> is used), and finally makes Ref a clone of the first-position databank. There are the following equivalences: READ = CLEAR<first> + IMPORT<all> + CLONE, and the inverse: IMPORT = READ<first merge respect>.

Because Gekko uses a so-called cache for databank files, the same file will load faster the next time it is read.

Syntax

read < period ALL FIRST REF MERGE > filename TO bankname;

filename	Filenames may contain an absolute path like c:\projects\gekko\bank.gbk, or a relative path \gekko\bank.gbk. Filenames containing blanks and special characters should be put inside quotes. Regarding reading of files, files in libraries can be referred to with colon (for instance lib1:bank.gbk), and "zip paths" are allowed too (for instance c:\projects\data.zip\bank.gbk). See more on filenames here. If the filename is set to '*', you will be asked to choose the file in Windows Explorer. The extension .gbk is automatically added, if it is missing.
period	(Optional). Without a time period indicated, Gekko will read all the data for all observations in the file. When a period is indicated, the read data(bank) is truncated.
FIRST	Reads the file into the first-position databank (#1 on the F2 window list).
REF	Reads the file into the reference databank (shown as REF on the F2 window list).
MERGE	(Optional). If MERGE is set, the data is merged into the existing first-position databank.
RESPECT	(Optional). With this option, if no period is given, the global period is used.
TO	(Optional). If TO bankname is indicated, Gekko will put the data into a seperate 'named' databank alongside the Work and Ref databanks. For instance, after read adambk TO a;, you may refer to the variables by means of colon, for instance prt a:var1;. If you use read adambk TO *;, the bankname will be the same as the file name. It should be noted that the databank will be read-only (protected) when opened like this (read ... TO ... is essentially the same as an OPEN statement)
TRACE=	(Optional). Default is yes. Set no to omit reading of data traces. The databank will load faster and use less RAM (if traces are present). Only relevant for Gekko databanks (.gbk files).

Examples

Reading a .gbk file called adambk.gbk is done with

read adambk;

or by writing

read *;

and then selecting the databank. Note that after such a READ of data into the first-position databank, the reference databank will always be created as an excact copy of the first-position databank. This behavior is practical for modeling purposes. You can merge with existing data in the first-position databank like this:

read <merge> adambk;

This merges adam.gbk with any pre-existing data in the first-position databank. Full or relative path names are possible:

read otherbanks\adam3;

This will look for adam3.gbk in the subfolder otherbanks, relative the the Gekko working folder.

Use the TO keyword like this:

read forecst2 TO f2;

This reads forecst2.gbk into the named databank f2. After this, you may use for instance prt f2:gdp; to print out the timeseries gdp from this databank. This databank will be read-only. You may use read forecst2 TO *; if you wish to use the filename as databank name. It is possible to use read * TO *;. Using read ... TO ... is essentially the same as an OPEN statement.

Note

When reading, extension .gbk is automatically added if it is missing. Global time settings do not affect the READ statement, so all the data in the .gbk file is read into the first-position databank regardless of how the timeperiod is set in Gekko. (Useread <respect> to restrict the read data to the global time period).

Annual, quarterly, monthly, weekly, daily and undated data may co-exist as series in the same .gbk file, together with other variables types.

The gbk format is currently 1.2 (corresponding to Gekko 3.0/3.1.x) and comes in the following versions:

gbk file format versions

1.0	(July 2011). The file extension is .tsdx. Inside this zip-file there is a .tsd file, and a xml file with meta-information (does not state the databank format number, which is implicitly "1.0"). Only supports timeseries. Can be read by Gekko 1.3.1 and later.
1.1	(November 2012). The file extension is .tsdx or .gbk. Inside there is a binary protobuffer file (either with extension .bin (older) or .data (newer)), and a xml file with meta-information, where databankVersion = "1.1". Only supports timeseries. Can be read by Gekko 1.5.8 and later.
1.2	(November 2018). The file extension is .gbk. Inside there is a binary protobuffer file (databank.data) and a xml file with meta-information (DatabankInfo.xml), where databankVersion = "1.2". It supports seven variable types: timeseries (including array-series), val, date, string, list, map, matrix. Can be read by Gekko 3.0 and later. The two older Gekko versions 2.5.1 and 2.5.2 can also read the 1.2 format.

If you need an old Gekko version (for instance Gekko 1.8, 2.2 or 2.4) to read a Gekko 3.x.x gbk databank, you can use Gekko 2.5.2 as a bridge. Write the databank in Gekko 3.x.x, read the databank in Gekko 2.5.2, write the databank in Gekko 2.5.2, and finally read the databank in the old Gekko version.

The option copylocal below copies the targeted file to a temporary file on the user's local hard disk before reading. This copying is typically very fast, and afterwards reading the temporary file is faster and more reliable, if the targeted file is located on a network drive. In general, this is a recommended option that alleviates some potential network problems.

The cache = nongbk option is set to skip gbk files. This is because the speed gains would be limited, because the internals of a .gbk file are essentially already a (protobuf) cache file. If the option is set to all, you may see a speed gain, because it is faster to calculate a MD5 hash code for a file than unzipping it.

The .gbk file may contain information regarding its corresponding model, last simulation period etc. If so, when READing the databank, a link to this model info is provided. This can be practical when in doubt about when the variables in a given databank were simulated, the simulation period, the model name and signature, etc.

To convert .tsd (or other formats) into a .gbk file, just read it with import<tsd>;, and WRITE it. Please note that a .tsd file operates with 8 significant digits (or less), so there will typically be a loss of precision compared to a .gbk file (which is in double-precision).

See the Gekko menu 'Options' --> 'Program dependency tracking' or use option global dependency tracking = ...; to activate dependency tracking, so that the use of external files (for instance program files, read/written databanks etc.) are shown as a list at the end of a Gekko session.

Related options

OPTION databank create auto = no; [yes|no]

OPTION databank create message = yes; [yes|no]

OPTION databank file cache = nongbk; [all|nongbk|none]

OPTION databank file copylocal = yes;

OPTION folder bank = [empty];

OPTION folder bank1 = [empty];

OPTION folder bank2 = [empty];

OPTION solve data create auto = yes; [yes|no]

Related statements

IMPORT, EXPORT, WRITE, OPEN, CLONE, DOWNLOAD