DispersalML

MDiG is designed to model the spread of invasive species. This page attempts to describe the XML format for specifying dispersal models.

The model element

All the model elements must be contained in the DispersalML file root element named <model>.

The user element

<user>
  <email>joel@fruitionnz.com</email>
</user>

This section allows an email to be specified which the system should attempt to email once the simulation is finished. This primarily for the potential case of MDiG used via a web-based interface, allowing jobs to be submitted with MDiG emailing the user on completion of the simulation with a URL to the results (requesting a login with necessary).

The name element

<name>lhumile</name>

A simple alphanumeric name for use in filenames, and for referring to the species.

The description element

<description>Argentine Ant</description>

Verbose description of the model and/or organism. Primarily intended for users to explain their model when they pass it on to other researchers or archive it.

The random element

<random>
  <initialSeed> 1 </initialSeed>
  <replicates> 1 </replicates>
  <offset> 0 </offset>
</random>

Sets up the random number generator and number of simulation replicates, <initialSeed> indicates the seed to be used for the first replicate. <replicates> is the number of times to repeat each permutation of parameters. The <offset>parameter indicates the state of the random number generator when MDiG last finished running simulations on the model (in the case that not all simulations were finished last time MDiG was run using this model definition file, allowing it to resume where it left off).

GRASS GIS location

The GRASS location containing all base data must be defined like this:

<GISLocation>mylocation</GISLocation>

Regions

Indicates a list of regions to carry out simulations on. Each region entry must be inside the <region> ... </region> element, and has the following format:

<region id="a" name="test">
  <resolution>150&</resolution>
  <extents north="6609068" south="6354012" west="2568074" east="2829814">
  <background>
    <map>aa_background</map>
  </background>
</region>

For a model to run successfully, at least one region must be present inside the regions element.

The <id> tag of a <region> stanza is used for completed simulations to refer to, the <name> parameter loads a predefined (and existing) GRASS region with the given name. In GRASS this is equivalent to the command g.region region=test. Any sub-elements will override the parameters of this loaded region, however. That is, to just instruct MDiG to use a GRASS named region, just use <region id="a" name="test"></region>.

Available sub-elements offer the possibility to redefine region resolution and extents, as well as to choose a default background map. In detail, <resolution> indicates the raster resolution for simulation, as in g.region res=150. The <extents> parameter indicates the boundaries of the simulation region. A background map can be indicated with the <background> tag, specifiyng what should be displayed first when updating the map display. This is a "map" type object.

A brief diversion into what a "map"" type is

Map types are nodes of the XML tree that can have the following values:

• A <map> sub element is the name of a map in the current location using with optional mapset (using @ GRASS format). Example: nz_dem@simulation refers to the nz_dem map in the simulation mapset.
• A <value> sub element indicates a constant value across the current region.
• A <mapcalc> sub element specifies a Map Algebra expression. This can have an optional attribute refresh, which means the map should be regenerated everytime it is accessed. This is in the case of random elements or dependencies on changing maps. The format of the expression is the same format that the GRASS command r.mapcalc accepts.

The period element

<period>
  <startTime> 1990 </startTime>
  <endTime> 2006 </endTime>
  <step> 1 <step>
  <timeUnit> Year </timeUnit>
  <numberOfTimeIntervals> 365 </numberOfTimeIntervals>
  <timeIntervalUnit> Day </timeIntervalUnit>
</period>

The period element (and its sub-elements) handle the simulation time frame. Here you must indicate the start and end time of the simulation. Optionally, ine can also specify the length of each discrete time step (<step>) and the unit of time that simulation is dealing with (<timeUnit>). It is also possibile to indicate how the <timeUnit> should be divided, e.g. for timing of lifestages.

The total range for phenology events to occur in is [1 .. (<numberOfTimeIntervals> * <step>)].

The default values for <step>, <timeUnit>, <numberOfTimeIntervals> and <timeIntervalUnit> are shown in the example above.

the output element

<output>
  <raster>
    <interval> 1 </interval>
    <lifestage> all </lifestage>
  </raster>
  <png>
    <interval> 1 </interval>
    <showTime> true </showTime>
    <showGrid size="500"> false </showGrid>
  </png>
</output>

The output element indicates what direct output (e.g. the population distribution maps) of the simulation/model should be saved and when. The <raster> sub-element allows to permanently save raster maps that are generated at given intervals and for selected lifestages. Such maps are then referenced in the completed instances of the simulation (e.g. for later access in analysis). In detail, the <interval>sub-element indicates how many maps should be skipped (1 indicates none). Note that if the time step for the simulation is greater than 1 then the interval is NOT the difference between successive time values, but the number of steps.

The <lifestage>sub-element refers tp the id of the lifestage to save the distribution of.

The <png> sub-element allows for bitmap graphics to be output while the simulation is being performed. This has the same format as <raster> above, but the PNG image can can also be overlaid with a grid (<showGrid>), with resolution <size> (in map units of course), and the simulation time can be displayed (<showTime>).

Lifestages

The <lifestages> ... </lifestages> section contains the definition of all the lifestages used by the model, you need at lest one <lifestage> element for the simulation to work. The lifestages module can cointain lifestage and transition sub-elements.

The transition sub-element

Population-based simulations with different lifestages can apply a matrix-based population model using this feature. The transition files parameter specified within the transition tags contains all of the detail pertaining to the transition matrix, including implementing stochasticity and using different matrices across the landscape.

<transition>
  <popMod file="stochasticMatrix_A.xml"/>
  <popMod file="stochasticMatrix_B.xml"/>
  <popMod file="stochasticMatrix_C.xml"/>
</transition>

The lifestage sub-element

Each lifestage is specified by a <lifestage> element. A lifestage must have a name, to be referred in maps, and it must be specified whether that lifestage depends or not by population density.

A basic definition for a lifestage can be:

<lifestage name="all" populationBased="false">

that is, no lifestage (in the biological meaning of the term) at all. The populationBased parameter indicates whether a lifestage is based on presence and absences (populationBased="false"), or on population density (populationBased="true").

A lifestage has the following sub-elements:

<initialDistribution>

This tag indicates the the initial distribution for the current lifestage. It has a parameter <region>, that expects a region id to indicate what region the initial distribution is for. This tag can refer to a GRASS GIS map, via a map type, or can contain an explicit coordinates list such as, e.g.:

<sites>
  <s x="2671900" y="6474300"/>
  <s x="2671900" y="6474400"/>
  <s x="2672400" y="6474500"/>
</sites>

Coordinates are read in as GRASS vector points, and then converted to a raster. An optional parameter to the s tag is count, useful to indicate number of individuals present at that point when the lifestage is population based.

A convenient way to define an initial distribution can be using a GRASS raster prepared in advance. Raster values are simply the number of individuals per raster cell. You can then have an <initialDistribution> block lihe this:

<initialDistribution region="myregion">
  <map>intDistr_rast</map>
</initialDistribution>

<phenology>

The phenology tag indicates when a lifestage occurs. This tag cointains a region parameter that must refer to an existing region id. A mandatory sub-element is a map type, the values of which indicate when in the range [1 .. <step> * <numberOfIntervals> ] the lifestage should occur.

a number of <event> elements

<event name="r.dispersal.neighbour">
  <param name="shape">
    <value> 186 </value>
  </param>
  <param name="radius">
    <variable id="var1">
      <value> 3000 </value>
      <value> 2000 </value>
    </variable>
  </param>
  <ifNotPopulationBased>
    <flag name="b"/>
  </ifNotPopulationBased>
</event>

Each <event> elements define a spread or population dynamics process.

The name parameter of an <event> indicates the GRASS command that carries out the process. Depending on the specific GRASS command, what then follows are a number of <param> elements which are command line arguments to name GRASS command. Each <param> can have a <value> element, or a <variable> element which indicates a number of values to simulate over. Every permutation of these values (mixed with all other variables) is an "instance", and each "instance" is run for the number of replicates defined above in the random tag.

Conditional tags can also be added for population vs. presence-absence models (<ifNotPopulationBased>). But one would better off using separate files at this stage...

Another option for events is the flag tag which contains parameters to commands that don't expect arguments.

Additionally, event commands can also receive an input= and an output= option that process the map specified by input and return a map with the name specified by output.

For example, the event stanza above corresponds to these two GRASS commands (two because of the radius parameter that has two values):

r.dispersal.neighbour input=a output=b shape=186 radius=3000 -b
r.dispersal.neighbour input=a output=b shape=186 radius=2000 -b

Analyses

 <analyses>
 	<analysis name="r.stats">
 		<param name="input">
 			<previousMap/>
 		</param>
 		<flag name="c"/>
 		<flag name="n"/>
 		<output>
 			<file generate="true" ext=".dat" append="true" date="true"/>
 		</output>
 	</analysis>
 </analyses>

Analyses can also be specified within the model, as well as being run later. Their format is similar to that of events, but also indicate an '''output''' tag that tells MDiG what to do with the output of the analysis. Sub nodes of '''param''' elements can also be '''currentMap''', '''previousMap''', and '''initialMap''' instead of '''value''' so that what that what the analysis examines can be specified (some analysis requires more than a single map - such trying to calculate the distance from initial points of a invasion to the current distribution).

The '''output''' tag is has a sub node '''file''', the optional text of which is the filename, and this has the parameters:

• generate - if true, it generates a filename, the text of the '''file''' tag is used as a prefix is it exists.
• append - if true will append onto the end of the file (default: false)
• ext - specify the extension of the file created.
• date - append the interval/timestep to the file created before appending the output of the analysis command.