Skip to content

Latest commit

 

History

History
242 lines (194 loc) · 18.3 KB

README.md

File metadata and controls

242 lines (194 loc) · 18.3 KB
Raw


Model of Routes of Invasive Spread

   

Human-mediated dispersal acts as a vector for many exotic species, both at the introduction and secondary spread stages. Primary and secondary introductions arise from human-mediated long distance dispersal happening at global scales. Secondary spread occurs at smaller spatial and time scales (e.g. landscape) and results from either natural or human-mediated dispersal. Despite the importance of materials transportation (e.g. landscaping, construction) for the spread of invasive species, few studies have investigated short distance human-mediated dispersal and even less have tried to model it.

MoRIS (Model of Routes of Invasive Spread) is a spatially explicit spread model designed to simulate invasive species dispersal by transport at local to regional spatial scales. MoRIS is an innovative, yet simple model, taking into account the road network topology to influence the direction of dispersal events. MoRIS is designed to minimize a priori making (e.g., expert knowledge), to enable the estimation of human-mediated dispersal parameters based on a simple presence/absence locations dataset and to produce predictive maps of spread.

To learn how to use MoRIS, first install the latest release, and follow the installation instructions and the first usage guide. MoRIS software requires input files built in a certain way. To learn how to build this files, read the input files tutorial.

Table of contents

Publications and communications

• C. Rocabert, S. Fenet, B. Kaufmann and J. M.W. Gippet. Accounting for the topology of road networks to better explain human-mediated dispersal in terrestrial landscapes. Ecography, e07068 (2024). https://doi.org/10.1111/ecog.07068

• J. M.W. Gippet, S. Fenet, A. Dumet, B. Kaufmann and C. Rocabert (2016, August). MoRIS: Model of Routes of Invasive Spread. Human-mediated dispersal, road network and invasion parameters. In Proceedings of IENE 2016 conference. 5th International Conference on Ecology and Transportation: Integrating Transport Infrastructures with Living Landscapes (Lyon, France). http://hal.cirad.fr/LJK_MAD_STEEP/hal-01412280v1

• J. M.W. Gippet, C. Rocabert, S. Fenet, A. Dumet and B. Kaufmann (2015, July). Modeling and evaluating human-mediated dispersal mechanisms at landscape scale: a study of road network and invasion parameters for Lasius neglectus ants invasive species. In Proceedings of World Conference on Natural Resource Modeling (Bordeaux, France). https://hal.archives-ouvertes.fr/hal-01242828/

Authors

MoRIS is being developed by Charles Rocabert, Jérôme M.W Gippet and Serge Fenet.

Major contributors

  • Aymeric Bonnamour
  • Bernard Kaufmann

Other contributors

  • Vivek Srivastava

Citing MoRIS

If you are using MoRIS software for research purpose and publication, please cite the following manuscript: https://doi.org/10.1111/ecog.07068

Installation instructions

Download the latest release of MoRIS, and save it to a directory of your choice. Open a terminal and use the cd command to navigate to this directory. Then follow the steps below to compile and build the executables.

Supported platforms

MoRIS software has been successfully tested on Unix/Linux and macOS platforms.

Dependencies

  • A C++ compiler (GCC, LLVM, ...),
  • CMake (command line version),
  • GSL for C/C++,
  • CBLAS for C/C++,
  • Python ≥ 3 (Packages CMA-ES and numpy are required),
  • R (optional, packages ggplot2, cowplot and sf are required).

Software compilation

User mode

To compile MoRIS, run the following instructions on the command line:

cd cmake/

and

bash make.sh

Debug mode

To compile the software in DEBUG mode, use make_debug.sh script instead of make.sh:

bash make_debug.sh

This mode should only be used for test or development phases.

Executable files emplacement

Binary executable files are in build/bin folder.

First usage

Once MoRIS has been installed, follow the next steps for a first usage of the software.

Ready-to-use examples

Ready-to-use examples are available in the folder examples:

• run_single_simulation.sh: This script will run a single MoRIS simulation with given human-mediated dispersal parameters. You can execute it using the following command line:

bash run_single_simulation.sh

At the end of the simulation, a figure providing an overview of the simulation result is created (single_simulation.pdf). You can edit the parameter values at will to test the behaviour of the model. See below for a full description of the parameters.

• run_optimization.sh: This script will launch an optimization session by running multiple MoRIS simulations, and trying to find the solution matching the experimental data at best. You can execute it using the following command line:

bash run_optimization.sh

You can track the ongoing optimization in the text-file optimization.txt. At the end of the optimization session, MoRIS writes the best parameters set in a text-file. Optimization parameters are defined in a specific file named parameters.txt. See below for a full description of the parameters.

Run a MoRIS simulation

To run one MoRIS simulation, place yourself in the folder examples using the cd command, and execute the following command line:

../build/bin/MoRIS_run <parameters>

The command line parameters are described below. The description is also available by executing the following command line in a terminal:

../build/bin/MoRIS_run -h

Parameters:

  • -h, --help: Print this help, then exit,
  • -v, --version: Print the current version, then exit,
  • -seed, --seed: Specify the PRNG seed,
  • -typeofdata, --type-of-data: Specify the type of experimental data (PRESENCE_ONLY or PRESENCE_ABSENCE),
  • -network, --network: Specify the network file (default: network.txt),
  • -map, --map: Specify the map file (default: map.txt),
  • -sample, --sample: Specify the sample file (default: sample.txt),
  • -reps, --reps: Specify the number of repetitions by simulation,
  • -iters, --iters: Specify the number of iterations by simulation (usually one iteration is one year),
  • -law, --law: Specify the jump distribution law (DIRAC, NORMAL, LOG_NORMAL, CAUCHY),
  • -optimfunc, --optimfunc: Specify the optimization function (LSS, LOG_LIKELIHOOD, LIKELIHOOD_LSS). Use preferably the option LOG_LIKELIHOOD,
  • -humanactivity, --humanactivity: Specify if the human activity index should be used to weight the number of jump events (NO, YES),
  • -xintro --xintro: Specify the x coordinate of the introduction cell,
  • -yintro, --yintro: Specify the y coordinate of the introduction cell,
  • -pintro, --pintro: Specify the prevalence of the introduction (usually 1),
  • -lambda, --lambda: Specify the mean number of jumps per cell per year,
  • -mu, --mu: Specify the mean of the jump distribution (only works with DIRAC, NORMAL, LOG_NORMAL),
  • -sigma, --sigma: Specify the variance of the jump distribution (only works with NORMAL, LOG_NORMAL),
  • -gamma, --gamma: Specify the gamma parameter of the jump distribution (only works with CAUCHY),
  • -w1, --w1: Specify the weight of category I roads,
  • -w2, --w2: Specify the weight of category II roads,
  • -w3, --w3: Specify the weight of category III roads,
  • -w4, --w4: Specify the weight of category IV roads,
  • -w5, --w5: Specify the weight of category V roads,
  • -w6, --w6: Specify the weight of category VI roads,
  • -wmin, --wmin: Specify the minimal weight between cells,
  • -save-outputs, --save-outputs: Save simulation outputs (final state, lineage tree, ...),
  • -save-all-states, --save--all-states: Save simulation state at any time.

Couple MoRIS to the optimization algorithm

To determine the HMD parameters explaining at best a given experimental dataset, MoRIS simulations are coupled to an optimization algorithm. MoRIS software provides a tool to do this: MoRIS_optimize.py. This script depends on a parameters file named parameters.txt that has a specific structure and parameters (see the example file ./examples/parameters.txt). This parameters file allows the user to define the number of HMD parameters to optimize, their boundaries, and the type of optimization function desired. The parameters file adds a layer on top of simulation parameters (see above):

  • EXEC_PATH: Specify the path of MoRIS_run executable,
  • NETWORK_FILE: Specify the path of the road network file (usually network.txt),
  • MAP_FILE: Specify the path of the map file (usually map.txt),
  • SAMPLE_FILE: Specify the path of the sample file (usually sample.txt),
  • SEED: Specify the PRNG seed,
  • TYPE_OF_DATA: Specify the type of experimental data provided in map.txt (PRESENCE_ONLY, PRESENCE_ABSENCE),
  • REPETITIONS_BY_SIMULATION: Specify the number of repetitions by simulation,
  • NUMBER_OF_ITERATIONS: Specify the number of iterations by simulation (usually, one iteration is one year),
  • JUMP_LAW: Specify the the jump distribution law (DIRAC, NORMAL, LOG_NORMAL, CAUCHY),
  • OPTIMIZATION_FUNCTION: Specify the optimization function (LSS, LOG_LIKELIHOOD, LIKELIHOOD_LSS),
  • HUMAN_ACTIVITY_INDEX: Specify if the human activity index should be used to weight the number of jump events (NO, YES),
  • WMIN: Specify the minimal weight between cells,
  • XINTRO_DEFAULT: Specify the default x coordinate of the introduction cell (if not optimized),
  • YINTRO_DEFAULT: Specify the default y coordinate of the introduction cell (if not optimized),
  • PINTRO_DEFAULT: Specify the default prevalence of introduction (if not optimized),
  • LAMBDA_DEFAULT: Specify the default mean number of jumps per cell per year (if not optimized),
  • MU_DEFAULT: Specify the default mean of the jump distribution (only works with DIRAC, NORMAL, LOG_NORMAL) (if not optimized),
  • SIGMA_DEFAULT: Specify the default variance of the jump distribution (with NORMAL, LOG_NORMAL) (if not optimized),
  • GAMMA_DEFAULT: Specify the default gamma parameter of the jump distribution (with CAUCHY) (if not optimized),
  • W1_DEFAULT: Specify the default weight of category I roads (if not optimized),
  • W2_DEFAULT: Specify the default weight of category II roads (if not optimized),
  • W3_DEFAULT: Specify the default weight of category III roads (if not optimized),
  • W4_DEFAULT: Specify the default weight of category IV roads (if not optimized),
  • W5_DEFAULT: Specify the default weight of category V roads (if not optimized),
  • W6_DEFAULT: Specify the default weight of category VI roads (if not optimized),
  • OPTIMIZE_XINTRO: Specify if the x coordinate of the introduction cell must be optimized (NO, YES),
  • OPTIMIZE_YINTRO: Specify if the y coordinate of the introduction cell must be optimized (NO, YES),
  • OPTIMIZE_PINTRO: Specify if the prevalence of introduction must be optimized (NO, YES),
  • OPTIMIZE_LAMBDA: Specify if the mean number of jumps per cell per year must be optimized (NO, YES),
  • OPTIMIZE_MU: Specify if the mean of the jump distribution must be optimized (NO, YES),
  • OPTIMIZE_SIGMA: Specify if the variance of the jump distribution must be optimized (NO, YES),
  • OPTIMIZE_GAMMA: Specify if the gamma parameter of the jump distribution must be optimized (NO, YES),
  • OPTIMIZE_W1: Specify if the weight of category I roads must be optimized (NO, YES),
  • OPTIMIZE_W2: Specify if the weight of category II roads must be optimized (NO, YES),
  • OPTIMIZE_W3: Specify if the weight of category III roads must be optimized (NO, YES),
  • OPTIMIZE_W4: Specify if the weight of category IV roads must be optimized (NO, YES),
  • OPTIMIZE_W5: Specify if the weight of category V roads must be optimized (NO, YES),
  • OPTIMIZE_W6: Specify if the weight of category VI roads must be optimized (NO, YES),
  • XINTRO_MIN and XINTRO_MAX: Specify the boundaries of x (0 ≤ x ≤ 1),
  • YINTRO_MIN and YINTRO_MAX: Specify the boundaries of y (0 ≤ y ≤ 1),
  • PINTRO_MIN and PINTRO_MAX: Specify the boundaries of pintro (0 ≤ pintro ≤ 1),
  • LAMBDA_MIN and LAMBDA_MAX: Specify the boundaries of λ (0 ≤ λ),
  • MU_MIN and MU_MAX: Specify the boundaries of μ (0 ≤ μ),
  • SIGMA_MIN and SIGMA_MAX: Specify the boundaries of σ (0.1 ≤ σ),
  • GAMMA_MIN and GAMMA_MAX: Specify the boundaries of γ (0 ≤ γ),
  • W1_MIN and W1_MAX: Specify the boundaries of w1 (0 ≤ w1 ≤ 1),
  • W2_MIN and W2_MAX: Specify the boundaries of w2 (0 ≤ w2 ≤ 1),
  • W3_MIN and W3_MAX: Specify the boundaries of w3 (0 ≤ w3 ≤ 1),
  • W4_MIN and W4_MAX: Specify the boundaries of w4 (0 ≤ w4 ≤ 1),
  • W5_MIN and W5_MAX: Specify the boundaries of w5 (0 ≤ w5 ≤ 1),
  • W6_MIN and W6_MAX: Specify the boundaries of w6 (0 ≤ w6 ≤ 1).

Input files tutorial

A tutorial to build MoRIS input files is available here.

Copyright

Copyright © 2014-2024 Charles Rocabert, Jérôme M.W Gippet, Serge Fenet. All rights reserved.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.