.. highlight:: xml

.. _lexicon-xml:

Lexicon
=======

The lexicon document defines the data hierarchy and vocabulary used. It's also used to document the system and to enable validity checks of other documents. The lexicon contains definitions for all attributes used in the data and models.

The lexicon is constructed as a hierarchy of data levels, in which the root level is always ``simulation``. Each data level contains the definitions for its attributes and possibly its sublevel.

The attributes are divided into two sets: numerical and categorical attributes.

An example of the document contents is given below, for a comprehensive description of all the possible content options see the `schema document <http://svn.simo-project.org/simo/trunk/simulator/xml/schemas/lexicon.xsd>`_. Data continuation and abbreviated content expressed as …:

The root level tag contains a reference to the schema document which is used to validate the content of the XML document::

   <rootlevel xmlns="http://www.simo-project.org/simo"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://www.simo-project.org/simo ../schemas/lexicon.xsd">

Here the simulation level attribute definitions are not shown. The simulation level has as its sublevel the first proper data level, here called ``comp_unit``::

   …
      <name>simulation</name>
      <num_vars>…</num_vars>
      <cat_vars>…</cat_vars>
      <sublevels>
         <sub_level>
            <name>comp_unit</name>
            <type>static</type>

An example of a numerical attribute definition: the name is ALT, that will be used to refer to this attribute in model definitions and model chains. The unit is metre, minimum allowed value is 0 m and the maximum value 600 m. If these limits are exceeded in the data, a warning is automatically generated::

   …
            <num_vars>
               <variable>
                  <name>ALT</name>
                  <unit>m</unit>
                  <min_value>0</min_value>
                  <max_value>600</max_value>
                  <description>Altitude above see level</description>
               </variable>
               …
            </num_vars>

``comp_unit`` level has also categorical variables (cat_vars). For categorical variables all the possible values are described in the lexicon. The PEAT attribute has two possible values: 0 meaning mineral soil and 1 meaning peatland:: 

   …
            <cat_vars>
               <variable>
                  <name>PEAT</name>
                  <min_value>0</min_value>
                  <max_value>1</max_value>
                  <description>Categorical variable referring to peatland
                  </description>
                  <values>
                     <enum>
                        <value>0</value>
                        <description>Mineral soil</description>
                     </enum>
                     <enum>
                        <value>1</value>
                        <description>Peatland</description>
                     </enum>
                  </values>
               </variable>
               …
            </cat_vars>

``comp_unit`` has also a sublevel called ``stratum`` which has attributes of its own. The structure of the ``stratum`` data level definition repeats that of the previous data levels::

   …
            <sublevels>
               <sublevel>
                  <name>stratum</name>
                  <type>dynamic</type>
                  <num_vars>
                     <variable>
                        <name>Age</name>
                        <unit>year</unit>
                        <min_value>0</min_value>
                        <max_value>350</max_value>
                        <description>Biological mean age</description>
                     </variable>
                  …
                  </num_vars>
                  …
               </sublevel>
            </sublevels>
         </sublevel>
      </sublevels>
   </rootlevel>


Merging multiple lexicons
=========================

Different projects that share the same basic XML components might have some project-specific variables. That means that each project should have it's own lexicon, or that there would be a single lexicon with all of the project-specific variables. Both of these solutions would cause some problems. A better solution is to have a single master lexicon, with all of the common variables (which includes most of the variables) and a number of project-specific extra lexicons, which are in their own XML documents.

Two or more lexicons can be merged together if the data hierarchies are compatible. This means that the level-names and parent-child relations in the master and extra lexicons are similar. The master lexicon should define the whole data model, but the extra lexicon does not need to contain the whole data hierarchy. For example, if the master lexicon defines a simple data hierarchy with levels "simulation-comp_unit-stratum-tree", the extra lexicons could have only levels "simulation-comp_unit-stratum" or "simulation-comp_unit", if there are no project specific variables in the lower levels.