The INDEX statement is used to search for variables in databanks, using wildcards or ranges (the result of the search may be put into a list). When indexing timeseries, remember that default INDEX only finds series of the currently active frequency from the first-position databank. You may use : and ! to broaden the search, for instance index *:*!*; to find all timeseries of all frequencies from all databanks.

Note that 'naked' wildcards are allowed in this statement, so you may for instance use a*b?c as wildcard instead of the more cumbersome {'a*b?c'}.

If one or more of the databanks contains many variables, this output may become voluminous. Use INDEX<mute> or COUNT if you prefer to avoid the output. Wildcard logic, including double and triple stars etc. (index **; or index ***;), is explained more generally on the wildcards page.

The INDEX statement works for array-subseries too, for instance index x[a*b?c]; to get the matching subseries of the 1-dimensional array-series x. Multidimensional indexing follows the same logic, for instance index y[b*,*z]; regarding the 2-dimensional array-series y. To match all subseries regardless of the number of dimensions, you may use double stars: index y[**];.

For convenient searching/suggestions of variable names you may use the keyboard keys [Tab] or [Ctrl+Space] to get autocompletion on timeseries names (cf. here). For instance you may type prt a*b?c and hit [Tab] or [Ctrl+Space] to select from a list of matching series names.

Syntax

index <MUTE BANK=... SHOWBANK=... SHOWFREQ=... > type wildcards TO listname ;

MUTE	(Optional). If set, Gekko will not print the list of found items on the screen. The COUNT statement is essentially an INDEX<mute>.
BANK=	(Optional). A databank name indicating where the variables are to be located.
SHOWBANK=	(yes\|no\|all), default = yes. If this option is no, banknames are not included in the items. If the option is all, banknames are always included in the items. If the option is yes (default), banknames are included in the items, except if the bankname is the same as the first-position databank.
SHOWFREQ=	(yes\|no\|all), default = yes. If this option is no, frequencies are not included in the items. If the option is all, frequencies are always included in the items. If the option is yes (default), frequencies are included in the items, except if the frequency is the same as the current frequency.
type	(Optional). Restrict the type of variables.
wildcard	The variables to be searched for. You may use banknames to indicate a particular bank, and you may separate the wildcards with commas. In general, wildcards are of the form ax to find all variables starting with a and ending with x, or a?x to match exactly one character between a and x. You may use syntax like x[a,*b] for array-series.
listname	(Optional). The list name where the result is stored. The listname may be for instance #m, or #(listfile m). The list is always a list of strings (names of variables), not the objects themselves.

•If a variable is stated without databank, the databank is assumed to be the first-position databank.

The following provides a list of all variables in all databanks, including banknames and frequencies (beware, this output may be voluminous if the databanks are large):

index <showbank=all showfreq=all> ***;   //all variables in all banks
index <showbank=all showfreq=all> *:**;     //the same
index <showbank=all showfreq=all> *:%*, *:#*, *:*!*;  //the same

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

The following INDEX statement will look for timeseries beginning with f in the first-position databank (and with the current frequency), and put the result into #m.

reset;
fa = 1; fb = 2; fc = 3;
index f* to #m;   //result: 'fa', 'fb', 'fc'
prt #m;   //prints the three strings
prt {#m};   //prints the three series

INDEX will print the list of found variables, unless the <mute> option is used. To look for the same pattern/wildcard in the Ref databank:

reset;
ref:fa = 1; ref:fb = 2; ref:fc = 3;
index ref:f* to #m;   //result: 'ref:fa', 'ref:fb', 'ref:fc'
prt #m;   //prints the three strings
prt {#m};   //prints the three series

Here, the bankname is included, since Ref is not the first-position databank. You may search in all banks like this:

reset;
fa = 1; fb = 2; fc = 3;
clone;
index *:f* to #m;     //result: 'fa', 'fb', 'fc', 'ref:fa', 'ref:fb', 'ref:fc'
prt #m;   //prints the six strings
prt {#m};   //prints the six series

Instead of the above, you could alternatively use this:

reset;
fa = 1; fb = 2; fc = 3;
clone;
#m = ['*:f*'];     //result: 'fa', 'fb', 'fc', 'ref:fa', 'ref:fb', 'ref:fc'
prt ['*:f*'];   //prints the six strings
prt {'*:f*'};   //prints the six series themselves
disp *:f*;     //also prints them: DISP does not need {'...'}-syntax for wildcards.

In the light of the above example, the reader may ask: why use the INDEX statement at all? The answer is three-fold:

•Often, one would just like to see the result of a wildcard search, without putting the result into any list. To that end, for instance index *:f*; is practical.

•In addition to the above, for INDEX, the ['....'] part of the wildcard can often be dropped, using the shorter index *:f*; instead of using {'*:f*'} or ['*:f*']. The shorter notation does not work generally for all statement types, for instance #m = *:f*; or prt *:f*; would fail with an error. Do not expect 'naked' wildcards like a*b to work in statements that also accept mathematical expressions.

•The INDEX statement provides options regarding the search. For instance, index string %*; only matches string scalars. You may also indicate the bank in which the variables are searched, and you may indicate how you want bank and frequency information shown in the resulting list.

For instance:

reset;
fa = 1; fb = 2; fc = 3;
clone;   //copies the series into the Ref databank
index {'*:f*'};     //just prints 'fa', 'fb', 'fc', 'Ref:fa', 'Ref:fb', 'Ref:fc'
index *:f*;     //same, shorter
index <bank=ref> f*;   //same as ref:f*, result = 'Ref:fa', 'Ref:fb', 'Ref:fc'
index <showbank=no> *:f*;     //omits banknames, result = 'fa', 'fb', 'fc', 'fa', 'fb', 'fc' (note dublets)
index <showbank=all> *:f*;   //all banknames, result = 'Work:fa', 'Work:fb', 'Work:fc', 'Ref:fa', 'Ref:fb', 'Ref:fc'
index <showfreq=all> *:f*;   //all freqs, result = 'fa!a', 'fb!a', 'fc!a', 'Ref:fa!a', 'Ref:fb!a', 'Ref:fc!a'
index string {'%*'};   //indicate type of variable, will find all strings in first-position bank

Matching rules: the wildcard * does not just match any variable. The wildcard * does not match starting characters % or # at the start of the variable name, nor does it match any frequency indicators at the end of the variable name (for instance !a or !q). So the following rules apply:

•* matches all series of the current frequency in the first-position databank

•*!* matches all series of all frequencies in the first-position databank

•%* matches all scalars in the first-position databank

•#* matches all collections in the first-position databank

•** matches all variables in the first-position databank

The last two-star wildcard is special, and can be understood as ** = *!* + %* + #*. If you need to perform the same search in a particular databank, or in all databanks, just add bankname and colon:

•*:* matches all series of the current frequency in all databanks

•*:*!* matches all series of all frequencies in all databanks

•*:%* matches all scalars in all databanks

•*:#* matches all collections in all databanks

•*:** matches all variables in all databanks

You may of course indicate a particular databank, for instance b2:*. To match everything, use the following three-star wildcard:

•*** matches all variables in all databanks, that is: 'everything'.

Array-series

You can match sub-series inside an array-series like this:

reset;
x = series(1);
x[ia] = 1; x[ib] = 2; x[ja] = 3; x[jb] = 4;
index x[i*];     //x[ia], x[ib]
y = series(2);
y[i, a] = 1; y[i, b] = 2; y[j, a] = 3; y[j, b] = 4;
index y[i, *];     //y[i,a], y[i,b]
index y[**];     //y[i,a], y[i,b], y[j,a], y[j,b]
index y[*, b] to #m; //y[i,b], y[j,b]
prt #m;   //list: ('y[i,b]', 'y[j,b]')
prt {#m};   //y[i,b], y[j,b]

If you want to use sub-series wildcards when for instance printing or in general expressions, you cannot use the 'naked' form of the wildcards (otherwise the meaning of * would become ambiguous). Instead, elements containing wildcards must be enclosed in single quotes ('), for instance:

//continued...
prt y['*', b]; //y[i,b], y[j,b]

Notes

See the wildcards page regarding wildcards, syntax, etc.

If you use variable names without wildcards or ranges, a kind of existence check is performed. The variable name will be kept in the resulting list only if the variable exists.

You may also try series ?;. to see how many series (and of which frequencies) exist in which databanks.

Related statements

LIST, COUNT