PLOT

<< Click to Display Table of Contents >>

Navigation:  Gekko commands >

PLOT

Previous pageReturn to chapter overviewNext 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.

 

You can create plots of variables with the PLOT command, see demo graphs. The PLOT arguments have the same syntax as PRT/MULPRT, SHEET and CLIP. You can store plot options/settings in external .gpt files, so that you can easily reuse the styling. PLOT uses the free open-source gnuplot 5.1 internally, and the settings/options of the PLOT command and corresponding .gpt files are named to match gnuplot naming conventions. PLOT can create an .emf, .svg, .png or .pdf file silently, if the FILE= option is used. The .emf files are practical for MS Office applications, including Word. The .svg format is practical for html pages, and should usually be preferred over .png for such pages. Gnuplot supports many output file formats (so-called 'terminals'), so more formats may be added if needed.

 

You may use <bank=... ref=...> to locally change the databanks used, instead of using OPEN and CLOSE.

 

Note: You may use the in-built XML Notepad editor to edit the .gpt files, cf. the XEDIT command. You can use a global .gpt file via "OPTION plot using = ... ;".

 

Note that Gekko 3.0 supports plotting (and printing) series with mixed frequencies.

 

PLOT uses the same internal component as PRT, so regarding operators and other details, also see the PRT help page.

 

 


 

Syntax

 

PLOT <period  operator   PLOTCODE=...  DUMP NOMAX mainOptions  BANK=...  REF=... MISSING=...>  elements   USING=...  FILE=... ;
 
 elements: element1, element2, ...
 
 element: expression  label <elementOptions>

 

If no period is given inside the <...> angle brackets, the global period is used (cf. TIME).

If a variable without databank indication is not found in the first-position databank, Gekko will look for it in other open databanks if databank search is active (cf. MODE).

The more general options shown above are the following (cf. the 'Main options' table below for all the plot-related options):

 

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.

PLOTCODE=

(Optional). The contents of this string must be gnuplot code (for instance 'set' commands separated by semicolon), and the contents is sent to gnuplot and inserted just before the gnuplot 'plot' statement.

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 command: 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 subseries and missing data values like GAMS, treating them as zero for sums and mathematical expressions, or skipping the printing of a subseries 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 be contain an absolute path like c:\projects\gekko\myfile, a relative path like \gekko\myfile.gbk, or be stated without a path. Filenames containing blanks and special characters should be put inside quotes. 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 be contain an absolute path like c:\projects\gekko\myfile, a relative path like \gekko\myfile.gbk, or be stated without a path. Filenames containing blanks and special characters should be put inside quotes. See more on filenames here.

 

 

You may use an operator to indicate which kind of data transformation you would like on your variables, for instance PLOT<d>, PLOT<q>, PLOT<pch>. As in the PRT command, you may also use element-specific operators (for instance PLOT unemp, gdp<p>;).  See the PRT command regarding the use of operators.

 

In addition to the above options, you may put graph-options inside either the main option field (PLOT <...>), or inside the element option fields (PLOT x1<...>, x2<...>). These options can alternatively be stored in an external xml-based .gpt file, for instance PLOT x1, x2 using=p; will use the file p.gpt to style the graph. The structure of the .gpt file corresponds to the distinction between PLOT main options and element options. Cf. the example section below.

 

Main options

 

Located inside the PLOT<...> option field, or in .gpt files directly inside the <gekkoplot> tag. The first column of the table is before the '=', and the second column of the table is after, for instance PLOT <type = linespoints>;. Some of the right-hand side expressions may require quotes around them, for instance PLOT<font = 'Verdana'>;, not PLOT<font = Verdana>;. If in doubt, try using quotes.

 

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]

arrow

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

 

 

 

Element options

 

Located in the element options, for instance PLOT x1<...>, x2<...>, or in .gpt files inside the <lines> tag (which contains <line> tags).

 

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

 

 

 


 

Example using PLOT options versus gpt file

 

For instance, you may produce a graph with dashed lines using this:

 

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

 

Here, in the main option field, the linetype is stated (type=lines), including the linecolor (color='blue'). These can also be stated individually in the elements options, if needed. In the element options, four dashtypes are given, for instance dashtype = '1'.

 

Instead of the above PLOT statement, you may use:

 

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

 

together with the following .gpt file (xml):

 

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

 

As you can see, the structure in the first PLOT statement corresponds to the structure of the .gpt file. You may also combine PLOT options and gpt files: in that case, the PLOT options will override the gpt options. So for instance, PLOT rfy, rfcp, rfm<color='red'>, rfe using=p; would make the third line red instead of blue.

 

 


 

Other examples

 

The command

 

PLOT <p> x1, x2;

 

plots percentage growth of the timeseries x1 and x2 from the first-position databank.

 

FOR %= fY, fX, fE;
  PLOT {%i} file=graph_{%i};
END;

 

This creates three graphs that are put into three different .emf files.

 

You may 'piggyback' gnuplot code along with the PLOT command, for instance:

 

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

 

This rotates the x-tic labels. If you need to state several gnuplot statements, you can separate them with ';'.

 

 

Age profiles

 

A special kind of plot shows the population of part of the population in age groups. If the annual array-series p!a is defined for different age-groups, for instance p[30] for 30-year olds, this array-series can be transformed via the rotate() function into another array-series p!u defined over the special 'undated' (u) frequency (now defined for different years like p!u[2020]).

 

= 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;
= rotate(p!a, 1); //definition of p!u
#= 2010, 2020; #= #t.strings();
plot p[#t];

 

This produces the following plot, with the age dimension on the x-axis.

 

clip0033

 

 


 

Plot file editor

 

At the moment, Gekko uses xml files to store the plot settings. In the longer run, another format might be chosen, and an graphical  interface to change these settings might be provided.

 

Until then, it is recommended that you use the in-built XML Notepad editor to edit the XML files, cf. the XEDIT command (if used, choose 'View' --> 'Expand All' to unfold all XML nodes). You may also use Notepad (cf. the EDIT command), but it is recommended to use a specific XML editor for editing the tables. Using a simple text editor like Notepad entails some potential problems; there will be no check that the XML syntax is correct. Also, the XML syntax represents some characters in a special way: notably the '<' , '>', and '&' characters (these should be written '&lt;', '&gt;', and '&amp;').

 

If the file is not in valid XML syntax, Gekko will complain that the file is invalid and abort.

 

 


 

Note

 

PLOT produces a graph by means of the open-source program gnuplot as an underlying engine. You do not need to install anything in order to use PLOT (the Gekko installation files contain gnuplot).

 

In the graph window, you may change the so-called operators by clicking on the radio buttons (or multiplier checkbox). This way, you can quickly change to for instance percentage growth rate etc. You may copy-paste the graph to e.g. a word-processor like Word by clicking the ‘Copy’ button. There are also options to save the graph as a emf/svg/png/pdf files.

 

You may close the PLOT graph window by pressing the 'Esc' button.

 

Per default, PLOT will place annual and undated data at the x-tics, and quarterly and monthly data between x-tics. See OPTION plot xlabels ... options, also if you prefer to use 15, 16, 17 etc., instead of 2015, 2016, 2017, etc.

 

Please note that the same graph may look different in different "environments". The Gekko graph window shows an .emf file, and the same .emf file may look a bit different when imported into Word (or converted to pdf or printed from Word). Also, a .svg version of the graph may look different in html. The differences apply to, for instance, dashed lines and fonts. Both .emf, .svg and .pdf are vector formats, whereas .png is a raster format (bitmap).

 

See the rotate() function if you need to plot for instance age profiles of array-series that are defined in the age dimension.

 

Planned enhancements:

 

Stacked curves and histograms shown as shares (summing to 1 or 100), perhaps using operator <s> for shares.

Indexed data, for instance showing all lines as index 2015=1, perhaps using operator <i> for index.

Options <a>, <ad>, and <ap> For instance, "PLOT<a>x1, x2;" would be the same as "PLOT x1, @x1, x2, @x2;", showing values from the Reference databank.

Multi-plots.

3D-plots.

Scatterplots.

Free-floating labels and arrows.

Outputting in more file formats like latex, etc.

It is the intention to make it possible to use R (using its plot function) as the graphing engine, too. Outputting R code instead of gnuplot code would not be too difficult. But gnuplot works ok, and is a small program that can be easily bundled with the Gekko package.

 

 


 

Related options

 

OPTION plot decimalseparator = period; [comma|period]

OPTION plot lines points = yes; [yes|no]

OPTION plot new = yes; [yes|no]

OPTION plot using = [filename];

OPTION plot xlabels annual = at; [at|between]

OPTION plot xlabels nonannual = between; [at|between]

OPTION plot xlabels digits = 4; [2|4]

 

 


 

Related commands

 

PRT, SHEET, CLIP, TABLE, XEDIT, EDIT, CUT