\subsection{Simulation parameter files}

The variable names used in the simulation parameter files must be defined in the model file. Each file must be in ASCII format. The simulation parameter files are:

\begin{enumerate}
\item Simulation file - The file hold the burn-in and thinning numbers.
\item Initial value file - Initial values of the variables are defined here.
\item Proposal file - Proposal strategies and distributions are defined in this file.
\item Update strategy file - Update strategy and the number of iterations are defined in this file.
\item Parameters to output file - The parameters to output are defined here.

\end{enumerate}

\subsubsection{Simulation file}
\label{simulationfile}

The burn-in length and the thinning factor are both integers. They must be given in a single file, given like in the example below: 

\textbf{An example of the file:}
\begin{verbatim}
?? simulation
? burn-in
100
? thinning
100
\end{verbatim}

The first line is a compulsory identifier line.

\subsubsection{Initial value file}
\label{initialvalues}
The user must provide initial values for all parameters (stochastic variables and variables which have missing values in the data). The initial values are given in a single file.

The first line of the file must be:

\begin{verbatim}
?? initial values
\end{verbatim}

The format of the file is:

1) Identifier, which can be one of the following:

\begin{verbatim}
? parametername

? parametername begin:end

? parametername begin:end begin2:end2
\end{verbatim}

2) The initial values in an array or a matrix corresponding to the identifier.

The file may contain several consecutive identifier - values - pairs.

\textbf{Some examples:}
\begin{verbatim}
? alpha
4.0
\end{verbatim}

The identifier of the example means that we are giving an initial value to a single variable on the line after the identifier.

\begin{verbatim}
? alpha 1:5 
3.2 
0.3 
3.1 
5.3 
2.9 
\end{verbatim}

The identifier describes that we are giving initial values to $alpha_1, alpha_2, alpha_3, alpha_4$ and $alpha_5$ in an array on the lines following the identifier line. After setting the initial values, we have $alpha_1=3.2, alpha_2=0.3$ etc.

\begin{verbatim}
? beta 1:3 
5.4 
2.1 
1.0 
\end{verbatim}

The identifier means that we are giving initial values to $beta_1, beta_2$ and $beta_3$ in an array on the lines after the identifier. After setting the initial values, we have $beta_1=5.4, beta_2=2.1$ etc.

\begin{verbatim}
? x 1:5 1:3 
1.0 3.2 5.3 
1.2 5.2 3.1 
3.8 4.1 8.0 
4.4 2.7 3.2 
5.6 0.4 1.2 
\end{verbatim}

The identifier describes that we are giving initial values to $x_{1, 1}, x_{1,2}, x_{1,3}, x_{2,1}, ... x_{5,3}$. The values are in a matrix form after the identifier line. The first index corresponds to the vertical dimension and the second index corresponds to the horizontal dimension of the matrix. After setting the initial values, we have $x_{3,2}=4.1$ for example.

If some instances of, say, the variable $obs$ are missing from the data, the user must provide initial values for them. 
\begin{verbatim}
? obs 4:4 1:1 
4.3 
\end{verbatim}
This definition states that the initial value of $obs_{4,1}$ is 4.3.

\subsubsection{Proposal file}
\label{proposalfile}
The format of the proposal strategies and distributions input file is similar to the initial values input file.

The first line of the file must be:

\begin{verbatim}
?? proposal distributions
\end{verbatim}

An example of giving the proposal distributions:

\begin{verbatim}
? b all
poisson(3.0) 
\end{verbatim}

This expression states that the parameters $b_1, ..., b_5$ have the same proposal distribution Poisson(3.0) and the fixed proposal strategy is used as default.

If the parameter is global, the word ``all'' is not needed. For example:
\begin{verbatim}
? alpha
continuous_uniform(0.0, 2.0)
\end{verbatim}

\begin{verbatim}
? b all
continuous_uniform(-1.0, 1.0) RW 
\end{verbatim}

This expression states that the parameters $b_{1,1}, ...$ use the random walk as proposal strategy (the `RW' keyword) and the proposal distribution for them is continuous\_uniform(-1.0, 1.0). 

Possible distributions for INTEGER variables include:
The following distributions are possible for INTEGER variables:
\begin{itemize}
\item discrete\_uniform(INTEGER a, INTEGER b)
\item binomial(INTEGER n, REAL p)
\item poisson(REAL mu)
\end{itemize}

The following distributions are possible for REAL variables:
\begin{itemize}
\item continuous\_uniform(REAL a, REAL b)
\item beta(REAL alpha, REAL beta)
\item user\_gamma(REAL a, REAL b)
\item user\_normal(REAL mu, REAL sigma2)
\end{itemize}

It is also possible to use a distribution defined by the user.

\subsubsection{Update strategy file}
\label{updatestrategy}
The update strategy file defined the update strategy used and the number of iterations. The first line of the specification file must be:
\begin{verbatim}
?? update
\end{verbatim}

%The format of the rest of the file depends on the update strategy to be chosen.

%1) If the user wants to update the parameters in sequential order:

Sequential update strategy is defined with:

\begin{verbatim}
? strategy
sequential

? iterations
42
\end{verbatim}

The user gives the number of iterations, that is: the parameters are updated once and then the output is printed (considering the thinning factor of course) and this is repeated until the iteration count is reached.

%2) If the user wants the next parameter to update to be chosen at random:

%\begin{verbatim}
%? strategy
%random

%? updates
%500

%? x all 
%600
%\end{verbatim}

%The user gives first gives the update strategy, then the default number of updates. Considering this example all parameters must be updated at least 500 times before the simulation is finished. After giving the default number, the user can also give the number of updates for a parameter group. 

%Note: It is possible to define the number of updates for a parameter group, not for a single parameter instance (for example, for $x$ but not for $x_{1,6}$).

%Note: The output is printed after each update so the user may want to use a bigger thinning factor.

Currently the only implemented update strategy is the sequential one.

\subsubsection{Parameters to output file}
\label{inputs_tooutput}

The parameters to output are defined in a manner similar to the initial values. For example:

The compulsory identifier is:
\begin{verbatim}
?? output outputFile summaryFile
\end{verbatim}

where outputFile is the filename of the output file and summaryFile is the filename of the summary file.

\begin{verbatim}
? b all
? mu all
? alpha 
\end{verbatim}

This definition states that the parameter to output are all $b:s$, all $mu:s$ and $alpha$. Note that it is not possible to define that only some instances, for example $b_1$, are output. More about outputs in \ref{outputsfortran}