### 2.5 Models

The model data type is used to store the results obtained from estimating the parameters of any model available in BayES. For example the statement:

myModel = lm( y ~ x1 x2 x3 );

runs a simple linear model, where y is the dependent variable and x1, x2 and x3 the independent variables, and prints a summary of the results on the BayES console. It also stores the results into a model item with id value myModel and these results become available for further processing (model comparison, testing restrictions on parameters, plotting or exporting the draws from the posterior, etc.). If the statement above is submitted without providing a left-hand-side value, i.e. if it were submitted simply as:

lm( y ~ x1 x2 x3 );

then BayES would still run the model and print the results, but these results would not be available for further processing.

If myModel is a model in memory in the current workspace then the statement:

print(myModel);

prints a summary of the results from the model on the BayES console. The statement:

who(myModel);

prints a list of the elements stored in myModel. These elements always include the values of the Gibbs-sampler parameters (number of chains, number of burn-in draws per chain, total number of retained draws from the posterior, value of the thinning parameter and the seed for the random-number generator), the value of the log-marginal likelihood using the Laplace approximation (Lewis & Raftery1997) and the draws from the posterior distribution for each parameter. All these elements can be accessed using the ‘.’ operator. For example, the statement:

print(myModel.logML);

will print the value of the log-marginal likelihood of myModel on the BayES console, while the statement:

samples_beta1 = myModel.x1;

will create a vector with id value samples_beta1 that contains the values of the draws for the parameter associated with variable x1.

Many diﬀerent types of models can be estimated in BayES by using diﬀerent model-creating functions. For example, the lm() function estimates a linear model, the sf_re() function estimates a stochastic-frontier model with random eﬀects and the probit() function estimates a Probit model. All model-creating functions take the model speciﬁcation as their (required) ﬁrst argument. The model speciﬁcation is typically given in the form:
<dependent variable> ~ <independent variables>
and an example of was this given at the beginning of this section. The model-creating functions also take a list of optional arguments, some of which are common to all functions and some being available only to speciﬁc models. These optional arguments always come in option-value pairs (eg. "chains"=3, "draws"=10000, etc.) and the order in which they are provided to the function does not play a role. That is, the following two statements are equivalent:

myModel = probit( y ~ x1 x2 x3, "chains"=3, "draws"=10000 );
myModel = probit( y ~ x1 x2 x3, "draws"=10000, "chains"=3 );

The meaning of both common and model-speciﬁc optional arguments and their default values is documented analytically in the following chapters, under each speciﬁc model. It is worth noting here, however, that the common optional arguments for all functions are:

• the values of the Gibbs sampler parameters (number of chains, number of burn-in and retained draws per chain, and the values of the thinning parameter and the random-number generator seed)
• a logical argument (its value could be either true or false) that indicates whether the Chib (1995) or Chib & Jeliazkov (2001) approximation to the log-marginal likelihood should be calculated; depending on the type of model, these calculations may be as demanding as the original estimation of the model

Because a model item stores the draws from the posterior, it may use much of the machine’s memory. It is, therefore, advisable to delete models from memory (using the clear() function) if the results from the model are no longer needed.

Sample "3$-$First models.bsf", located at "$BayESHOME/Samples/1$-$GettingStarted" provides a ﬁrst exposure to estimating models in BayES. The samples located at "$BayESHOME/Samples/2$-$Models" illustrate how all types of supported models can be estimated and their results analyzed.