User Guide

From Modular Dispersal in GIS

Please excuse the state of this guide. Being the sole maintainer and contributor of this project (among other projects and commitments), means I'm unable to do full justice to the user guide. Feel free to contribute or to email me questions about sections that are unclear or are of particular interest.

Concepts

The Instance execution loop

A dispersal model can have a number of instances. Each instance is a unique combination of parameters (if you've set up a range of parameters to simulate, i.e. for sensitivity analysis) and a management strategy.

Each instance runs a number of replicates. When a replicate is run, it goes through each timestep, and then splits the execution of the timestep into the lifestages. When a lifestage is run, it processes the various events associated with it in sequential order.

After all lifestages are executed (just before transitioning to the next timestep), and if their is an associated Management Strategy for the instance, then the appropriate treatments are applied to each lifestages' distribution map.

Getting Started

Installation

See either Installation on Linux or Installation on Windows for installation instructions.

Usage

Without options, MDiG will print out the actions it can perform:

~$ mdig.py 
Usage: mdig.py <action> [options] experiment.xml

=== Actions ===
add      - Add a model to the repository based on an xml definition.
admin    - Perform miscellaneous administative tasks
analysis - Perform analysis on a model and create occupancy envelopes
export   - Export images and movies of simulation.
info     - Display information about a model in the MDiG repository.
list     - List the models currently in MDiG repository.
node     - Runs MDiG as a node in a distributed instance of MDiG
remove   - Remove a model from the repository and delete mapset.
roc      - Create Receiver Operating Characteristic curves for occupancy envelopes and calculate AUC.
run      - Run a model
web      - Run a webserver that allows interaction with MDiG
Options:
-h (--help) 	 Display action specific help

experiment.xml is the file containing the simulation details.

Note, depending on how current this documentation is and which version of MDiG you are using, this list of actions could be different to what you see when you ask MDiG for help. For more information about each action, see the List of MDiG Actions.

Setting up a model

To create and run a model there are several steps:

• First create the DispersalML file.
• Run the MDiG add action specifying the filename of your model:

$ mdig.py add my_dispersal_model.xml

• This will parse the model file, and ensure it doesn't have any obvious errors, and then add it to the MDiG Repository. The result of the add action is that it creates a new mapset in your current GRASS location with the same name as the model. Thus, when you add the model, you should be in the same location as all the other data that the model references. Maps from other mapsets may be referred to in the model DispersalML file by using the map_name@mapset_name syntax. For more detail see Creating a new location.
• Run MDiG, referencing the model by it's name (not the filename, as was used in the add action):

$ mdig.py run my_dispersal_model_name

• Go have a cup of coffee or a nap while you wait for the model to run (depending on the size of the region, resolution and number of replicates).

After you have run the simulation, you probably want to analyse the results. Here are some examples of useful analysis commands.

Configuration

A configuration file is created at .mdig/mdig.conf by default if it doesn't exist. MDiG will create the .mdig directory if it doesn't already exist.

MDiG uses ConfigObj for config file management, and so follows the format specified here. The specific options and their default values are discussed at mdig.conf.

Modules

Dispersal models are composed of a series of modules which temporally advance the population distribution map in some way. There are modules that come with MDiG but modules can also be composed from GRASS GIS commands.

Management

This section covers simulating management strategies in MDiG. These are additionally instances of the dispersal model which are altered according to a set of treatments. These treatments can be global or restricted to a certain region. Treatments impact the spread of population distribution either by adding an additional event to a lifestage, or by modifying a variable that has previously been specified in the event loop.

Model format

Create a <management> tag between <lifestages> and before <instances> or the closing tag </model>. The rough layout is:

<management>
  <strategy name="outliers_mw" region="mdig_region_id">
    <description>Control outliers in Manuwatu</description>
    <delay>1</delay> <!--optional-->
    <treatments>
     <t>treatment action... see below</t>
     <t>...</t>
     ...
    </treatments>
  </strategy>
  <strategy>...</strategy>
</management>

Each <strategy> element is a separate management strategy to try. All dispersal instances will be run without management first, and then with all defined strategies. You can think of management strategies as another variable upon which dispersal instance permutations are created from (indeed, this is the way it's implemented in the code). As a result of this, it's worth realising that adding various strategies is going to create a potentially large number of dispersal instances if you are also doing sensitivity analysis of variables. The author suggests you do sensitivity analysis as a separate model, and then run management strategies with the mean expected value for variables.

Note that region="mdig_region_id" refers to the region id specified earlier in the model (see User Guide#Region), it doesn't specify the region where the ManagementStrategy is applied (for that aspect see User Guide#Treatment Area).

Treatments

Treatments come in two flavours...

The first is to apply an event-type action to a lifestage, this action will be applied to the lifestage population distribution map at the end of the timestep. If the treatment needs to be restricted to populations that are certain age then it's up to the module being used to implement this.

An examples of this type of treatment could be attempting to control new outlier populations, essentially it's doing something about long distance dispersal after the fact (and could therefore this type of treatment could be thought of as post-dispersal treatment).

<t>
  <area ls="lifestage_id" combine="and">
    <map>manuwatu_mask</map>
    <m_filter name="r.mdig.get_outliers">...same format as events</m_filter>
  </area>
  <event ls="lifestage_id" name="r.mdig.survival" prob="0.5">
    <!-- prob = 0.5 means 50% chance of this treatment being applied -->
    <param name="survival">
      <value>90</value> <!-- 90% chance of populations surviving -->
    </param>
  </event>
</t>

Alternatively, a treatment can alter a parameter for an event in the life-stage loop. If this type of treatment is restricted to a particular area like the above, then this requires that the event module supports a map as the parameter input.

<t>
  <alterVariable var="variable_id" prob="0.5">
    <decrease></decrease>
    <!-- or <increase></increase> -->
    <!-- or <ratio></ratio> which allows the decrease/increase to be dependent on var value --> 
    <!-- or <value></value> which allows the variable to be changed to a specific value... --> 
  </alterVariable>
</t>

In order to work out what parameter is being modified, it has to be specified as a <variable> (TODO: see ...). This is instead to just specifying an event parameter with the <value> tag, as this is just a constant parameter and more importantly, it doesn't have an ID by which reference it.

Treatment Area

There are several different scopes for the area impacted by treatment:

1. Global - the entire simulation region has the same impact applied. I.e. all of New Zealand (if your simulation is across all of New Zealand).
2. Static and regional - pre-set areas of the simulation region consistently have the same impact applied. E.g. high value areas or conservancies.
3. Dynamic and regional - dynamic area of the simulation region have an impact applied. E.g. attempting to control outlier populations.

If <area> isn't specified, the management is applied globally.

If it is defined, then <area> specifies a list of the following elements:

• <map>, a map that should be a mask; or
• <mapcalc>, a Map Algebra expression; or
• <mfilter>, a command that is used to determine the mask (this uses the same format as the dispersal <event> elements, an example is r.mdig.outliers).

Each of these is combined to give their intersection by default, or you can change the combine attribute of the <area> element to "or" if you want the list of maps to be combined to give their union.

For example:

<t>
  <area ls="lifestage_id" combine="and">
    <map>manuwatu_mask</map>
    <m_filter name="r.mdig.get_outliers"></m_filter>
  </area>
  ...
</t>

This treatment area definition would take the map "manuwatu_mask" (presumably a mask to limit management to the the Manuwatu region in New Zealand), and then find the intersection that with the outliers of the population distribution. In other words, the outliers within the Manuwatu region are affected by this treatment. If the combine attribute were set to "or", then the english translation would be: treat all outliers and all of the Manuwatu region.

Note: Actions that have global and static regional areas will be computationally faster as the control areas will not need to be recalculated at each time-step.

The <mapcalc> area definition is slightly different to one allowed elsewhere. It allows the use of POP_MAP and START_MAP terms. These will be replaced with the last population distribution for a lifestage, and the very first population distribution for the lifestage, respectively.

Examples

For example, if you wanted to reduce long distance dispersal in a certain area MDiG would:

1. Get the mask/map that specifies the area. If the area is dynamic then MDiG will regenerate it (e.g. finding outliers, or the boundary areas around population), otherwise it will use a cache (e.g. if using regional councils).
2. Create an input map for the parameter in question (for long distance dispersal this would be the freq parameter for r.mdig.kernel), where:
   1. values of 1 in the area map are replaced by the treatment value of the parameter
   2. and otherwise they have the parameter value specified in the main code.

You can also specify multiple treatments. Each one must be enclosed in <t>..</t> tags.

The above example, with separate treatments for outliers and certain areas (e.g. high value sites) is shown in the xml description below:

<strategy name="test_dyn_area" region="a">
  <description>reduce long distance dispersal</description>
  <treatments>
    <t>
      <area ls="all">
        <mfilter name="r.mdig.outliers"></mfilter>
      </area>
      <event ls="all" name="r.mdig.survival">
        <param name="survival">
          <value>0</value>
        </param>
      </event>
    </t>
    <t>
      <area ls="all">
        <map>high_value_sites</map>
      </area>
      <affectVariable var="freq">
        <ratio>0.2</ratio> <!-- reduce to 20% of the current frequency -->
      </affectVariable>
    </t>
  </treatments>
</strategy>

More examples for these types of impacts?

1. Decrease persistance
2. Decrease establishment (this will require distinguishing new from existing populations, or juvenile from adult populations... i.e. some way of distinguishing from the simulation of persistence).
3. Decrease/prevent local spread
4. Decrease/prevent long distance dispersal