\subsection{Model description language}

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

%The order of the lines or capitalization make no difference.

%\textbf{Examples:}

%\begin{verbatim}
%float alpha ~ Gamma(0.1, 1.0)
%\end{verbatim}
%Alpha is a stochastic variable with a Gamma distribution. The distribution's %parameters are 0.1 and 1.0.

%\begin{verbatim}
%int beta = alpha + delta^2
%\end{verbatim}
%Beta is a functional variable. It's value is alpha + delta\verb+^+2.

%\begin{verbatim}
%day, "day.txt" {
%    x(10)
%}
%\end{verbatim}

%Day is an entity. The value of x\_i is found in the file day.txt on row i, col 10.

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'. No other characters are allowed. The variable names must not be equal reserved words of Fortran.

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

\subsubsection{Defining variables}

Variables can be either integers or floating point numbers. This is expressed by an `INTEGER' or `REAL' in front of their names. 

If the variable is functional, an equation must be provided. If the variable is stochastic, a distribution must be provided. The syntax is:

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

%\textbf{Pattern for stochastic variables:} (INTEGER | REAL) \textit{name} %\verb+~+ \textit{distribution}

%\textbf{Pattern for functional variables:} (INTEGER | REAL) \textit{name} = %\textit{equation}

A variable must be defined before it can be used in other variables' equations or distributions.

\textbf{List of 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)
\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)
\end{itemize}

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

\textbf{List of operators allowed in equations}

1) Functional parameters describing spatial relations

A special character \& has a meaning ``all neighbour units''. \& x means ``all x instances in neighbour units''. 

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

Note that functional parameters describing spatial relations can only appear inside entities. Note also that the expressions SUM and COUNT cannot appear inside other expressions.

\textbf{Examples:}
\begin{verbatim}
REAL q=SUM(&x)
INTEGER c=COUNT(&x)
REAL p = q / c
# the average of x in the neighbour units
\end{verbatim}

2) Other functional parameters

The following operations are possible:
\begin{itemize}
\item +
\item -
\item *
\item /
\item ** (power expression in Fortran)
\item EXP()
\item LOG()
\end{itemize}

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


%Within an entity it's possible to define that a variable is from data, using the following pattern:

%(int | float) \textit{name}(\textit{column}) [ \verb+~+ \textit{distribution}]

%In the case of two dimensional data, the column is `*'.

\subsubsection{Defining entities}

%- format of name yms.

%\textit{name} ([, `\textit{file name}'] ([, `\textit{spatial file name}']?)? [, combines(\textit{entity}, \textit{entity}] \{

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

The variables related to the entity are defined inside the brackets. The variables are defined as earlier except that is is possible to define where the variable is found in the data. 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.

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

In this example there is an entity called bird. It contains one variable which is taken from data. The data is found in file birds.txt at column 1.

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
\end{verbatim}

\begin{verbatim}
ENTITY square, "squares.txt", "spatial.txt" 
{
    INTEGER northerness(1)
}
\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)
{
    REAL p = EXP(alpha * northerness) / (1 + EXP(alpha * northerness))
    INTEGER x ~ user_bernoulli(p)
    INTEGER obs(*) ~ user_defined_points(x)
}
\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 that there can be only one intersection entity and it cannot be spatial.

\subsubsection{Distribution defined by the user}

User-defined distributions can be used like the other distributions. The names of user-defined distributions must begin with ``user\_''.

For example: 
\begin{verbatim}
x ~ user_bernoulli(p)
\end{verbatim}

See also: \ref{Adding distributions}

%\subsubsection{Formal syntax}

%{\it An explanation of the notation used can be found at}

%{\it http://www.python.org/dev/doc/devel/ref/notation.html}

%--> REF

%\

%model: (variable | entity | comment)*

%variable: stochastic\_variable | functional\_variable

%entity: identifier [`,' file] [`,' file] [`, combines(' identifier `,' identifier `)'] `\verb+{+' (variable | data\_variable)* `\verb+}+'

%comment: `\#' .*

%stochastic\_variable: type ` ' identifier `\verb+~+' distribution

%functional\_variable: type ` ' identifier `=' equation

%data\_variable: type ` ' identifier `(' (integer | `*') `)' [`\verb+~+' distribution]

%type: `int' | `float'

%identifier: letter*

%distribution: identifier `(' ((number | identifier) `,')* (number | identifier) `)'

%equation: [`('] ((number | identifier | equation) operator)* (number | identifier | equation) [`)'] | `log(' (number | identifier | equation) `)'

%\textit{logarithm, sum and product}

%operator: `+' | `-' | `*' | `/' | `**'

%number: integer | float

%integer: (`0'..`9')+

%float: (`0'..`9')+`.'(`0'..`9')+

%file: letter* `.txt'

%letter: `a'...`z'
