\subsection{Model file}
\label{inputs_model}
The model file describes the Bayesian model used in the simulation. The file must be in ASCII text format.

A model description consists of variable and entity definitions. It can also include comment lines, any line beginning with `\#' is considered a comment. 

The model description file consists of the following parts:
\begin{enumerate}
\item Definitions of global variables
\item Definitions of entities, which contain definitions of variables
\end{enumerate}

\subsubsection{Names and constants}

Names of variables and entities can include lowercase letters `a' - `z' and numbers `0' - `9'. A name must start with a letter. No other characters are allowed. The variable names must not be equal to any reserved words of Fortran.

Floating point constants may be expressed using the scientific format except that the exponent `E' must be an uppercase `E'.

\subsubsection{Defining global variables}

Variables can be either integer or floating point type. Every variable is also either stochastic or functional. Stochastic variables can also be data variables, if they are defined inside an entity. Global variables can be stochastic or functional, but they can not be defined in a data file.

NOTE: Variables must be defined in topological order; That is, if the variable `alpha' affects variable `beta' then alpha must be defined before beta. Functional variables with spatial expressions are an exception, see \ref{spatial}.

The definition of global variables should be before any definition of an entity.

NOTE: Chaining of multiple functional variables is not allowed! The chain of two functional variables can be expressed by one functional variable. Functional variables with spatial expressions are an exception, more about this later.

The type of a variable is expressed by an `INTEGER' or `REAL' in front of their names. The syntax is:

\begin{verbatim}
type name ...
type name ...
\end{verbatim}

For example:

\begin{verbatim}
REAL alpha ...
INTEGER delta ...
\end{verbatim}

If the variable is functional, an equation must be provided. If the variable is stochastic, a distribution must be provided (variables coming from data are an exception). The syntax is:

\begin{verbatim}
type name ~ distribution
type name = expression
\end{verbatim}

For example:

\begin{verbatim}
REAL alpha = 1 * gamma
INTEGER delta ~ poisson(alpha)
\end{verbatim}

\textbf{Distributions}

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)
\item user\_bernoulli(REAL p)
\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}

Note that it's possible to define other ``user-defined'' distributions. The name of these distributions must start with `user\_'. The user defined function file is described in \ref{userdefined}.

\textbf{Examples:}
\begin{verbatim}
REAL alpha ~ beta(0.1, 1.0)
INTEGER delta ~ poisson(alpha)
\end{verbatim}

\textbf{Expressions}

Expressions are not allowed as parameters for distributions. A parameter must be a real or integer number, depending on the type of the distribution, or a variable of the correct type.

\textbf{List of operators allowed in equations}

The following operations are possible:
\begin{itemize}
\item +
\item -
\item *
\item /
\item ** (power expression in Fortran)
\item EXP()
\item LOG()
\item Fortran intrinsic functions (such as SIN())
\item Type conversions (such as REAL())
\end{itemize}

\textbf{Examples:}
\begin{verbatim}
REAL beta = alpha**2
REAL gamma = EXP(alpha + 1) / EXP(alpha - 1)
\end{verbatim}

There are two spatial operations SUM() and COUNT(). See \ref{spatial}.

The user must take care of type conversions, that is, the program doesn't perform any type conversions other than the conversions automatically performed by Fortran.

\textbf{Examples:}
\begin{verbatim}
INTEGER n = ...
INTEGER p = ...
REAL q = REAL(p) / n
\end{verbatim}

\subsubsection{Defining entities}
\label{def_entities}

An entity is an object that groups variables together. An entity can describe for example a bird species or a geographical area.

The first line, identified with ENTITY, defines the name of the entity. It also defines the data file where all data about the entity is found (if some variables from the entity are taken from data), the data file name defining spatial relations (if it exists) and which other entities the entity combines (if the entity describes an intersection of two entities).

The adjacency matrix which defines spatial relations is defined in \ref{Adjacency}. The format of data files is defined in \ref{data}.

\textbf{Examples:}
\begin{verbatim}
ENTITY bird, "birds.txt" 
{
    ...
}
\end{verbatim}

In this example the name of the entity is `bird' and the data file is `birds.txt'.

If no data is provided, the data file name must equal ``''. It is also possible that an entity has no variables in it. For example:

\begin{verbatim}
ENTITY bird, "" 
{

}
\end{verbatim}

\begin{verbatim}
ENTITY square, "squares.txt", "spatial.txt" 
{
    ...
}
\end{verbatim}

Similarly we define an entity called square. In this example, `square' is a spatial unit, so a file name of the adjacency matrix is given.

\begin{verbatim}
ENTITY observation, "observations.txt", combines(square, bird)
{
		...
}
\end{verbatim}

This example shows how to define an intersection entity. The combines-clause states that the squares are the vertical units and birds are the horizontal units in the matrices related to the intersection entity (for example, data matrices).

NOTE: an intersection entity cannot be spatial. Also, a model file may define only one spatial entity.

\subsubsection{Defining variables inside entities}

The variables related to the entity are defined inside the brackets. The variables inside entities can be defined in a data file. This is done by adding ``(column\_number)'' after the variable name, where column\_number defines the column of the data file in which the corresponding data is found. If the data is a matrix, there is no single column containing the data and this situation is specified simply by adding ``(*)'' after the variable name.

The variables are defined in the same way inside entities, as are the global variables.

\textbf{Examples:}
\begin{verbatim}
ENTITY bird, "birds.txt" 
{
    REAL size(1)
}
\end{verbatim}

\begin{verbatim}
ENTITY square, "squares.txt", "spatial.txt" 
{
    INTEGER northerness(1)
}
\end{verbatim}

\begin{verbatim}
ENTITY observation, "observations.txt", combines(square, bird)
{
    REAL p = EXP(alpha * northerness) / (1 + EXP(alpha * northerness))
    INTEGER x ~ user_bernoulli(p)
    INTEGER obs(*) ~ user_defined_points(x)
}
\end{verbatim}

\subsubsection{Spatial operations}
\label{spatial}

Functional parameters describing spatial relations can be defined inside entities, which have an adjacency matrix defined. Spatial functional parameters can also be used inside an entity which combines a spatial and a `normal' entity.the character `\&' has a special meaning `all neighbouring units'. \& x means `all instances of the variable x in neighbouring units'. 

The referenced variable in a \&-expression can only be a stochastic variable. For example, in '\& x' the variable x must be stochastic. 

The following spatial operations are possible:
\begin{itemize}
\item SUM(\&variable)
\item COUNT(\&variable)
\end{itemize}

A functional variable can only have one spatial operation in it. (e.g. One cannot define `a = SUM(\&x) * 53' or `a = SUM(\&x)/COUNT(\&x)') (see \ref{restrict_spat})

\textbf{Example:}
\begin{verbatim}
ENTITY square, "squares.txt", "spatial.txt" 
{
		INTEGER n = COUNT(&mu)
		REAL p = SUM(&mu)
		REAL alpha = p / n
		REAL mu ~ beta(alpha, beta)
}
\end{verbatim}

In this example alpha is the average of all neighbour mu variables. Since we need to define variable in topological order, alpha needs to be defined before mu. Also p and n must be defined before alpha. However as you can see topological order is not possible with spatial variables since n and p depend on mu, which is defined after them. In cases like this the functional variables with a SUM() or COUNT() operation can and must be defined before the variable they depend on.

There is also a chain of functional variables in the last example. Chaining functional variables is only allowed in spatial cases like this, since SUM() and COUNT() must appear in separate variables' expressions.

\newpage
\subsubsection{General restrictions}

There are a few global restrictions to the semantics of the model description file.

\textbf{Spatial operations}
\label{restrict_spat}
A functional variable can have a SUM() or COUNT() operation in its expression. If either of these operations is used, no other operations may be used in the expression. 

\textbf{Dependencies between variables}

A global variable can affect another global variable, a variable inside an entity or a variable inside an intersection of entities.

A variable inside an entity can affect a variable inside the same entity, or a variable inside an intersection of entities where either one is the entity of the affecting variable.

A variable inside an intersection of two entities can only affect a variable inside the same intersection.

Cycles are not allowed in the model, excluding the spatial relations.


\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/dependencies.ps,width=12cm,height=12cm}
%\end{center}
\caption{Allowed dependencies}
\label{fig: dependencies}
\end{figure}

\newpage 

\textbf{Chaining of functional variables}

Chaining functional variables is only allowed in spatial cases like this, where SUM() and COUNT() variables can't be used in an expression with any other operations.

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/chaining.ps,height=10cm}
%\end{center}
\caption{Chains can be combined into single variable.}
\label{fig: chaining}
\end{figure}

\textbf{Topological order}

Variables must be defined in topological order. If variable `alpha' affects variable `beta' then alpha must be defined before beta. Topological ordering is not always possible with spatial variables. In these cases functional variables, with a SUM() or COUNT() operation can and must be defined before the variable they depend on.

\newpage 

\subsubsection{Example model}

In this section we will construct a model file from scratch. We will use the lip cancer model, which describes the amount of lip cancers among the populations of different regions in England.

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/example1.ps,width=17cm,height=8cm}
%\end{center}
\caption{Model in logical form.}
\label{fig: example1}
\end{figure}

`alpha' and `sigma' are global variables. `e' is the expected number of cases in a county and `x' describes the amount of farmland in a county. `mu' is a variable which combines other variables. `b' contains a spatial expression. Note that `b' is not valid PIANOS model format. The spatial operations need to be split into their own variables. We will do this later in this section.

As the figure shows, alpha and sigma are global variables. They should be defined first since they do not depend on any other variable. The normal and gamma distribution have been programmed in the testing phase of PIANOS. they are examples of user-defined distributions and are used in this model.

\begin{verbatim}
REAL alpha ~ user_normal(0, 100)
REAL sigma ~ user_gamma(1, 1)
\end{verbatim}

The figure has only one entity. It is spatial (COUNT() and SUM() operations are used) and there are variables which are defined in data (obs, x and e). Let's assume the data file is called `data.txt' and the adjacency matrix file `spatial.txt'. Let's also assume that the variable obs is defined in the first column, x in the second and e in the third column. The entity describes a geographical area, a county, so lets call it `county'.

\begin{verbatim}
REAL alpha ~ user_normal(0, 100)
REAL sigma ~ user_gamma(1, 1)

ENTITY county, "data.txt", "spatial.txt"
{
		...
}
\end{verbatim}

We need to define variables in topological order, so variables x and e need to be defined next.

\begin{verbatim}
REAL alpha ~ user_normal(0, 100)
REAL sigma ~ user_gamma(1, 1)

ENTITY county, "data.txt", "spatial.txt"
{
		REAL x(2)
		REAL e(3)
		...
}
\end{verbatim}

We assume here that both x and e are real type in the data. Before we can define mu we need to define b. However as you can see, we hit a problem here. B is defined as b \~ normal(SUM(\&b) / COUNT(\&b), COUNT(\&b)). A distribution can only have fixed numbers or variables as parameters. We need to replace the operations with two new variables. Lets call those variables `t and `n'.

Now we can define n as n = COUNT(\&b) and t as t = SUM(\&b) / COUNT(\&b). However we still have a problem. T has three operations in it's expression. Since we are using spatial operations, only one is allowed. We need to replace both spatial operations with new variables. Luckily we have a variable for COUNT() already, the variable n. Lets define a new variable called q as q = SUM(\&b). Now we can define b, n, t and q in the model file:

\begin{verbatim}
REAL alpha ~ user_normal(0, 100)
REAL sigma ~ user_gamma(1, 1)

ENTITY county, "data.txt", "spatial.txt"
{
		REAL x(2)
		REAL e(3)
		REAL n = COUNT(&b)
		REAL q = SUM(&b)
		REAL t = q/n
		REAL b ~ user_normal(t, n)
		...		
}
\end{verbatim}

It's impossible to topologically order n, q, t and b. Since n and q are using spatial operations, they need to be defined first. After them we define t, since b depends on it. Now we can add definition of mu and obs to the model. 

\begin{verbatim}
REAL alpha ~ user_normal(0, 100)
REAL sigma ~ user_gamma(1, 1)

ENTITY county, "data.txt", "spatial.txt"
{
		REAL x(2)
		REAL e(3)
		REAL n = COUNT(&b)
		REAL q = SUM(&b)
		REAL t = q/n
		REAL b ~ user_normal(t, n)
		REAL mu = EXP(LOG(e) + alpha * x / 10 + sigma * b)
		INTEGER obs(1) ~ poisson(mu)
}

# x is the percentage of farmland
# e is expected count of lip cancer patients
# b is something spatial
# mu is the real count of lip cancer patients
# obs is observed count of lip cancer patients
\end{verbatim}

\newpage 

Our model file is ready. Here is a graphical presentation of it.

\begin{figure}[ht]
%\begin{center}
\epsfig{file=content/diagrams/example2.ps,width=17cm,height=8cm}
%\end{center}
\caption{Model in the PIANOS model description language.}
\label{fig: example2}
\end{figure}