The main class to control the spread simulation. More...
#include <simulation.hpp>
Public Member Functions | |
| Simulation (unsigned random_seed, RasterIndex rows, RasterIndex cols, ModelType model_type=ModelType::SusceptibleInfected, unsigned latency_period=0, bool dispersers_stochasticity=true, bool establishment_stochasticity=true, bool movement_stochasticity=true) | |
| Creates simulation object and seeds the internal random number generator. More... | |
| Simulation ()=delete | |
| void | remove (IntegerRaster &infected, IntegerRaster &susceptible, const FloatRaster &temperature, double lethal_temperature, const std::vector< std::vector< int >> &suitable_cells) |
| removes infected based on min or max temperature tolerance More... | |
| void | mortality (IntegerRaster &infected, IntegerRaster &total_hosts, double mortality_rate, int mortality_time_lag, IntegerRaster &died, std::vector< IntegerRaster > &mortality_tracker_vector, const std::vector< std::vector< int >> &suitable_cells) |
| kills infected hosts based on mortality rate and timing. More... | |
| unsigned | movement (IntegerRaster &infected, IntegerRaster &susceptible, std::vector< IntegerRaster > &mortality_tracker_vector, std::vector< IntegerRaster > &exposed, IntegerRaster &resistant, IntegerRaster &total_hosts, IntegerRaster &total_exposed, unsigned step, unsigned last_index, const std::vector< std::vector< int >> &movements, std::vector< unsigned > movement_schedule, std::vector< std::vector< int >> &suitable_cells) |
| Moves hosts from one location to another. More... | |
| void | generate (IntegerRaster &dispersers, const IntegerRaster &infected, bool weather, const FloatRaster &weather_coefficient, double reproductive_rate, const std::vector< std::vector< int >> &suitable_cells) |
| Generates dispersers based on infected. More... | |
| template<typename DispersalKernel > | |
| void | disperse (const IntegerRaster &dispersers, IntegerRaster &susceptible, IntegerRaster &exposed_or_infected, IntegerRaster &mortality_tracker, const IntegerRaster &total_populations, IntegerRaster &total_exposed, std::vector< std::tuple< int, int >> &outside_dispersers, bool weather, const FloatRaster &weather_coefficient, DispersalKernel &dispersal_kernel, const std::vector< std::vector< int >> &suitable_cells, double establishment_probability=0.5) |
| Creates dispersal locations for the dispersing individuals. More... | |
| template<typename DispersalKernel > | |
| void | move_overpopulated_pests (IntegerRaster &susceptible, IntegerRaster &infected, const IntegerRaster &total_hosts, std::vector< std::tuple< int, int >> &outside_dispersers, DispersalKernel &dispersal_kernel, const std::vector< std::vector< int >> &suitable_cells, double overpopulation_percentage, double leaving_percentage) |
| Move overflowing pest population to other hosts. More... | |
| void | infect_exposed (unsigned step, std::vector< IntegerRaster > &exposed, IntegerRaster &infected, IntegerRaster &mortality_tracker, IntegerRaster &total_exposed) |
| Infect exposed hosts (E to I transition in the SEI model) More... | |
| template<typename DispersalKernel > | |
| void | disperse_and_infect (unsigned step, const IntegerRaster &dispersers, IntegerRaster &susceptible, std::vector< IntegerRaster > &exposed, IntegerRaster &infected, IntegerRaster &mortality_tracker, const IntegerRaster &total_populations, IntegerRaster &total_exposed, std::vector< std::tuple< int, int >> &outside_dispersers, bool weather, const FloatRaster &weather_coefficient, DispersalKernel &dispersal_kernel, const std::vector< std::vector< int >> &suitable_cells, double establishment_probability=0.5) |
| Disperse, expose, and infect based on dispersers. More... | |
Detailed Description
template<typename IntegerRaster, typename FloatRaster, typename RasterIndex = int>
class pops::Simulation< IntegerRaster, FloatRaster, RasterIndex >
The main class to control the spread simulation.
The Simulation class handles the mechanics of the model, but the timing of the events or steps should be handled outside of this class unless noted otherwise. The notable exceptions are exposed hosts in the SEI model type and mortality.
The template parameters IntegerRaster and FloatRaster are raster image or matrix types. Any 2D numerical array should work as long as it uses function call operator to access the values, i.e. it provides indexing for reading and writing values using (). In other words, the operations such as the two following ones should be possible:
The PoPS library offers a Raster template class to fill this role, but other classes can be used as well.
Template parameter RasterIndex is type used for maximum indices of the used rasters and should be the same as what the actual raster types are using. However, at the same time, comparison with signed type are perfomed and a signed type might be required in the future. A default is provided, but it can be changed in the future.
Definition at line 126 of file simulation.hpp.
Constructor & Destructor Documentation
◆ Simulation() [1/2]
|
inline |
Creates simulation object and seeds the internal random number generator.
The same random number generator is used throughout the simulation and is seeded once at the beginning.
The number or rows and columns needs to be the same as the size of rasters used with the Simulation object (potentially, it can be also smaller).
- Parameters
-
model_type Type of the model (SI or SEI) latency_period Length of the latency period in steps random_seed Number to seed the random number generator rows Number of rows cols Number of columns dispersers_stochasticity Enable stochasticity in generating of dispersers establishment_stochasticity Enable stochasticity in establishment step movement_stochasticity Enable stochasticity in movement of hosts
Definition at line 157 of file simulation.hpp.
◆ Simulation() [2/2]
|
delete |
Member Function Documentation
◆ disperse()
|
inline |
Creates dispersal locations for the dispersing individuals.
Depending on what data is provided as the exposed_or_infected parameter, this function can be part of the S to E step or the S to I step.
Typically, the generate() function is called beforehand to create dispersers. In SEI model, the infect_exposed() function is typically called afterwards.
DispersalKernel is callable object or function with one parameter which is the random number engine (generator). The return value is row and column in the raster (or outside of it). The current position is passed as parameters. The return value is in the form of a tuple with row and column so that std::tie() is usable on the result, i.e. function returning std::make_tuple(row, column) fulfills this requirement.
The total_populations can be total number of hosts in the basic case or it can be the total size of population of all relevant species both host and non-host if dilution effect should be applied.
If establishment stochasticity is disabled, establishment_probability is used to decide whether or not a disperser is established in a cell. Value 1 means that all dispersers will establish and value 0 means that no dispersers will establish.
- Parameters
-
[in] dispersers Dispersing individuals ready to be dispersed [in,out] susceptible Susceptible hosts [in,out] exposed_or_infected Exposed or infected hosts [in,out] mortality_tracker Newly infected hosts (if applicable) [in,out] total_exposed Total exposed in all exposed cohorts [in] total_populations All host and non-host individuals in the area [in,out] outside_dispersers Dispersers escaping the raster weather Whether or not weather coefficients should be used [in] weather_coefficient Weather coefficient for each location dispersal_kernel Dispersal kernel to move dispersers establishment_probability Probability of establishment with no stochasticity
- Note
- If the parameters or their default values don't correspond with the disperse_and_infect() function, it is a bug.
Definition at line 499 of file simulation.hpp.
◆ disperse_and_infect()
|
inline |
Disperse, expose, and infect based on dispersers.
This function wraps disperse() and infect_exposed() for use in SI and SEI models.
In case of SEI model, before calling this function, last item in the exposed vector needs to be ready to be used for exposure, i.e., typically, it should be empty in the sense that there are no hosts in the raster. This is normally taken care of by a previous call to this function. The initial state of the exposed vector should be such that size is latency period in steps plus 1 and each raster is empty, i.e., does not contain any hosts (all values set to zero).
See the infect_exposed() function for the details about exposed vector, its size, and its items.
See disperse() and infect_exposed() for a detailed list of parameters and behavior. The disperse() parameter documentation can be applied as is except that disperse() function's parameter exposed_or_infested is expected to change based on the context while this function's parameter infected is always the infected individuals. Besides parameters from disperse(), this function has parameter exposed which is the same as the one from the infect_exposed() function.
Definition at line 771 of file simulation.hpp.
◆ generate()
|
inline |
Generates dispersers based on infected.
- Parameters
-
[out] dispersers (existing values are ignored) infected Currently infected hosts weather Whether to use the weather coefficient weather_coefficient Spatially explicit weather coefficient reproductive_rate reproductive rate (used unmodified when weather coefficient is not used)
Definition at line 421 of file simulation.hpp.
◆ infect_exposed()
|
inline |
Infect exposed hosts (E to I transition in the SEI model)
Applicable to SEI model, no-operation otherwise, i.e., parameters are left intact for other models.
The exposed vector are the hosts exposed in the previous steps. The length of the vector is the number of steps of the latency period plus one. Before the first latency period is over, the E to I transition won't happen because no item in the exposed vector is old enough to become infected.
The position of the items in the exposed vector determines their age, i.e., for how long the hosts are exposed. The oldest item is at the front and youngest at the end. Before the the first latency period is over, items in the front are still empty (unused) because no hosts were exposed for the given time period. After the first latency period, this needs to be true before the function is called and it is true after the function finished with the difference that after the function is called, the last item is empty in the sense that it does not contain any hosts.
When the E to I transition happens, hosts from the oldest item in the exposed vector are moved to the infected (and mortality tracker). They are removed from the exposed item and this item is moved to the back of the vector.
Like in disperse(), there is no distinction between infected and mortality_tracker, but different usage is expected outside of this function.
The raster class used with the simulation class needs to support .fill() method for this function to work.
- Parameters
-
step Step in the simulation (>=0) exposed Vector of exposed hosts infected Infected hosts mortality_tracker Newly infected hosts total_exposed Total exposed in all exposed cohorts
Definition at line 710 of file simulation.hpp.
◆ mortality()
|
inline |
kills infected hosts based on mortality rate and timing.
In the last year of mortality tracking the first index all remaining tracked infected hosts are removed. In indexes that are in the mortality_time_lag no mortality occurs. In all other indexes the number of tracked individuals is multiplied by the mortality rate to calculate the number of hosts that die that time step. The mortality_tracker_vector has a minimum size of mortality_time_lag + 1.
- Parameters
-
infected Currently infected hosts total_hosts All hosts mortality_rate percent of infected hosts that die each time period mortality_time_lag time lag prior to mortality beginning died dead hosts during time step mortality_tracker_vector vector of matrices for tracking infected host infection over time. Expectation is that mortality tracker is of length (1/mortality_rate + mortality_time_lag) suitable_cells used to run model only where host are known to occur
Definition at line 223 of file simulation.hpp.
◆ move_overpopulated_pests()
|
inline |
Move overflowing pest population to other hosts.
When the number of pests (pest population) is too high, part of them moves to a different location. Number of infected/infested hosts is considered to be the number of pests (groups of pest) in a raster cell.
The movement happens in two stages. First, all the leaving pests are identified and removed from the source cells. Second, the move to the target cells is performed. This means that even if the resulting number of pests in the target cell is considered too high, it is left as is and the move is performed the next time this function is called.
If the pests (pest population) cannot be accommodated in the target cell due to the insufficient number of susceptible hosts, the excessive pests die.
- Parameters
-
[in,out] susceptible Susceptible hosts [in,out] infected Infected hosts total_hosts All host individuals in the area. Is equal to infected + exposed + susceptible in the cell. [in,out] outside_dispersers Dispersers escaping the rasters dispersal_kernel Dispersal kernel to move dispersers (pests) overpopulation_percentage Percentage of occupied hosts when the cell is considered to be overpopulated leaving_percentage Percentage pests leaving an overpopulated cell
- Note
- Exposed hosts do not count towards total number of pest, i.e., total_host is assumed to be S + E in SEI model.
- Mortality is not supported by this function, i.e., the mortality rasters are not modified while the infected are.
Definition at line 591 of file simulation.hpp.
◆ movement()
|
inline |
Moves hosts from one location to another.
- Note
- Note that unlike the other functions, here, total_hosts, i.e., number of hosts is required, not number of all hosts and non-host individuals.
- Parameters
-
infected Currently infected hosts susceptible Currently susceptible hosts mortality_tracker_vector Hosts that are infected at a specific time step total_hosts All host individuals in the area. Is equal to infected + exposed + susceptible in the cell. total_exposed Total exposed in all exposed cohorts step the current step of the simulation last_index the last index to not be used from movements movements a vector of ints with row_from, col_from, row_to, col_to, and num_hosts movement_schedule a vector matching movements with the step at which the movement from movements are applied
- Note
- Mortality and non-host individuals are not supported in movements.
Definition at line 286 of file simulation.hpp.
◆ remove()
|
inline |
removes infected based on min or max temperature tolerance
- Parameters
-
infected Currently infected hosts susceptible Currently susceptible hosts temperature Spatially explicit temperature lethal_temperature temperature at which lethal conditions occur suitable_cells used to run model only where host are known to occur
Definition at line 187 of file simulation.hpp.
The documentation for this class was generated from the following file:
- include/pops/simulation.hpp
