NAME
r.pops.spread - A dynamic species distribution model for pest or pathogen spread in forest or agricultural ecosystems (PoPS)
KEYWORDS
raster,
spread,
model,
simulation,
disease,
pest
SYNOPSIS
r.pops.spread
r.pops.spread --help
r.pops.spread [-ms] host=name total_plants=name infected=name [average=name] [average_series=basename] [single_series=basename] [stddev=name] [stddev_series=basename] [probability=name] [probability_series=basename] [outside_spores=name] [spread_rate_output=name] model_type=string [latency_period=integer] [treatments=name[,name,...]] [treatment_date=string[,string,...]] [treatment_length=integer[,integer,...]] [treatment_application=string] [moisture_coefficient_file=name] [temperature_coefficient_file=name] [weather_coefficient_file=name] [lethal_temperature=float] [lethal_month=integer] [temperature_file=name] start_date=string end_date=string seasonality=from,to step_unit=string step_num_units=integer [output_frequency=string] [output_frequency_n=integer] [reproductive_rate=float] natural_dispersal_kernel=string natural_distance=float natural_direction=string [natural_direction_strength=float] [anthropogenic_dispersal_kernel=string] [anthropogenic_distance=float] [anthropogenic_direction=string] [anthropogenic_direction_strength=float] [percent_natural_dispersal=float] [mortality_rate=float] [mortality_time_lag=integer] [mortality_series=basename] [random_seed=integer] [runs=integer] [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
Flags:
- -m
- Apply mortality
- After certain number of years, start removing dead hosts from the infected pool with a given rate
- -s
- Generate random seed (result is non-deterministic)
- Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
- --overwrite
- Allow output files to overwrite existing files
- --help
- Print usage summary
- --verbose
- Verbose module output
- --quiet
- Quiet module output
- --ui
- Force launching GUI dialog
Parameters:
- host=name [required]
- Input host raster map
- Number of hosts per cell.
- total_plants=name [required]
- Input raster map of total plants
- Number of all plants per cell
- infected=name [required]
- Input raster map of initial infection
- Number of infected hosts per cell
- average=name
- Average infected across multiple runs
- average_series=basename
- Basename for output series of average infected across multiple runs
- single_series=basename
- Basename for output series of infected as single stochastic run
- stddev=name
- Standard deviations
- stddev_series=basename
- Basename for output series of standard deviations
- probability=name
- Infection probability (in percent)
- probability_series=basename
- Basename for output series of probabilities
- outside_spores=name
- Output vector map of spores or pest units outside of modeled area
- spread_rate_output=name
- Output CSV file containg yearly spread rate in N, S, E, W directions
- model_type=string [required]
- Epidemiological model type
- Options: SI, SEI
- Default: SI
- SI: Susceptible-infected epidemiological model
- SEI: Susceptible-exposed-infected epidemiological model (uses latency_period)
- latency_period=integer
- Latency period in simulation steps
- How long it takes for a hosts to become infected after being exposed (unit is a simulation step)
- treatments=name[,name,...]
- Raster map(s) of treatments (treated 1, otherwise 0)
- treatment_date=string[,string,...]
- Dates when treatments are applied (e.g. 2020-01-15)
- treatment_length=integer[,integer,...]
- Treatment length in days
- Treatment length 0 results in simple removal of host, length > 0 makes host resistant for certain number of days
- treatment_application=string
- Type of treatmet application
- Options: ratio_to_all, all_infected_in_cell
- Default: ratio_to_all
- moisture_coefficient_file=name
- Input file with one moisture coefficient map name per line
- Moisture coefficient
- temperature_coefficient_file=name
- Input file with one temperature coefficient map name per line
- Temperature coefficient
- weather_coefficient_file=name
- Input file with one weather coefficient map name per line
- Weather coefficient
- lethal_temperature=float
- Temperature at which the pest or pathogen dies
- The temerature unit must be the same as for thetemerature raster map (typically degrees of Celsius)
- lethal_month=integer
- Month when the pest or patogen dies due to low temperature
- The temperature unit must be the same as for thetemperature raster map (typically degrees of Celsius)
- temperature_file=name
- Input file with one temperature raster map name per line
- The temperature should be in actual temperature units (typically degrees of Celsius)
- start_date=string [required]
- Start date of the simulation in YYYY-MM-DD format
- end_date=string [required]
- End date of the simulation in YYYY-MM-DD format
- seasonality=from,to [required]
- Seasonal spread (from,to)
- Spread limited to certain months (season), for example 5,9 for spread starting at the beginning of May and ending at the end of September
- Default: 1,12
- step_unit=string [required]
- Unit of simulation steps
- Options: day, week, month
- Default: month
- day: Compute next simulation step every N days
- week: Compute next simulation step every N weeks
- month: Compute next simulation step every N months
- step_num_units=integer [required]
- Number of days/weeks/months in each step
- Step is given by number and unit, e.g. step_num_units=5 and step_unit=day means step is 5 days
- Options: 1-100
- Default: 1
- output_frequency=string
- Frequency of simulation output
- Options: yearly, monthly, weekly, daily, every_n_steps
- Default: yearly
- output_frequency_n=integer
- Output frequency every N steps
- Options: 1-100
- Default: 1
- reproductive_rate=float
- Number of spores or pest units produced by a single host
- Number of spores or pest units produced by a single host under optimal weather conditions
- Default: 4.4
- natural_dispersal_kernel=string [required]
- Natural dispersal kernel type
- Options: cauchy, exponential
- Default: cauchy
- natural_distance=float [required]
- Distance parameter for natural dispersal kernel
- natural_direction=string [required]
- Direction of natural dispersal kernel
- Typically prevailing wind direction; none means that there is no directionality or no wind
- Options: N, NE, E, SE, S, SW, W, NW, NONE, none
- Default: none
- natural_direction_strength=float
- Strength of direction of natural dispersal kernel
- The kappa parameter of von Mises distribution (concentration); typically the strength of the wind direction
- anthropogenic_dispersal_kernel=string
- Anthropogenic dispersal kernel type
- Options: cauchy, exponential
- anthropogenic_distance=float
- Distance parameter for anthropogenic dispersal kernel
- anthropogenic_direction=string
- Direction of anthropogenic dispersal kernel
- Value none means that there is no directionality
- Options: N, NE, E, SE, S, SW, W, NW, NONE, none
- Default: none
- anthropogenic_direction_strength=float
- Strength of direction of anthropogenic dispersal kernel
- The kappa parameter of von Mises distribution (concentration); typically the strength of the wind direction
- percent_natural_dispersal=float
- Percentage of natural dispersal
- How often is the natural dispersal kernel used versus the anthropogenic dispersal kernel
- Options: 0-1
- mortality_rate=float
- Mortality rate of infected hosts
- Percentage of infected hosts that die in a given year (hosts are removed from the infected pool)
- Options: 0-1
- mortality_time_lag=integer
- Time lag from infection until mortality can occur in years
- How many years it takes for an infected host to die (value 1 for hosts dying at the end of the first year)
- mortality_series=basename
- Basename for series of number of dead hosts
- Basename for output series of number of dead hosts (requires mortality to be activated)
- random_seed=integer
- Seed for random number generator
- The same seed can be used to obtain same results or random seed can be generated by other means.
- runs=integer
- Number of simulation runs
- The individual runs will obtain different seeds and will be averaged for the output
- nprocs=integer
- Number of threads for parallel computing
- Options: 1-
Module
r.pops.spread
is a dynamic species distribution model for pest or pathogen spread in forest
or agricultural ecosystems. The model is process based
meaning that it uses understanding of the effect of weather on reproduction
and survival of the pest or pathogen in order to simulate
spread of the pest or pathogen into the future using simulation.
Figure: Infected hosts in a landscape, a typical model result
The module is using the PoPS Core library which is implementing
the PoPS model and it is a central part of the
Pest or Pathogen Spread (PoPS) project.
Figure: Logo of the Pest or Pathogen Spread framework the PoPS is part of
The PoPS model is a stochastic spread model of pests
and pathogens in forest and agricultural landscapes.
It is used for various pest, pathogens, and hosts including animals,
not just plants, as hosts.
It was originally developed for Phytophthora ramorum and the original
version of the model was written in R, later with Rcpp (Tonini, 2017),
and was based on Meentemeyer (2011) paper.
The current implementation of the GRASS GIS module is using PoPS Core
header-only C++ library which implements the PoPS model.
The primary development of
PoPS Core
and of
this module
happens in a
separate repositories and GRASS GIS Addons repository contains the latest
release of the model.
An alternative
steering version
of this module exists which includes a set of
features supporting geospatial simulation steering (Petrasova, 2020)
which is useful for exploring adaptive management scenarios.
Two basic epidemiological model types (
model_type) are available for a transition
of hosts between susceptible and infected classes:
1) susceptible-infected (SI) for an immediate transition when
a disperser establishes on the host and
2) susceptible-exposed-infected (SEI) for an intermediate state when
the host first becomes exposed and only after a latency period
(
latency_period) is over.
This page lists above the numerous inputs and parameters, although many
of them have default values, some need careful consideration and
calibration. The best way how to identify options relevant to
a given use case is to go through one of the available tutorials.
Typically, the model needs to be calibrated.
You can obtain the calibration from a published work,
colleague, calibrate the model manually (in GRASS GIS),
or use the R interface to PoPS called
rpops
which has dedicated functions for calibration.
-
The directions of wind consider north (N) to be grid north, if your
true north is different direction, you need to make an adjustment.
-
The module currently does not handle NULL (no data) as input, so you
need to change the NULLs to (most likely) zeros, for example:
r.null map=infection null=0
.
Use
R script to create weather coefficients based on a defined polynomial.
Example of creating file with list of input maps (unix-like command
line):
g.list type=raster pattern="moisture_*" mapset=climate -m > moistures.txt
g.list type=raster pattern="temperature_*" mapset=climate -m > temperatures.txt
Note that the above assumes that the names will be ordered by time.
This will happen automatically if they are, e.g. numbered as 001, 002,
etc. (e.g.
temperature_001 and not
temperature_1).
If they are numbered without the zero-padding, i.e. 1, 2, ..., 10,
11, ..., then in a unix-like command line, you can do pipe the result
through
sort with
-n (
| sort -n).
For example, for map names like
temperature_1, the following
unix-like command will do the sorting:
g.list type=raster pattern="temperature_*" mapset=climate | sort -k2 -t_ -n > temperatures.txt
Note the underscore which tells sort where to split the name for sorting
and the number 2 which indicates which part of the name to use for
sorting after splitting.
If you have the weather-related timeseries in a separate mapset, you
can add this mapset to the search path of your current mapset so that
you can have the rasters in the list without specifying the mapset.
To add to the search path, use for example:
In case the moisture coefficient is not used, we can generate a constant
raster map to be used as the coefficient:
Then using unix-like command line, we can create a list of these rasters
in a file based on the number of lines in a temperature list files we
created earlier:
NUM_LINES=`cat temperatures.txt | wc -l`
echo const_1 > moistures.txt
for LINE in `seq 2 $NUM_LINES`; do echo const_1 >> moistures.txt; done;
To account for (vector) treatments partially covering host cells:
# set resolution for treatments and convert to raster
g.region res=10 -ap
v.to.rast input=treatment output=treatment use=val
# resample to lower resolution (match host map resolution)
g.region align=host_map -p
r.resamp.stats -w input=treatment output=treatment_resampled method=count
# get maximum value, which is dependent on resolution
# e.g. when resampling from 10m to 100m, max will be 100 (100 small cells in 1 big cell)
r.info -r treatment_resampled
# result will be 0 to 1
r.mapcalc "treatment_float = test_treatment_resampled / 100"
# adjust host layer
r.mapcalc "treated_host = host - host * treatment_float"
Example of the run of the model (unix-like command line):
r.pops.spread host=host total_plants=all infected=infected_2005 \
moisture_coefficient_file=moistures.txt temperature_coefficient_file=temperatures.txt \
output=spread step=week start_time=2005 end_time=2010 \
reproductive_rate=4 dispersal_kernel=cauchy wind=NE random_seed=4
To cite this module, please refer to
How to cite
section in the readme file.
-
Meentemeyer, Ross K., Nik J. Cunniffe, Alex R. Cook, Joao A. N. Filipe,
Richard D. Hunter, David M. Rizzo, and Christopher A. Gilligan, 2011.
Epidemiological modeling of invasion in heterogeneous landscapes:
spread of sudden oak death in California (1990-2030).
Ecosphere 2:art17.
DOI: 10.1890/ES10-00192.1
-
Tonini, Francesco, Douglas Shoemaker, Anna Petrasova, Brendan Harmon,
Vaclav Petras, Richard C. Cobb, Helena Mitasova,
and Ross K. Meentemeyer.
Tangible geospatial modeling for collaborative solutions
to invasive species management.
Environmental Modelling & Software 92 (2017): 176-188.
DOI: 10.1016/j.envsoft.2017.02.020
-
Petrasova, A., Gaydos, D.A., Petras, V., Jones, C.M., Mitasova, H. and
Meentemeyer, R.K., 2020.
Geospatial simulation steering for adaptive management.
Environmental Modelling & Software 133: 104801.
DOI: 10.1016/j.envsoft.2020.104801
r.spread,
r.grow,
r.lake,
r.futures
Tutorials and other resources:
(in alphabetical order)
Chris Jones*
Margaret Lawrimore*
Vaclav Petras*
Anna Petrasova*
Previous contributors:
Zexi Chen*
Devon Gaydos*
Francesco Tonini*
* Center for Geospatial Analytics, NC State University
SOURCE CODE
Available at:
r.pops.spread source code
(history)
Latest change: Monday Nov 11 18:04:48 2024 in commit: 59e289fdb093de6dd98d5827973e41128196887d
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
© 2003-2024
GRASS Development Team,
GRASS GIS 8.4.1dev Reference Manual