\chapter{Structured data types}
\label{chap:structypes}

Hansl possesses two kinds of ``structured data type'': associative
arrays, called \emph{bundles} and arrays in the proper sense of the
word. Loosely speaking, the main difference between the two is that in
a bundle you can pack together variables of different types, while
arrays can hold one type of variable only.

\section{Bundles}
\label{sec:bundles}

Bundles are \emph{associative arrays}, that is, generic containers for
any assortment of hansl types (including other bundles) in which each
element is identified by a string. Python users call these
\emph{dictionaries}; in C++ and Java, they are referred to as
\emph{maps}; they are known as \emph{hashes} in Perl. We call them
\emph{bundles}. Each item placed in the bundle is associated with a
key which can used to retrieve it subsequently.

To use a bundle you first either ``declare'' it, as in
%
\begin{code}
bundle foo
\end{code}
%
or define an empty bundle using the \texttt{defbundle} function
without any arguments:
%
\begin{code}
bundle foo = defbundle()
\end{code}
%
However, since defining a bundle is a common trope in hansl a handy
abbreviation is supported: \dtk{_()} is short for
\texttt{defbundle()}.

The formulations above are basically equivalent, in that they both
create an empty bundle. The difference is that the second variant,
with explicit assignment, may be reused---if a bundle named
\texttt{foo} already exists the effect is to empty it---while the
first may only be used once in a given gretl session; it is an error
to declare a variable that already exists.

To add an object to a bundle you assign to a compound left-hand value:
the name of the bundle followed by the key. The most common way to do
this is to join the key to the bundle name with a dot, as in
\begin{code}
  foo.matrix1 = m
\end{code}
which adds an object called \texttt{m} (presumably a matrix) to bundle
\texttt{foo} under the key \texttt{matrix1}. The key must satisfy the
rules for a gretl variable name (31 characters maximum, starting
with a letter and composed of just letters, numbers or underscore)

An alternative way to achieve the same effect is to give the key as a
quoted string literal enclosed in square brackets, as in
\begin{code}
  foo["matrix1"] = m
\end{code}
When using the more elaborate syntax, keys do not have to be valid as
variable names---for example, they can include spaces---but they are
still limited to 31 characters.

To get an item out of a bundle, again use the name of the bundle
followed by the key, as in

\begin{code}
matrix bm = foo.matrix1
# or using the long-hand notation
matrix m = foo["matrix1"]
\end{code}

Note that the key identifying an object within a given bundle is
necessarily unique. If you reuse an existing key in a new assignment,
the effect is to replace the object which was previously stored under
the given key. In this context it is not required that the type of the
replacement object is the same as that of the original.

A quicker way is to use \cmd{defbundle} or \dtk{_()}, as in
\begin{code}
  bundle b = _(s="Sample string", m=I(3))
\end{code}
Note that in this style the key-strings are not quoted; this works only
if they do not contain spaces. An alternative syntax can handle
arbitrary keys:
\begin{code}
  bundle b = _("s", "Sample string", "m", I(3))
\end{code}
Here every odd-numbered argument must evaluate to a key, and every
even-numbered argument to an object of a type that can be included in
a bundle.

Note that when you add an object to a bundle, what in fact happens is
that the bundle acquires a copy of the object. The external object
retains its own identity and is unaffected if the bundled object is
replaced by another. Consider the following script fragment:

\begin{code}
bundle foo
matrix m = I(3)
foo.mykey = m
scalar x = 20
foo.mykey = x
\end{code}

After the above commands are completed bundle \texttt{foo} does not
contain a matrix under \texttt{mykey}, but the original matrix
\texttt{m} is still in good standing.

To delete an object from a bundle use the \texttt{delete} command,
with the bundle/key combination, as in

\begin{code}
delete foo.mykey
delete foo["quoted key"]
\end{code}

This destroys the object associated with the key and removes the key
from the hash table.\footnote{Internally, gretl bundles in fact take
  the form of \textsf{GLib} hash table.}

Besides adding, accessing, replacing and deleting individual items,
the other operations that are supported for bundles are union and
printing. As regards union, if bundles \texttt{b1} and \texttt{b2} are
defined you can say

\begin{code}
bundle b3 = b1 + b2
\end{code}

to create a new bundle that is the union of the two others. The
algorithm is: create a new bundle that is a copy of \texttt{b1}, then
add any items from \texttt{b2} whose keys are not already present in
the new bundle. (This means that bundle union is not necessarily
commutative if the bundles have one or more key strings in common.)

If \texttt{b} is a bundle and you say \texttt{print b}, you get a
listing of the bundle's keys along with the types of the corresponding
objects, as in

\begin{code}
? print b
bundle b:
 x (scalar)
 mat (matrix)
 inside (bundle)
\end{code}

\subsection{Bundle usage}
\label{sec:bundle-usage}

To illustrate the way a bundle can hold information, we will use the
Ordinary Least Squares (OLS) model as an example: the following code
estimates an OLS regression and stores all the results in a bundle.

\begin{code}
/* assume y and X are given T x 1 and T x k matrices */

bundle my_model = _()           # initialization
my_model.T = rows(X)            # sample size
my_model.k = cols(X)            # number of regressors
matrix e                        # will hold the residuals
b = mols(y, X, &e)              # perform OLS via native function
s2 = meanc(e.^2)                # compute variance estimator
matrix V = s2 .* invpd(X'X)     # compute covariance matrix

/* now store estimated quantities into the bundle */

my_model.betahat = b
my_model.s2 = s2
my_model.vcv = V
my_model.stderr = sqrt(diag(V))
\end{code}

The bundle so obtained is a container that can be used for all sort of
purposes. For example, the next code snippet illustrates how to use
a bundle with the same structure as the one created above to perform
an out-of sample forecast. Imagine that $k=4$ and the value of
$\mathbf{x}$ for which we want to forecast $y$ is
\[
  \mathbf{x}' = [ 10 \quad 1  \quad -3 \quad 0.5 ]
\]
The formulae for the forecast would then be
\begin{eqnarray*}
  \hat{y}_f & = & \mathbf{x}'\hat{\beta} \\
  s_f & = & \sqrt{\hat{\sigma}^2 + \mathbf{x}'V(\hat{\beta})\mathbf{x}} \\
  CI & = & \hat{y}_f \pm 1.96 s_f 
\end{eqnarray*}
where $CI$ is the (approximate) 95 percent confidence interval. The
above formulae translate into
\begin{code}
  x = { 10, 1, -3, 0.5 }
  scalar ypred    = x * my_model.betahat
  scalar varpred  = my_model.s2 + qform(x, my_model.vcv)
  scalar sepred   = sqrt(varpred)
  matrix CI_95    = ypred + {-1, 1} .* (1.96*sepred)
  print ypred CI_95
\end{code}

\section{Arrays}
\label{sec:arrays}

A gretl array is a container which can hold zero or more objects of a
certain type, indexed by consecutive integers starting at 1. It is
one-dimensional. This type is implemented by a quite ``generic''
back-end. The types of object that can be put into arrays are strings,
matrices, bundles, lists and arrays (that is, arrays can be nested). A
given array can hold only one of these types.

\subsection{Array operations}

The following is, we believe, rather self-explanatory:

\begin{code}
strings S1 = array(3)
matrices M = array(4)
strings S2 = defarray("fish", "chips")
S1[1] = ":)"
S1[3] = ":("
M[2] = mnormal(2,2)
print S1
eval inv(M[2])
S = S1 + S2
print S
\end{code}

The \texttt{array()} takes an integer argument for the array size; the
\texttt{defarray()} function takes a variable number of arguments (one
or more), each of which may be the name of a variable of the given
type or an expression which evaluates to an object of that type.  The
corresponding output is

\begin{code}
Array of strings, length 3
[1] ":)"
[2] null
[3] ":("

     0.52696      0.28883 
    -0.15332     -0.68140 

Array of strings, length 5
[1] ":)"
[2] null
[3] ":("
[4] "fish"
[5] "chips"
\end{code}

In order to find the number of elements in an array, you can use the
\texttt{nelem()} function.

\subsection{High-dimensional objects}

Since one can construct an array of matrices, and arrays can be
nested, it is possible to build numerical objects of higher
dimensionality than matrices. For example a 3-tensor can be
represented as an array of matrices, and a 4-tensor as an array of
arrays of matrices.

But since such objects are compound you have be careful to get
indexation right. For example, if you have an array \texttt{M} holding
at least three matrices and you want to access element 2,2 of matrix 3
you'll need two sets of square brackets, as in
%
\begin{code}
M[3][2,2]
\end{code}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "hansl-primer"
%%% End: 

