Function name

Description

Examples

abs(x)

Returns the absolute value of x (series, val or matrix).

Returns: series/value/matrix

%v1 = abs(%v2);

avg(x1, x2, ...)

Returns the average of x1, x2, ... etc. The input parameters may be series or value.

Returns: series/value

y = avg(x1, x2, x3);
%v = avg(%v1, %v2, %v3);

avgt(x)

avgt(<t1 t2>, x)

Returns the time-average of the observations of the timeseries x over the local/global time period (or over t1 to t2, if indicated)

Returns: series

y = avgt(x);
y = avgt(<2020 2025>, x);
y = x.avgt(<2020 2025>);  //same as above

ceiling(x)

Returns the the smallest integer which is greater than or equal to x (series, val or matrix). See also int(), floor() and round().

Returns: series/value/matrix

prt ceiling(-2.2);

dif(x) or diff(x)

Absolute time-difference of  series x: can also be used on left side of '='. Does not work on value.

Returns: series

y = dif(x);
dif(y) = 100;

dify(x) or diffy(x)

Yearly difference. Same as dif(x), but will use 4 lags for quarterly data, and 12 lags for monthly data.

Returns: series

y = dify(x);

dlog(x)

Logarithmic time-difference of series x: can also be used on left side of '='. Does not work on value.

Returns: series

y = dlog(x);
dlog(y) = 0.02;

dlogy(x)

Yearly logarithmic time-difference. Same as dlog(x), but will use 4 lags for quarterly data, and 12 lags for monthly data.

Returns: series

y = dlogy(x);

exp(x)

Returns the exponential value of x (series, value or matrix).

Returns: series/value

y = exp(x);
%v1 = exp(%v2);

floor(x)

Returns the largest integer which is less than or equal to x (series, val or matrix). See also int(), ceiling() and round().

Returns: series/value/matrix

prt floor(-2.2);

iif(in1, op, in2, out1, out2)

Conditional, works like an if statement. Think of it like if in1 op in2 then out1 else out2, where op is a string containing the operator ==, <>, <, <=, >=, >. The function can be used to avoid explicit time looping for timeseries. The op input must be a string, and the rest of the inputs must be of math type (there is another iif()-example here). If needed, you can use == (or <>) together with m() to test for the presence of missing values, see example.

You may alternatively use $-conditionals, see examples under SERIES. See also the replace() and isMiss() functions for series.

Returns: series/value

time 2010 2012;
in1 = 1, 2, 3;
in2 = 3, 2, 1;
y1 = iif(in1, '<=', in2, 50, 100);
//Result: y1 = 50, 50, 100.
 
 
in3 = 100, m(), 300;
y2 = iif(in3, '==', m(), 1000, in3);
//Result: y2 = 100, 1000, 300

int(x)

Returns the integer value of x (series, val or matrix), discarding the fractional part (after the .). See also floor(), ceiling() and round().

Returns: series/value/matrix

prt int(-2.2);

isMiss(x)

isMiss(x, 'all')

The input parameter may be series or value, and the function returns 1 or 0 (or 1's and 0's).

If x is a series, the first variant of the function returns 1, else 0, over the period that contains data (cf. fromSeries(x, 'dataStart') and fromSeries(x, 'dataEnd')). With option 'all', the local or global period is used instead.

An example is provided regarding how to replace missing values inside series, but note that this can also be done with the iif() or replace() functions.

See also allMiss().

Returns: series/value

prt isMiss(1); prt isMiss(miss());
time 2020 2023;
z = 1, m(), 3, m();
prt <n> z, z.isMiss(), z.isMiss('all');
//Note that for 2023, the function returns a
//missing value. The function only finds missing
//values between non-missing values.
//With 'all' option, missing values that are not
//enclosed between non-missing values will be 
//set to 1, too.
prt sumt(z.isMiss('all'));
//Prints the number of missings over 2020-23.
 
time 2021 2025;
x = 1, 2, m(), 4, 5;
y = 100;
y = y $ (x.isMiss()) + x $ (not x.isMiss());
//y becomes 1, 2, 100, 4, 5. See also iif() function.
 
time 2021 2026;
x = 1, m(), m(), 4, m(), 6;
x $ (x.ismiss('all')) %= 0;
//x becomes 1, 1, 1, 4, 4, 6, 
//filling out missing "holes"

lag(x, lag)

Lags series x a number of periods. Note the sign of the lag: lag(x, 2) = x[-2]. Can be used if x is an expression.

Returns: series

y = lag(x, 2);  //same as x[-2]

log(x)

Returns the natural logarithmic value of x (series, value or matrix). Can also be used on the left side of '='.

Returns: series/value/matrix

y = log(x);
%v1 = log(%v2);

log(y) = a * log(b);

max(x1, x2, ... )

Finds the largest value. Arguments may be value, series or date.

Returns: value/series/date.

[New in 3.1.6]

prt max(2, 4, 1, 3);
prt max(2000q1, 2000q4);
time 2001 2003;
x1 = 1, 2, 3;
prt max(x1, 2);

min(x1, x2, ... )

Finds the lowest value. Arguments may be value, series or date.

Returns: value/series/date.

[New in 3.1.6]

prt min(2, 4, 1, 3);
prt min(2000q1, 2000q4);
time 2001 2003;
x1 = 1, 2, 3;
prt min(x1, 2);

mod(x1, x2)

Modulo, the remainder of the division x1/x2.

Returns: value/series.

[New in 3.1.12]

%x = mod(7, 4); //3
%x = mod(8, 4); //0
%x = mod(9, 4); //1

movavg(x1, lags)

Moving average of series x1.

Returns: series

y = movavg(x, 3);
y = (x + x[-1] + x[-2])/3;  //same

movsum(x1, lags)

Moving sum of series x1, cf. movavg().

Returns: series

y = movsum(x, 3);
y = x + x[-1] + x[-2];  //same

pch(x)

Percentage growth in series x: can also be used on left side of '='. Does not work on value.

Returns: series

y = pch(x);
pch(y) = 2;

pchy(x)

Yearly growth. Same as pch(x), but will use 4 lags for quarterly data, and 12 lags for monthly data.

Returns: series

y = pchy(x);

pow(x, y)

The exponent must be a value or number, not a series. The function pow(x, y) is equal to x**y or x^y, that is, a in the y'th power. You may use power(x, y) as synonym.

Returns: series/value

y = pow(x1, %x2);
%v = pow(%x1, %x2);

rnorm(mean, var)

rnorm(mean, vcov)

Returns a random number from a normal distribution with mean and variance provided. If fed with a n x 1 matrix of averages, and a n x n covariance matrix, the function will return a n x 1 matrix of values. See also rseed() and runif().

Returns: value/matrix

%n = rnorm(0, 1);
%n = rnorm(-100, 25**2);
#n = rnorm(#mean, #vcovar);

rseed(x)

Given value x, it sets a random seed for runif() and rnorm() functions. The function returns the seed as a value, but can be used without return value.

Returns: value

rseed(12345);
 

round(x, d)

Rounds x (series, val or matrix) to d decimal places. See also int(), floor() and ceiling().

Returns: series/value/matrix

%v1 = round(%v2, 3);

runif()

Returns a random number from a uniform distribution between 0 and 1. See also rseed() and rnorm().

Returns: value

%v = runif();

seq(start, end)

Returns a list of integer values or dates between start and end (both included). Start and end must be two values or two dates.

Returns: list

#m = seq(1, 100);
#t = seq(2001q1, 2005q4);

sqrt(x)

Returns the square root of x (series, value or matrix).

Returns: series/value/matrix

y = sqrt(x);
%v1 = sqrt(%v2);

sum(x1, x2, ...)

sum(list, x)

Returns the sum of x1, x2, ... etc. The input parameters may be series or value.

If the first argument is a list name (or a list of list names), the sum function will sum the second argument over these lists.

Returns: series/value

y = sum(x1, x2, x3);
%v = sum(%v1, %v2, %v3);

y = sum(#j, x[a, #j]);
y = sum((#i, #j), x[#i, #j]);
y = sum(#j, xa{#j});
y = sum((#i, #j), x{#i}{#j});

To sum a simple list #j of series names, you may use this:

y = sum({#j}); //shorter than sum(#j, {#j})

Note that for PRT/PLOT etc., you should use the more explicit PRT sum(#j, {#j}); because PRT/PLOT auto-unfolds 'uncontrolled' lists into columns/lines.

sumt(x)

sumt(<t1 t2>, x)

Returns the time-sum of the observations of the timeseries x over the local/global time period (or over t1 to t2, if indicated)

Returns: series

y = sumt(x);
y = sumt(<2020 2025>, x);
y = x.sumt(<2020 2025>);  //same as above

tanh(x)

Returns the hyperbolic tangens of x (series, value or matrix). Returns: series/value/matrix

%x = tanh(0.5);

Function name

Description

Examples

date(x)

Tries to convert the scalar x to date type. See also under "date combining functions".

Returns: date

%d = date(2000+15);
Result: %d = 2015.

dates(x)

Tries to convert each element of the list x into a date.

Returns: list

#m1 = (2001, 2002, 2003);
#m2 = dates(#m1);  //or: #m1.dates()

data(x)

Converts a string x containing blank-separated numbers to a list of values.

Returns: list of values

#m = data('1 2 3');
x = data('1 2 3');

format(x, code)

Formats the value/date/string x by means of the formatting code. The formatting code is as follows for values:

'[width]:[format]'
'[width]:[format]=[culture]'

The width specifies that the string will be at least [width] characters wide. If the [width] is positive, the number is right-aligned within the field, and if it is negative, it is left-aligned.

The [format] follows the conventions shown here or here, so you may either use a pattern like 0.000 or 0.### (exactly three digits or at most three digits), or you may use a description like F3 (floating point, three digits). So 12:0.000 or 12:F3 are both a 12 characters wide field, and a number with three decimals.

The [culture] argument after an optional = symbol changes how thousands and decimal operators look like. For instance, en-US is English (US variant), da-DK is Danish, see the possible cultures here. So format(1234567.8987, '0,0.00=da-DK') will return 1.234.567,90. Without culture, it would return 1,234,567.90.

A value format can be set globally with option string interpolate format val = ... ;. This can be practical when printing out for instance a table of values with the same value formatting.

You may also format strings or dates: in that case only [width] can be used (positive or negative). In this way, table-like alignment is quite straightforward.

Returns: string.

%v = 12.3456;

%d = 2020q1;
%s = 'abc';
 
tell;
tell '123456789012' + '|';
tell '------------' + '|';
tell %v.format('0.000') + '|';
tell %v.format('12:0.000') + '|';
tell %d.format('12') + '|';
tell %s.format('12') + '|';
tell %v.format('-12:0.000') + '|';
tell %d.format('-12') + '|';
tell %s.format('-12') + '|';
tell '------------' + '|';
 
// 123456789012|
// ------------|
// 12.346|
//       12.346|

//       2020q1|
//          abc|
// 12.346      |

// 2020q1      |
// abc         |
// ------------|

string(x)

Tries to convert the scalar x to string type. See also under "string combining functions".

If x is a list of strings, the string() function returns a comma-separated list of strings.

Returns: string

%s = string(12) + string(34);
Result: %s = '1234'.

strings(x)

Tries to convert each element of the list x into a string.

Returns: list

#m1 = (1, 2, 3);
#m2 = strings(#m1); //or: #m1.strings()

val(x)

Tries to convert the scalar x to value type.

Returns: value

%v = val('12' + '34');
Result: %v = 1234.

vals(x)

Tries to convert each element of the list x into a value.

Returns: list

#m1 = ('1', '2', '3');
#m2 = vals(#m1);  //or: #m1.vals()

Function name

Description

Examples

date(d, f, opt)

date(d, f)

Converts the date d into a new date with frequency f (string). The optional option can be omitted, or be 'start' or 'end'. Using 'start' or 'end' is only relevant when converting from a lower to a higher frequency.

Beware that week numbers are special around New Year.

Returns: date

%d = 2021q1;
prt %d.date('a'); //2021

prt %d.date('m'); //error!
prt %d.date('m', 'start'); //2021m1
prt %d.date('m', 'end');   //2021m3
prt %d.date('w', 'start'); //2020w53 !!
prt %d.date('w', 'end');   //2021w13
//Note that the first week that fully 
//contains the first quarter of 2021 starts
//in 2020!

date(y, f, sub)

date(y, 'm', m, 'd', d)

Constructs a new quarterly/monthly/weekly date from y (integer), frequency (string), and subperiod (integer). You may also construct a daily date with a similar syntax.

Note: you may also use date(x), where x can be a value or a string, and Gekko will try to convert the argument into a date.

Returns: date

%d = date(2020, 'q', 2);  //2020q2
%d = date(2020, 'w', 42);  //2020w42
%d = date(2020, 'm', 12, 'd', 24);  //2020m12d24

fromExcelDate(v)

Converts an Excel date (the val v, counting the number of days since January 1, 1900) to a date with daily frequency.

Returns: date (daily)

See examples regarding the toExcelDate() function.

getFreq(d)

Extracts the frequency of a date

Returns: string

%d = 2020q2;
prt %d.getfreq();  //'q'

getDay(d)

Extracts the day number from a date. Will fail if the date is not daily.

Returns: value (integer)

%d = 2020m3d25;
prt %d.getday(); //25

getSpecialDay(year, name)

Finds a special day by year and name, and returns its daily date. Mostly used for holidays. If you input a wrong name, Gekko will provide a link showing all possible special days. Current possible holiday names (English, and equivalent Danish names):

Note that getSpecialDay(%year, 'Leap_Day') may return a null value, else it returns February 29 in leap years). The leap day is not a holiday, but is nevertheless kept in this list of special days. See example.

prt 2021.getSpecialDay('Easter_Sunday'); //2021m4d4
prt 2021.getSpecialDay('Paaskedag');     //same day
 
for(val %year = 2021 to 2025);
  %day = %year.getSpecialDay('Christmas_Eve');
  %s = %day.getWeekday('en');
  tell 'In {%year}, Christmas Eve is on a {%s}';
end;
//Result:
//In 2021, Christmas Eve is on a Friday
//In 2022, Christmas Eve is on a Saturday
//In 2023, Christmas Eve is on a Sunday
//In 2024, Christmas Eve is on a Tuesday
//In 2025, Christmas Eve is on a Wednesday
 
prt 2020.getSpecialDay('Leap_Day');
prt 2021.getSpecialDay('Leap_Day');
 
%y = 2020;
if(not %y.getSpecialDay('Leap_Day').isNull());
  //code to handle if %y is a leap year
end;

getMonth(d)

getMonth(d, lang)

Extracts the month number from a date. More specific than getSubPer(), and will fail if the date is not monthly or daily.

You may input a language ('en' = English, 'da' = Danish), in which case a string is returned.

Returns: value (integer) or string

%d = 2020m2;
prt %d.getmonth();  //2
prt %d.getmonth('en');  //'February'
prt %d.getmonth('en').lower()[1..3]; //'feb'

getQuarter(d)

Extracts the quarter number from a date. More specific than getSubPer(), and will fail if the date is not quarterly.

Returns: value (integer)

%d = 2020q2;
prt %d.getquarter();  //2

getSubPer(d)

Extracts the sub-period from a date (1 if annual or undated, the quarter if quarterly, the month if monthly or daily, and the week if weekly).

Returns: value (integer)

%d = 2020q2;
prt %d.getsubper();  //2

getWeek(d)

Get the week number from a date of weekly frequency. Does not accept daily frequency as argument, but the conversion date('w') can be used as intermediary for this (see examples). Beware that the year may change when converting from daily to weekly frequency.

Returns: value (integer)

[New in 3.1.13]

%d = 2020w20;
p %d.getWeek(); //20
p %d.getYear(); //2020
 
%d = 2019m12d31;

p %d.getWeek(); //error!
p %d.date('w').getWeek(); //1
p %d.date('w').getYear(); //2020!
 
%d = 2021m1d1;
p %d.date('w').getWeek(); //53
p %d.date('w').getYear(); //2020!

getWeekday(d)

getWeekday(d, lang)

Extracts the weekday number from a date. Will fail if the date is not daily. The numbers are as follows:

Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7.

You may input a language ('en' = English, 'da' = Danish), in which case a string is returned.

Returns: value (integer) or string.

[New in 3.1.12]

%d = 2020m3d25;
prt %d.getweekday();     //3
prt %d.getweekday('en'); //Wednesday
prt %d.getweekday('en').lower()[1..3]; //wed
prt %d.getweekday('da'); //Onsdag

getYear(d)

Extracts the year from a date.

Returns: value (integer)

%d = 2020q2;
prt %d.getyear();  //2020

max(d1, d2, ... )

Finds the largest of any number of dates. (max() can also be used with value arguments).

Returns: date

[New in 3.1.6]

prt max(2002q1, 2001q4);

min(d1, d2, ... )

Finds the smallest of any number of dates. (min() can also be used with value arguments).

Returns: date

[New in 3.1.6]

prt min(2002q1, 2001q4);

observations(d1, d2)

Counts the number of observations (periods), with both start and end date included. The date difference using - is always the same as the number of observations minus 1.

prt observations(2020q2, 2023q3); //14
prt 2023q3 - 2020q2;              //13

toExcelDate(d)

Converts a daily date into an Excel date (counting the number of days since January 1, 1900). See also fromExcelDate(). Excel dates can be subtracted to obtain day spans. [New in 3.0.7]

Returns: value.

%v1 = toExcelDate(2019m11d12);
%v2 = toExcelDate(2019m12d3);
prt %v1, %v2; //43781 and 43802
prt %v2 - %v1; //21 days (span)
%d = fromExcelDate(%v1 + 100);
prt %d; //100 days from 2019m11d12

truncate(d1, d2)

Finds overlap between two different time periods. The period d1 to d2 is compared with the global time period (if no local period is indicated), or with the local time period (if such a period is indicated in the <...> fields). Use a local time period if you need to find the overlap between two arbitrary time windows.

Returns: a list of two elements, start and end date of the resulting period. If the two elements are both null, there is no overlap.

[New in 3.1.6]

time 2010 2020;
#m = truncate(2000, 2030);  //(2010, 2020)
#m = truncate(2000, 2015);  //(2010, 2015)
#m = truncate(2000, 2005);  //(null, null)
time 1980 1990;
#m = truncate(<2010 2020>, 2000, 2030);  //(2010, 2020)
#m = truncate(<2010 2020>, 2000, 2015);  //(2010, 2015)
#m = truncate(<2010 2020>, 2000, 2005);  //(null, null)

//

// The overlapping period (z) can be visualized as

// the overlap of these time windows/periods:     

//                                                

// period1    . x x x x x . . .                   

// period2    . . . y y y y y .                   

// truncate() . . . z z z . . .                   

Function name

Description

Examples

[x]-index

Index: returns the character at position x.

Returns: string

%s = 'abcd';
prt %s[2];  //'b'

[x1..x2]-index

Index: returns the range of characters from position x1 to x2 (both inclusive). You may omit x1 or x2.

Returns: string

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

concat(s1, s2)

Appends the two strings: same as s1 + s2.

Returns: string

%s = concat('He', 'llo'); Result: 'Hello'.

endswith(s1, s2)

Returns 1 if the string s1 starts with the string s2, else 0. The comparison is case-insensitive.

Returns: val

%v = endswith('abcde', 'cde');
Returns: 1

includes(s1, s2)

Returns 1 if the string s2 is found inside (as a part of) string 1, else 0 is returned. The search is case-insensitive. Note that the contains() function is not useful regarding such in-string searches.

Returns: val

[New in 3.1.17].

%s = 'abCd';
prt %s.includes('bc');  //1

index(s1, s2)

Searches for the first occurrence of string s2 in string s1 and returns the position. It returns 0 if the string is not found. The search is case-insensitive

Returns: val

%v = index('onetwothreetwo', 'two'); 

Returns: 4. 
%v = index('oneTWO', 'two'); 

Returns: 4.

isAlpha(s)

Returns 1 if all the characters are letters (alphabet). [New in 3.0.5].

%v = isAlpha('aBc');
Returns: 1

isLower(s)

Returns 1 if the string contains no uppercase characters. [New in 3.0.5].

%v = isLower('abc12');
Returns: 1

isNumeric(s)

Returns 1 if all the characters are of numeric value. [New in 3.0.5].

%v = isNumeric('123');
Returns: 1

isUpper(s)

Returns 1 if the string contains no lowercase characters. [New in 3.0.5].

%v = isUpper('ABC12');
Returns: 1

length(s)

The length of the string (number of characters). You may use len() instead of  length().

Returns: val

%v = %s.length();

lower(s)

The string in lower-case letters.

Returns: string

%s = lower('aBcD'); 

Result: 'abcd'.

nl()

A system newline/linebreak. Computerwise, nl() is equal to the C# string "\n", but beware that you cannot use the Gekko string '\n' instead of nl(), because the former is equal to the C# string "\\n".

Returns: string

%s = 'a' + nl() + 'b'; //string with newline
tell %s;
#m = %s.split(nl()); //list with 2 elements
p #m;

prefix(s1, s2)

If s1 is a string, it has the string s2 prefixed (prepended).

Returns: string

%s1 = %s2.prefix('a');

replace(s1, s2, s3)

replace(s1, s2, s3, max)

In the string s1, the function replaces all occurrences of s2 with s3. Replacement is case-insensitive.

If max > 0, the replacement is performed at most max times.

Returns: string

%s = replace(%s1, %s2); 

//or: replace(%s, %s1, %s2)

split(s1, s2)

split(s1, s2, removeempty)

split(s1, s2, removeempty, strip)

Splits the string s1 by means of the delimiter s2. Empty elements are removed per default, and the resulting strings are stripped (blanks are removed from the start and end of the strings). The last two options are 1 and 1, if omitted. [New in 3.0.6]

%s = 'a, b,c,,d, , e';
#m1 = %s.split(','); 
//--> ('a', 'b', 'c', 'd', 'e')
#m2 = %s.split(',', 1, 1); 
//--> ('a', 'b', 'c', 'd', 'e');
#m3 = %s.split(',', 0, 1);'); 
//--> ('a', 'b', 'c', '', 'd', '', 'e')
#m4 = %s.split(',', 1, 0);'); 
//--> ('a', ' b', 'c',  'd', ' ', ' e')
#m5 = %s.split(',', 0, 0);'); 
//--> ('a', ' b', 'c', '', 'd', ' ', ' e')
 
%s = 'a' + nl() + 'b'; //string with newline
#m = %s.split(nl(), 0); //--> ('a', 'b')
//Note: the 0 argument keeps empty lines

startswith(s1, s2)

Returns 1 if the string s1 starts with the string s2, else 0. The comparison is case-insensitive.

Returns: val

%s = 'abcde';
%v = %s.startswith('abc');
Returns: 1

strip(s)

Removes blank characters from the start and end of the string.

Returns: string

%s1 = %s2.strip();  //or: strip(%s1)

stripstart(s)

Removes blank characters from the start of the string.

Returns: string

%s1 = %s2.striptart();  //or: stripstart(%s1, %s2)

stripend(s)

Removes blank characters from the end of the string.

Returns: string

%s1 = %s2.stripend();  //or: stripend(%s1, %s2)

substring(s, start, length)

The piece of the string between character number start and length (these must be integer values).

You can alternatively use a 'slice', using []-notation, see example.

Returns: string

%s = %s1.substring(3, 2);  

//or: substring(%s1, 3, 2)
%s = %s1[3 .. 5];  

//a slice from pos 3 to 5 (both inclusive)

suffix(s1, s2)

If s1 is a string, it has the string s2 suffixed (appended)

Returns: string

%s1 = %s2.suffix('a');

upper(s)

The string with upper-case letters.

Returns: string

%s = upper('aBcD'); Result: 'ABCD'.

Function name

Description

Examples

[x]-index

Index: picks out a single element. In contrast to R, this does not return a 1-element list containing the variable. If you need that, use for instance #m[3..3].

Returns: var

#m[3];  //the third element

[x1..x2]-index

Index: picks out a range of elements. You may omit x1 or x2.

Returns: list

#m[3..5];  //the third to fifth elements

[x1, x2]-index

For a nested list of lists, #m[3, 5] will return the same element as #m[3][5], so this is just convenience to make a nested list accessible like a matrix. See more here.

Returns: variable

[New in 3.0.6].

#m = ((1, 2), (3, 4));
prt #m[2, 1], #m[2][1];  //same

[x1..y1, x2..y2]-index

[x1..y1, x2]-index

[x1, x2..y2]-index

For a nested list of lists, #m[2..3, 2..4] will select the given 'rows" and "columns", corresponding to selecting a submatrix from a matrix. Beware that in general, #m[2..3, 2..4] is completely different from #m[2..3][2..4].  See more here.

Returns: list

[New in 3.0.6].

//  1  2  3
//  4  5  6
//  7  8  9
// 10 11 12
#m = ((1, 2, 3), (4, 5, 6), (7, 8, 9), (10, 11, 12));
prt #m[2, 2..3];
prt #m[2][2..3]; //same as above
prt #m[2..4, 2]; //matrix-like selection
prt #m[2..4][2]; //different from above!
prt #m[2..4, 2..3]; //matrix-like selection
prt #m[2..4][2..3]; //different from above!

append(x1, x2)

append(x1, i, x2)

Adds variable x2 as it is at the end of list x1. Note that if x2 is a list of for instance 3 items, only 1 element is added (the list itself). If you need to add the 3 elements individually, use extend().

If used with i argument, x2 is inserted at index i, instead of at the end. See also extend().

To prepend, use append(x1, 1, x2).

Returns: list

#y = #x1.append(#x2);  //or: append(#x1, #x2)
#y = #x1.append(2, #x2);  //insert at position 2

contains(x1, x2)

Checks if the list of strings x1 contains the string x2. Returns 1 if true, 0 otherwise. You may alternatively use x2 in x1, see the last example. See also the count() and index() functions. The comparisons are case-insensitive.

Returns: val

%v = #x1.contains(%s);
if(#x1.contains(%s) == 1); tell 'yes'; end;
if(%s in #x1); tell 'yes'; end;

count(x1, x2)

Counts the number of times the string x2 is present in the list of strings x1. See also the contains() and index() functions.

Note: to obtain the number of elements in a list, use the length() function. The comparisons are case-insensitive.

Returns: val

%v = #x1.count(%s);  //or: count(#x1, %s)

data(x)

Accepts a string of blank-separated values x and turns them into a list of values. This is handy for long sequences of blank-separated numbers, instead of manually setting the commas.

Returns: list

#m = data('1.0  2.0  1.5');

dates(x)

Tries to convert each element of the list x to a date.

Returns: list

#y = dates(#x);

except(x1, x2)

The except() function subtracts x2 from x1. You may alternatively use the operator -. Only works for lists of strings. See also intersect() and union().

Was called difference() in Gekko 2.0. See also extend().

Returns: list

#y = #x1.except(#x2);  //or: except(#x1, #x2)
#y = #x1 - #x2;        //same
 
#y -= #x1;  //subtract from itself

extend(x1, x2)

extend(x1, i, x2)

The arguments x1 and x2 must be lists. The function inserts the elements of list x2 one by one at the end of (or at position i in) the list x1. The resulting list may contain dublets.

For two lists x1 and x2, you may alternatively use the + operator. See also except() and append().

To pre-extend, use extend(x1, 1, x2).

Returns: list

#y = #x1.extend(#x2);  //or: extend(#x1, #x2)
#y = #x1 + #x2; //same as above
#y = #x1.extend(2, #x2);  //insert at position 2
 
#y += #x1; //add to itself

flatten(x)

For at list x, the function returns a flattened version of the list. For instance, the list (1, (2, 3)) is transformed into a non-recursive list of non-list elements: (1, 2, 3).

Returns: list

#m1 = (1, (2, 3));
#m2 = #m1.flatten(); //or: flatten(#m1).

index(x1, x2)

Returns the index of the first occurrence of the string x2 in the list of strings x1. Returns 0 if x2 is not found in x1. See also the count() and contains() functions. The comparisons are case-insensitive.

Returns: val

%i = #x1.index(%s);  //or: index(#x1, %s)

intersect(x1, x2)

The intersect() function finds the common elements of the two list of strings x1 and x2. The resulting list will not contain dublets. You may alternatively use the operator &&. Only works for lists of strings. See also except() and union().

Returns: list

#y = #x1.intersect(#x2);  //or: intersect(#x1, #x2)
#y = #x1 && #x2;

length(x)

Returns the number of elements in the list x. You may use len() instead of length().

Returns: val

%v = #x.length();  //or: length(#x).
%v = #x.len(); //the same

list(x1, x2, ...)

Returns a list of the variables x1, x2, etc. The function is handy for lists with only 0 or 1 elements. See examples.

Returns: list

#m = ();      //will fail
#m = list();  //ok: empty list

#m = (1, 2);  //easy
#m = (1);     //will fail
#m = (1,);    //is ok
#m = list(1); //is ok

lower(x)

Returns string elements in the list as lower-case.

Returns: list

#y = #x1.lower();  //or: lower(#x1)

pop(x1, i)

pop(x1)

Removes the element at position i in the list x1. Removes the last element if called with pop(x).

Returns: list

#y = #x1.pop(2);  //or: pop(#x1, 2)
#y = #x1.pop();  //last element
#y = #x1.pop(1);  //first element

preextend(x1, x2)

Same as extend(x1, 1, x2), putting the elements of x2 in the first position of x1.

#y = #x1.preextend(#x2);  //insert at position 1

prefix(x1, x2)

If x1 is a list of strings, each element has the string x2 prefixed (prepended)

Returns: list

#y = #x1.prefix(%s);  //or: prefix(#x1, %s);

prepend(x1, x2)

Same as append(x1, 1, x2), putting x2 in the first position of x1.

#y = #x1.prepend(#x2);  //insert at position 1

sort(x)

sort(x, 'natural')

Returns a sorted list of strings, provided that x is a list of strings. Sorting is case-insensitive.

When the 'natural' argument is used, strings containing numbers will sort naturally, for instance returning a8, a9, a10, instead of a10, a8, a9.

Returns: list

Natural sort: [New in 3.1.10].

#y = #x.sort();  //or: sort(#x)
#y = #x.sort('natural');

remove(x1, x2)

Removes any string x2 from the list of strings x1. See also the except() function.

Returns: list

#y = #x1.remove(%s);  //or: remove(#x1, %s);

#y = #x1 - %s;        //also legal

replace(x1, x2, x3)

replaceinside(x1, x2, x3)

replaceinside(x1, x2, x3, max)

replace(): In the list of strings x1, if this string element is the same as x2, x3 is inserted instead.

replaceinside(): the string element has any occurences of x2 inside the string replaced with x3. The replacements may be limited via the max argument.

Returns: list

#y = #x1.replace(%x2, %x3); //or: replace(#x1, %x2, %x3)
 
#y = #x1.replaceinside(%x2, %x3); //or: replace(#x1, %x2, %x3, 'inside')

reverse(x)

To be done

split(x, s)

To be done

strings(x)

Tries to convert each element of the list x to a string

Returns: list

#y = strings(#x);

suffix(x1, x2)

If x1 is a list of strings, each element has the string x2 suffixed (appended)

Returns: list

#y = #x1.suffix(%s);  //or: suffix(#x1, %s);

t(x)

For a nested list of lists, the t() function returns the transpose, similar to transposing a matrix. [New in 3.0.6].

Returns: list (of lists)

#m = ((1, 2), (3, 4));
p #m, t(#m);

union(x1, x2)

The union() function finds the union of the two lists. Alternatively use the operator ||. The resulting list will not introduce dublets, in contrast to the similar + operator (simple concatenation). Only works for lists of strings. See also except() and intersect().

Returns: list

#y = #x1.union(#x2);  //or: union(#x1, #x2)
#y = #x1 || #x2;

unique(x1)

Retains only those elements of list x1 that are unique (list of strings only).

Returns: list

#y = #x1.unique();  //or: unique(#x1)

upper(x)

Returns string elements in the list as upper-case.

Returns: list

#y = #x1.upper();  //or: upper(#x1)

vals(x)

Tries to convert each element of the list x to a value

Returns: list

#y = vals(#x);

venn(x1, x2)

For two lists of strings, this function prints out lists corresponding to a Venn diagram.

That is, intersection and two differences. For instance, venn(#m1, #m2) corresponds to printing out the following:

•#m1 && #m2

•#m1 - #m2

•#m2 - #m1

See also intercept(), except() and union().

Returns: nothing.

#m1 = a, b, c, d, e;
#m2 = c, d, e, f, g;
venn(#m1, #m2);
 

//Results:

 
//The following 3 strings are in both lists:
//'c', 'd', 'e'
 
//The following 2 strings are in list #1, but not in list #2:
//'a', 'b'
 
//The following 2 strings are in list #2, but not in list #1:
//'f', 'g'

Function name

Description

Examples

addBank(x, bank)

If x does not have a bankname, a bankname is added. The input x may be string or list.

Returns: string or list

%name = addBank('x!q', 'b2');
Result: 'b2:x!q'

addFreq(x, freq)

If x does not have a freq, a freq is added. The input x may be string or list.

Returns: string or list

%name = addFreq('x', 'q');
Result: 'x!q'

getBank(x)

Returns the bank part of x. The input x may be series, string or list.

Returns: string or list

%bank = getBank('b2:x!q');
Result: 'b2'

getFreq(x)

Returns the freq part of x. The input x may be series, string or list.

Returns: string or list

%bank = getFreq('b2:x!q');
Result: 'q'

getFullName(bank, name, freq)

Returns the full name corresponding to the input, where bank, name and freq are strings.

Returns: string

%name = getFullName('b2', 'x', 'q');
Result: 'b2:x!q'

getFullName(bank, name, freq, index)

Returns the full name corresponding to the input, where bank, name and freq are strings, and index is a list (of strings)

Returns: string

%name = getFullName('b2', 'x', 'q', ('a', 'b'));
Result: 'b2:x!q[a,b]'

getIndex(x)

Returns the index part of x. The input x may be string or list.

Returns: list

#index = getIndex('b2:x!q[a, b]');
Result: ('a', 'b')
If the input is a list, the output will be a list of lists.

getName(x)

Returns the name part of x. The input x may be series, string or list.

Returns: string or list

%name = getName('b2:x!q');
Result: 'x'

getNameAndFreq(x)

Returns the name part of x. The input x may be series, string or list.

Returns: string or list

%name = getNameAndFreq('b2:x!q');
Result: 'x!q'

removeBank(x)

Removes any bank in x. The input x may be string or list.

Returns: string or list

%name = removeBank('b2:x!q');
Result: 'x!q'

removeBank(x, bank)

Removes any banks in x with the indicated bankname. The input x may be string or list.

Returns: string or list

%name = removeBank('b2:x!q', 'b2');
Result: 'x!q'
%name = removeBank('b3:x!q', 'b2');
Result: 'b2:x!q'

removeFreq(x)

Removes any freq in x. The input x may be string or list.

Returns: string or list

%name = removeFreq('b2:x!q');
Result: 'b2:x'

removeFreq(x, freq)

Removes any freq in x with the indicated freqname. The input x may be string or list.

Returns: string or list

%name = removeFreq('b2:x!q', 'q');
Result: 'b2:x'
%name = removeFreq('b3:x!q', 'm');
Result: 'b2:x!q'

removeIndex(x)

Removes any index in x. The input x may be string or list.

Returns: string or list

%name = removeIndex('b2:x!q[a, b]');
Result: 'b2:x!q'

replaceBank(x, b1, b2)

Replaces any banks in x having name b1 with name b2. The input x may be string or list.

Returns: string or list

%name = replaceBank('b2:x!q', 'b2', 'b3');
Result: 'b3:x!q'
%name = replaceBank('b2:x!q', 'b3', 'b4');
Result: 'b2:x!q'

replaceFreq(x, f1, f2)

Replaces any freq in x having freq b1 with freq b2. The input x may be string or list.

Returns: string or list

%name = replaceFreq('b2:x!q', 'q', 'm');
Result: 'b3:x!m'
%name = replaceFreq('b2:x!q', 'm', 'a');
Result: 'b3:x!q'

setBank(x, bank)

The indicated bankname is set, even if it exists already. The input x may be string or list.

Returns: string or list

%name = setBank('b3:x!q', 'b2');
Result: 'b2:x!q'

setFreq(x, freq)

The indicated freq is set, even if it exists already. The input x may be string or list.

Returns: string or list

%name = setFreq('b2:x!q', 'm');
Result: 'b2:x1!m'

setName(x, name)

The indicated name is set. The input x may be string or list.

Returns: string or list

%name = setName('b2:x!q', 'y');
Result: 'b2:y!m'

setNamePrefix(x, p)

The name of x has prefix p added.The input x may be string or list.

Returns: string or list

%name = setNamePrefix('b2:x!q', 'a');
Result: 'b2:ax!m'

setNameSuffix(x, s)

The name of x has suffix s added.The input x may be string or list.

Returns: string or list

%name = setNameSuffix('b2:x!q', 'b');
Result: 'b2:xb!m'

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(), and fromSeries('dataStart'), and fromSeries('dataStart').

[New in Gekko 3.1.20].

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().

[New in 3.1.16]

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().

[New in 3.1.16]

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.

[New in 3.1.16]

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.

[New in 3.1.16]

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.
flatten('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.

[New in 3.1.14]

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.

[New in 3.1.11]

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.

[New in 3.1.16]

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 containing the domains for each dimension of the array-series x. Returns an empty list if there are no domains given. 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().

[New in 3.1.10]

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.

[New in 3.1.14]

//See example under setFixType()

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-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 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.

[New in 3.1.11]

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 is an array-series, and 0 otherwise.

[New in 3.1.14]

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

isTimelessSeries(x)

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

[New in 3.1.14]

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.

[New in 3.1.11]

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: renames and reorders dimension elements, according to a cfg nested list.

[New in 3.1.16]

TODO

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, 3, ... , n), the function returns an identical array-series.

[New in 3.1.16]

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)

Sets a list of strings (d) containing the domains for each dimension. You may use '*' to indicate a domain-free 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);

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().

[New in 3.1.14]

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). 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 (it is only used for 'overlay' smoothing).

Returns: series.

[New in 3.1.13]

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 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.

[New in 3.1.15]

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.

•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().

[New in 3.1.10]

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, to 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] = ...