The READ statement puts variables from a .gbk file (or other formats) into the first-position databank (use OPEN if you need to open a 'named' databank instead). A .gbk file is a Gekko-specific binary databank format that stores Gekko variables. A READ clears first-position databank before reading the .gbk file, so after reading, the first-position databank will correspond to the .gbk file (this behavior may be altered with the <merge> option). After reading (optionally merging) data from the .gbk file into the first-position databank, the Ref (reference) databank is always constructed as an exact copy of the first-position databank (corresponding to the CLONE statement). Regarding timeseries inside the .gbk file, READ reads all data observations regardless of the global time period.

READ is intended for .gbk files, but can also be used for other data files like for instance .csv or .xlsx (see more under IMPORT) and READ can in that sense be thought of as an enhanced version of IMPORT. Between the close cousins READ and IMPORT, there are the following equivalences: read ...; = clear<first>; import<all>...; clone;, and the inverse: import ...; = read<first merge respect>...;. READ is quite often used for non-gbk files too, for instance read <gdx>, because READ clears the first-position databank and does not restrict the data period.

Because READ clears the first-position databank, it may often be practical to store variables in the Global databank when READ is being used. 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 .frm model 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).

Because Gekko uses a so-called cache for databank files, the same databank 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 Ref (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. When using <merge>, and the data contains missing values, beware that such values are only transferred to Gekko if they exist in-between 'real' values, so if you import a (part of a) series with values M, 1, M, 2, M, only the middle missing value is transferred.
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 first-position and Ref databanks. For instance, after read bank1 to b;, you may refer to the variables by means of colon, for instance prt b:var1;. If you use read bank1 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).

Note: READ actually accepts all IMPORT options, too.

Examples

Reading a Gekko databank file data.gbk is done with

read data;

or by writing

read *;

and then selecting the databank. If you wish to merge with the existing first-position databank, use <merge> like this:

read <merge> data;

This merges data.gbk with any pre-existing data. Full or relative path names are possible:

read otherbanks\data;

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

Notes

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 (or other formats like .gdx, .xlsx, etc.) is read into the first-position databank regardless of how the timeperiod is set in Gekko. (Use read <respect> to restrict the read data to the global time period).

The .gbk format is currently 1.2 (corresponding to Gekko 3.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 2.x (< 2.5.1) to read a Gekko 3.x .gbk databank, you may use Gekko 2.5.2 as a bridge. Write the databank in Gekko 3.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 databank file copylocal is yes per default and copies the targeted file to a temporary file on the user's local hard disk before importing. This copying is typically very fast, and afterwards reading the temporary file is faster and more reliable, if the targeted file is for instance located on a network drive. In general, this is a recommended option that alleviates some potential network problems.

The option databank file cache = nongbk is recommended, too. It does the following: (a) it finds the data file, (b) it optionally copies it to the user's local hard disk, and (c) it calculates a MD5 hash code from the file. If this hash code is already known, Gekko uses a cache file representing the databank data, which in most cases is much faster to read (it is in protobuf format: the same format that is used for .gbk files). So there is a small speed penalty for calculating the hash, and a large speed gain for using the protobuf/cache file.

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.

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 file cache = all;
option databank file copylocal = yes;
option databank file gbk compress = yes;
option databank file gbk internal = databank.data;

option databank file gbk underscore = no;
option databank trace = yes;
option databank trace divide = no;
option databank trace dublets = no;
option folder bank = '';
option folder bank1 = '';
option folder bank2 = '';
option gams exe folder = '';
option gams fast = yes;
option gams time detect auto = no;
option gams time freq = a;
option gams time offset = 0.0;
option gams time prefix = '';
option gams time set = t;
option gams trim = 0;
option interface csv decimalseparator = period;
option interface csv delimiter = semicolon;
option interface csv ignoremissing = no;
option interface csv ndec = 100;
option interface excel ignoremissing = no;
option interface excel language = danish;
option interface excel modernlook = yes;
option interface prn decimalseparator = period;
option interface prn delimiter = blank;
option interface prn ndec = 100;
option sheet engine = internal;

Related statements

CLONE, COPY, DOWNLOAD, EXPORT, GLOBAL, OPEN, READ, WRITE