Guide: plotting

For an easier introductory guide on Gekko plotting, see this page.

Gekko uses gnuplot 5.1 internally for plotting. The gnuplot engine may crash if fed with illegal syntax or nonsensical data. Unfortunately, the gnuplot error messages seem hard to extract into Gekko, but you may use PLOT<dump> and feed the gnuplot.gp file into gnuplot 5.1 to inspect the error messages.

period

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

operator

(Optional). 'Long': abs, dif, pch, gdif, or 'short': n, d, p, dp, m, q, mp, r, rd, rp, rdp

variables

Name of the variable(s) printed. Several variables can be printed at once using var1, var2, var3, .... You may also use lists or expressions. Labels may be provided, like plot x 'Production'; , or plot x x.fromseries('label'); to use label metadata.

PLOTCODE=

(Optional). The contents of this string must be gnuplot code (for instance 'set' statements separated by semicolon), and the contents is sent to gnuplot and inserted just before the gnuplot 'plot' statement. If plotcode is also stated in the .gpt schema file, both plotcodes are transferred to gnuplot (first the .gpt plotcode, and then the local option plotcode).

DUMP

(Optional). With option <dump>, Gekko will put two gnuplot files in the working folder: gnuplot.gp (the gnuplot script), and gnuplot.data (the gnuplot data). The gnuplot script can be run inside gnuplot 5.1 with the following statement: load 'gnuplot.gp' (note the quotes).

NOMAX

(Optional). Do not restrict the number of curves, cf. option plot elements max.

BANK

(Optional). A bankname where variables are looked up. For instance plot <bank = b1> x; is equivalent to PLOTb1:x;. See also <REF = ...>. These options can be convenient instead of opening and closing banks.

REF

(Optional). A bankname where reference variables are looked up. For instance plot <bank = b1 ref = b2 m> x; uses banks b1 and b2 for the multiplier. See also <BANK = ...>. These options can be convenient instead of opening and closing banks

MISSING=

(Optional). With <missing = ignore>, PLOT will deal with missing array sub-series and missing data values like GAMS, treating them as zero for sums and mathematical expressions, or skipping the printing of a sub-series if it does not exist. The following options are set locally and reverted afterwards: option series array print missing = skip; option series array calc missing = zero; option series data missing = zero. See also the appendix page on missings.

USING=

(Optional). Indicates a .gpt file (xml template) to style your plot. You may use '*' as filename to select from .gpt files in the working folder. If no extension is provided, .gpt is added automatically. See also option plot using = ... .

Filenames may contain an absolute path like c:\projects\gekko\bank.gbk, or a relative path \gekko\bank.gbk. Filenames containing blanks and special characters should be put inside quotes. Regarding reading of files, files in libraries can be referred to with colon (for instance lib1:bank.gbk), and "zip paths" are allowed too (for instance c:\projects\data.zip\bank.gbk). See more on filenames here.

FILE=

(Optional).  Use extension emf (default), png, svg or pdf.

The resulting file is in .emf format as default. Such a file can be imported into many Windows programs such as Word and others. You may use a filename with explicit extension .png/.svg/.pdf instead, and PLOT will produce the file in that format. The .svg files are very useful for insertion into html document.

Filenames may contain an absolute path like c:\projects\gekko\bank.gbk, or a relative path \gekko\bank.gbk. Filenames containing blanks and special characters should be put inside quotes. Regarding reading of files, files in libraries can be referred to with colon (for instance lib1:bank.gbk), and "zip paths" are allowed too (for instance c:\projects\data.zip\bank.gbk). See more on filenames here.

type

The most used of the following are the line-types linespoints and lines, together with boxes (column chart).

•linespoints, lines: Normal lines, with or without point markers.

•boxes: bar chart/histogram. If several timeseries are boxes, these will be clustered, unless the stacked option is set.

•filledcurves: lines where the area below each line is an area. If the stacked option is set, the areas are stacked instead of overlayed.

•steps: Step-wise lines, a bit box-like.

•points: Just the point markers, no lines.

•dots: Just tiny dots.

•impulses: vertical lines instead of boxes.

Quotes may be omitted.

dashtype

'1':normal, '2':dashed, '3':dotted, ... (default: '1'). More. Quotes should be used.

linewidth

A number. Default: 3.

linecolor

You may use named colors (for instance 'red') or color codes known from html (for instance '#0000FF'). Default: color is taken from the palette setting. Quotes should be used.

pointtype

An integer. These points are shown for each period, if the linetype is linespoints or points.

•1:'+'

•2:'x'

•3:'*'

•4:box

•... etc.

Default: 7 (circle). More.

pointsize

A number. The size of the points. Default: 0.5.

fillstyle

String. Only relevant for linetype boxes. You may use many combinations, for instance 'empty', 'solid', 'solid 0.5' (50% transparent), 'solid border', 'pattern 0', 'pattern 1', etc. To provide a black border around the boxes, use for instance 'solid 1.0 border linetype -1'. Default: 'solid'. More. Quotes should be used.

title

The title of the entire plot. Quotes should be used.

subtitle

A subtitle underneath the title. Quotes should be used.

font

Set for instance 'Verdana', 'Arial', 'Times', 'Courier New' ... . Default is 'Verdana'. Quotes should be used.

fontsize

Default is 12.

bold

Use this option to indicate bold font type for different elements. Choose from 'title', 'ytitle', 'xtics', 'ytics', 'key', or indicate several of these separated with commas, for instance 'title, ytitle, key'. Quotes should be used.

italic

Use this option to indicate italic font type for different elements. Choose from 'title', 'ytitle', 'xtics', 'ytics', 'key', or indicate several of these separated with commas, for instance 'title, ytitle, key'. Quotes should be used.

tics

You may choose between 'in' or 'out'. Default: 'out'. Quotes should be used. Regarding number formatting, see option plot decimalseparator = ....

grid

Choose between yes|no|xline|yline. If yes, both vertical and horizontal lines are shown. If xline, only vertical lines are shown. If yline, only horizontal lines are shown. Default: yes. Quotes can be omitted.

gridstyle

This sets how gridlines are formatted, stated in gnuplot syntax. Quotes should be used.

•Default is the following, which are light grey dashed lines: 'linecolor rgb "#d3d3d3" dashtype 3 linewidth 1.5'.

•The gridstyle 'linecolor black dashtype 2 linewidth 2.0' will provide black dashed lines which look ok in Word.

•To emulate the solid grey style of Gekko 2.2.4 and earlier, use 'linecolor rgb "#f0f0f0" linetype 1 linewidth 1'.

In general, the same dashed lines can look quite different in different "environments". So there may be differences in the Gekko window versus inside Word versus pdf (exported from Word) versus html (via svg) versus pdf (exported from html) versus printed from Word or a browser. In general, there will be small differences between the .emf, .svg, .png and .pdf files. For html pages, please use .svg instead of .png for better quality.

key

In gnuplot, the legend is called 'key'. This sets how the legend is to be displayed, stated in gnuplot syntax. Default is the following, which is outside of the plot area, at the bottom center: 'out horiz bot center Left reverse'. Quotes should be used.

To remove the key completely, you can use gnuplot-code 'set key off': plot<plotcode='set key off'>;.

palette

You may use a comma-separated list of named colors (for instance: "red, blue, green", or rgb color codes (like "#0000FF, #FFFF00, #00FFFF"). Default is this: "red, web-green, web-blue, orange, dark-blue, magenta, brown4, dark-violet, grey50, black" (these are gnuplot internal color names). More. Quotes should be used.

stack

If the element is set active (<stack>), boxes are stacked instead of clustered, and filledcurves are stacked instead of overlayed. Default: no.

boxwidth

The width of the boxes. Set to 1 for max width. Default: 0.75.

boxgap

The gap between clusters of boxes (only relevant if you are using two or more boxes at the same time). Default: 2, that is, a gap of what two boxes would fill.

separate

With the separate option, lines and boxes are separated, so that all lines (non-boxes) are shown at the top of the plot (with labels on the left y axis), whereas all boxes are shown at the bottom of the plot (with labels on the right y2 axis). For instance, this is practical for residual plots, so that the residuals do not interfere with observed/fitted lines. The option will override any y2 options regarding the lines. This functionality is Gekko-specific and does not yet work for stacked boxes (option boxstack), where the scaling will not be precise (this will be fixed in a future version). Default: no.

xline

Vertical line at the given period. Several lines may be given. For instance: <xline>2020q2</xline>.

xlinebefore

Vertical line between the given period and the period before. Several lines may be given. For instance: <xlinebefore>2020q2</xlinebefore>.

xlineafter

Vertical line between the given period and the period after. Several lines may be given. <xlineafter>2020q2</xlineafter>

xzeroaxis

x2zeroaxis

The xzeroaxis is the horiontal axis corresponding to y=0, and the x2zeroaxis is the axis corresponding to y2=0 (the right-hand side y-axis). These xzeroaxes will only be shown if the y or y2 values change sign. Default for xzeroaxis is yes, and default for x2zeroaxis is no.

ymirror

Mirror the left y axis on the right side. You may choose between '0':none, '1':only tics, '2':tics with labels, and '3': tics with labels + axis label. If the y2 axis is used, the ymirror setting is ignored.

ytitle

y2title

A title for the y or y2 axis. Quotes should be used. If the title should break, you may use a '\n', for instance plot<ytitle='Balance\nof payments'>;.

yline

y2line

Horizontal line at the given y- or y2-value. Several lines may be given. For instance: <yline>150</yline>. The lines are not shown if the lines are outside of the y values of the variables shown in the graph (you may combined with ymaxsoft/yminsoft).

You may alternatively do horizontal lines manually, for instance: plot 150 '' <type=lines dashtype='3' linecolor='gray'>, x1, x2, x3;. The quotes '' after 150 indicated that the label is skipped. Putting the line first means that it will appear in the background (looks better for type=boxes).

ymax

y2max

Fixed max for the y or y2 values. Will overrule any maxhard or maxsoft values. Can cut off data points.

ymaxhard

y2maxhard

All values > maxhard are filtered out, but all values < maxhard are shown. This setting is practical for filtering out outliers. Think of 'hard' as being capable of cutting off data points.

ymaxsoft

y2maxsoft

All values are shown, but the axis will not scale down below ymaxsoft. This keeps a sensible scale, even if the y or y2 values are very small.  Think of 'soft' as being incapable of cutting off any data points.

ymin

y2min

Fixed min for the y or y2 values. Will overrule any minhard or minsoft values. Can cut off data points.

yminhard

y2minhard

All values < minhard are filtered out, but all values > minhard are shown.This setting is practical for filtering out outliers. Think of 'hard' as being capable of cutting off data points.

yminsoft

y2minsoft

All values are shown, but the axis will not scale up above yminsoft. This keeps a sensible scale, even if the y or y2 values are very small. Think of 'soft' as being incapable of cutting off any data points.

label

A free-floating label is inserted at the given position. Several labels may be given. Quotes should be used. [Not available yet]

plotcode

The contents of this <plotcode> tag must be gnuplot code (for instance 'set' statements separated by semicolon), and the contents is sent to gnuplot and inserted just before the gnuplot 'plot' statement. If plotcode is also stated as a local option to the PLOT statement, both plotcodes are transferred to gnuplot (first the .gpt plotcode, and then the local option plotcode).

arrow

An arrow is inserted between the given positions. Several arrows may be given. [Not available yet]

type

See under the main options.

dashtype

See under the main options.

linewidth

See under the main options.

linecolor

See under the main options.

pointtype

See under the main options.

pointsize

See under the main options.

fillstyle

See under the main options.

y2

Set y2 to indicate the you want the series shown at the y2 axis (right-hand y axis).

plot <type=lines linecolor='blue'> rfy<dashtype='1'>, rfcp<dashtype='2'>, rfm<dashtype='3'>, rfe<dashtype='4'>;

plot rfy, rfcp, rfm, rfe using=p;

<gekkoplot>
  <type>lines</type>
  <linecolor>blue</linecolor>
  <lines>
    <line>
      <dashtype>1</dashtype>
    </line>
    <line>
      <dashtype>2</dashtype>
    </line>
    <line>
      <dashtype>3</dashtype>
    </line>
    <line>
      <dashtype>4</dashtype>
    </line>
  </lines>
</gekkoplot>

plot <p> x1, x2;

for %i = fY, fX, fE;
  plot {%i} file=graph_{%i};
end;

plot <plotcode = 'set xtics rotate by 90'> fy, fe, fcp;

p = series(1);  //definition of p!a
time 2010 2010;
p[1]=30763;p[2]=30245;p[3]=30815;p[4]=30148;p[5]=30128;p[6]=30025;p[7]=29782;p[8]=30081;p[9]=30949;p[10]=30662;
p[11]=31110;p[12]=31687;p[13]=32047;p[14]=33354;p[15]=33328;p[16]=32485;p[17]=32721;p[18]=31099;
p[19]=31014;p[20]=29813;p[21]=28828;p[22]=27482;p[23]=27095;p[24]=26161;p[25]=25148;p[26]=24692;
p[27]=25552;p[28]=25396;p[29]=27388;p[30]=28247;p[31]=29575;p[32]=29460;p[33]=31299;p[34]=33925;
p[35]=33371;p[36]=33795;p[37]=35484;p[38]=35658;p[39]=33441;p[40]=33635;p[41]=35034;p[42]=37751;
p[43]=40948;p[44]=39479;p[45]=38715;p[46]=37808;p[47]=35552;p[48]=34724;p[49]=34556;p[50]=33315;
p[51]=33557;p[52]=33536;p[53]=33749;p[54]=33433;p[55]=32546;p[56]=33232;p[57]=32415;p[58]=32114;
p[59]=32524;p[60]=32391;p[61]=34024;p[62]=36128;p[63]=37357;p[64]=35715;p[65]=33192;p[66]=29981;
p[67]=27998;p[68]=24250;p[69]=23210;p[70]=21832;p[71]=21054;p[72]=19568;p[73]=18497;p[74]=17021;
p[75]=15906;p[76]=14517;p[77]=13512;p[78]=12562;p[79]=11708;p[80]=10933;p[81]=10325;p[82]=8973;
p[83]=8333;p[84]=7341;p[85]=6515;p[86]=5397;p[87]=4546;p[88]=4041;p[89]=3310;p[90]=2351;p[91]=1872;
p[92]=1333;p[93]=1050;p[94]=720;p[95]=571;p[96]=367;p[97]=254;p[98]=160;p[99]=117;
time 2020 2020;
p[1]=27264;p[2]=26908;p[3]=27469;p[4]=26166;p[5]=25795;p[6]=25508;p[7]=26932;p[8]=27216;p[9]=29669;
p[10]=29818;p[11]=31033;p[12]=30449;p[13]=30993;p[14]=30335;p[15]=30378;p[16]=30302;p[17]=30028;
p[18]=30318;p[19]=31164;p[20]=30731;p[21]=31201;p[22]=31704;p[23]=31914;p[24]=33129;p[25]=32977;
p[26]=31932;p[27]=32133;p[28]=30374;p[29]=30287;p[30]=29122;p[31]=28110;p[32]=26856;p[33]=26424;
p[34]=25606;p[35]=24717;p[36]=24215;p[37]=25122;p[38]=25045;p[39]=26969;p[40]=27926;p[41]=29178;
p[42]=29110;p[43]=30941;p[44]=33585;p[45]=33056;p[46]=33317;p[47]=35020;p[48]=35098;p[49]=32844;p[50]=33005;
p[51]=34311;p[52]=36833;p[53]=39870;p[54]=38345;p[55]=37392;p[56]=36442;p[57]=33988;p[58]=33062;
p[59]=32753;p[60]=31330;p[61]=31473;p[62]=31238;p[63]=31115;p[64]=30537;p[65]=29512;p[66]=29949;
p[67]=28929;p[68]=28386;p[69]=28458;p[70]=27964;p[71]=29209;p[72]=30604;p[73]=31225;p[74]=29191;
p[75]=26370;p[76]=23418;p[77]=21426;p[78]=18105;p[79]=16738;p[80]=15133;p[81]=14107;p[82]=12447;
p[83]=10997;p[84]=9411;p[85]=8152;p[86]=6914;p[87]=5836;p[88]=4815;p[89]=3976;p[90]=3233;p[91]=2625;
p[92]=1976;p[93]=1552;p[94]=1110;p[95]=751;p[96]=483;p[97]=317;p[98]=220;p[99]=132;
time 2010 2020;
prt <n> p;
option freq u; //undated
time 1u 99u;
p = rotate(p!a, 1); //definition of p!u
#t = 2010, 2020; #t = #t.strings();
plot p[#t];