User Manual
If invoked without options, MDiG will print out its help page, as any GRASS command:
GRASS 6.4.3 (MDiG):~/mdig > ./mdig.py
Unknown action 'None'
MDiG 0.3.2 - "Digger"
Usage: mdig.py <action> [options] [model_name|model.xml]
=== Actions ===
add - Add a model to the repository based on an xml definition.
admin - Perform miscellaneous administrative 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
reduce - Take a series of CSV output files and calculate average and std.
remove - Remove a model from the repository and delete mapset.
repository - Set/modify the current MDiG repository and location
reset - Reset the model. Delete all prior instances/replicates.
roc - Create Receiver Operating Characteristic curves for occupancy envelopes and calculate AUC.
run - Run a model
stats - Calculate univariate statistics for maps.
web - Run a webserver that allows interaction with MDiG
Options:
-h (--help) Display action specific help
model_name is the name of a model within the repository.
model.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.
To create and run a model you must:
- Define your model creating a file in DispersalML
- Add the model definition you've created to the model repository
- Run MDiG, referencing the model by its name
To create a model definition file, see DispersalML
Use the add action, specifying the filename of your model definition file:
$ mdig.py add my_dispersal_model.xml
This will parse the model definition file, ensure it doesn't have any obvious errors, and add it to the MDiG Repository. As a result, a new mapset will be created in your current GRASS location, with the same name as the model. Thus, when you add a 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 definition file by using the standard GRASS map_name@mapset_name syntax. For more detail see Creating a new location.
Invoke MDiG with the run action, referencing the model by its name (not the filename of the model definition file, 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 (runtime depends on the size of the region, on the region resolution and on number of replicates).
After you have run the simulation, you probably want to analyse the results. There are some examples of useful analysis commands.
A configuration file (that is not a model definition file!) is created at .mdig/mdig.conf, in the curerent directory, by default if it doesn't exist. MDiG will create the .mdig directory if it doesn't already exist.
MDiG uses ConfigObj for configuration file management, and so follows the format specified here. The specific options available in the mdig.conf file are discussed here.
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 stabdard GRASS GIS commands.
In MDiG it is possible also to simulatine management strategies. There are in fact additional 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.
Create a section tagged <management> between <lifestages> section and before <instances> section or before the closing </model> tag . 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 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 from which dispersal instance permutations are created (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 greater than a threshold age, then it's up to the module being used to implement this. An example 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 therefore this type of treatment could be thought of as a post-dispersal treatment). manuwatu_mask <m_filter name="r.mdig.get_outliers">...same format as events</m_filter> 90 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 treatment area as in the example the above, then this requires that the event module supports a map as the parameter input. In order to work out what parameter is being modified, it has to be specified as a (TODO: see ...). This is instead to just specifying an event parameter with the 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: Global - the entire simulation region has the same treatment applied. I.e. all of New Zealand (if your simulation is across all of New Zealand). Static and regional - pre-set areas of the simulation region consistently have the same treatment applied. E.g. high value areas or conservancies. Dynamic and regional - dynamically-defined area of the simulation region has a treatment applied. E.g. attempting to control outlier populations involves defining outlying populations, which can change each timestep. If isn't specified, the management is applied globally. If it is defined, then specifies a list of the following elements: , a map that should be a mask; or , a Map Algebra expression; or , a command that is used to determine the mask (this uses the same format as the dispersal 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 element to "or" if you want the list of maps to be combined to give their spatial union. For example: manuwatu_mask <m_filter name="r.mdig.get_outliers"></m_filter> ... 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 or static regional areas will be computationally faster, as the treatment areas will not need to be recalculated at each time-step. The area definition is slightly different to those 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: 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 core populations), otherwise it will use a cache (e.g. if using administrative boundaries such as regional councils). Create an input map for the parameter in question (for long distance dispersal this would be the freq parameter for r.mdig.kernel), where: values of 1 in the area map are replaced by the treatment value of the parameter and otherwise they have the parameter value specified in the main code. You can also specify multiple treatments. Each one must be enclosed in .. tags. The above example, with separate treatments for outliers and certain areas (e.g. high value sites) are shown in the xml description below: reduce long distance dispersal 0 high_value_sites 0.2 More examples for these types of impacts? Decrease persistence 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). Decrease/prevent local spread Decrease/prevent long distance dispersal