Chapter 6. Graphs and plots
40
6.2 Plotting graphs from scripts
When working with scripts, you may want to have a graph shown onto your display or savedinto a
file. In fact, if in your usual workflow you find yourself creating similar graphs over and over again,
you might want to consider the option of writing a script which automates this process for you.
Gretl gives you two main tools for doing this: one is a command called gnuplot, whose main use
is to create standard plot quickly. The other one is the plot command block, which has a more
elaborate syntax but offers you more control on output.
The gnuplot command
The gnuplot command is described at length in the Gretl Command Reference and the online help
system. Here, we just summarize its main features: basically, it consists of the gnuplot keyword,
followedby a list of items, telling the commandwhat you want plottedand a list ofoptions, telling
it how you want it plotted.
For example, the line
gnuplot y1 y2 x
will give you a basic XY plot of the two series y1 and y2 on the vertical axis versus the series x on
the horizontal axis. In general, the arguments to the gnuplot command is a list of series, the last
of which goes on the x-axis, while all the other ones go onto the y-axis. By default, the gnuplot
command gives you a scatterplot. If you just have one variable on the y-axis, then gretl will also
draw a the OLS interpolation, if the fit is good enough.2
Several aspects of the behavior describedabove can be modified. You do this by appending options
to the command. Most options can be broadly grouped in three categories:
1. Plot styles: we support points (the default choice), lines, lines and points together, and im-
pulses (vertical lines).
2. Algorithm for the fitted line: here you can choose between linear, quadratic and cubic inter-
polation, but also more exotic choices, such as semi-log, inverse or loess (non-parametric). Of
course, you can also turn this feature off.
3. Input and output: you can choose whether you want your graph on your computer screen
(and possibly use the in-built graphical widget to further customize it — see above, page37),
or rather save it to a file. We support several graphical formats, among which PNG and PDF,
to make it easy to incorporate your plots into text documents.
The following script uses the AWM dataset to exemplify some traditional plots in macroeconomics:
open AWM.gdt --quiet
# --- consumption and income, different styles ------------
gnuplot PCR YER
gnuplot PCR YER --output=display
gnuplot PCR YER --output=display --time-series
gnuplot PCR YER --output=display --time-series --with-lines
# --- Phillips’ curve, different fitted lines -------------
gnuplot INFQ URX --output=display
2
Thetechnical conditionforthis isthatthe two-tailed p-valuefortheslopecoefficientshouldbeunder 10%.
Convert pdf to powerpoint online no email - control application platform:C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF in C#.net, ASP.NET MVC, WinForms, WPF
Online C# Tutorial for Creating PDF from Microsoft PowerPoint Presentation
www.rasteredge.com
Convert pdf to powerpoint online no email - control application platform:VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to PDF in vb.net, ASP.NET MVC, WinForms, WPF
VB.NET Tutorial for Export PDF file from Microsoft Office PowerPoint
www.rasteredge.com
Chapter 6. Graphs and plots
41
gnuplot INFQ URX --suppress-fitted --output=display
gnuplot INFQ URX --inverse-fit --output=display
gnuplot INFQ URX --loess-fit --output=display
FIXME: comment on the above
For more detail, consult the Gretl Command Reference.
The plot command block
The plot environment is a way to pass information to Gnuplot in a more structured way, so that
customization of basic plots becomes easier. It has the following characteristics:
The block starts with the plot keyword, followed by a required parameter: the name of a list, a
single series or a matrix. This parameter specifies the data to be plotted. The starting line may be
prefixed with the savename <- apparatus to save a plot as an icon in the GUI program. The block
ends with end plot.
Inside the block you have zero or more lines of these types, identified by an initial keyword:
option: specify a single option (details below)
options: specify multiple options on a single line; if more than one option is given on a line, the
options should be separated by spaces.
literal: a command to be passed to gnuplot literally
printf: a printf statement whose result will be passed to gnuplot literally; this allows the use of
string variables without having to resort to @-style string substitution.
The options available are basically those of the current gnuplot command, but with a few dif-
ferences. For one thing you don’t need the leading double-dash in an "option" (or "options") line.
Besides that,
 You can’t use the option --matrix=whatever with plot: that possibility is handled by pro-
viding the name of a matrix on the initial plot line.
 The --input=filename option is not supported: use gnuplot for the case where you’re
supplying the entire plot specification yourself.
 The several options pertaining to the presence and type of a fitted line, are replaced in plot
by a single option fit which requires a parameter. Supported values for the parameter are:
none, linear, quadratic, cubic, inverse, semilog and loess. Example:
option fit=quadratic
As with gnuplot, the default is to show a linear fit in an X-Y scatter if it’s significant at the 10
percent level.
Here’s a simple example, the plot specification from the “bandplot” package, which shows how
to achieve the same result via the gnuplot command and a plot block, respectively—the latter
occupies a few more lines but is clearer
gnuplot 1 2 3 4 --with-lines --matrix=plotmat \
--suppress-fitted --output=display \
{ set linetype 3 lc rgb "#0000ff"; set title "@title"; \
set nokey; set xlabel "@xname"; }
control application platform:RasterEdge.com General FAQs for Products
Q3: Why there's no license information in my it via the email which RasterEdge's online store sends powerful & profession imaging controls, PDF document, image
www.rasteredge.com
control application platform:RasterEdge Product License Agreement
is active, you may contact RasterEdge via email. permitted by applicable law, in no event shall powerful & profession imaging controls, PDF document, tiff
www.rasteredge.com
Chapter 6. Graphs and plots
42
plot plotmat
options with-lines fit=none
literal set linetype 3 lc rgb "#0000ff"
literal set nokey
printf "set title \"%s\"", title
printf "set xlabel \"%s\"", xname
end plot --output=display
Note that --output=display is appended to end plot; also note that if you give a matrix to plot
it’sassumedyou want to plot all the columns. In addition, ifyou give a single series and the dataset
is time series, it’s assumed you want a time-series plot.
FIXME: provide an example with real data.
6.3 Boxplots
0
20000
40000
60000
80000
FAMINC
mean
Q3
Q1
median
minimum
maximum
outliers
Figure 6.3: Sample boxplot
These plots (after Tukey and Chambers) display the distribution of a variable. The central box
encloses the middle 50 percent of the data, i.e. it is bounded by the first and third quartiles. The
“whiskers” extendto from each end of theboxfora range equal to 1.5 times the interquartile range.
Observations outside that range are considered outliers and represented via dots.3 A line is drawn
across the box at the median and a “+” sign identifies the mean—see Figure6.3.
In the case ofboxplots with confidence intervals, dotted lines showthe limits of an approximate 90
percent confidence interval for the median. This is obtained by the bootstrap method, which can
take a while if the data series is very long. For details on constructing boxplots, see the entry for
boxplot in the Gretl Command Reference or use the Help button that appears when you select one
of the boxplot items under the menu item “View, Graph specified vars” in the main gretl window.
3
To give youanintuitiveidea, ifa variableisnormallydistributed, the chancesofpicking an outlier by thisdefinition
areslightlybelow0.7%.
control application platform:VB.NET Create PDF from Excel Library to convert xlsx, xls to PDF
VB.NET How-to, VB.NET PDF, VB.NET Word, VB.NET Excel, VB.NET PowerPoint, VB.NET Tiff, VB.NET Imaging, VB.NET OCR, VB.NET Convert Excel to PDF document free
www.rasteredge.com
control application platform:C# Create PDF from Excel Library to convert xlsx, xls to PDF in C#
or no border. Free online Excel to PDF converter without email. Quick integrate online C# source code into .NET class. C# Demo Code: Convert Excel to PDF in
www.rasteredge.com
Chapter 6. Graphs and plots
43
Factorized boxplots
Anice feature which is quite useful for data visualization is the conditional, or factorized boxplot.
This type of plot allows you to examine the distribution of a variable conditional on the value of
some discrete factor.
As an example, we’ll use one of the datasets supplied with gretl, that is rac3d, which contains an
example taken fromCameronandTrivedi(2013) on the health conditions of 5190 people. The
script below compares the unconditional (marginal) distribution of the number of illnesses in the
past 2 weeks with the distribution of the same variable, conditional on age classes.
open rac3d.gdt
# unconditional boxplot
boxplot ILLNESS --output=display
# create a discrete variable for age class:
# 0 = below 20, 1 = between 20 and 39, etc
series age_class = floor(AGE/0.2)
# conditional boxplot
boxplot ILLNESS age_class --factorized --output=display
After running the code above, you should see two graphs similar to Figure6.4. By comparing the
marginal plot to the factorized one, the effect of age on the mean number of illnesses is quite
evident: by joining the green crosses you get what is technically known as the conditional mean
function, or regression function if you prefer.
0
1
2
3
4
5
ILLNESS
0
1
2
3
4
5
0
1
2
3
ILLNESS
age_class
Distribution of ILLNESS by age_class
Figure 6.4: Conditional and unconditional distribution of illnesses
control application platform:VB.NET Image: RasterEdge JBIG2 Codec Image Control for VB.NET
The encoded images in PDF file can also be viewed and processed online through our VB.NET PDF web viewer. No, image quality will not degrade.
www.rasteredge.com
control application platform:C#: Frequently Asked Questions for Using XDoc.HTML5 Viewer for .
If you have additional questions or requests, please send email to support@rasteredge. com. The site configured in IIS has no permission to operate.
www.rasteredge.com
Chapter 7
Joining data sources
7.1 Introduction
Gretl provides two commands for adding data from file to an existing dataset in the program’s
workspace, namely append and join. The append command, which has been available for a long
time, is relatively simple and is described in the Gretl Command Reference. Here we focus on the
join command, which is much more flexible and sophisticated. This chapter gives an overview
of the functionality of join along with a detailed account of its syntax and options. We provide
several toy examples and discuss one real-world case at length.
First, a note on terminology: in the following we use the terms “left-hand” and “inner” to refer
to the dataset that is already in memory, and the terms “right-hand” and “outer” to refer to the
dataset in the file from which additional data are to be drawn.
Two main features ofjoin are worth emphasizing at the outset:
 “Key” variables can be used to match specific observations (rows) in the inner and outer
datasets, and this match need not be 1 to 1.
 A row filter may be applied to screen out unwanted observations in the outer dataset.
As will be explained below, these features support rather complexconcatenation andmanipulation
of data from different sources.
Afurther aspect ofjoin should be noted—one that makes this commandparticularly useful when
dealing with very large data files. That is, when gretl executes a join operation it does not, in gen-
eral, read into memory the entire content of the right-hand side dataset. Only those columns that
are actually needed for the operation are read in full. This makes join faster and less demanding
of computer memory than the methods available in most other software. On the other hand, gretl’s
asymmetrical treatment of the “inner” and “outer” datasets in join may require some getting used
to, for users of other packages.
7.2 Basic syntax
The minimal invocation of join is
join filename varname
where filename is the name of a data file and varname is the name of a series to be imported.
Only two sorts of data file are supported at present: delimited text files (where the delimiter may
be comma, space, tab or semicolon) and “native” gretl data files (gdt or gdtb). A series named
varname may already be present in the left-hand dataset, but that is not required. The series to be
imported may be numerical or string-valued. For most ofthe discussion belowwe assume that just
asingle series is imported by each join command, but see section7.7 for an account of multiple
imports.
The effect of the minimal version of join is this: gretl looks for a data column labeled varname in
the specified file; if such a column is found and the number of observations on the right matches
the number of observations in the current sample range on the left, then the values from the right
are copied into the relevant range of observations on the left. If varname does not already exist
44
control application platform:C# Tiff Convert: How to Convert Dicom to Tiff Image File
If you need to convert and change one image to another image in C# program, there would be no need for RasterEdge.XDoc.PDF.dll. RasterEdge.XDoc.PowerPoint.dll.
www.rasteredge.com
control application platform:RasterEdge Product License Options
Among all listed products on purchase page, Twain SDK has no Server License and only SDK To know more details or make an order, please contact us via email.
www.rasteredge.com
Chapter 7. Joining data sources
45
on the left, any observations outside of the current sample are set to NA; if it exists already then
observations outside of the current sample are left unchanged.
The case whereyou want to rename a serieson import ishandledby the --data option. Thisoption
has one required argument, the name by which the series is known on the right. At this point we
need to explain something about right-hand variable names (column headings).
Right-hand names
We accept on input arbitrary column heading strings, but if these strings do not qualify as valid
gretl identifiers they are automatically converted, and in the context of join you must use the
converted names. A gretl identifier must start with a letter, contain nothing but (ASCII) letters,
digits and the underscore character, and must not exceed 31 characters. The rules used in name
conversion are:
1. Skip any leading non-letters.
2. Until the 31-character is reached or the input is exhausted: transcribe “legal” characters; skip
“illegal” characters apart from spaces; and replace one or more consecutive spaces with an
underscore, unless the last character transcribed is an underscore in which case space is
skipped.
In the unlikely event that this policy yields an empty string, we replace the original with coln,
where n is replaced by the 1-based index of the column in question among those used in the
join operation. If you are in doubt regarding the converted name of a given column, the function
fixname() can be used as a check: it takes the original string as an argument and returns the
converted name. Examples:
? eval fixname("valid_identifier")
valid_identifier
? eval fixname("12. Some name")
Some_name
Returning to the use of the --data option, suppose we have a column headed "12. Some name"
on the right and wish to import it as x. After figuring how the right-handname converts, we can do
join foo.csv x --data="Some_name"
No right-hand names?
Some data files have no column headings; they jump straight into the data (and you need to deter-
mine from accompanying documentation what the columns represent). Since gretl expects column
headings, you have to take steps to get the importation right. It is generally a goodidea to insert a
suitable header row into the data file. However, if for some reason that’s not practical, you should
give the --no-header option, in which case gretl will name the columns on the right as col1, col2
and so on. If you do not do either of these things you will likely lose the first row of data, since
gretl will attempt to make variable names out of it, as described above.
7.3 Filtering
Rows from the outer dataset can be filtered using the --filter option. The required parameter
for this option is a Boolean condition, that is, an expression which evaluates to non-zero (true,
include the row) or zero (false, skip the row) for each of the outer rows. The filter expression may
include any of the following terms: up to three “right-hand” series (under their converted names as
Chapter 7. Joining data sources
46
explainedabove); scalar or stringvariablesdefined “on the left”; any ofthe operators andfunctions
available in gretl (including user-defined functions); and numeric or string constants.
Here are a few simple examples of potentially validfilter options (assuming that the specified right-
hand side columns are found):
# 1. relationship between two right-hand variables
--filter="x15<=x17"
# 2. comparison of right-hand variable with constant
--filter="nkids>2"
# 3. comparison of string-valued right-hand variable with string constant
--filter="SEX==\"F\""
# 4. filter on valid values of a right-hand variable
--filter=!missing(income)
# 5. compound condition
--filter="x < 100 && (x > 0 || y > 0)"
Note that if you are comparing against a string constant (as in example 3 above) it is necessary
to put the string in “escaped” double-quotes (each double-quote preceded by a backslash) so the
interpreter knows that F is not supposed to be the name of a variable.
It is safest to enclose the whole filter expression in double quotes, however this is not strictly
required unless the expression contains spaces or the equals sign.
In general, an error is flagged if a missing value is encountered in a series referenced in a filter
expression. This is because the condition then becomes indeterminate; taking example 2 above, if
the nkids value is NA on any given row we are not in a position to evaluate the condition nkids>2.
However, you can use the missing() function—or ok(),which is a shorthand for !missing()—if
you need a filter that keys off the missing or non-missing status of a variable.
7.4 Matching with keys
Things get interesting when we come to key-matching. The purpose of this facility is perhaps best
introduced by example. Suppose that (as with many survey and census-based datasets) we have a
dataset that is composed of two or more related files, each having a different unit of observation;
for example we have a “persons” data file and a “households” data file. Table7.1 shows a simple,
artificial case. The file people.csv contains a unique identifier for the individuals, pid. The
households file, hholds.csv, contains the unique household identifier hid, which is also present
in the persons file.
As a first example of join with keys, let’s add the household-level variable xh to the persons
dataset:
open people.csv --quiet
join hholds.csv xh --ikey=hid
print --byobs
The basic key option isnamedikey; this indicates “inner key”, that is, the key variable found in the
left-hand or inner dataset. By default it isassumed that theright-handdataset contains a column of
the same name, though as we’ll see below that assumption can be overridden. The join command
above says, find a series named xh in the right-hand dataset and add it to the left-hand one, using
the values of hid to match rows. Looking at the data in Table 7.1 we can see how this should
work. Persons 1 and 2 are both members of household 1, so they should both get values of 1 for
xh; persons 3 and 4 are members of household 2, so that xh = 4; and so on. Note that the order
Chapter 7. Joining data sources
47
in which the key values occur on the right-hand side does not matter. The gretl output from the
print command is shown in the lower panel of Table7.1.
people.csv
hholds.csv
pid,hid,gender,age,xp
hid,country,xh
1,1,M,50,1
1,US,1
2,1,F,40,2
6,IT,12
3,2,M,30,3
3,UK,6
4,2,F,25,2
4,IT,8
5,3,M,40,3
2,US,4
6,4,F,35,4
5,IT,10
7,4,M,70,3
8,4,F,60,3
9,5,F,20,4
10,6,M,40,4
pid
hid
xh
1
1
1
2
1
1
3
2
4
4
2
4
5
3
6
6
4
8
7
4
8
8
4
8
9
5
10
10
6
12
Table 7.1: Two linked CSV data files,andthe effect of a join
Note that key variables are treated conceptually as integers. If a specified key contains fractional
values these are truncated.
Two extensions of the basic key mechanism are available.
 If the outer dataset contains a relevant key variable but it goes under a different name from
the inner key, you can use the --okey option to specify the outer key. (As with other right-
hand names, this does not have to be a valid gretl identifier.) So, for example, if hholds.csv
contained the hid information, but under the name HHOLD, the join command above could
be modifiedas
join hholds.csv xh --ikey=hid --okey=HHOLD
 Ifa single key isnot sufficient to generate the matchesyou want, you can specify a double key
in the form of two series names separatedby a comma; in this case the importation of data is
restricted to those rows on which both keys match. The syntax here is, for example
join foo.csv x --ikey=key1,key2
Again, the --okey option may be used if the corresponding right-hand columns are named
differently. The same number of keys must be given on the left and the right, but when a
Chapter 7. Joining data sources
48
double key is used and only one of the key names differs on the right, the name that is in
common may be omitted (although the comma separator must be retained). For example, the
second of the following lines is acceptable shorthand for the first:
join foo.csv x --ikey=key1,Lkey2 --okey=key1,Rkey2
join foo.csv x --ikey=key1,Lkey2 --okey=,Rkey2
The number of key-matches
The example shown in Table7.1 is an instance of a 1 to 1 match: applying the matching criterion
produces exactly one value of the variable xh corresponding to each row of the inner dataset. Two
other possibilities arise: it may be that some rows in the inner dataset have no match on the right,
and/orsome rowson the left have multiplematcheson the right. Thelattercase (“1 to nmatching”)
is addressed in detail in the next section; here we discuss the former.
The case where there’s no match on the right is handled differently depending on whether the join
operation is adding a new series to the inner dataset or modifying an existing one. If it’s a new
series, then the unmatched rows automatically get NA for the imported data. If, on the other hand,
the join is pulling in values for a series that is already present on the left, only matched rows will
be updated—or in other words, we do not overwite an existing value on the left with NA in the case
where there’s no match on the right.
These defaults may not produce the desired results in every case but gretl provides the means to
modify the effect if need be. We will illustrate with two scenarios.
First, consider adding a new series recording “number of hours worked” when the inner dataset
contains individuals and the outer file contains data on jobs. If an individual does not appear in
the jobs file, we may want to take her hours worked as implicitly zero rather than NA. In this case
gretl’s misszero() function can be used to turn NA into 0 in the imported series.
Second, consider updating a series via join, when the outer file is presumedto contain all available
updated values, such that “no match” should be taken as an implicit NA. In this case we want the
(presumably out-of-date) values on any unmatched rows to be overwritten with NA. Let the series
in question be called x (both on the left and the right) and let the common key be called pid. The
solution is then
join update.csv tmpvar --data=x --ikey=pid
x = tmpvar
As a new variable, tmpvar will get NA for all unmatched rows; we then transcribe its values into
x. In a more complicated case one might use the smpl command to limit the sample range before
assigning tmpvar to x, or use the conditional assignment operator ?:.
One further point should be mentioned here. Given some missing values in an imported series you
may sometimes want to know whether (a) the NAs were explicitly represented in the outer data file
or (b) they arose due to “no match”. You can find this out by using a method described in the
following section, namely the count variant of the aggregation option: this will give you a series
with 0 values for all and only unmatched rows.
7.5 Aggregation
In the case of 1 to n matching of rows (n >1) the user must specify an “aggregation method”; that
is, a method for mapping from n rows down to one. This is handled by the --aggr option which
requires a single argument from the following list:
Chapter 7. Joining data sources
49
Code
Value returned
count
count of matches
avg
mean of matching values
sum
sum of matching values
min
minimum of matching values
max
maximum of matching values
seq:i
the i
th
matching value (e.g. seq:2)
min(aux)
minimum of matching values of auxiliary variable
max(aux)
maximum of matching values of auxiliary variable
Note that the count aggregation method is special, in that there is no need for a “data series” on
the right; the imported series is simply a function of the specified key(s). All the other methods
require that “actual data” are found on the right. Also note that when count is used, the value
returned when no match is found is (as one might expect) zero rather than NA.
The basicuse ofthe seq methodis shown above: following the colon you givea positive integer rep-
resenting the (1-based) position of the observation in the sequence of matched rows. Alternatively,
anegative integer can be used to count down from the last match (seq:-1 selects the last match,
seq:-2 the second-last match, and so on). If the specified sequence number is out of bounds for a
given observation this method returns NA.
Referring again to the data in Table7.1, suppose we want to import data from the persons file into
adataset established at household level. Here’s an example where we use the individual age data
from people.csv to add the average andminimum age of household members.
open hholds.csv --quiet
join people.csv avgage --ikey=hid --data=age --aggr=avg
join people.csv minage --ikey=hid --data=age --aggr=min
Here’sa further example where we addto the household data the sum of the personal data xp, with
the twist that we apply filters to get the sum specifically for household members under the age of
40, and for women.
open hholds.csv --quiet
join people.csv young_xp --ikey=hid --filter="age<40" --data=xp --aggr=sum
join people.csv female_xp --ikey=hid --filter="gender==\"F\"" --data=xp --aggr=sum
The possibility ofusing an auxiliary variable with the min andmax modes of aggregation givesextra
flexibility. For example, suppose we want for each householdthe income of its oldest member:
open hholds.csv --quiet
join people.csv oldest_xp --ikey=hid --data=xp --aggr=max(age)
7.6 String-valued key variables
The examples above use numerical variables (household and individual ID numbers) in the match-
ing process. It is also possible to use string-valued variables, in which case a match means that the
string values of the key variables compare equal (with case sensitivity). When using double keys,
you can mix numerical and string keys, but naturally you cannot mix a string variable on the left
(via ikey) with a numerical one on the right (via okey), or vice versa.
Here’s a simple example. Suppose that alongside hholds.csv we have a file countries.csv with
the following content:
Documents you may be interested
Documents you may be interested