Appendix > Indexing

Indexing means the use of []-brackets to index a variable, like for instance x[a] (the 'a' element of the array-series x). In some cases dot notation is possible too: for instance, #m.a can be used as synonym for the map element #m['a'], and x.1 can be used as synonym for the lag x[-1]. Gekko has 7 variable types, and in the following it will be shown how indexing can be used for each of these types.

Auto-quoting

Regarding indexing in Gekko, beware that using a simple non-quoted variable name inside []-brackets is always interpreted as if it was quoted. For instance, x[a] is interpreted as x['a'], and hence some typing of '-quotes can be omitted. This convenience only applies if the contents of the []-bracket is 1 simple variable name (for instance abc, _xy, px45 and the like). The name cannot contain other symbols than alphanumeric or underscore if it is to be auto-quoted (and it cannot start with a digit).

Value

A value like %v = 123; cannot be indexed.

Date

A date like %d = 2023q3; cannot be indexed.

String

A string like %s = 'abc'; can be indexed, but only with integers and ranges ...

%s = 'abc';
prt %s[2]; //'b'
prt %s[2..3]; //'bc'
prt %s[2..]; //'bc'

Such indexing picks out an element or a range of elements, see more here. If you try to use a non-integer index, Gekko will issue an error. For instance, %s[b] or %s['b'] will fail. To find substrings inside a string, you can use the index() function.

Series

For a normal series x, you can use indexing to pick out a particular observation value, like for instance x[2023q3]. In addition, you can use lags or leads, like x[-1] or x[+1]. Note that for lags or leads, a - or + must always be the first character of the index. To lag a normal series, you may alternatively use dot-notation x.1 instead of x[-1].

For an array-series x, you can use notation like x[a] or x['a'] (if x is 1-dimensional) to pick out the subseries 'a' inside x. You may also use lists of strings as indexes, for instance:

x = series(1); //1-dimensional
x[a] = 2; x[b] = 3; x[c] = 4;
#m = a, c;
prt x[#m]; //prints out x[a] and x[c]
x[#m] = 5; //changes values of x[a] and x[c]

For an array-series x, you cannot (at the moment at least) use for instance dot notation x.a as synonym for x['a']. This is to avoid confusion.

For an array-series x, you cannot use for instance x['a*'] to search for subseries.

List

Lists can be indexed in different ways. You may use integers and ranges .. to select sub-lists. For instance #m[2] to get element #2, #m[2..3] or #m[2..] to get a range of elements. For multidimensional nested lists (lists inside lists), there are some special Python-inspired rules regarding such 'slices', cf. the descriptions here.

On a list of strings, if you use a string as index, you essentially ask if the list contains the string (case-insensitive), and Gekko returns 0 (false) or 1 (true). Or you can use a wildcard or range, in which case Gekko returns a list of hits. Examples:

#m = ax, ay, bz, aw2; //four strings
prt #m['az'], #m['bz']; //0 and 1
prt #m['a*']; //returns the list ax, ay, aw2
prt #m['a?']; //returns the list ax, ay
prt #m['aw'..'ax']; //returns the list ax, aw2

Matrix

Matrices can only contain values, and you may use integers and ranges .. to select sub-matrices.

#m = [1, 2, 3; 4, 5, 6; 7, 8, 9]; //3x3 matrix
prt #m[2, 3]; //6
prt #m[2..3, 1..2]; //[4, 5; 7, 8]
prt #m[2.., ..]; //[4, 5, 6; 7, 8, 9]

Map

Maps can be thought of as mini-databanks. To pick out a series a from a map #m, you can use #m['a'], or the shorter dot-notation #m.a. Examples:

#m = (a = 100, %d = 2023q3); //a map with a series and a date inside
prt #m['a'], #m.a; //prints out the series a inside #m (note: #m[a] can be used for series)
prt #m['%d'], #m.%d; //prints out the date %d inside #m (note: #m[%d] will fail)

At the moment, no other form of indexing is possible for maps. If a databank m contains the series a, it can be referenced by means of the colon syntax m:a, and the dot syntax #m.a for maps can be thought of as being analogous to the colon.

It is planned to offer wildcard and range searching for maps, for instance #m['a*'], but this has not been implemented yet. For such wildcards, the same logic as databank search will be used (special handling of %, # and ! characters).