\subsection{Simulation parameters as input}

\subsubsection{The burn-in length and the thinning factor}

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: 

\begin{verbatim}
?? simulation
? burn-in 
1000

? thinning
4
\end{verbatim}

The first line is a compulsory legend line.

%\subsubsection{Blocking and the algorithm used}

%A block is defined by listing parameters which belong to it. The format is 
%\begin{verbatim}
%(parameter1, parameter2)
%(parameter3, parameter4, parameter5)
%etc.
%\end{verbatim}

%If the user wants to define that the Gibbs sampling algorithm must be used when updating the block, the key word ``Gibbs'' is entered after the block's definition. For example:

%\begin{verbatim}
%(alpha_1, beta_3, gamma) Gibbs
%\end{verbatim}

%The default algorithm used is the Metropolis-Hastings algorithm.

%If the block contains only one parameter, it doesn't have to be defined unless the user wants to use the Gibbs sampling algorithm.

\subsubsection{Initial values}

The user must provide initial values for all parameters. 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) Legend, 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 legend.

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

An example:

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/basic_ij.ps,height=8cm}
%\end{center}
\caption{A model with two intersecting entities}
\end{figure}


\begin{verbatim}
? gamma
4.0
\end{verbatim}

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

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

The legend 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 legend 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 legend means that we are giving initial values to $beta_1, beta_2$ and $beta_3$ in an array on the lines after the legend. 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 legend 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 legend 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 strategies and proposal distributions}

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}
? alpha all
poisson(3.0) 
\end{verbatim}

This expression states that the parameters $alpha_1, ..., alpha_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}
? gamma
continuous_uniform(0.0, 2.0)
\end{verbatim}

%\begin{verbatim}
%? alpha 3:3 
%poisson(1) 
%\end{verbatim}

%This expression states that the parameter $alpha_3$ has its own proposal distribution, Poisson(1). This definition overrides the previous one.

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

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

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

Possible distributions for REAL variables include:
\begin{itemize}
\item continuous\_uniform(REAL a, REAL b)
\item beta(REAL alpha, REAL beta)
\end{itemize}

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

\subsubsection{The update strategy and the number of updates}

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:

\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.

\subsubsection{Which parameters to output}

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

%\begin{verbatim}
%alpha all
%beta 2:2 
%gamma 
%\end{verbatim}

%This definition states that the parameter to output are $alpha_1, ..., alpha_5, beta_2$ and $gamma$.

The compulsory legend 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}
? alpha all
? beta all
? gamma 
\end{verbatim}

This definition states that the parameter to output are all $alphas$, all $betas$ and $gamma$. Note that it is not possible to define that only some instances, for example $alpha_1$, are output.