r.pops.spread
A dynamic species distribution model for pest or pathogen spread in forest or agricultural ecosystems (PoPS)
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] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.pops.spread host=name total_plants=name infected=name average=name model_type=SI start_date=string end_date=string seasonality=1,12 step_unit=month step_num_units=1 natural_dispersal_kernel=cauchy natural_distance=float natural_direction=none
grass.script.run_command("r.pops.spread", host, total_plants, infected, average=None, average_series=None, single_series=None, stddev=None, stddev_series=None, probability=None, probability_series=None, outside_spores=None, spread_rate_output=None, model_type="SI", latency_period=None, treatments=None, treatment_date=None, treatment_length=None, treatment_application="ratio_to_all", moisture_coefficient_file=None, temperature_coefficient_file=None, weather_coefficient_file=None, lethal_temperature=None, lethal_month=None, temperature_file=None, start_date, end_date, seasonality="1,12", step_unit="month", step_num_units=1, output_frequency="yearly", output_frequency_n=1, reproductive_rate=4.4, natural_dispersal_kernel="cauchy", natural_distance, natural_direction="none", natural_direction_strength=None, anthropogenic_dispersal_kernel=None, anthropogenic_distance=None, anthropogenic_direction="none", anthropogenic_direction_strength=None, percent_natural_dispersal=None, mortality_rate=None, mortality_time_lag=None, mortality_series=None, random_seed=None, runs=None, nprocs=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r.pops.spread", host="name", total_plants="name", infected="name", average="name", model_type="SI", start_date="string", end_date="string", seasonality="1,12", step_unit="month", step_num_units=1, natural_dispersal_kernel="cauchy", natural_distance=float, natural_direction="none")
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
Allowed values: 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
Allowed values: 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
Allowed values: 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
Allowed values: 1-100
Default: 1
output_frequency=string
Frequency of simulation output
Allowed values: yearly, monthly, weekly, daily, every_n_steps
Default: yearly
output_frequency_n=integer
Output frequency every N steps
Allowed values: 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
Allowed values: 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
Allowed values: 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
Allowed values: 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
Allowed values: 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
Allowed values: 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)
Allowed values: 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
Allowed values: 1-
-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
--qq
Very quiet module output
--ui
Force launching GUI dialog
host : str, required
Input host raster map
Number of hosts per cell.
Used as: input, raster, name
total_plants : str, required
Input raster map of total plants
Number of all plants per cell
Used as: input, raster, name
infected : str, required
Input raster map of initial infection
Number of infected hosts per cell
Used as: input, raster, name
average : str, optional
Average infected across multiple runs
Used as: output, raster, name
average_series : str, optional
Basename for output series of average infected across multiple runs
Used as: output, raster, basename
single_series : str, optional
Basename for output series of infected as single stochastic run
Used as: output, raster, basename
stddev : str, optional
Standard deviations
Used as: output, raster, name
stddev_series : str, optional
Basename for output series of standard deviations
Used as: output, raster, basename
probability : str, optional
Infection probability (in percent)
Used as: output, raster, name
probability_series : str, optional
Basename for output series of probabilities
Used as: output, raster, basename
outside_spores : str, optional
Output vector map of spores or pest units outside of modeled area
Used as: output, vector, name
spread_rate_output : str, optional
Output CSV file containg yearly spread rate in N, S, E, W directions
Used as: output, file, name
model_type : str, required
Epidemiological model type
Allowed values: SI, SEI
SI: Susceptible-infected epidemiological model
SEI: Susceptible-exposed-infected epidemiological model (uses latency_period)
Default: SI
latency_period : int, optional
Latency period in simulation steps
How long it takes for a hosts to become infected after being exposed (unit is a simulation step)
treatments : str | list[str], optional
Raster map(s) of treatments (treated 1, otherwise 0)
Used as: input, raster, name
treatment_date : str | list[str], optional
Dates when treatments are applied (e.g. 2020-01-15)
treatment_length : int | list[int] | str, optional
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 : str, optional
Type of treatmet application
Allowed values: ratio_to_all, all_infected_in_cell
Default: ratio_to_all
moisture_coefficient_file : str, optional
Input file with one moisture coefficient map name per line
Moisture coefficient
Used as: input, file, name
temperature_coefficient_file : str, optional
Input file with one temperature coefficient map name per line
Temperature coefficient
Used as: input, file, name
weather_coefficient_file : str, optional
Input file with one weather coefficient map name per line
Weather coefficient
Used as: input, file, name
lethal_temperature : float, optional
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 : int, optional
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 : str, optional
Input file with one temperature raster map name per line
The temperature should be in actual temperature units (typically degrees of Celsius)
Used as: input, file, name
start_date : str, required
Start date of the simulation in YYYY-MM-DD format
end_date : str, required
End date of the simulation in YYYY-MM-DD format
seasonality : tuple[str, str] | list[str] | str, 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
Used as: from,to
Default: 1,12
step_unit : str, required
Unit of simulation steps
Allowed values: day, week, 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
Default: month
step_num_units : int, 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
Allowed values: 1-100
Default: 1
output_frequency : str, optional
Frequency of simulation output
Allowed values: yearly, monthly, weekly, daily, every_n_steps
Default: yearly
output_frequency_n : int, optional
Output frequency every N steps
Allowed values: 1-100
Default: 1
reproductive_rate : float, optional
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 : str, required
Natural dispersal kernel type
Allowed values: cauchy, exponential
Default: cauchy
natural_distance : float, required
Distance parameter for natural dispersal kernel
natural_direction : str, required
Direction of natural dispersal kernel
Typically prevailing wind direction; none means that there is no directionality or no wind
Allowed values: N, NE, E, SE, S, SW, W, NW, NONE, none
Default: none
natural_direction_strength : float, optional
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 : str, optional
Anthropogenic dispersal kernel type
Allowed values: cauchy, exponential
anthropogenic_distance : float, optional
Distance parameter for anthropogenic dispersal kernel
anthropogenic_direction : str, optional
Direction of anthropogenic dispersal kernel
Value none means that there is no directionality
Allowed values: N, NE, E, SE, S, SW, W, NW, NONE, none
Default: none
anthropogenic_direction_strength : float, optional
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, optional
Percentage of natural dispersal
How often is the natural dispersal kernel used versus the anthropogenic dispersal kernel
Allowed values: 0-1
mortality_rate : float, optional
Mortality rate of infected hosts
Percentage of infected hosts that die in a given year (hosts are removed from the infected pool)
Allowed values: 0-1
mortality_time_lag : int, optional
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 : str, optional
Basename for series of number of dead hosts
Basename for output series of number of dead hosts (requires mortality to be activated)
Used as: output, raster, basename
random_seed : int, optional
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 : int, optional
Number of simulation runs
The individual runs will obtain different seeds and will be averaged for the output
nprocs : int, optional
Number of threads for parallel computing
Allowed values: 1-
flags : str, optional
Allowed values: m, s
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: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
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
About the model
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.
Model parameters
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.
Calibration
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.
NOTES
- 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.
EXAMPLES
Obtaining list of rasters
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:
g.mapsets mapset=climate
Generating a constant coefficient
In case the moisture coefficient is not used, we can generate a constant raster map to be used as the coefficient:
r.mapcalc "const_1 = 1"
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;
Creating treatments
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"
Running the model
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
REFERENCES
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
SEE ALSO
r.spread, r.grow, r.lake, r.futures
Tutorials and other resources:
AUTHORS
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: Friday Feb 21 10:10:05 2025 in commit 7d78fe3