Gekko User Manual > User manual introduction

The following describes some of the fundamentals of 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), weekly (w), daily (d) or undated (u). IMPORT can handle (collapse) higher frequencies than daily, if needed. Note that week numbering follows the ISO 8601 standard.

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 a hierarchical list of open databanks, where the first-position databank has number 1 (cf. the F2 window: press F2 to see the list of open databanks).

Gekko can READ/WRITE such databanks as external Gekko databank 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 start up, the Work databank has number 1 in the list of open databanks, with the Ref (reference) databank shown just below (non-numbered). 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 statements for more on this. Try to click F2 to see 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 has been altered).

If you need to import data into a 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 statement is often practical, but READ can be useful for data management, too. You may use WRITE to write the contents of the first-position databank to an external .gbk 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 databank 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 statement like prt x; or y = 2 * x;, the way Gekko looks for x depends upon databank search options. Per default, 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 variables without databank indication, since this databank is only used for comparison purposes, cf. MULPRT, PLOT<m>, COMPARE, and similar statements. You may refer to a variable in the reference databank with ref:x or the shorter @x. In general, you can use colon (:) to refer to a particular databank, for instance b1:x tries to find x in the b1 databank.

Timeseries variables

A timeseries (or just: series) can can have frequency annual, quarterly, monthly, weekly, daily, 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 if x corresponds to x(t) , x[-1] corresponds to x(t–1), and x[+1] corresponds to x(t+1). Note that lags must start with the symbol -, and leads with +, these may not be omitted. 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 = x[-1] + 1, consider using x <dyn> = x[-1] + 1, or a BLOCK with series dynamic = yes. Accumulating lags are explained in more depth here.

Timeseries names may be composed, for instance %i = 'a'; y = x{%i};, which is equivalent to y = xa;, where the string %i (with value 'a') is used to compose the series name (more on scalar strings and name composition under the following 'Scalars' and 'Strings as name references' sections).

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 x = 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'.

Regarding strings, beware that Gekko supports string interpolation, where Gekko replaces any {...} curlies inside a string with the result of evaluating the curlies. For instance, after %s1 = 'rise'; %s2 = 'sun{%s1}';, %s2 will be 'sunrise'. (This is analogous to variable name composition like y = sun{%s1};, which would be equivalent to y = sunrise;).

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. A list stores variables in a sequence (by numbers 1, 2, etc.), a 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 (a timeseries inside the map), 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: 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 the combination ('a', 'x') in the two-dimensional array-series y. In all three cases, a timeseries is returned. Inside Gekko, banks and maps are built in the same way, whereas array-series are a bit different in that they (a) only store series inside, and (b) allow several dimensions of look-up keys.

Strings as name references

As mentioned above, scalar strings (or a list of strings) may be used to refer to other variables. Consider the string %s = '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 (using the string %s as a reference to the variable b2:x!m). Therefore, the curly {}-braces are handy regarding name composition. Also, if %i = 'b', and %j = 'd', the variable a{%i}c{%j}e refers 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 be used in the same way. Consider the list of strings #m = ('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, again using the strings to refer to the variables). In general, list definitions are enclosed in parentheses, like #m = ('a', 'b', 'c');, but for simple strings, the equivalent 'naked' list #m = a, b, c; is legal, too. In the latter case (naked list), it should be emphasized that the list elements are still three strings 'a', 'b', 'c', not the variables (objects) themselves (that would be the case with #m = (a, b, c);).

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, consider whether the statement would accept a string like 'abc' or a name like abc. If the statement would accept the string 'abc', just use %s. If it would accept a name abc, use {%s}.

Wildcards

In general, wildcards are stated with the ['...'] or {'...'} patterns, depending upon the context. For instance, you can use #m = ['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 statements, you can omit the curlies and single quotes, for instance index a*x; instead of index {'a*x'}; (in the former case, a*b will not be interpreted as a mathematical product in that statement). 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 statement for more on this.

Much more on wildcards on the wildcards page.

Analysis

For modeling, 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 statements 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 statement. This statement 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 also a cleanup-statement: RESTART. This statement 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 statements, for instance MODEL and READ statements, that the user wishes to "survive" a RESTART). If you wish a clean state without any potential gekko.ini file, use RESET.

Periods

Note that statements 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 statement.

There are some details regarding periods. Most statements that involve timeseries use the global time period if no local time period is stated, for instance statements like PRT, IMPORT, EXPORT, etc. For some of these statements, 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 statements COPY, READ and WRITE, omitting a local time period does not entail the use of the global time period. These statements 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 statements, 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). For instance plot<p> var1; to plot the growth rate of var1: other oft-used operators are d (time differences), p (growth rate), m (absolute multiplier difference), q (relative multiplier difference). The 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 statements. Regarding equation syntax, you may consult the latter part of the MODEL help file, if you need more information on this.

Files

Regarding file names, you may use relative paths like \subfolder\data.txt. Using relative paths makes it easier to move a system of Gekko program 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.

Gekko program files/batch jobs

Gekko programs can either be run directly from the Gekko main window, or assembled in a program file (script file) for later execution. Gekko program files can be run with the RUN statement. 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 the menu 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.

Basic concepts

Basic concepts