Basic concepts

<< Click to Display Table of Contents >>

Navigation:  Gekko 3.0 user manual >

Basic concepts

Previous pageReturn to chapter overviewNext page

This document describes some of the basic concepts used in Gekko.

 


 

Timeseries-oriented

 

Among other things, Gekko handles timeseries (often just called 'series' in this documentation). Gekko is a timeseries-oriented software system, that is, it has easy handling of timeseries as one of its main objectives. Because of this orientation, it is often not necessary to indicate a time period when dealing with timeseries variables, because the time dimension is implicitly understood. Gekko can operate on different frequencies, at the moment annual ('a'), quarterly ('q'), monthly ('m') or undated ('u'). IMPORT can handle (collapse) higher frequencies than months, if needed.

 

Gekko handles other kinds of variable types, too, as described in the next section.

 


 

Databanks

 

Databanks are in-memory storage of variables types series, value, date, string, list, map, and matrix. The names of values, dates and strings (scalars) always start with the % symbol, whereas the names of lists, maps and matrices (collections) always start with the # symbol. Databanks are opened in succession, where the first-position databank has number 1 on the databank list (cf. the F2 window: click F2).

 

Gekko can READ/WRITE such databanks as external files (.gbk extension), or IMPORT/EXPORT data from/to other file formats. Gekko always starts out with four empty databanks (in memory): 'Work' (first-position bank), 'Ref' (reference bank), 'Local' (local variables), and 'Global' (global variables). At startup, the Work databank has the number 1 in the list of open databanks, with the Ref (reference) databank shown just below. In addition, more databanks with different names (so-called 'named' databanks) can be opened (OPEN), but note that the first-position and reference databanks have special capabilities regarding printing/plotting/comparing etc. The local and global databanks are used to store and access temporary variables (local), or store settings etc. (global). See the LOCAL and GLOBAL commands for more on this. See the F2 window regarding the list of open databanks (note that reference, local and global databanks are only shown in that window when they contains data).

 

You may open other databanks as first-position databank with OPEN<first>/OPEN<edit>. You may use CLOSE to close a databank (and possibly write it to file, if it is altered).

 

If you need to import data into an existing (opened) databank, you may use IMPORT for non-Gekko data, or READ for Gekko databanks. For instance, "IMPORT <xlsx> data.xlsx;" imports Excel-data into the first-position databank, but you could alternatively use "IMPORT<ref xlsx> data.xlsx;" to import the data into the reference databank. For simulation purposes, the READ command is often practical. You may use WRITE to write the first-position databank to file.

 

As mentioned, in the F2 window, the first-position databank has number 1, whereas other 'named' databanks have numbers 2, 3, etc. If the local databanks contains data, it will show up in the list above the first-position databank, and if the global databank has data, it will show up last in the databank list. When issuing a command like PRT x; or = 2 * x;, the way Gekko looks for x depends upon databank search options. In sim-mode, Gekko will only look for x in the first-position and local/global databank, whereas in data- and mixed mode, Gekko will look for x first in the local databank (first bank in the databank list), then in the first-position databank (number 1 in the databank list), then in other open databanks (numbers 2, 3, ... etc. in the databank list), and finally in the global databank (last bank in the databank list). Note here that the reference databank is never searched for bankless variables, since this databank is only used for comparison purposes, cf. MULPRT, PLOT<m>, COMPARE, and similar commands. You may refer to a variable in the reference databank with ref:x or the shorter @x;

 


 

Series

 

A timeseries (or just: series) can can have frequency annual, quarterly, monthly, or undated, and it may contain any number of observations. If data has been read for timeseries x regarding the period 2010-2015, printing out x for the period 2016 will show a missing value ('M'). Series can be lagged and leaded, for instance x[-1] or x[+1] in the sense that x corresponds to x(t) , x[-1] corresponds to x(t1), and x[+1] corresponds to x(t+1).  Note that lags must start with the symbol -, and leads with +. Individual observations can be picked out with for instance x[2020], or x[2020q3], the latter being the third quarter of 2020, if x is a quarterly series. If you need accumulating lags like = x[-1] + 1, consider using <dyn> = x[-1] + 1, or a BLOCK with series dynamic = yes.

 


 
Array-series

An array-series is a special kind of multidimensional timeseries, where indexing with for instance x[a] or y[b, c] is possible. You may use x['a'] or y['b', 'c'] as synonyms in that case, and array-series are practical for many purposes, instead of for instance using naming conventions like xa or ybc. In general, you can perform the same operations with the array-series x[a] as you would be able to do with a normal timeseries. Array-series must be defined before they are used, for instance = series(1); y = series(2); to state the dimensionality.

 


 
Scalars

Gekko scalars are the types value, date or string. Scalars names must begin with the symbol %. Scalars can be thought of as containing just one element: the single value, the single date, or the single string. Values are numeric values like 1.2 or 2e8, dates are for instance 2020 or 2020q3, and strings use single quotes like 'dk'.

 


 

Collections

Gekko collections are of the type list, map or matrix. Collection names must begin with the symbol #. Collections can be thought of as a number of elements bundled together inside the collection. List stores variables in a sequence (by numbers 1, 2, etc.), map stores variables by name (like 'dkk', 'eur', 'usd'), and matrices are 2-dimensional structures of numeric values, also ordered by numbers 1, 2, etc. So for a list, #x[2] refers to the second element. For a map, #x['dkk'] refers to the element that has this name, and for a matrix, #x[2, 1] refers to the numeric value stored in row 2, column 1. It should be mentioned that it is possible to write #x['dkk'] as #x[dkk] or #x.dkk, too.

 

Lists and maps can store any other variable types as elements, whereas matrices only store values (for the time being).

 


 

Banks, maps, and array-series

Note for advanced users: all these three datastructures look up elements by means of names (also called look-up keys). For instance, b2:x looks up x in bank b2, #m['x'] looks up x in the map #m, whereas y['a', 'x'] looks up ('a', 'x') in the two-dimensional array-series y. Inside Gekko, banks and maps are built in the same way, whereas array-series are a bit differrent in that they (a) only store series inside, and (b) allow several dimensions of look-up keys. But maps and array-series are in reality not that different, it is mostly a question of syntax. For instance, y['a', 'x'] could be emulated with the map call #y['#a']['x'], where #y is a map, #a is another map stored inside #y, and x is a normal series stored inside #a. But the array-series notation is more convenient, and array-series have special capabilities regarding summing, printing, etc.

 


 

Strings as name references

Scalar strings (or a list of strings) may refer to other variables. Consider the string %= 'b2:x!m';. If you state PRT %s;, Gekko will just print out the raw string. But if you use PRT {%s};, Gekko will instead print out the monthly series x from the b2 databank (in a sense performing a forwarding operation, forwarding from the variable %s to the variable b2:x!m). Therefore, the curly {}-braces are handy regarding name composition. Also, if %= 'b', and %= 'd', the variable a{%i}c{%j}e is equal to abcde, and in general one should read the curly braces {} as if they are simply a sequence of unknown characters that are glued to other characters (or other {}-braces). See more on strings, or see the syntax diagrams.

A list of strings may function in the same way. Consider the list #= ('b2:x!m', 'y');. If you state PRT #m;, raw strings are printed out, whereas PRT {#m}; will print out the variables corresponding to the strings (monthly series x from the b2 databank, and the series y, and again performing a forwarding operation). In general, list definitions are enclosed in parentheses, like #= ('a', 'b', 'c');, but for simple strings, the equivalent 'naked' list #= a, b, c; is legal. In the latter case (naked list), it should be emphasized that the list elements are still three strings 'a', 'b', 'c', not the variables themselves. If you need to put three series a, b, and c into a list, you should use #= (a, b, c);. So defining a list while omitting parentheses on the right-hand side always produces a list of strings.

Sometimes the user may be in doubt whether he or she should use a normal string %s, or a name-reference {%s}? In such cases, the "abc test" may be performed. Would it be natural to use a quoted string like 'abc' in the command, or would it be natural to use a name like abc instead? If the former is the case, use %s;if the latter is the case, use {%s}.


 
Wildcards

In general, wildcards are stated with the ['...'] or {'...'} patterns, depending upon the context. For instance, you can use #= ['a*x'] to obtain a list of strings of variables starting with 'a' and ending with 'x' (from the first-position databank, with the current frequency). If you need to for instance print out the variables in this list, PRT ['a*x'] will just print out the raw strings corresponding to the matched wildcard. Instead, PRT {'a*x'} should be used to print out the variables themselves. Ranges can be stated as for instance 'pxa..pxe', or 'bank:pxa..bank:pxe'.

In INDEX, COPY, RENAME, DISP and similar commands, you can omit the curlies and single quotes, for instance INDEX a*x; (a*b will not be interpreted as a mathematical product in that command). You can also use '?' to select a single character, and wildcards can also be used to search for banks, frequencies, and indexes. See the INDEX and COPY command for more on this.

Much more on wildcards on the wildcards page.


 

Analysis

 

In sim-mode, the reference databank is typically used for multiplier analysis (i.e., experiments). Say you read a databank and then perform some experiment. This experiment will only alter timeseries in the first-position databank, so after the experiment is finished, you can compare the timeseries in the first-position and reference databanks (Gekko has a lot of commands to do such comparisons, for instance MULPRT, DECOMP etc.). If, at some point, you wish to make sure that the first-position and reference databanks are identical (for instance after a simulation), you can use the CLONE command. This command clears the reference databank, and copies the first-position databank into it (in memory). You may alternatively read a file directly into the reference databank by means of READ<ref>. There is a cleanup-command: RESTART. This command clears the first-position and reference databanks, in addition to clearing models, variables, user functions, procedures, and other things. The operation provides a clean state of Gekko, as if it had been closed and reopened (if there is a file with the name 'gekko.ini' in the program and/or working folder, this file will be re-read, so gekko.ini can be used to contain options and other commands, for instance MODEL and READ commands, that the user wishes to "survive" a RESTART). If you wish a clean state without any potential gekko.ini file, use RESET.


 
Creation

 

In sim-mode you have to CREATE a series before you update its values/observations with the SERIES commands (unless the timeseries starts with the letters 'xx', indicating that it is to be thought of as a temporary variable). However, it should be noted that when a databank is read (READ), after a model has been loaded previously (MODEL), any model variables not present in the databank will be auto-created as timeseries (with all observations set to missing values). Because of this, it may often be convenient to put MODEL statements before READ statements. In data- and mixed mode, timeseries are auto-created with the SERIES command.


 

Periods

 

Note that commands involving series variables can include a local time period, like for instance PRT <2010 2020> x, y;. The local time period will overrule the global time period, which can only be set via the TIME command. In assignments, the time period may be stated before or after the left-hand side variable, so both <2020 2030> x = 100; and <2020 2030> = 100; are legal.

 

There are some details regarding periods. Most commands that involve timeseries use the global time period if no local time period is stated, for instance commands like PRT, IMPORT, EXPORT, etc. For some of these commands, you may use local option <all> to use all existing data points (observations). You cannot combine <all> with a local time period.

 

But for the commands COPY, READ and WRITE, omitting a local time period does not entail the use of the global time period. These commands will use all existing data points (observations) for all series, if no local time period is stated. If a local time period is stated, only the local sample is used, and if you need to observe the global time period, you can use the <respect> option. You cannot combine <respect> with a local time period.

 

For some commands, you may use a time period with another frequency than the series object used. In that case, Gekko will try to convert the frequency meaningfully. For instance, PRT <2010q2 2010q3> x!q, x!m; will just use 2010q2-q3 for the quarterly series x!q, whereas 2010q2-q3 is converted to 2010m4-m9 for the monthly series x!m (covering from the start of q2 to the end of q3).

 

If you need to change the time period temporarily, you may use the BLOCK structure. Also, user defined functions and procedures may use a <>-field to indicate time period arguments.

 


 
Operators

 

The so-called operators are used in many places, in order to perform easy transformations (for instance percentage growth rate, or multiplier difference between first-position and reference databank values). The operators come in two versions: 'long' and 'short'. The 'long' ones are used in the PRT and MULPRT commands (for instance PRT<abs> var1; to only print the absolute level, and not percentage growth), whereas the 'short' ones can be applied more generally (for instance PLOT<p> var1; to graph the growth rate of var1). The most important of the 'long' ones are dif and pch, and the most important of the 'short' ones are d, p, m, q. The functionality of the 'long' and 'short' operators overlap: see PRT for more details. The short operators will also show up in TABLEs and the DECOMP window, and can also be used in SERIES, PLOT and SHEET.

 


 

Models

 

Regarding models, it should also be noted that the list of endogenous variables in a model is simply the set of all the variables at the left-hand side of the equations. This may be changed afterwards by means of the ENDO and EXO commands. Regarding equation syntax, you may consult the latter part of the MODEL help file, if you need more information on this. (Models are cached in binary form on the user's hard disk in order to load faster next time).

 


 

Files

 

Regarding file names, you may use relative paths like '\subfolder\data.txt'. Using relative paths makes it easier to move a system of command files to another location/computer if needed. Special user-paths can also be given by means of the OPTION folder ... settings. If the path or filename contains blanks or special characters, you may enclose it in single quotes.

 


 

No blanks

 

Generally, sequences of elements are delimited by commas, not blanks. Gekko 3.0 has a number of capabilities regarding the transformation of such lists, for instance setting or removing commas instead of blanks, setting or removing quotes, etc. See the Gekko main window, under Edit --> Paste as.... [not done yet].


 

Command files/batch job

 

Gekko commands can either be run directly from the Gekko main window, or assembled in a command file (script file) for later execution. Command files can be run with the RUN command. This is also called a batch job (also possible by means of calling gekko.exe with parameters, see more in the RUN help file). You may track the execution of jobs via 'Utilities' --> 'Run status...' in the Gekko menu (or double-click on the traffic light in the lower right corner of Gekko).

Gekko also provides user-defined functions and procedures to deal with repetitive tasks.