Guide: timeseries

For an easier introductory guide on Gekko timeseries, see this page. For an introductory guide on array-timeseries, see this page.

period

(Optional). Local period, for instance 2010 2020, 2010q1 2020q4 or %per1 %per2+1.

operator

The operator can be d, p, m, q, mp, l or dl. See the 'Operators' section below.

KEEP=

If <keep=p> is used, Gekko will keep the growth rate of the left-hand series intact after the period over which the series is updated. For instance, x <2020 2025 m keep=p> = 100; will add 100 to x over the period 2020-25. The keep=p setting makes sure that the growth rate of x regarding 2026 and later already existing observations in x is the same as before the update. Use <keep=d> for absolute change.

LABEL=

(Optional). Label (string) for the series, cf. DOC.

SOURCE=

(Optional). Source (string) for the series, cf. DOC.

UNIT=

(Optional). Unit (string) for the series, cf. DOC. If you prefer, you may use units=... instead of unit=....

STAMP=

(Optional). Stamp (string) for the series, cf. DOC.

DYN

(Optional). With this option, lagged dependent/endogenous variables like x[-1] in the expression x = x[-1] + 1; accumulate over time. Using <dyn> entails a speed penalty, so please do not use if not needed (in this particular case, x ^= 1;, x <d>= 1; or dif(x) = 1; could be used instead). The following two are equivalent:

Using <dyn>

x <2021 2023 dyn> = x[-1] + 1;  //the <dyn> option implicitly runs the expression three times

Explicit

x <2021 2021> = x[-1] + 1;  //these three lines are equivalent to the use of <dyn> above
x <2022 2022> = x[-1] + 1;
x <2023 2023> = x[-1] + 1;

Starting from Gekko 3.1.7, statements like x = x[-1] + 1; must have an indication of whether they are to be run dynamically or not, cf. the page on dynamic statements for much more information on such 'dynamics errors' and how to handle them.

MISSING=

(Optional). With <missing = ignore>, SERIES will deal with missing array sub-series and missing data values like GAMS, treating them as zero for sums and mathematical expressions. The following options are set locally and reverted afterwards: option series array calc missing = zero; option series data missing = zero. An analogous <missing=ignore> option can also be used for PRT, PLOT, SHEET, CLIP, and DECOMP. See also the appendix page on missings.

variable

Left-side name

expression

Any expression

In addition to = (assignment), the following variants can also be used (see the 'Operators' section below):

• +=  add to existing

• -=  subtract from existing

• *=  multiply to existing

• /=  divide from existing

• ^=  set absolute time change

• %=  set percent time change

• #=  add to percent time change

x = 100;

time 2021 2023;
x = 100, 110, 90;
y = (10*10, 113-3, 88+2);  //a list with expressions must use parentheses 

time 2020 2030;
x <2021 2023 label='Gekko-variable'> = 100, 110, 90;

time 2010 2012;
x1a = 10; x2a = 20;
y1a = 100; y2a = 200;
y1b = 1000; y2b = 2000;
%i = 'a'; //string
#i = a, b; //list of strings 'a' and 'b'
x{%i} = x1{%i} + x2{%i}; //xa = x1a + x2a
y{#i} = y1{#i} + y2{#i}; //ya = y1a + y2a; yb = y1b + y2b;
prt <n> xa, ya, yb;
//                  xa             ya             yb 
// 2010        30.0000       300.0000      3000.0000 
// 2011        30.0000       300.0000      3000.0000 
// 2012        30.0000       300.0000      3000.0000 

time 2010 2012;
xa = 1; xb = 2;
#i = a, b;
prt <n> x{#i};
//                  xa             xb 
// 2010         1.0000         2.0000 
// 2011         1.0000         2.0000 
// 2012         1.0000         2.0000 

x = series(2);         //two dimensions
x[a,b] = 100;         //or: x['a','b'] = 100;
x[a,o] = 200;         //or: x['a','o'] = 200;

Type

Operator

Example

Result

Note

Absolute

^=

x ^= 1200;

x = x[-1] + 1200

Same as <d> or dif(x) = 1200;. See also the <dyn> option.

Relative

%=

x %= 3.5;

x = x[-1]*(1+3.5/100)

Same as <p> or pch(x) = 3.5;. See also the <dyn> option.

Absolute

+=

x += 1200;

x = x + 1200

Same as <m>. You can also use -= to subtract values.

Relative

*=

x *= 1.03;

x = x*1.03

Similar to <q>. You can also use /= to divide with values.

Change in

relative

#=

x #= 2.1;

x = x[-1]*(x0/x0[-1] + 2.1/100)

Same as <mp>. See also the <dyn> option.

Type

Option

Example

Result

Note

Absolute

<d>

x <d>= 1200;

x <dyn> = x[-1] + 1200

Same as ^=. or dif(x) = 1200;. See also the <dyn> option.

Relative

<p>

x <p>= 3.5;

x <dyn> = x[-1]*(1+3.5/100)

Same as %= or pch(x) = 3.5;. See also the <dyn> option.

Absolute

<m>

x <m>= 1200;

x = x + 1200

Same as +=. You can also use -= to subtract values.

Relative

<q>

x <q>= 3;

x = x*(1+3/100)

Similar to *=. You can also use /= to divide with values.

Change in

relative

<mp>

x <mp>= 2.1;

x <dyn> = x[-1]*(x0/x0[-1] + 2.1/100)

Same as #=. See also the <dyn> option.

Log

<l>

x <l>= 5;

x = exp(5)

Same as log(x) = 5;.

Relative

<dl>

x <dl>= 0.035;

x <dyn> = x[-1]*exp(0.035)

Same as dlog(x) = 0.035;.

Type

Option

Example

Result

Note

Absolute

dif()
diff()

dif(x) = 1200;

x <dyn> = x[-1] + 1200

Same as ^= or <d>=. See also the <dyn> option. You may use diff() as synonym.

Relative

pch()

pch(x) = 3.5;

x <dyn> = x[-1]*(1+3.5/100)

Same as %= or <p>=. See also the <dyn> option.

Log

log()

log(x) = 5;

x = exp(5)

Same as <l>=.

Relative

dlog()

dlog(x) = 0.035;

x <dyn> = x[-1]*exp(0.035)

Same as <dl>=.

time 2010 2013;
p = 1.00, 1.12, 1.15, 1.14;
v = 100, 102, 104, 106;
q = v/p;
prt q;  //or: plot q;

time 2011 2013;
x <2010 2010> = 1;    //uses a local time period
x %= 2.5;             //x is set to grow with 2.5 percent annually
x <p>= 2.5;           //same as above, alternative syntax
pch(x) = 2.5;         //same as above, alternative syntax
prt x;                //grows with 2.5% p.a.

time 2011 2013;
x = 1, 2, 3;
clone;                              //Ref bank made as copy of Work bank
x <q>= 10;                          //or: x *= 1.10;
prt <n r m q> x;                    //level, ref-value, difference, %difference
prt <n> x, @x, x-@x, 100*(x-@x)/@x; //same info, done manually

x[2020] = %v;  //%v is a scalar value

x <2020 2020> = %v

#m = a, b; %v = 10;
y1 = 3 $ ('b' in #m and %v == 10);
y2 $ ('b' in #m and %v == 10) = 3;

time 2001 2005;
x = 10, 10, 11, 12, 10;
y1 = 110 $ (x == 10) + 111 $ (x <> 10);
y2 = iif(x, '==', 10, 110, 111);
//                  y1         %             y2         % 
// 2001       110.0000         M       110.0000         M 
// 2002       110.0000      0.00       110.0000      0.00 
// 2003       111.0000      0.91       111.0000      0.91 
// 2004       111.0000      0.00       111.0000      0.00 
// 2005       110.0000     -0.90       110.0000     -0.90 

jx <2010 2010> += 1000;
jx <2010 2010 m> = 1000;  //same result

%f1 = 0.02;
x <2010 2012> += (%f1, 2*%f1, 0.01);

time 2010 2012;
#m = x1, x2;               //or: ('x1', 'x2')
{#m} = 100, 80, 110;
{#m} <2010 2012> *= 1.02;  //x1 and x2 become 2% larger, could also use <q> option
prt {#m};

{'j*'} <2010 2010> = 0;

bank1:x = 100;

@x = 200;

reset;
#i = a, b, o;                       //or: ('a', 'b', 'o')
#j = a, b, o;
#j0 = a, o;
x = series(2);                      //two dimension
p = series(2);                      //two dimensions
x[#i,#j] = 100;                     //all elements = 100
p[#i,#j] = 2;                       //all elements = 2
prt <n> x;                          //prints all elements of the array-series x
prt <n> p * x;                      //same as p[#i, #j] * x[#i, #j], simple array-series algebra
prt <n> x[a,#j];                    //prints the elements with 'a' in the first dimension
prt <n> x[#i,#j];                   //prints all elements, similar to prt x;
y = sum((#i,#j), x[#i,#j]);         //the sum of all elements, y = 900
z = sum(#j, x[a,#j] $ (#j in #j0)); //the sum of those #j that are in #j0
x.setdomains(('#i', '#j'));         //domains set, necessary for #default logic
p.setdomains(('#i', '#j'));         //domains set, necessary for #default logic
#default = map();                   //#default is a map type
#default.#j = #j0;                  //chose elements of #j to print
prt x;                              //will omit printing middle column 'b' in set #j
prt <split> x;                      //splits the output
prt x.getelements();                //elements belonging to each of the 2 dimensions
prt x.subseries('elements');        //element combinations for each of the 9 sub-series

reset;

x = series(2);
x[a,10] = 100; x[a,11] = 101; x[b,10] = 102; x[b,11] = 103;
e = series(2);
e[a,10] = 0; e[a,11] = 1; e[b,10] = 1; e[b,11] = 0; //sparsity
#e = (('a', '11'), ('b', '10')); //sparsity
#i = ('a', 'b');
#j = ('10', '11');
y1 = sum((#i, #j) $ (e[#i, #j]), x[#i, #j]); //203
y2 = sum((#i, #j) $ (#e[#i, #j]), x[#i, #j]); //203

z = sum(#j, x['a', #j] $ (#j in #j.remove('b')));
z = sum(#j, x['a', #j] $ (#j in #j - ('b', 'o')));

disp x1;                                         //shows info regarding dimensions, elements, etc.
disp x1[a, b];                                   //shows info for the the sub-series
prt x1;                                          //will print out all elements
prt x1[#i,#j];                                   //prints out the elements in lists #i and #j (combined)

reset;
#s = e1, e2;
a = series(1);                   //array-series with 1 dimension
a[#s] = 100;                     //sets a[e1] = a[e2] = 100
a.setdomains(('#s',));           //assigns #s to dimension 1 of the array-series
p <n> a;                         //prints a[e1] and a[e2]
#default = map();                //defines map #default and puts it in the global databank
#default.#s = ('e1',);           //or in one line: #default = (#s = ('e1',))
p <n> a;                         //now, because of #default, only a[e1] is printed

reset;                   
x1 = 1; x2 = 2;          //create some data here
index * to #m;           //put all series names into the list #m
x = series(1);           //define an array-series with 1 dimension
x[#m] = {#m};            //put the normal series into the array-series
prt x;                   //print the 2 elements of x, try also "disp x;"
delete x1, x2, #m;       //delete everything except x
#m = x.getelements()[1]; //get the elements of dimension #1 of x
{#m} = x[#m];            //recreate the normal series from the array-series
prt x1, x2;              //print the normal series

option interface alias = yes;            //this option must be set
global:#alias = #(listfile alias);       //reads alias.lst from file
c = series(1); c[a] = 100; c[b] = 200;
y = 300; 
prt x1, x2,  x3;

--------------- alias.lst --------------------
x1; c[a]
x2; c[b]
x3; y
----------------------------------------------

time 2021 2024;
x = 100;
time 2022 2024;
x = x[-1] + 1;  //ERROR: will fail with a dynamics error
x <dyn = no> = x[-1] + 1;  //result: 101, 101, 101
x <dyn> = x[-1] + 1;  //result: 101, 102, 103

time 2021 2024;
x = 100;
time 2022 2024;
x ^= 1;     //result: 101, 102, 103
x <d>= 1;   //result: 101, 102, 103
dif(x) = 1; //result: 101, 102, 103

time 2021 2024;
x = 100;
time 2022 2024;
x <dyn> = x[-1] + 1;     //result: 101, 102, 103
block series dyn = yes;
  x = x[-1] + 1;         //result: 101, 102, 103
end;

Function name

Description

Examples

allMiss(x)

On a timeseries x, the function returns 1 if all observations are missing values ("no data at all"), else it returns 0. See also isMiss(), fromSeries('dataStart'), and fromSeries('dataStart').

time 2021 2023;
x1 = m();
prt x1.allMiss();  //1
x1 <2022 2022> = 1;
prt x1.allMiss();  //0

arrayPack(name, lname)

This function finds all non-array ("normal") timeseries in the first-position databank and puts them into a single 1-dimensional array-series called name. In addition, a list lname is created, containing the names of the "packed" timeseries.

Note that after the function is called, the first-position databank only contains the array-series and the list. See also arrayUnpack().

read adambank.gbk;
arraypack('adam', '#adamvars');
write <gdx> adambank.gdx;
//Creates the 1-dimensional array-series adam,
//with elements corresponding to the normal timeseries
//inside adambank.gbk. For instance, adambank.gbk may
//contain the series fY, which is mirrored in the element
//adam[fY]. Also, the list #adamvars will contain the
//element 'fY' (and more).

//When writing the gdx file, the adam variable will

//have domain names 'adamvars' and 't'.
//(You may use arraypack('adam', '*'), in which case
//the Gekko list is not created).

arrayUnpack(name)

This function takes the 1-dimensional array-series called name from the first-position databank and transforms ("unpacks") all the elements of the array-series into normal timeseries. The function deletes the array-series before it returns. See also arrayPack().

read <gdx> adambk.gdx; //has adam variable inside
arrayunpack('adam');
//Now the first-position databank contains normal
//timeseries corresponding to the elements of the
//array-series adam.

bankFlatten(t)

bankFlatten(bank, t)

For the global (or locally given) period, all series and array-series are flattened. This means that over the global (or local) period, all values are set to their value in t. A bank name may be provided: if not, the first-position databank is used.

time 1960 2022;
bankFlatten(2000);
//All series and array-series are set to
//their 2000 value, over the global period
//1960-2022.
bankFlatten(<1970 2010>, 2000);
//same, but now flattened over 1970-2010.
bankFlatten('Ref', 2000);
//for the Ref databank

bankReplace(x1, x2)

bankReplace(bank, x1, x2)

For the global (or locally given) period, in all series and array-series, the value x1 is replaced with x2. A bank name may be provided: if not, the first-position databank is used.

time 1960 2022;
bankReplace(m(), 0);
//All series and array-series have missing value replaced with 0, over the global period 1960-2022.
bankReplace(<1970 2010>, m(), 0);
//same, but now over 1970-2010.
bankReplace('Ref', m(), 0);
//for the Ref databank

binary(x)

Converts a table-like nested list of strings into a corresponding array-series where the present elements (that is, the 'rows' of the nested list) are represented with value 1. The nested list must contain time info as the last element of each sublist. The function can be used to tranform a multidimensional GAMS set into a corresponding array-series. This can be convenient for printing, etc.

time 2001 2002;
#m = (('a', 'b', '2001'), ('a', 'c', '2002'));
x1 = #m.binary();
x2 = #m.binary().replace(m(), 0); //set missing to 0
prt #m; //try also prt <view> #m;
prt <n> x1;  //1 or missing
prt <n> x2;  //1 or 0
 
//         x1[a, b]    x1[a, c] 
// 2001      1.0000           M 
// 2002           M      1.0000 
//
//         x2[a, b]    x2[a, c] 
// 2001      1.0000      0.0000 
// 2002      0.0000      1.0000 

collapse(x)

collapse(x, method)

collapse(x, freq)

collapse(x, freq, method)

Function variant of the COLLAPSE statement, converting from higher to lower frequency. Note possible differences compared to COLLAPSE regarding the use of databanks and time periods.

You may input a frequency (freq), choose from 'a', 'q', 'm', 'w'. If frequency is not indicated, the function will per default collapse from d to m, w to m, m to q, or q to a.

The method argument can be 'total', 'avg', 'first', 'last', 'strict' or 'flex'. The last two of these indicate how missing values are handled. You may combine the first four and the last two of these with -, for instance 'avg-flex' to choose method 'avg' combined with missing handling 'flex'. Note that missing handling 'flex' is currently only available for collapse of daily (!d) series. Regarding these options, see the COLLAPSE statement.

You may use option collapse method = ... ; and option collapse missing d = ... ; to control default values for the method and missing handling. See OPTION.

Returns: series.

time 2020 2020;
option freq q;
x = 1, 3, 2, 6;
p <n> x, x.collapse();
//same: x.collapse('total')
//same: x.collapse('a')
//same: x.collapse('a', 'total')
 
//Result:
//                   x   x.collapse() 
// 2020                               
// q1           1.0000                
// q2           3.0000                
// q3           2.0000                
// q4           6.0000                
// a                          12.0000 
 
//Nested collapse, d --> m --> q --> a
time 2020 2025;
option freq d;
x!d = 1;
p <n> x!d.collapse().collapse().collapse();
 
//          x!d.collap 
//       se().collapse 
//       ().collapse() 
// 2020       366.0000 
// 2021       365.0000 
// 2022       365.0000 
// 2023       365.0000 
// 2024       366.0000 
// 2025       365.0000 
 
//x!d.collapse('a') could be used instead

flatten(x, d)

Transforms 1 array-timeseries x into n normal timeseries with names reflecting the array-series dimensions and delimiter corresponding to the string argument d. For instance, an array-series npop defined over the two dimensions #sex and #age could contain the element (sub-series) npop[m, 40], which flatten() would turn into the normal series npop_m_40.

npop = series(1);
npop[m,40] = 60000;
npop[f,40] = 62000;
npop[m,41] = 59000;
npop[f,41] = 61000;
npop.flatten('_');
delete npop;
p <n dec=0 width=10> {'*'};
 
//Output:
//       npop_f_40   npop_f_41   npop_m_40   npop_m_41 
//2014       62000       61000       60000       59000 
//2015       62000       61000       60000       59000 
//...

getDomains(x)

Returns a list of strings (with the number of elements corresponding to the number of dimensions) containing the domain for each dimension of the array-series x, for instance '#i' or '*' (the latter means no domain). See also getFixType(), setFixType(), setDomains().

Returns: list

#d = getdomains(x); //or: #d = x.getdomains();

getElements(x)

Returns a nested list of strings, which for each dimension of the array-series shows which elements occur (in all sub-series). In the example on the right, the first dimension only contains a's, whereas the second dimension contains b and c. The returned list has as many elements as the dimensionality of the array-series. See also subseries().

x = series(2);
x[a, b] = 1;
x[a, c] = 2;
prt x.getelements();
// ('a',), ('b', 'c')

prt x.getelements()[2];

// 'b', 'c'

prt x.getelements()[2][1];

// 'b'

getFixType(x)

Returns the "fix" type of an array-timeseries x, where the return value can be 'variable' or 'parameter'. Array-series imported from GAMS gdx can be of variable or parameter type. See also setFixType(), getDomains(), setDomains().

Returns: string.

//See example under setFixType()

getParent(x)

For an array-subseries x, its parent series is returned. See example.

x = series(1);
x[a] = 100;
x[b] = 200;
prt x[b].getParent();  //prints both

hpfilter(x, lambda)

hpfilter(<t1 t2>, lambda)

hpfilter(x, lambda, log)

hpfilter(<t1 t2> x, lambda, log)

Returns a HP-filtered version of series x. Lambda is normally 6.25 for annual, 1600 for quarterly, and 129600 for monthly series. An additional argument 0 or 1 may be added (1 if log-transforms are to be used inside the calculation). Time period may be indicated with t1 and t2.

Returns: series

y = hpfilter(x, 6.25);
y = hpfilter(x, 6.25, 1);  //log-transforms
y = hpfilter(<1970 2015>, x, 6.25);
y = x.hpfilter(<1970 2015>, 6.25); //alternative syntax

interpolate(x)

interpolate(x, method)

interpolate(x, freq)

interpolate(x, freq, method)

Function variant of the INTERPOLATE statement, converting x from lower to higher frequency. Note possible differences compared to INTERPOLATE regarding the use of databanks and time periods.

Method must be 'total' or 'avg' (optionally combined with Olsette/Cholette/Denton, for instance 'total-olsette' or 'avg-cholette').

Destination freq must be 'q', 'm', 'w', or 'd'. Per default, interpolate() will transform from a to q, q to m, m to d and w to d.

Returns: series.

time 2020 2021;
x = 1, 3;
p <n> x, x.interpolate();
 
//                                 x. 
//                   x  interpolate() 
// 2020                               
// q1                          1.0000 
// q2                          1.0000 
// q3                          1.0000 
// q4                          1.0000 
// a            1.0000                
//                                    
// 2021                               
// q1                          3.0000 
// q2                          3.0000 
// q3                          3.0000 
// q4                          3.0000 
// a            3.0000   

isArraySeries(x)

Returns 1 if the variable x is an array-series, and 0 otherwise.

x = series(1);
x[a] = 100;
prt isArraySeries(x);

isTimelessSeries(x)

Returns 1 if the variable x is a timeless series, and 0 otherwise.

x = timeless(100);
prt isTimelessSeries(x);

laspchain(plist, qlist, t)

laspchain(<t1 t2>, plist, qlist, t)

laspchain(<t1 t2>, plist, qlist, t, option)

laspchain(vals, valsLag, t)

laspchain(<t1 t2>, vals, valsLag, t)

Laspeyres chain index for quantities. Can be used with either (a) two lists of strings, or (b) two timeseries. In both cases the result is a map containing two consistent aggregated series p and q (price and quantity). The price is set = 1 in the t period. A period can be indicated in the <t1 t2> field. The function is robust regarding missing values at the start or end of the time period.

(a): Two lists of strings (names)

The names inside the two lists indicate the series that are to be aggregated.

See also the bottom of the LIST help page.

(b): Two series (accumulation)

A different way to use the function is to input one series (vals) with values in current prices, and one series (valsLag) with values in the previous period's prices. From this, Gekko will compute the aggregate price and quantity.

If you need to fill out holes (missings) between non-missings, for instance in prices series, you can use the smooth() function or SMOOTH statement.

Quarterly data

For quarterly data, using two lists of strings, option 'annualoverlap' must be indicated. When quarterly data are input, the so-called annual overlap method is used, where the algorithm starts out collapsing the quarterly data into annual data, then computes a "normal" annual chain index for the aggregate price, and lastly uses this annual price index to compute the quarterly indexes.

Returns: map

time 2017 2020;
p1 = 1.02, 1.03, 1.04, 1.05;
p2 = 1.12, 1.13, 1.14, 1.15;
q1 = 2, 3, 4, 5;
q2 = 12, 13, 14, 15;
#p = p1, p2;
#q = q1, q2;
//(a): With lists of strings
#a = laspchain(#p, #q, 2020);
prt #a.p, #a.q;
v = p1*q1 + p2*q2;
vlag = p1[-1]*q1 + p2[-1]*q2;
//(b): With series (accumulation)
#b = laspchain(v, vlag, 2020);
prt #b.p, #b.q;
 
//With explicit time indication:
//laspchain(<2017 2020>, #p, #q, 2020);
//laspchain(<2017 2020>, v, vlag, 2020);

laspfixed(plist, qlist, t)

laspfixed(<t1 t2>, plist, qlist, t)

laspfixed(<t1 t2>, plist, qlist, t, option)

Laspeyres fixed-price index. As laspchain(), but with fixed prices. Cannot be used with series input.

Returns: map

//See example regarding laspchain()

percentile(x, v)

Computes the v percentile for the series x, for the global time period. Any missing values within that sample are ignored. Setting v = 0.5 results in the median.

Returns: val

%z = percentile(y, 0.25);
%z = percentile(y, 0.50);

rebase(x, t)

rebase(x, t, index)

Function variant of the REBASE statement. Note possible differences compared to REBASE regarding the use of databanks and time periods.

You cannot use start/end dates with this function, only a single date (alternatively, use REBASE statement).

Returns: series.

time 2020 2022;
x = 10, 11, 12;
prt <n> x, x.rebase(2021), x.rebase(2021, 1);
//                                  x           x.re 
//                   x  .rebase(2021)  base(2021, 1) 
// 2020        10.0000        90.9091         0.9091 
// 2021        11.0000       100.0000         1.0000 
// 2022        12.0000       109.0909         1.0909 

rename(x, cfg)

For an array-series x: the function renames and reorders dimension elements, according to a cfg list (possibly as a listfile). See example.

//Given this listfile:
// ----- x_cfg.csv -----
// 2; dim1; a; aa;
// 3; dim2; b; bb;
// 3; dim2; c; cc;
// 1; dim3; d; dd;
// ---------------------
 
time 2001 2002;
x = series(3);
x[a,b,d] <2001 2001> = 1.2;
x[a,c,d] <2001 2001> = 3.4;
x[a,b,d] <2002 2002> = 5.6;
x[a,c,d] <2002 2002> = 7.8;
p <n> x;
z = x.rename(#(listfile x_cfg.csv));
prt <n> z;
 
//Output:
//            x[a,b,d]       x[a,c,d] 
// 2001         1.2000         3.4000 
// 2002         5.6000         7.8000 
//
//         z[bb,dd,aa]    z[cc,dd,aa] 
// 2001         1.2000         3.4000 
// 2002         5.6000         7.8000 
 
//So the rename() function can both rename dimension
//elements and reorder them.

reorder(x, ord)

For array-series x, this function reorders the dimensions according to the list ord. The list must contain the integers 1..n, where n is the dimensionality of the array-series.

Note: for an array-series dimension of size n, if reorder() is fed with the list (1, 2, ... , n), the function returns an identical array-series.

x = series(3);
x[a, c, e] = 1; x[a, c, f] = 2;
x[b, d, e] = 3; x[b, d, f] = 4;
y = x.reorder((2, 3, 1));
prt y;
//Will print subseries y[c, e, a], y[c, f, a], 
//y[d, e, b] and y[d, f, b]. The first dimension of x

//has been moved to the last dimension of y, and

//the other two dimensions are moved forwards.

replace(x, v1, v2)

For the series or array-series x, the function replaces the value v1 with the value v2, over the given sample.

See also iif(), isMiss(), and the $-conditional.

Returns: series

time 2001 2003;
x = (1, m(), 3);  //m() is missing value
//result is (1, 0, 3):
y = x.replace(m(), 0);  //or: replace(x, m(), 0)
//the replacement is done for the sample:
z <2000 2004> = x.replace(m(), 0);
//result is (0, 1, 0, 3, 0)

rotate(x, d)

Transforms the array-series x to a new array-series, where the time dimension and dimension number d swap places.

For instance, the array-series pop may contain sub-series for each age group 0 to 100, that is, pop['0'], pop['1'], ... , pop[100']. These 101 sub-series are all defined over a time period, say 2020-2050. Then profile = rotate(pop, 1); will be a new array-series containing sub-series for each time period 2020 to 2050, that is, profile['2020'], profile['2021'], ... , profile['2050']. These 31 sub-series are all defined over an undated time period 0 to 100, corresponding to the age dimension. Hence, plot <0u 100u> profile['2020']; will plot the age profile of the population in the year 2020.

See example under PLOT (age profiles section).

Returns: series

//pop is a 1-dimensional array-series 
//with ages 0-100 in its dimension.
//note: 'u' indicates undated frequency
 
profile!u = rotate(pop, 1);
#t = ('2020', '2030', '2040', '2050');
plot <0u 100u> profile!u[#t];
 
 
 

series(freq, n)

Constructs a series or array-series of the given frequency and with the given dimensions (n). You can skip some of these options, see examples.

See also isArraySeries().

Returns: series

x = series('q', 3);  //quarterly array-series, 3-dim
x = series('q');  //quarterly normal series
x = series(3);  //3-dim array-series with current frequency
x = series();  //normal series with current frequency
 
y = series(1);
y['a'] = 100;  //or: y[a] = ...
 

setDomains(x, d)

Uses a list of strings (d) to set the domains for each dimension of the array-series x. Use '*' to indicate a domain-less dimension (in GAMS called the universal set), but otherwise each element should start with symbol # (to indicate that it is a list). See also getFixType(), setFixType(), getDomains().

Returns: nothing

#d = ('#b', '#x');
setdomains(x, #d);  //or: x.setdomains(#d);
y.setdomains(('*', '#x'));

setFixType(x, type)

Sets the "fix" type of an array-timeseries x, where type can be 'variable' or 'parameter'. When exporting an array-series to a GAMS gdx file, this difference is of significance. See also getFixType(), getDomains(), setDomains().

x = series(1);
x[a] = 100;
p x.getFixType();
//returns: 'variable', which is default
write <gdx> data1; //variable in GAMS
x.setFixType('parameter');
p x.getFixType();
write <gdx> data2; //parameter in GAMS

smooth(x)

smooth(x, method)

smooth(x, y)

smooth(x, method, y)

Function variant of the SMOOTH statement to fill holes (missing values) in the series x. Note possible differences compared to SMOOTH regarding the use of databanks and time periods.

Method must be 'linear', 'geometric', 'repeat', 'spline', or 'overlay'. If method is not stated, 'linear' is default. The y variable can be a series, value or 1x1 matrix (y is only used for 'overlay' smoothing).

Returns: series.

z = x.smooth('linear');     //user linear smoothing
z = x.smooth();             //short for the above
z = x.smooth('overlay', y); //use y series to fill holes
z = x.smooth(y);            //short for the above
z = x.smooth(0);            //use 0 value as overlay

splice(x1, x2, ...)

splice(x1, t1, x2, ...)

splice(x1, t1, t2, x2, ...)

splice(type, x1, ...)

Function variant of the SPLICE statement to splice two or more overlapping timeseries x1, x2, ... into one resulting timeseries. Note possible differences compared to SPLICE regarding the use of databanks and time periods.

Type can be 'rel1', 'rel2', 'rel3', 'abs' for the method, or 'first', 'last', '1', '2', '3', etc. for indicating the "primary" series number (such numbers must be strings). You may combine the method and "primary" indication with -, for instance 'rel3-first' or 'abs-2'. Default is 'rel1-last'. See many more details under SPLICE.

Returns: series.

time 2001 2005;
x1 <2001 2003> = 1, 2, 3;
x2 <2003 2005> = 11, 12, 13;
y = splice(x1, x2);
prt y, x1, x2;

//Regarding the left-hand side series,

//note that splice() never inserts
//values outside of the given 
//local or global time period.

//So this time period is respected,

//in contrast to the SPLICE statement.

subseries(x, option)

Helper function for array-series x.

•option = 'elements': nested list of strings with element combinations for each sub-series.

•option = 'names': list of sub-series names (as strings). You may remove the frequency part of these names with removefreq(), see example.

•option = 'length': the number of sub-series inside the array-series.

•option = 'dimensions': the number of dimensions of the array-series.

See also getelements().

x = series(2);
x[a, b] = 1;
x[a, c] = 2;
prt x.subseries('elements');
// ('a', 'b'), ('a', 'c')
prt x.subseries('names');
// 'x!a[a, b]', 'x!a[a, c]'
prt x.subseries('names').removefreq();
// 'x[a, b]', 'x[a, c]'
prt x.subseries('length');
// 2

prt x.subseries('dimensions');
// 2

timeless(freq, v)

Constructs a timeless series of the given frequency freq, with value v. You can skip some of these options, see examples.

In many cases, you can just use a value scalar with the same functionality. But timeless series can be practical, for instance they can be used as array-series.

See also isTimelessSeries().

Returns: series

x = timeless('q', 3);  //quarterly timeless series, with value = 3.
x = timeless('q');  //quarterly timeless series, no value set.
x = timeless(3);  //timeless series with current frequency, with value = 3.
x = timeless();  //timeless series with current frequency, no value set.
 
y = series(1);
y['a'] = timeless(100);  //or: y[a] = ...