### 3.6 Interface to Stata^{®}

Stata is a proprietary software package designed for data analysis, data management, and graphics. Stata provides canned procedures for estimating many popular econometric models, most of them being frequentist. However, recent versions of Stata also include Bayesian procedures. Stata has a complete GUI but it also features a simple scripting language, which makes running it in batch mode feasible.

BayES’ stata() function provides a convenient interface to Stata, which allows the user to:

- pass BayES matrices and a single dataset as input to Stata
- request Stata to execute code written in its native language
- retrieve output from Stata and store it in BayES dataset and matrix items; all data to be returned from Stata are stored inside a BayES structure item

The general syntax of the stata() function is the
following:^{6}

$[$, "data"=<list of matrices/dataset to pass to Stata> $]$

$[$, "return"=<list of matrices to retrieve from Stata> $]$

);

where:

- <structure name> is a BayES id value which will be associated with the BayES structure that the stata() function returns. This structure will contain any Stata matrices or dataset that the user requests to be returned to BayES (using the "return" option) after execution of the Stata .do ﬁle completes.
- <Stata .do file> is a string pointing to the ﬁle which contains the code (written in Stata’s language) that Stata will be requested to execute. If this ﬁle is not in the current directory then the ﬁle name must be prepended by the path to the ﬁle, either in absolute terms (eg. "C:/MyFiles/myFile.do") or relative to the current working directory (eg. "../myFile.do"). This is the only mandatory argument of the stata() function.
- "data" speciﬁes the data that will be passed as input to Stata. <list of matrices/dataset
to pass to Stata> is a list of the id values of matrices or a dataset (comma-separated
names inside curly brackets), as they appear in the Stata .do ﬁle. The list can contain
any number of BayES matrices and at most one BayES dataset. When a BayES matrix is
passed as input to Stata then this becomes available as a Stata matrix in Stata. When
a BayES dataset is passed as input to Stata then this becomes available in Stata as its
dataset.
^{7}These matrices/dataset must be deﬁned in the current workspace. - "return" speciﬁes the Stata objects that will be returned to BayES when execution of
the .do ﬁle completes. <list of matrices to retrieve from Stata> is a list of id values
(comma-separated id values inside curly brackets) that specify the names of the matrices
that should be returned from Stata, as they appear in the Stata .do ﬁle. Any Stata matrix
that is returned will be stored in BayES as a matrix. If a dataset is available in Stata
when execution of the code contained in the provided .do ﬁle completes, then stata()
retrieves this Stata dataset and stores it as a BayES dataset, even is not requested by the
user.
^{8}These retrieved matrices/dataset are grouped together into a BayES structure. Passing other data types (structures, models, strings, etc.) between BayES and Stata is not supported.

When the stata() function calls Stata, Stata starts only part of its GUI and executes the code contained in the provided Stata .do ﬁle. BayES automatically directs any Stata output to a log ﬁle. When execution of the code contained in the .do ﬁle completes BayES reads the Stata output and prints it on the BayES console. Therefore, BayES may appear frozen during the time Stata executes the commands in the .do ﬁle. The output printed on the BayES console is entirely determined by Stata and the commands contained in the Stata .do ﬁle provided to stata().

The sample script ﬁle in
"$BayESHOME/Samples/5$-$Interfaces/stata"
contains an example of using the stata() function, along with a simple Stata .do ﬁle. The Stata
interface is also accessible from the BayES main menu via Interfaces → Stata^{®}.

^{6}Arguments inside square brackets are optional. Optional arguments passed to the stata() function can be
provided in any order, but always after the mandatory argument (Stata .do ﬁle). Optional arguments always come in
pairs (eg. "data"={myDataset,myMatrix}).

^{7}Stata can handle only a single dataset at a time. If the user attempts to pass more than one datasets as
data to Stata, stata() will issue an error.

^{8}If you do not want the Stata dataset to be returned to BayES, simply include clear as the last line of code
in the provided Stata .do ﬁle.