14
13
\subsection{Creating and modifying named lists}
16
15
A named list is created using the keyword \texttt{list}, followed by
17
the name of the list, an equals sign, and either \texttt{null} (to
18
create an empty list) or one or more variables to be placed on the
16
the name of the list, an equals sign, and an expression that forms a
17
list. The most basic sort of expression that works in this context
18
is a space-separated list of variables, given either by name or
19
by ID number. For example,
22
22
list xlist = 1 2 3 4
23
23
list reglist = income price
24
list empty_list = null
26
Note that the variables in question must be of the series type: you
27
cannot include scalars in a named list.
29
Two abbreviations are available in defining lists:
31
\item You can use the wildcard character, ``\texttt{*}'', to create a
32
list of variables by name. For example, \texttt{dum*} can be used to
33
indicate all variables whose names begin with \texttt{dum}.
34
\item You can use two dots to indicate a range of variables. For
35
example \texttt{income..price} indicates the set of variables whose
36
ID numbers are greater than or equal to that of \texttt{income}
37
and less than or equal to that of \texttt{price}.
40
In addition there are two special forms:
42
\item If you use the keyword \texttt{null} on the right-hand side,
43
you get an empty list.
44
\item If you use the keyword \texttt{dataset} on the right, you get
45
a list containing all the series in the current dataset (except
46
the pre-defined \texttt{const}).
27
49
The name of the list must start with a letter, and must be composed
28
50
entirely of letters, numbers or the underscore character. The maximum
29
51
length of the name is 15 characters; list names cannot contain
30
spaces. When adding variables to a list, you can refer to them either
31
by name or by their ID numbers.
33
54
Once a named list has been created, it will be ``remembered'' for the
34
duration of the \app{gretl} session, and can be used in the context of
35
any \app{gretl} command where a list of variables is expected. One
36
simple example is the specification of a list of regressors:
55
duration of the \app{gretl} session (unless you delete it), and can be
56
used in the context of any \app{gretl} command where a list of
57
variables is expected. One simple example is the specification of a
39
61
list xlist = x1 x2 x3 x4
43
Lists can be modified in two ways. To \textit{redefine} an existing
65
To get rid of a list, you use the following syntax:
69
Be careful: \texttt{delete xlist} will delete the variables contained
70
in the list, so it implies data loss (which may not be what you want).
71
On the other hand, \texttt{list xlist delete} will simply ``undefine''
72
the \texttt{xlist} identifier and the variables themselves will not be
75
Similarly, to print the names of the variables in a list you have to
76
invert the usual print command, as in
80
If you just say \texttt{print xlist} the list will be expanded and
81
the values of all the member variables will be printed.
83
Lists can be modified in various ways. To \textit{redefine} an existing
44
84
list altogether, use the same syntax as for creating a list. For
52
92
After the second assignment, \texttt{xlist} contains just variables 4,
55
95
To \textit{append} or \textit{prepend} variables to an existing list,
56
we simply make use of the fact that a named list can stand in for a
96
we can make use of the fact that a named list stands in for a
57
97
``longhand'' list. For example, we can do
60
100
list xlist = xlist 5 6 7
61
list xlist = 9 10 xlist 11 12
101
xlist = 9 10 xlist 11 12
104
Another option for appending a term (or a list) to an existing list is
105
to use \texttt{+=}, as in
111
To drop a variable from a list, use \texttt{-=}:
118
In most contexts where lists are used in \app{gretl}, it is expected
119
that they do not contain any duplicated elements. If you form a new
120
list by simple concatenation, as in \texttt{list L3 = L1 L2}
121
(where \texttt{L1} and \texttt{L2} are existing lists), it's possible
122
that the result may contain duplicates. To guard against this you can
123
form a new list as the union of two existing ones:
129
The result is a list that contains all the members of \texttt{L1},
130
plus any members of \texttt{L2} that are not already in \texttt{L1}.
132
In the same vein, you can construct a new list as the intersection of
139
Here \texttt{L3} contains all the elements that are present in both
140
\texttt{L1} and \texttt{L2}.
142
You can also subtract one list from another:
148
The result contains all the elements of \texttt{L1} that are not
149
present in \texttt{L2}.
152
\subsection{Lists and matrices}
154
Another way of forming a list is by assignment from a matrix. The
155
matrix in question must be interpretable as a vector containing ID
156
numbers of (series) variables. It may be either a row or a column
157
vector, and each of its elements must have an integer part that is
158
no greater than the number of variables in the data set. For example:
165
The above is OK provided the data set contains at least 4 variables.
64
167
\subsection{Querying a list}
86
189
list xlist = 1 2 3
87
genr nl = nelem(xlist)
90
The scalar \texttt{nl} will be assigned a value of 3 since
193
The (scalar) variable \texttt{nl} will be assigned a value of 3 since
91
194
\texttt{xlist} contains 3 members.
93
You can display the membership of a named list as illustrated in this
196
You can determine whether a given series is a member of a specified
197
list using the function \texttt{inlist()}, as in
97
? list xlist = x1 x2 x3
200
scalar k = inlist(L, y)
103
Note that \texttt{print xlist} will do something different, namely
104
print the values of all the variables in \texttt{xlist} (as should be
203
where \texttt{L} is a list and \texttt{y} a series. The series may
204
be specified by name or ID number. The return value is the (1-based)
205
position of the series in the list, or zero if the series is not
107
208
\subsection{Generating lists of transformed variables}
109
210
Given a named list of variables, you are able to generate lists of
110
transformations of these variables using a special form of the
111
commands \texttt{logs}, \texttt{lags}, \texttt{diff}, \texttt{ldiff},
112
\texttt{sdiff} or \texttt{square}. In this context these keywords
113
must be followed directly by a named list in parentheses. For example
211
transformations of these variables using the functions \texttt{log},
212
\texttt{lags}, \texttt{diff}, \texttt{ldiff}, \texttt{sdiff} or
213
\texttt{dummify}. For example
116
216
list xlist = x1 x2 x3
117
list lxlist = logs(xlist)
217
list lxlist = log(xlist)
118
218
list difflist = diff(xlist)
121
When generating a list of \textit{lags} in this way, you can specify
122
the maximum lag order inside the parentheses, before the list name and
221
When generating a list of \textit{lags} in this way, you specify the
222
maximum lag order inside the parentheses, before the list name and
123
223
separated by a comma. For example
134
234
list laglist = lags(order, xlist)
137
These command will populate \texttt{laglist} with the specified number
138
of lags of the variables in \texttt{xlist}. (As with the ordinary
139
\texttt{lags} command, you can omit the order, in which case this is
140
determined automatically based on the frequency of the data.) One
141
further special feature is available when generating lags, namely, you
142
can give the name of a single variable in place of a named list on the
143
right-hand side, as in
147
list laglist = lags(4, lx)
150
Note that the ordinary syntax for, e.g., \texttt{logs}, is just
156
If \texttt{xlist} is a named list, you can also say
162
but this form will not save the logs as a named list; for that you
166
list loglist = logs(xlist)
170
\subsection{Checking for missing values}
172
\app{Gretl} offers several functions for recognizing and handling
173
missing values (see the \GCR{} for details). In this context it is
237
These commands will populate \texttt{laglist} with the specified
238
number of lags of the variables in \texttt{xlist}. You can give the
239
name of a single series in place of a list as the second argument to
240
\texttt{lags}: this is equivalent to giving a list with just one
243
The \texttt{dummify} function creates a set of dummy variables coding
244
for all but one of the distinct values taken on by the original
245
variable, which should be discrete. (The smallest value is taken as
246
the omitted catgory.) Like lags, this function returns a list even if
247
the input is a single series.
250
\subsection{Generating series from lists}
252
Once a list is defined, \app{gretl} offers several functions that
253
apply to the list and return a series. In most cases, these functions
254
also apply to single series and behave as natural extensions when
255
applied to a list, but this is not always the case.
257
For recognizing and handling missing values, \app{Gretl} offers
258
several functions (see the \GCR{} for details). In this context, it is
174
259
worth remarking that the \texttt{ok()} function can be used with a
175
260
list argument. For example,
184
269
\texttt{x3} has a missing value, and value 0 for any observations
185
270
where this condition is not met.
272
The functions \texttt{max}, \texttt{min}, \texttt{mean}, \texttt{sd},
273
\texttt{sum} and \texttt{var} behave horizontally rather than
274
vertically when their argument is a list. For instance, the following
277
list Xlist = x1 x2 x3
278
series m = mean(Xlist)
280
produce a series \texttt{m} whose $i$-th element is the average of
281
$x_{1,i}, x_{2,i}$ and $x_{3,i}$; missing values, if any, are implicitly discarded.
285
\begin{tabular}{lllllllll}
287
& YpcFR & YpcGE & YpcIT & NFR & NGE & NIT \\
290
1997 & 114.9 & 124.6 & 119.3 & 59830.635 & 82034.771 & 56890.372 \\
291
1998 & 115.3 & 122.7 & 120.0 & 60046.709 & 82047.195 & 56906.744 \\
292
1999 & 115.0 & 122.4 & 117.8 & 60348.255 & 82100.243 & 56916.317 \\
293
2000 & 115.6 & 118.8 & 117.2 & 60750.876 & 82211.508 & 56942.108 \\
294
2001 & 116.0 & 116.9 & 118.1 & 61181.560 & 82349.925 & 56977.217 \\
295
2002 & 116.3 & 115.5 & 112.2 & 61615.562 & 82488.495 & 57157.406 \\
296
2003 & 112.1 & 116.9 & 111.0 & 62041.798 & 82534.176 & 57604.658 \\
297
2004 & 110.3 & 116.6 & 106.9 & 62444.707 & 82516.260 & 58175.310 \\
298
2005 & 112.4 & 115.1 & 105.1 & 62818.185 & 82469.422 & 58607.043 \\
299
2006 & 111.9 & 114.2 & 103.3 & 63195.457 & 82376.451 & 58941.499 \\
302
\caption{GDP per capita and population in 3 European countries (Source: Eurostat)}
305
In addition, \app{gretl} provides three functions for weighted
306
operations: \texttt{wmean}, \texttt{wsd} and \texttt{wvar}. Consider
307
as an illustration Table \ref{tab:EuroData}: the first three columns are GDP
308
per capita for France, Germany and Italy; columns 4 to 6 contain the
309
population for each country. If we want to compute an aggregate
310
indicator of per capita GDP, all we have to do is
312
list Ypc = YpcFR YpcGE YpcIT
318
y_{1996} = \frac{114.9 \times 59830.635 + 124.6 \times 82034.771 +
319
119.3 \times 56890.372} {59830.635 + 82034.771 + 56890.372} =
322
See the \GCR\ for more details.
188
324
\section{Named strings}
189
\label{named-strings}
325
\label{sec:named-strings}
191
327
For some purposes it may be useful to save a string (that is, a
192
328
sequence of characters) as a named variable that can be reused.
193
329
Versions of \app{gretl} higher than 1.6.0 offer this facility, but
194
330
some of the refinements noted below are available only in \app{gretl}
197
333
To \textit{define} a string variable, you can use either of two
198
334
commands, \texttt{string} or \texttt{sprintf}. The \texttt{string}
199
command is simpler: you just type, for example,
335
command is simpler: you can type, for example,
202
string foo = "some stuff I want to save"
338
string s1 = "some stuff I want to save"
339
string s2 = getenv("HOME")
205
343
The first field after \texttt{string} is the name under which the
206
string should be saved, then comes an equals sign, then comes the
207
string to be saved, enclosed in double quotes. The latter can be
208
represented as a sequence of sub-strings if need be, as in
211
string bits = "first " "and" " second"
214
See below for further variants of the string command, including use of
344
string should be saved, then comes an equals sign, then comes a
345
specification of the string to be saved. This can be the keyword
346
\texttt{null}, to produce an empty string, or may take any of the
350
\item a string literal (enclosed in double quotes); or
351
\item the name of an existing string variable; or
352
\item a function that returns a string (see below); or
353
\item any of the above followed by \texttt{+} and an integer offset.
356
The role of the integer offset is to use a substring of the preceding
357
element, starting at the given character offset. An empty string is
358
returned if the offset is greater than the length of the string in
361
To add to the end of an existing string you can use the operator
365
string s1 = "some stuff I want to "
368
or you can use the \verb|~| operator to join two or more strings, as
372
string s2 = "Home, " ~ s1 ~ " home."
375
Note that when you define a string variable using a string literal, no
376
characters are treated as ``special'' (other than the double quotes
377
that delimit the string). Specifically, the backslash is not used as
378
an escape character. So, for example,
384
is a valid assignment, producing a string that contains a single
385
backslash character. If you wish to use backslash-escapes to denote
386
newlines, tabs, embedded double-quotes and so on, use \texttt{sprintf}
217
389
The \texttt{sprintf} command is more flexible. It works exactly as
218
390
\app{gretl}'s \texttt{printf} command except that the ``format''
224
396
sprintf foo "var%d", x
227
To \textit{retrieve the value} of a string variable, you give the name
228
of the variable preceded by the ``at'' sign, \verb|@|.
230
In most contexts, the \verb|@| notation is treated as a ``macro''.
231
That is, if a sequence of characters in a \app{gretl} command
232
following the symbol \verb|@| is recognized as the name of a string
233
variable, the value of that variable is sustituted literally into the
234
command line before the regular parsing of the command is
235
carried out. This is illustrated in the following interactive
399
To use the \emph{value} of a string variable in a command, give the
400
name of the variable preceded by the ``at'' sign, \verb|@|. This
401
notation is treated as a ``macro''. That is, if a sequence of
402
characters in a \app{gretl} command following the symbol \verb|@| is
403
recognized as the name of a string variable, the value of that
404
variable is sustituted literally into the command line before the
405
regular parsing of the command is carried out. This is illustrated in
406
the following interactive session:
262
432
It would therefore print the value(s) of the variable \texttt{var8},
263
433
if such a variable exists, or would generate an error otherwise.
265
In certain specific contexts, however, it is natural to treat
266
\verb|@|-variables as variables in their own right, and \app{gretl}
267
does so. These contexts are:
435
In some contexts, however, one wants to treat string variables as
436
variables in their own right: to do this, give the name of
437
the variable without the leading \verb|@| symbol. This is the
438
way to handle such variables in the following contexts:
269
441
\item When they appear among the arguments to the commands \texttt{printf} and
270
442
\texttt{sprintf}.
271
443
\item On the right-hand side of a \texttt{string} assignment.
272
\item When they appear as an argument to the function
273
\texttt{isstring} (see below).
444
\item When they appear as an argument to the function taking
276
448
Here is an illustration of the use of named string arguments with
280
? string vstr = "variance"
281
Saved string as 'vstr'
282
? printf "vstr: %12s\n", @vstr
452
string vstr = "variance"
453
Generated string vstr
454
printf "vstr: %12s\n", vstr
286
Note that \verb|@vstr| should not be put in quotes in this context.
458
Note that \texttt{vstr} should not be put in quotes in this context.
289
? string copy = @vstr
461
? string vstr_copy = vstr
292
464
\subsection{Built-in strings}
294
466
Apart from any strings that the user may define, some string variables
295
467
are defined by \app{gretl} itself. These may be useful for people
296
468
writing functions that include shell commands. The built-in strings
297
are as shown in Table~\ref{tab-strings}.
469
are as shown in Table~\ref{tab:pred-strings}.
299
471
\begin{table}[htbp]
301
473
\begin{tabular}{ll}
302
\verb|@gretldir| & the \app{gretl} installation directory \\
303
\verb|@userdir| & user's \app{gretl} directory \\
304
\verb|@gnuplot| & path to, or name of, the \app{gnuplot} executable \\
305
\verb|@tramo|& path to, or name of, the \app{tramo} executable \\
306
\verb|@x12a| & path to, or name of, the \app{x-12-arima} executable \\
307
\verb|@tramodir| & \app{tramo} data directory \\
308
\verb|@x12adir| & \app{x-12-arima} data directory \\
474
\texttt{gretldir} & the \app{gretl} installation directory \\
475
\texttt{workdir} & user's current \app{gretl} working directory \\
476
\texttt{dotdir} & the directory \app{gretl} uses for temporary files \\
477
\texttt{gnuplot} & path to, or name of, the \app{gnuplot} executable \\
478
\texttt{tramo}& path to, or name of, the \app{tramo} executable \\
479
\texttt{x12a} & path to, or name of, the \app{x-12-arima} executable \\
480
\texttt{tramodir} & \app{tramo} data directory \\
481
\texttt{x12adir} & \app{x-12-arima} data directory \\
310
483
\caption{Built-in string variables}
484
\label{tab:pred-strings}
314
487
\subsection{Reading strings from the environment}
330
503
To check whether you got a non-empty value from a given call to
331
\texttt{getenv}, you can use the function \texttt{isstring}, as in
504
\texttt{getenv}, you can use the function \texttt{strlen}, which
505
retrieves the length of the string, as in
334
508
? string temp = getenv("TEMP")
335
509
Saved empty string as 'temp'
336
? scalar x = isstring(@temp)
510
? scalar x = strlen(temp)
337
511
Generated scalar x (ID 2) = 0
340
Note that \texttt{isstring} is really shorthand for ``is a string that
341
actually contains something''.
514
The function \texttt{isstring} returns 1 if its argument is the name
515
of a string variable, 0 otherwise. However, if the return is 1
516
the string may still be empty.
343
518
At present the \texttt{getenv} function can only be used on the
344
519
right-hand side of a \texttt{string} assignment, as in the above
522
\subsection{Capturing strings via the shell}
524
If shell commands are enabled in \app{gretl}, you can capture the
525
output from such commands using the syntax
527
\texttt{string} \textsl{stringname} = \texttt{\$(}\textsl{shellcommand}\texttt{)}
529
That is, you enclose a shell command in parentheses, preceded by
532
\subsection{Reading from a file into a string}
534
You can read the content of a file into a string variable using
537
\texttt{string} \textsl{stringname} = \texttt{readfile(}\textsl{filename}\texttt{)}
539
The \textsl{filename} field may be given as a string variable. For
543
? sprintf fname "%s/QNC.rts", x12adir
544
Generated string fname
545
? string foo = readfile(fname)
549
The above could also be accomplished using the ``macro'' variant
550
of a string variable, provided it is placed in quotation marks:
552
\verb|string foo = readfile("@x12adir/QNC.rts")|
554
\subsection{The \texttt{strstr} function}
556
Invocation of this function takes the form
558
\texttt{string} \textsl{stringname} =
559
\texttt{strstr(}\textsl{s1}\texttt{,} \textsl{s2}\texttt{)}
561
The effect is to search \textsl{s1} for the first occurrence of
562
\textsl{s2}. If no such occurrence is found, an empty string is
563
returned; otherwise the portion of \textsl{s1} starting with
564
\textsl{s2} is returned. For example:
567
? string hw = "hello world"
569
? string w = strstr(hw, "o")
347
578
%%% Local Variables:
added
removed
doc/tex_pt/persistent.tex
