READ

<< Click to Display Table of Contents >>

Navigation:  Gekko commands >

READ

Previous pageReturn to chapter overviewNext page

The READ command 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 commands, and are in that sense long-lived.

 

It should be noted that if a model has been loaded, the READ command will auto-create any model variables not present in the .gbk file (and fill these variables with missing values). Because of this, in command files it may often be convenient to put the MODEL statement before the READ statement.

 

READ is intended for .gbk files, and can be thought of as a strong 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>.

 

 


 

Syntax

 

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

 

filename

Filenames may be contain an absolute path like c:\projects\gekko\myfile, a relative path like \gekko\myfile.gbk, or be stated without a path. Filenames containing blanks and special characters should be put inside quotes. 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 command)

 

 

 


 

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 command.

 

 

 


 

Note

 

When reading, extension .gbk is automatically added if it is missing. Global time settings do not affect the READ command, so all the data in the .gbk file 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).

 

Annual, quarterly, monthly 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) 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 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 .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).

 

 


 

Related options

 

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

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

OPTION databank file copylocal = yes;

OPTION databank file gbk version = 1.1; [1.0|1.1]

OPTION folder bank = [empty];

OPTION folder bank1 = [empty];

OPTION folder bank2 = [empty];

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

 

 


 

Related commands

 

IMPORT, EXPORT, WRITE, OPEN, CLONE, DOWNLOAD