-
Notifications
You must be signed in to change notification settings - Fork 1
DispersalML
MDiG is designed to model the spread of invasive species. This page attempts to describe the XML format for specifying dispersal models.
All the model elements must be contained in the DispersalML file root element named <model>
.
<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).
<name>lhumile</name>
A simple alphanumeric name for use in filenames, and for referring to the species.
<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.
<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).
The GRASS location containing all base data must be defined like this:
<GISLocation>mylocation</GISLocation>
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.
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 thenz_dem
map in thesimulation
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 attributerefresh
, 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 commandr.mapcalc
accepts.
<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.
<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 interval
s and for selected lifestage
s. 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>
).
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.
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>
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:
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>
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.
<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 value
s 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> <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.