#' @title Model Landscape Epidemiology & Evolution
#' @name model_landsepi
#' @description Stochastic, spatially-explicit, demo-genetic model simulating the spread and evolution of a pathogen in a heterogeneous landscape.
#' @param timeP list of simulation parameters (number of years, number of time-steps per year)
#' @description Stochastic, spatially-explicit, demo-genetic model simulating the spread and evolution of a pathogen
#' in a heterogeneous landscape.
#' @param time_param list of simulation parameters (number of years, number of time-steps per year)
#' @param landscape landscape generated through AgriLand
#' @param dispersal list of dispersal parameters (vectorised dispersal matrix of the pathogen, vectorised dispersal matrix of the host)
#' @param dispersal list of dispersal parameters (vectorised dispersal matrix of the pathogen, vectorised dispersal
#' matrix of the host)
#' @param inits list initial conditions (initial probability of infection by the pathogen)
#' @param val_seed seed (for random number generation)
#' @param hostP list of host parameters (number of cultivars, initial planting density, maximal carrying capacity, growth rate, reproduction rate, death rate, resistance formula,
#' parameters of the sigmoid invasion function: kappa, sigma and s)
#' @param pathoP list of pathogen parameters (probability to survive the off-season, probability to reproduce via sex rather than via cloning,
#' infection rate, reproduction rate, average latent period duration, variance of the latent period, average infectious period duration
#' , variance of the infectious period duration, parameters of the sigmoid contamination function: kappa, sigma, s)
#' @param evolP list of evolution parameters (cost of infectivity, cost of aggressiveness, mutation rate, efficiency of major
#' resistance genes, efficiency of quantitative resistance, trade-off strength, number of increments of quantitative
#' resistance erosion, average time to expression of quantitative resistance, Variance of the time to expression of quantitative resistance,
#' adaptation formula)
#' @param seed seed (for random number generation)
#' @param cultivars_param list of host parameters (number of cultivars, initial planting density, maximal carrying
#' capacity, growth rate, reproduction rate, death rate, resistance formula, parameters of the sigmoid invasion
#' function: kappa, sigma and s)
#' @param basic_patho_param list of pathogen parameters (probability to survive the
#' off-season, probability to reproduce via sex rather than via cloning, infection rate, reproduction rate, average
#' latent period duration, variance of the latent period, average infectious period duration, variance of the
#' infectious period duration, parameters of the sigmoid contamination function: kappa, sigma, s)
#' @param genes_param list of evolution parameters (cost of infectivity, cost of aggressiveness, mutation rate,
#' efficiency of major resistance genes, efficiency of quantitative resistance, trade-off strength, number of
#' increments of quantitative resistance erosion, average time to expression of quantitative resistance, Variance of
#' the time to expression of quantitative resistance, adaptation formula)
#' @details \itemize{
#' \item The model is stochastic, spatially explicit (the basic spatial unit is an individual field), based on a SEIR
#' (‘susceptible-exposed-infectious-removed’) structure with a discrete time step. It simulates the spread and evolution
#' of a pathogen in an agricultural landscape, across cropping seasons split by host harvests which impose potential bottlenecks
#' to the pathogen.
#' \item A wide array of deployment strategies can be simulated: mosaics, mixtures, rotations and pyramiding of multiple
#' major resistance genes which affect pathogen infectivity, and up to four quantitative resistance traits.
#' These traits target different aggressiveness components of the pathogen, i.e. the infection rate, the duration of the latent
#' period and the infectious period, and the propagule production rate. Quantitative resistance may be expressed from the time of planting,
#' or later in the cropping season (Adult Plant Resistance or Mature Plant Resistance).
#' \item The genotype of cultivated plant cultivars is specified using
#' the "resistance formulas", i.e. a vector of size 8. the four first elements indicate whether the cultivar carries major resistance
#' genes #1, #2, #3 and #4, respectively. The following four elements indicate whether the cultivar carried a quantitative resistance
#' trait against the infection rate, the latent period duration, the sporulation rate, or the sporulation duration of the pathogen, respectively.
#' For example, the formula c(1,0,0,0,0,1,0,0) indicates the presence of major gene #1 and a quantitative resistance
#' which increases the duration of the latent period of the pathogen.
#' \item Initially, the pathogen is not adapted to any source of
#' resistance, and is only present on susceptible hosts. However, through mutation, it can evolve and may acquire infectivity
#' genes (which leads to breakdown of major resistance genes) or increase aggressiveness (which leads to the erosion of the
#' relevant quantitative resistance traits). These genes may also be reassorted via sexual reproduction.
#' \item Evolution of a pathogen toward infectivity or increased aggressiveness on
#' a resistant host is often penalised by a fitness cost on susceptible hosts. Consequently, in the present model, pathogens
#' carrying infectivity genes may have reduced infection rate (cost of infectivity) on susceptible hosts relative
#' to pathogens that do not carry these genes. Similarly, a gain in pathogen aggressiveness on quantitatively resistant hosts
#' is penalised by a decreased aggressiveness on susceptible hosts, leading to a trade-off.
#' }
#' @return A set of binary files is generated for every year of simulation and every compartment: \itemize{
#' \item H: healthy hosts,
#' \item Hjuv: juvenile healthy hosts,
#' \item L: latently infected hosts,
#' \item I: infectious hosts,
#' \item R: removed hosts,
#' \item S: propagules.
#' }
#' Each file indicates for every time-step the number of individuals in each field, and when appropriate for each cultivar and pathotype)
#' @references Rimbaud L., Papaïx J., Rey J.-F., Barrett L. G. and Thrall P. H. (2018). Assessing the durability and efficiency of landscape-based strategies to deploy plant resistance to pathogens. \emph{PLoS Computational Biology} 14(4):e1006067.
#' \item The model is stochastic, spatially explicit (the basic spatial unit is an individual field), based on a SEIR
#' (‘susceptible-exposed-infectious-removed’) structure with a discrete time step. It simulates the spread and
#' evolution of a pathogen in an agricultural landscape, across cropping seasons split by host harvests which impose
#' potential bottlenecks to the pathogen.
#' \item A wide array of deployment strategies can be simulated: mosaics, mixtures, rotations and pyramiding of
#' multiple major resistance genes which affect pathogen infectivity, and up to four quantitative resistance traits.
#' These traits target different aggressiveness components of the pathogen, i.e. the infection rate, the duration of
#' the latent period and the infectious period, and the propagule production rate. Quantitative resistance may be
#' expressed from the time of planting, or later in the cropping season (Adult Plant Resistance or Mature Plant
#' Resistance).
#' \item The genotype of cultivated plant cultivars is specified using the "resistance formulas", i.e. a
#' vector of size 8. the four first elements indicate whether the cultivar carries major resistance genes #1, #2, #3
#' and #4, respectively. The following four elements indicate whether the cultivar carried a quantitative resistance
#' trait against the infection rate, the latent period duration, the propagule production rate, or the infectious
#' period duration of the pathogen, respectively. For example, the formula c(1,0,0,0,0,1,0,0) indicates the presence
#' of major gene #1 and a quantitative resistance which increases the duration of the latent period of the pathogen.
#' \item Initially, the pathogen is not adapted to any source of resistance, and is only present on susceptible hosts.
#' However, through mutation, it can evolve and may acquire infectivity genes (which leads to breakdown of major
#' resistance genes) or increase aggressiveness (which leads to the erosion of the relevant quantitative resistance
#' traits). These genes may also be reassorted via sexual reproduction.
#' \item Evolution of a pathogen toward
#' infectivity or increased aggressiveness on a resistant host is often penalised by a fitness cost on susceptible
#' hosts. Consequently, in the present model, pathogens carrying infectivity genes may have reduced infection rate
#' (cost of infectivity) on susceptible hosts relative to pathogens that do not carry these genes. Similarly, a gain
#' in pathogen aggressiveness on quantitatively resistant hosts is penalised by a decreased aggressiveness on
#' susceptible hosts, leading to a trade-off.}
#' @return A set of binary files is generated for every year of simulation and every compartment: \itemize{
#' \item H: healthy hosts,
#' \item Hjuv: juvenile healthy hosts,
#' \item L: latently infected hosts,
#' \item I: infectious hosts,
#' \item R: removed hosts,
#' \item P: propagules.}
#' Each file indicates for every time-step the number of individuals in each field, and when appropriate for
#' each cultivar and pathotype)@references Rimbaud L., Papaïx J., Rey J.-F., Barrett L. G. and Thrall P. H. (2018).
#' Assessing the durability andefficiency of landscape-based strategies to deploy plant resistance to pathogens.
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# 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
...
...
@@ -21,11 +21,13 @@
#' @title Inverse logit function
#' @name invlogit
#' @description Given a numeric object return the invlogit of the values. Missing values (NAs) are allowed.
#' @description Given a numeric object return the invlogit of the values. Missing values (NAs) are allowed.
#' @param x a numeric object
#' @details The invlogit is defined by exp(x) / (1+exp(x)). Values in x of -Inf or Inf return invlogits of 0 or 1 respectively. Any NAs in the input will also be NAs in the output.
#' @details The invlogit is defined by exp(x) / (1+exp(x)). Values in x of -Inf or Inf return invlogits of 0 or 1 respectively. Any NAs in the input will also be NAs in the output.
#' @return An object of the same type as x containing the invlogits of the input values.
#' @author Jean-Francois Rey \email{jean-francois.rey@@inra.fr}
#'
#'
#' Maintainer: Jean-Francois Rey \email{jean-francois.rey@@inra.fr}
#' @docType package
#' @name landsepi-package
#' @details \tabular{ll}{
#' Package: \tab landsepi\cr
#' Type: \tab Package\cr
#' Version: \tab 0.0.8\cr
#' Date: \tab 2018-11-27\cr
#' Version: \tab 0.1.0\cr
#' Date: \tab 2018-10-16\cr
#' License: \tab GPL (>=2)\cr
#' }
#'
#' The landsepi package implements a spatially explicit stochastic model able to assess the epidemiological and evolutionary outcomes of four major strategies
#' to deploy plant resistance to pathogens. These strategies include the combination of several resistance sources across time (crop rotations) or space.
#' The spatial scale of deployment can vary from multiple resistance sources occurring in a single cultivar (pyramiding),
#' in different cultivars within the same field (cultivar mixtures) or in different fields (mosaics). The simulated sources of resistance can
#' consist of qualitative resistance (i.e. major genes) or quantitative resistance traits (including Adult Plant Resistant genes) against several components of pathogen aggressiveness:
#' infection rate, latent period duration, propagule production rate, and infectious period duration. This model provides a useful tool to assess
#' the performance of a wide range of deployment options, and helps investigate the effect of landscape, epidemiological and evolutionary parameters
#' on the performance of a given strategy.
#'
#' The simulation model is based on a SEIR (Susceptible-Exposed-Infectious-Removed) architecture to describe host response to disease. The lansdcape is
#' represented by a set of polygons where the pathogen can disperse. Initially, the pathogen is not adapted to any source of resistance, and is only
#' present on susceptible hosts. However, through mutation, it can evolve and may acquire infectivity genes (which leads to breakdown of major resistance genes)
#' or increase aggressiveness (which leads to the erosion of the relevant quantitative resistance traits). Furthermore, loci may be re-assorted via sexual reproduction.
#' However, evolution of a pathogen toward infectivity or increased aggressiveness on a resistant host may be penalised
#' by a fitness cost on susceptible hosts. Consequently, pathogens carrying infectivity genes may have reduced infection rate (cost of infectivity) on susceptible
#' hosts relative to pathogens that do not carry these genes. Similarly, a gain in pathogen aggressiveness on quantitatively resistant hosts is penalised by a
#' The spatial scale of deployment can vary from multiple resistance sources occurring in a single cultivar (pyramiding),
#' in different cultivars within the same field (cultivar mixtures) or in different fields (mosaics). The simulated sources of resistance can
#' consist of qualitative resistance (i.e. major genes) or quantitative resistance traits (including Adult Plant Resistant genes) against several components of pathogen aggressiveness:
#' infection rate, latent period duration, propagule production rate, and infectious period duration. This model provides a useful tool to assess
#' the performance of a wide range of deployment options, and helps investigate the effect of landscape, epidemiological and evolutionary parameters
#' on the performance of a given strategy.
#'
#' The simulation model is based on a SEIR (Susceptible-Exposed-Infectious-Removed) architecture to describe host response to disease. The lansdcape is
#' represented by a set of polygons where the pathogen can disperse. Initially, the pathogen is not adapted to any source of resistance, and is only
#' present on susceptible hosts. However, through mutation, it can evolve and may acquire infectivity genes (which leads to breakdown of major resistance genes)
#' or increase aggressiveness (which leads to the erosion of the relevant quantitative resistance traits). Furthermore, loci may be re-assorted via sexual reproduction.
#' However, evolution of a pathogen toward infectivity or increased aggressiveness on a resistant host may be penalised
#' by a fitness cost on susceptible hosts. Consequently, pathogens carrying infectivity genes may have reduced infection rate (cost of infectivity) on susceptible
#' hosts relative to pathogens that do not carry these genes. Similarly, a gain in pathogen aggressiveness on quantitatively resistant hosts is penalised by a
#' decreased aggressiveness on susceptible hosts, leading to a trade-off.
#'
#'
#' The evolutionary outcome of a deployment strategy is assessed by measuring the time until the pathogen reaches the three steps to adapt to plant resistance: \itemize{
#' \item (d1) first appearance of adapted mutants,
#' \item (d2) initial migration to resistant hosts and infection, and
#' \item (d1) first appearance of adapted mutants,
#' \item (d2) initial migration to resistant hosts and infection, and
#' \item (d3) broader establishment in the resistant host population (i.e. the point at which extinction becomes unlikely). }
#' Epidemiological outcomes are evaluated using: \itemize{
#' \item (e1) the Green Leaf Area (GLA) as a proxy for yield, and
#' \item (e1) the Green Leaf Area (GLA) as a proxy for yield, and
#' \item (e2) the area under the disease progress curve (AUDPC) to measure disease severity.}
#'
#' The package includes five examples of landscape structures and a default parameterisation to represent plant pathogens as typified by rusts of cereal crops
#' (genus \emph{Puccinia}, e.g. stripe rust, stem rust and leaf rust of wheat and barley). The main function of the package is \code{simul_landsepi()}.
#'
#' The package includes five examples of landscape structures and a default parameterisation to represent plant pathogens as typified by rusts of cereal crops
#' (genus \emph{Puccinia}, e.g. stripe rust, stem rust and leaf rust of wheat and barley). The main function of the package is \code{simul_landsepi()}.
#' It can be parameterised to simulate various resistance deployment strategies using the provided landscapes and parameters for cereal rusts.
#'
#'
#' A set of graphics and a video showing epidemic maps can also be generated.
#'
#'
#' \strong{Future versions:}
#'
#'
#' Future versions of the package will include in particular:\itemize{
#' \item A more flexible parameterisation of pathogen life-history traits, in order to simulate other plant pathogens.
#' \item A more flexible parameterisation of deployment strategies, in order to simulate complex strategies combining several options (e.g. mosaic
