Giter VIP home page Giter VIP logo

rpops's Introduction

PoPS (Pest or Pathogen Spread) R Package

R-CMD-check lint codecov DOI

Overview

This is an R package for simulating the spread of pests and pathogens. The package is an R package with multiple functions built around the PoPS (Pest or Pathogen Spread) model implemented in the C++ library maintained in the PoPS Core Repository.

PoPs is a stochastic spread model of pests and pathogens in forest and agricultural landscapes to learn more visit popsmodel.org. The R package provides an easy way for researchers to calibrate, validate, and test what if scenarios of treatment interventions. The model is also available in GRASS GIS you can install and use r.pops.spread to run the model in GRASS GIS.

Installation

If you are on Windows, you need to first install Rtools to get a C++ compiler that R can use.

Version Specific

If you want to install a specific version just change the version number.

install.packages("remotes")
remotes::install_github("ncsu-landscape-dynamics/rpops", ref = "v2.0.0")
library(PoPS)

Development Version

install.packages("remotes")
remotes::install_github("ncsu-landscape-dynamics/rpops")
library(PoPS)

Features

the PoPS package in R is built on top of PoPS Core C++ library includes:

  • Susceptible-infected (SI) and susceptible-exposed-infected (SEI) model types (model_type, latency_period).
  • Host mortality tracking (mortality_rate, mortality_time_lag, mortality).
  • Host removal and pesticide application treatments (treatments, treatment_date, pesticide_duration).
  • Host resistance based on pesticide application treatments (pesticide_duration > 0).
  • Treatments applied only to a ratio of hosts (treatment_application).
  • Yearly pest removal based on lethal temperature (lethal_temperature, lethal_month).
  • Two different dispersal kernels (natural_dispersal_kernel, anthropogenic_dispersal_kernel).
  • Cauchy, Exponential, Uniform, Power-law, Deterministic neighbor, Hyperbolic-Secant, Gamma, Weibull, Normal, and Logistic radial dispersal kernels use Von Mises distribution.
  • Seasonal spread (seasonality in months).
  • Host movement for animals moving from farm to farm or plants via nursery trade (use_movements, movements_file).
  • Reduced stochasticity options (generate_stochasticity, establishment_stochasticity, movement_stochasticity) and deterministic versions of kernels (deterministic) other required parameters if reducing stochasticity are (dispersal_percentage, establishment_probability).
  • Spread rate measurement in 4 cardinal directions (west_rate, east_rate, south_rate, north_rate) when (use_spreadrates) is true.
  • Distance to quarantine in 4 cardinal directions (north_distance_to_quarantine, south_distance_to_quarantine, east_distance_to_quarantine, west_distance_to_quarantine) when (use_quarantine) is true and (quarantine_areas_file) is provided.
  • Probability of quarantine escape (escape_probability).
  • Overpopulation function (individuals in areas of high population leave the area and disperse longer distances on average) (use_overpopulation, overpopulation_percentage, leaving_percentage, leaving_scale_coefficient).
  • Flexible output frequency with n number of days, weeks, months, or years as options (output_frequency, output_frequency_n).

Functions in rpops

  • calibrate: Calibration of the model parameters using either MCMC (markov chain monte carlo) or ABC (approximate bayesian computation).
  • validate: Validation of the model using quantiy, allocation, and configuration disagreement.
  • pops_multirun: Parallel execution of multiple stochastic runs (number_of_cores used to set cores used if left NULL defaults to using n - 1 cores on the machine). Outputs statistics of infected/infested hosts across multiple runs (simulation_mean, single_run, simulation_sd, simulation_min, simulation_max), current state using the median (infected, exposed, and susceptible), average and standard deviations whole area statistics (number_infecteds, infected_areas), and probability of infection (probability) which is the percent of model runs that a cell has at least one infestation/infection.
  • pops: Runs a single stochastic run of the model. This function is primarily used for automated testing of model functionality.

How to cite

If you use this software or code, please cite the following papers:

  • Jones, C., Jones, S., Petrasova, A., Petras, V., Gaydos, D., Skrip, M., Takeuchi, Y., Bigsby, K., and Meentemeyer, R., 2021. Iteratively forecasting biological invasions with PoPS and a little help from our friends. Frontiers in Ecology and the Environment DOI: 10.1002/fee.2357

In case you are using the automatic management feature in rpops or the steering version of r.pops.spread (from the branch steering), please cite also:

  • 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

In addition to citing the above paper, we also encourage you to reference, link, and/or acknowledge specific version of the software you are using for example:

Contributing

Please see the pops-core repository for contributing best practices and release policies. Other than that, just open pull requests against this repo. We suggest following the Style Guide from Hadley for R code.

Authors and contributors

Authors

(alphabetical order)

  • Chris Jones
  • Vaclav Petras
  • Anna Petrasova

Contributors

(alphabetical order)

  • Zexi Chen
  • Devon Gaydos
  • Margaret Lawrimore
  • Nick Kruskamp
  • Francesco Tonini

See Git commit history, GitHub insights, or CHANGELOG.md file for details about contributions.

License

Permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU General Public License version 2 or higher is hereby granted. No representations are made about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. See the GNU General Public License for more details.

rpops's People

Contributors

chrisjones687 avatar cyborginhas avatar dagaydos21 avatar malawrim avatar nkruskamp avatar petrasovaa avatar wenzeslaus avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

rpops's Issues

Validate and others give no valid constructor available for the argument list

When running devtools:test() locally with terra 1.1.13, I get the following error:

Error (test-validate.R:72:5): Validation has correctly formatted returns with multiple output
  comparisons
Error: no valid constructor available for the argument list
Backtrace:
  1. PoPS::validate(...) test-validate.R:72:4
  2. PoPS::configuration(config) /home/vpetras/Projects/pops/rpops/R/validate.R:165:2
  3. PoPS::initial_raster_checks(config$infected_file) /home/vpetras/Projects/pops/rpops/R/configuration.R:130:4
  5. terra::rast(x)
  6. terra:::.local(x, ...)
  7. SpatRaster$new(f, subds - 1, "", FALSE, 0[])
  8. methods::new(def, ...)
 10. methods::initialize(value, ...)
 11. .Object$initialize(...)
 12. Rcpp::cpp_object_initializer(.self, .refClassDef, ...)
 13. Rcpp:::new_CppObject_xp(fields$.module, fields$.pointer, ...)
> packageVersion("terra")
[1] ‘1.1.13’

However, I don't see the in the CI.

CI failing on MacOS

seems warnings are being thrown from RCPP so will probably not fix in the near future.

add tests for other functions

  • helpers
  • auto_manage
  • uncertainty_propogation
  • over-population (individuals disperse longer distance in an area of high population)
  • movements
  • mortality
  • deterministic spread

New Item

Created by Chris via monday.com integration. 🎉

Update model to output at different intervals

Currently model only provides outputs to the user on a yearly interval. Update to output at a user-specified interval. Doing so should allow for the model to be shifted toward an iterative disease-forecasting system.

latest/dev PoPS version fails to install with CRAN version of terra

With a fresh dev version install of PoPS, (e.g. devtools::install_github("ncsu-landscape-dynamics/rpops") it will install terra 1.1-4 from CRAN if terra is not already installed. However, the dev version of PoPS now depended on a version of terra (1.1.7) only on github.

If terra was originally installed from github, it will prompt to update. If terra was originally installed from CRAN, the latest version of PoPS will fail to install. You can of course manually update terra from github, but I don't believe this is the desired behavior.

Tests with parallelization fail

Potentially a package loading issue in the test file or a system issue but happens both locally and in CI when run using R CMD Check but not when used locally.

Have calibrate function happen yearly in a Bayesian Framework

Use last years output as the prior for the new year so we don't have to run the entire time series of data for calibration but can update it quickly as new information becomes available by only running the new data. Need to figure out how to weight the priors from previous years.

Better specs for terra version

Problem description

I'm not sure how exactly the terra versions are numbered, but there is couple of commits in Git which have 1.1-7 in the DESCRIPTION file. Just any of them is not enough. The first commit rpops now works with is rspatial/terra@cd4c35c.

Expected behavior, suggested solution

Notably, this will resolve itself over time (when the version we need is on CRAN) and I'm not sure what is the right for now.

The terra package is changing rapidly and we are currently using the development version from GitHub, so maybe using specific version in readme which is guaranteed to work?

devtools::install_github("rspatial/terra", ref="cd4c35c7818adc26be896d65d130070843fb61c5")

And/or using 1.1.8 (1.1-8) in DESCRIPTION file?

On the other hand, in the CI we are simply using the latest version/commit, so with active development in rpops (or a scheduled action we set up), we discover a potential incompatibility with terra here in the repo.

More info

Currently, you can get things like:

> devtools::load_all()
...
Warning message:
object ‘patches’ is not exported by 'namespace:terra' 
> packageVersion("terra")
[1] ‘1.1.7’

Update functions to use means and cov_matrix

Update all functions that use pops_model to take the vector of means and the cov_matrix from the abc calibration to draw from the current parameter distribution. This should will work even if the user wants to not use the distribution as they can pass in a cov matrix of all 0's and then each draw will just be the mean.

Model runs but only returns exposed

When running the model using timestep of days, yearly outputs, the model returned exposed but not other metrics. 2 problem spots come to mind

  • export statement in pops_model function

  • scheduler functionality

Here is the example code that doesn't work it is in abc calibration but the issue is calling the pops_model function.
'''
infected_years_file <- ffIn("purelines_7weeks.tif")
number_of_observations <- 68 ### This is the number of infected cells - just make sure it's consistent across years
prior_number_of_observations <- 0
prior_means <- c(0, 0, 0, 0, 0, 0) ### leave as 0 for now, means that you are giving them no weight
prior_cov_matrix <- matrix(ncol = 6, nrow = 6, 0)
params_to_estimate <- c(T, T, T, T, F, F) ### 1st: reproductive rates, 2nd: natural distance, 3rd: percent natural, 4tH: anthropogenic distance, 5th Natural Kappa, 6th anthropogenic kappa
number_of_generations <- 6
generation_size <- 50
checks = c(60, 20000, 1000, 10000)
infected_file <- ffIn("Pure_infected.tif")
host_file <- ffIn("Pure_host.tif")
total_plants_file <- ffIn("Pure_host.tif")
temp <- FALSE
temperature_coefficient_file <- ""
precip <- FALSE
precipitation_coefficient_file <- ""
model_type = "SEI"
latency_period = 14
time_step <- "day"
season_month_start <- 1
season_month_end <- 12
start_date <- '2003-01-01'
end_date <- '2003-02-13'
use_lethal_temperature <- FALSE
temperature_file <- ""
lethal_temperature <- -30
lethal_temperature_month <- 1
mortality_on <- FALSE
mortality_rate <- 0
mortality_time_lag <- 0
management <- FALSE
treatment_dates <- c('2003-01-24')
treatments_file <- ""
treatment_method <- "ratio"
natural_kernel_type <- "cauchy"
anthropogenic_kernel_type <- "cauchy"
natural_dir <- "N"
natural_kappa <- 0
anthropogenic_dir <- "NONE"
anthropogenic_kappa <- 0
pesticide_duration <- c(0)
pesticide_efficacy <- 1.0
mask <- NULL
success_metric <- "residual error" ### keep this the same
output_frequency <- "year"
movements_file = "" ## ignore - for pigs
use_movements = FALSE
percent_natural_dispersal <- 1.0
anthropogenic_distance_scale <- 0.0
'''

The C++ pops_model function has too many parameters

Adding more arguments to the C++ pops_model function causes too many arguments in foreign function call. Currently the function has 62 parameters. Adding 4 (e.g., for the overpopulation movements in #83) causes the error as the limit of 65 is hit. This is according to the documentation (the foreign function here is our pops_model):

arguments to be passed to the foreign function. Up to 65.

The best fix seems to be embrace the concept of config more. For #83, I'm working on a solution along these lines which will be a good prototype for the overall fix. Although it fixes this problem, I'm not sure yet if it works 100%.

rcmdcheck reports that all declared Imports should be used

The call:

rcmdcheck::rcmdcheck(args = c("--no-manual", "--no-multiarch"), error_on = "warning")

Gives:

N  checking dependencies in R code (3.1s)
   Namespaces in Imports field not imported from:
     ‘igraph’ ‘rgdal’ ‘rlist’
     All declared Imports should be used.
   Missing or unexported object: ‘PoPS::pops_model’

Move to a create configuration setup

This will need to be in version 2.0 as it will be a major change to the API. The idea is to create 2 configuration creation functions (one for current parameter layout and one that works with a JSON format) that write out a Rdata file that has the config file ready to run for the function selected (e.g. calibrate, validate, multi-run, or auto-manage). The idea is that it simplifies the addition of new parameters which will be especially relevant with the addition of multiple networks and support for multi-host systems. The setup should save users time and make for more easily reproducible workflows.

terra::as.points does not have fun and spatial parameters

Unlike rasterToPoints, terra::as.points does not have fun and spatial parameters. The current code:

  suitable_points <- terra::as.points(suitable,
                                    fun = function(x) {
                                      x > 0
                                    },
                                    spatial = TRUE)

produces:

Error: unused arguments (fun = function(x) {
    x > 0
}, spatial = TRUE)

with devtools::test().

Discovered in #81. Terra introduced in #79.

Link to website

Once the website version 1.0.0 launches add links to website for tutorials, FAQ, etc.

Add link to database API

Once public-facing database API is available put the link and how to use it in the readme. Additionally, add functionality for pulling directly from the API.

Add exposed file

Add exposed file so can have starting position of the model have both infected and exposed individuals at the start of the simulation.

auto_manage function needs better variable handling

Here are two possibly related problems with auto_manage code:

  1. R CMD check reports possible problems for the auto_manage function. Here are the results:
checking R code for possible problems ... NOTE
  auto_manage: no visible binding for global variable ‘infected’
  auto_manage: no visible global function definition for ‘stack’
  auto_manage: no visible binding for global variable ‘host’
  auto_manage: no visible global function definition for ‘nlayers’
  auto_manage: no visible binding for global variable ‘num_cells’
  auto_manage: no visible binding for global variable ‘buffer_cells’
  auto_manage: no visible binding for global variable ‘random_seeds’
  auto_manage: no visible binding for global variable ‘exposed’
  auto_manage: no visible binding for global variable ‘total_populations’
  auto_manage: no visible binding for global variable ‘mortality_tracker’
  auto_manage: no visible binding for global variable ‘mortality’
  auto_manage: no visible binding for global variable ‘quarantine_areas’
  1. Function is ignoring config or needs some explanation: The auto_manage function takes parameters, adds them to config list, but then config is not used to set parameters in the pops_model call. If this is an intention, it should be documented in a comment. If not, it should be fixed.

Combine abc_calibration with calibrate and abc_validate with validate

Combine abc_calibration function with calibrate function and abc_validate function with validate function. This reduces the amount of code that is duplicated across these and should be easily handled with a selection between the methods of calibration and thus the way they export the parameters and uncertainties.

.tif file size exceeds regular tif limits

1: TIFFAppendToStrip:Maximum TIFF file size exceeded. Use BIGTIFF=YES creation option. (GDAL error 1)
2: C:/Users/nfkruska/AppData/Local/Temp/RtmpKO6IQ2/spat_VDJGg7EJVrX8RAq.tif: WriteEncodedTile/Strip() failed. (GDAL error 1)

I'm posting here, although this may be an issue with terra. When the data files are too large, PoPS will fail with the above warnings from R. This is likely the weather data file. It appears when the file is being copied to the TEMP location it is being written without the BIGTIFF flag set to YES which allows a .tif file to exceed 4GB. My current weather file is ~2.88GB, but it is compressed. It may be we need to ensure the .tif profile is adjusted when replicating the data (to YES or IF_SAFER), or this may fall to terra not offering that option. This is not an issue with available RAM.

Chris, this is for the 250m CA data.

Add sensitivity and specificity function

Add a function to run the multi-run version of pops multiple times to get calculate sensitivity and specificity for model outputs compared to data. Currently being used in PEDv case study.

Update documentation

  1. Add variable ranges or values
  • Calibrate
  • Validate
  • PoPS
  • quantity allocation
  • pops_model

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.