<< Click to Display Table of Contents >> Navigation:  Gekko User Manual > Gekko statements > LIST

A Gekko list contains sequentially ordered variables (elements) of any type. List names always start with the symbol #, like the other collection types map and matrix. You may refer to list elements by means of indexes, for instance #m[1] for the first element of #m. Listfiles can be used, using for instance #(listfile m) instead of #m, where the list elements are stored in the external file m.lst instead of in a databank.

 

 

A general list is defined with parentheses and commas, for instance #m = ('a', 120, 2020q3);. In that case, the list contains a string, a value, and a date. In the special case where all the list elements are simple alphanumeric words (including '_') without special characters, you may use for instance #m = a, a38, 7z, 5, 007, 2001q1; instead of the more cumbersome #m = ('a', 'a38', '7z', '5', '007', '2001q1');. The 'naked' version without parentheses and quotes is practical for lists of names etc. If all the list elements are values, like #m = 1, 2, 3;, a list of values is produced instead of a list of strings (among other things, this is practical regarding the series statement, for instance y = 1, 2, 3;). A naked list either returns a list of strings or a list of values, cf. the page on naked lists.

 

You may may use the operators += and -= to add or subtract elements from a list (this works for naked lists, too: #m = a, b; #m += c, d; #m -= c, d;). If you need to use a naked list with one element, use a trailing comma, for instance #m = a,;. This way, you can easily add or remove a single element like this: #m = a, b; #m += c,; #m -= c,;. Single-item lists (so-called singletons) can alternatively be stated as #m = list('a') or #m = ('a',). Using #m = a or #m = ('a') will fail with an error, since Gekko understands this as setting a list equal to a series or a string. An empty list can be created with #m = list().

 

The first element of a list #m is #m[1], and the last element is #m[#m.length()]. Slices/sublists can be cut out by means of ranges, for instance #m[2..5]. Non-naked lists may contain any other variable types, including lists, so #m = (1, (2, 3)); is a nested/reursive list, where #m[2][1] would refer to 2 (because #m[2] refers to the sublist (2, 3)).

 

---

 

Syntax

 

#name = ( expr1 REP n1 , expr2 REP n2, ... ); //REP repeats the item
#name = name, name, ... ;                     //short form for 2 or more string variables
#(listfile m1) = #(listfile m2);             //use of listfiles m1.lst and m2.lst (for lists of scalars, or nested lists of scalars)
#name = list(...);                           //useful for singleton lists or empty lists like #m = list('a') or #m = list().
list #name = ...;                             //list keyword may be added, but is typically not necessary.
list ?;                                       //show/count lists in open databanks

 

It is no longer legal to use for instance list m = ... ;, omitting the # on the left-hand side.

 

Referring:

 

{#m}               //use braces {...} to use strings as variable names.

 

 

 

The LIST keyword is optional and can typically be omitted. Use rep to repeat items. For the last item, when defining or calculating timeseries, you may use rep *. You may use a list definition with parentheses (strict version) everywhere a variable or expression is expected.

 

There are quite a lot of functions to deal with string lists, for instance sort() to sort elements, unique() to remove dublets, prefix()/suffix() to add prefixes/suffixes to elements, etc. You can also use the union(), except(), and intersect() functions for lists of strings, or equivalently via operators ||, -, and &&. Please see the examples below, and the functions section. Regarding string lists of variable names, there are a lot of functions to handle banks, frequencies, indexes, etc., cf. the functions section, under 'Bank/name/frequency/index manipulations'.

 

A listname always starts with the symbol '#', like the other collection types map and matrix. If you prefer to refer to a list item by name instead of numbers/indexes, see the MAP collection. In that case, you could use for instance #m['nairu'] or #m.nairu rather than for instance #m[1] to refer to a particular named object in the collection (this makes the programs easier to read).

 

String lists with variable names, optionally including banks, frequencies, indexes, etc. are often used, and to refer to the variables themselves, {}-curlies must be used. For instance: #m = ('x', 'b2:y!m[a, u]', '%z'); contains the strings corresponding to x (series x without bank indication, and with default frequency), monthly array series y from bank b2 with indexes [a, u], and finally a scalar %z. If you want to refer to the variables corresponding to these strings, use {}-curlies, for instance PRINT {#m};. This is the same as PRINT x, b2:y!m[a, u], %z;.

 

Lists of values are often used, for instance to define series. A list of values could be #m = 1, 2, 3;, omitting the parentheses. If you need to use the sequential data in linear algebra, instead of #m = 1, 2, 3; or #m = (1, 2, 3); you may use a row or column vector instead, for instance #m = [1, 2, 3]; or #m = [1; 2; 3];. The latter column vector is a bit more similar to the list in the sense that #m[1], #m[2] is allowed regarding column vectors, where row vectors would have to use #m[1, 1], #m[1, 2], etc. If a list of values is given as mathematical expressions, you must use enclosing parentheses, for instance #m = (1/7, 2 + %v, 3*%v);.

 

All Gekko functions implement so-called UFCS so that a function like for instance extend(#x, #y) can generally be written as #x.extend(#y). This makes chaining of such function calls more readable, for instance #m = #m1.extend(#m2).except(#m3).

 

 

 

 

List functions:

 

Note that some of the functions assume that the lists are lists of strings. This will be fixed regarding values and dates.

 

 

 

A string (or list of strings) representing variable names may be manipulated by means of Gekko's inbuilt functions to handle these. Variable names here include bank, frequency, indexes, etc., and examples of such functions could be setBank(), removeBank(), replaceBank(), setFreq(), removeFreq(), setNamePrefix(), etc. There are many more of such functions, see the functions section, under ‘Bank/name/frequency/index manipulations’.

 

For instance, if you have a list #m = ('x', 'y');, you may use prt {#m}; to print out x and y, prt {#m.setBank('b')}; to print out b:x and b:y, or prt {#m.setFreq('q')}; to print out x!q and y!q (here, prt b:{#m}; and prt {#m}!q; will work, too).

 

 

---

 

Examples

 

Define a list:

 

 

If instead of for instance d, e, etc. above you need to use strings like %s1 or %s2, you may use for instance #m += {%s1}, {%s2}; or #m += {%s},;.

 

As shown, for naked lists you may use indexes to state array-series, for instance x[#i] is unfolded into x[a], x[b], x[c], if #i = a, b, c. In the last list, #m[1] refers to the list ('a', 'b'), #m[2] refers to the list (1, 3), and for instance #m[1][2] refers to 'b'. To print a list, simply use prt #m;. If the list is a list of strings, and you want to print the variables corresponding to the strings, use {}-curlies:

 

 

There are two functions to add items to a list: append() and extend():

 

 

Gekko functions implement so-called UFCS, so the function append(#m1, #m2) may alternatively be written #m1.append(#m2), moving the first argument of the original function out of the parentheses. This provides a more fluent interface, and enables easy chaining of list functions (see examples below). As it is seen, append() puts the list #m at position 4 in #m1, whereas extend() unpacks #m2 and puts the two elements at positions 4 and 5 in #m1. Therefore, if you need to add a single value to a list, use append(), but if you need to add the elements of a list to another list, use extend():

 

   

Instead of #m1.extend(#m2), the + operator can be used instead of extend() when dealing with two lists:

 

 

It should be noted that #m1 + %s does not append %s to the list (but will fail with an error). Use #m1.append(%s) or #m1 + list(%s) instead. In earlier Gekko versions, the expression #m1 + %s appended %s to each element of #m1, but this behavior is deprecated.

 

Lists in Gekko may contain dublets. Still, set operations are possible with the functions union(), except() and intersect():

 

 

It is noted that union() avoids introducing dublets in the list, which is not the case regarding extend() and the + operator. Instead of these functions, you may use operators ||, - and &&:

 

 

If the list #x1 contains none of the #x2 elements, the expression #x1 + #x2 - #x2 will be = #x1. However, Gekko lists may contain dublets, and you can use the unique() function to remove these, and the sort() function for sorting. For instance:

 

 

The above example also illustrates function chaining. The expression #m1.extend(#m2).unique().sort() is easier to understand than the equivalent but more backwards expression sort(unique(extend(#m1, #m2)).

 

To check if a list contains an item, use contains() or index():

 

 

You may replace elements in a list, for instance:

 

 

The last function, replaceinside(), replaces text inside the individual elements.

 

List elements may be of mixed types, for instance (1, 'two', 2003q3), and lists of values are often used to feed values into timeseries:

 

                                   

You can use rep to repeat values, and rep *  is special when used to define a series, since it repeats the last item to make the list fit with the sample (here: 7 observations). If you have input data with (a lot of) blank-separated values, you may use the data() function instead of manually setting the commas:

 

                                   

Lists can be looped, for instance:

 

 

Lists can be nested, for instance an #alias list (cf. OPTION interface alias):

 

 

An #alias list can among other things be convenient as a bridge between the naming conventions of two different models.

 

Listfiles

 

Instead of storing lists in a databank, you may optionally use an external file instead. Using a listfile animals.lst (you may use edit animals.lst; to do this):

 

 

You can use the listfile in the following way:

 

 

Listfiles may contain strings or values, and for simple strings starting with a letter, you may omit single quotes. If you need to make sure that an element is interpreted as a string and not as a value, you can enclose the string in single quotes.

 

When Gekko reads an element, if it is enclosed in quotes, it always becomes a string. Otherwise, the interpretation rules are the same as for naked lists. When writing elements, if all elements are simple strings starting with a letter, Gekko will omit the quotes. Else it will write strings with single quotes, and dates are written as strings, too. To convert a list of strings into a list of dates, just use the dates() function. Like normal lists, listfiles may contain elements beginning with '-',for instance:

 

 

But you cannot put complicated items like expressions into a listfile (use a normal list for that). You can create a listfile m.lst with #(listfile m) = a, b, c;. Nested listfiles are possible: just separate the elements with the ';' symbol:

 

 

All these items are converted into strings, because they are not all values. You could create this file with #(listfile nested) = ('1', ('2', '3'), 'mouse', ('2010q1', '2010q3')). The last element can be followed by the ';' symbol, but it may also be omitted. The following list is similar to a matrix:

 

 

If #m = #(listfile matrix), for instance #m[2][1] = 3, corresponding to row 2, column 1. This is similar to the matrix #m = [1, 2; 3, 4], where #m[2, 1] = 3. In general, the listfile format corresponds to .csv, and the reason ',' is not used to delimit elements is that csv files may allow numbers to be stored with decimal separator ',' instead of '.'.

 

Instead of using a two-dimensional csv-like listfile like matrix.lst above, you may instead store such data in an Excel spreadsheet, and load them with sheet <import list> #m file = ... ;.

 

 

Searching

 

You may search a list of strings using wildcards, in order to return certain patterns of string elements.

 

 

As the last line shows, there are a lot of functions available, if you need to handle for instance banknames, frequency indicators, etc. on such lists of names. See under functions, bank/name/frequency/index manipulations. Note that if you need to for instance print the elements of #m1 with a particular bank and frequency, you may use either prt {#m1.addbank('b1').addfreq('q')};, or the easier prt b1:{#m1}!q;.

 

You may use a 'naked' wildcard to obtain variable names from open databanks, for instance:

 

 

The wildcards match variable names found in open databanks. Please keep in mind that the logic regarding such 'naked' wildcards is a bit different from searching inside a list of strings. A wildcard like ['a*d'] will look for series starting with 'a' and ending with 'd', but only in the current first-position databank, and only regarding variables with the same frequency as the current frequency. To get series names from all banks with all frequencies, starting with 'a' and ending with 'd', you would have to use ['*:a*d!*']. And to get, for instance variables starting with % (scalars), and then followed by 'a' and ending with 'd', you would have to use ['%a*d']. See more on the wildcards page and on INDEX section.

 

To print out results of wildcards searches, {}-curlies must be used, for instance:

 

 

As seen above, you must use {}-curlies to print out the variables corresponding to a wildcard search. And as shown, you do not have to use the pattern {['....']}, but can omit the innermost []-brackets and just use {'....'} to print wildcard variables.

 

 

---

 

Lists and array-series

 

As a last note, lists can be used to define domains for array-series. See the SERIES section, but the following example illustrates the use:

 

 

The result is the following:

 

 

 

So x[#i] prints out the three elements, sum(#i, x[#i]) sums them up, and sum(#i, x[#i] $ (#i in #i.remove('b'))) show the sum for the list #i except the element 'b'.

 

You may assign a domain to array-series dimensions with the setdomains() function, and you may restrict which elements are printed/plotted via a special #default map. See more in the SERIES section.

 

 

---

 

Note

 

See the page with syntax diagrams if the basics of names, expressions, etc. is confusing.

 

You can remove <direct> in list<direct> from older Gekko 2.0/2.2/2.4 code.

 

You can use minus (-) before a list item in a naked list. This can for instance be used in the Laspeyres chain index function laspchain(), to indicate a variable that is to be deducted. For instance:

 

 

The function returns a map #m containing the aggregated p and q series as named elements, where series x3 is to be deducted from the aggregation (and the price p is set to 1 in 2010). The resulting series and quantities can be accessed with #m.p and #m.q.

 

If you have input data with blank-separated values, you may use the data() function to avoid having to set the commas, for instance #m = data('1.0  2.0  1.5');. This function can be practical for long lists of numbers. Data from an Excel spreadsheet can be loaded into a nested list by means of sheet <import list>.

 

Note that an assignment like #m1 = #m2;, where #m2 is a list, #m1 will become a copy of #m2, not a reference to it. The same is the case regarding function arguments, where manipulating #m1 inside the function body of f(#m1) will not affect #m1 after the function has been left.

 

The lists #all (all model variables), #endo (all endogenous variables), and #exo (all exogenous variables) and some more are defined beforehand, if a model is loaded by the MODEL statement. These lists are located in the Global databank. See list ?;.

 

The reader may wonder why it is not possible to add a list #m and a scalar %s like this: #m + %s, appending %s to #m? This is tempting, but then what about %s1 + %s2 + #m + %s3? Should this mean a list with %s1, then %s2, then the elements of #m, and lastly %s3? But if %s1 and %s2 are two strings, these strings are added into another string. And if they are values, the values are added first. Hence, to avoid such confusion, using + between a list and a scalar is disallowed (which is also the case in Python and other languages).

 

Regarding variable types and the Gekko type system, see the VAR section. In this appendix, variable assignment rules, including variable types, is explained in more detail.

 

Beware that any rep * in a list definition will be ignored (rep * is designed for timeseries calculations).

 

A Gekko list relates to the following in different languages:

 

•Gekko: #m = ('x', 2.2);.

•R: list (holds different types of variables), m <- list("x", 2.2). A R vector is similar, but holds only variables of the same type, for instance m <- c("a","b","c"). Note that #m[%i] in Gekko returns the object at position %i, not a 1-element list containing the object, like R. Use #m[%i..%i] to get such a R-like slice. In this sense, #m[%i] in Gekko corresponds to m[[i]] in R.

•Python: list (holds different types of variables), m = ["x", 2.2]. Python has a built-in set type, with union(), intersection() and difference() methods. Note that for union(), Python uses operator | where Gekko uses ||, for intersection() Python uses operator & where Gekko uses &&, and for difference() both Python and Gekko use operator - (difference() is called except() in Gekko). Python sets do not allow dublets, but Python lists do not provide methods union(), intersection() and difference().

•Matlab: same type elements: array, else: cell array, m = {"x", 2.2}.

 

 

---

 

Related statements

 

MAP, MATRIX, FOR