,
Stuart Brown [aut] ,
Damien Fordham [aut] | Title: | Pattern-Oriented Modeling Framework for Coupled Niche-Population Paleo-Climatic Models |
|---|---|
| Description: | This extension of the poems pattern-oriented modeling (POM) framework provides a collection of modules and functions customized for paleontological time-scales, and optimized for single-generation transitions and large populations, across multiple generations. |
| Authors: | Sean Haythorne [aut],
July Pilowsky [aut, cre] ,
Stuart Brown [aut] ,
Damien Fordham [aut] |
| Maintainer: | July Pilowsky <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 2.1.7 |
| Built: | 2025-01-27 20:48:05 UTC |
| Source: | https://github.com/globalecologylab/paleopop |
A raster dataset defining estimated habitat suitability values for each grid cells of the Siberian study region of the bison example vignette.
bison_hs_rasterbison_hs_raster
A raster::RasterStack object:
21 rows by 180 columns by 1001 layers
2 by 2 degree grid cells
longitude -180 to 180 degrees; latitude 42 to 84 degrees
Estimated habitat suitability values of 0 to 1
TBA
The paleopop package is an extension of the poems framework of R6 classes, which
simulate populations on a dynamic landscape and validate the results via pattern-oriented modeling. paleopop adds
functionality for modeling populations over paleo time scales.
The new functions and R6 classes added by paleopop to the poems framework are:
paleopop_simulator function: Analogous to the population_simulator
function in poems, this is the engine of simulation in paleopop, handling input parameters,
simulating over long time scales, and outputting up to six different types of results.
PaleoRegion class: Inherited from Region, this class defines a
geographic region that changes over time, creating a temporal mask that defines which cells are occupiable at a
time step.
region_subset function: a utility function for subsetting regions defined by coordinates.
PaleoPopModel class: Inherited from
SimulationModel, this class encapsulates the input parameters
utilized by the paleopop_simulator.
PaleoPopResults class: Inherited from
SimulationResults, this class encapsulates the results generated
by the paleopop_simulator, as well as dynamically generating
additional derived results.
Simulates a population model customized for paleontological time-scales, optimized for single-generation transitions and large populations, across multiple generations and returns simulation results. Each generational time-step includes:
Density dependence calculations
Environmental stochasticity calculations
Generational transition calculations
Harvest calculations
Dispersal calculations
Results collection
paleopop_simulator(inputs)paleopop_simulator(inputs)
inputs |
Nested list/object with named elements:
|
Simulation results as a nested list (as selected):
abundanceMatrix of simulation abundances (populations rows by time_steps columns).
emaMatrix of expected minimum abundances (populations rows by time_steps columns).
extirpationArray of extirpation times for each population.
harvestedMatrix of estimated individuals harvested (populations rows by time_steps columns).
occupancyArray of number of populations occupied at each time-step.
human_densityMatrix of human densities, (populations rows by time_steps columns).
library(raster) library(poems) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template model_template <- PaleoPopModel$new( region = region, time_steps = 10, years_per_step = 12, # years per generational time-step standard_deviation = 0.1, growth_rate_max = 0.6, harvest = FALSE, populations = region$region_cells, initial_abundance = seq(9000, 0, -1000), transition_rate = 1.0, carrying_capacity = rep(1000, 17), dispersal = (!diag(nrow = 17, ncol = 17))*0.05, density_dependence = "logistic", dispersal_target_k = 10, occupancy_threshold = 1, abundance_threshold = 10, results_selection = c("abundance") ) # Simulations results <- paleopop_simulator(model_template) # input as PaleoPopModel object inputs <- model_template$get_attributes() paleopop_simulator(inputs) # input as list of attributeslibrary(raster) library(poems) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template model_template <- PaleoPopModel$new( region = region, time_steps = 10, years_per_step = 12, # years per generational time-step standard_deviation = 0.1, growth_rate_max = 0.6, harvest = FALSE, populations = region$region_cells, initial_abundance = seq(9000, 0, -1000), transition_rate = 1.0, carrying_capacity = rep(1000, 17), dispersal = (!diag(nrow = 17, ncol = 17))*0.05, density_dependence = "logistic", dispersal_target_k = 10, occupancy_threshold = 1, abundance_threshold = 10, results_selection = c("abundance") ) # Simulations results <- paleopop_simulator(model_template) # input as PaleoPopModel object inputs <- model_template$get_attributes() paleopop_simulator(inputs) # input as list of attributes
R6 class representing a
spatially-explicit demographic-based population model. It extends the
poems class with parameters for the
paleopop_simulator. It inherits functionality for creating a
nested model, whereby a nested template model with fixed parameters is
maintained when a model is cloned for various sampled parameters. Also
provided are extensions to the methods for checking the consistency and
completeness of model parameters.
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::SimulationModel -> PaleoPopModel
attachedA list of dynamically attached attributes (name-value pairs).
simulation_functionName (character string) or source path of the default simulation function, which takes a model as an input and returns the simulation results.
model_attributesA vector of model attribute names.
regionA Region (or inherited class) object specifying the study region.
coordinatesData frame (or matrix) of X-Y population coordinates (WGS84) in longitude (degrees West) and latitude (degrees North).
random_seedNumber to seed the random number generation for stochasticity.
time_stepsNumber of simulation time steps.
years_per_stepNumber of years per time step.
populationsNumber of population cells.
initial_abundanceArray (matrix) of initial abundance values at each population cell.
transition_rateRate (numeric) of transition between generations at each time-step.
standard_deviationStandard deviation (numeric) for applying environmental stochasticity to transition rates.
compact_decompositionList containing a compact transposed
(Cholesky) decomposition matrix (t_decomposition_compact_matrix)
and a corresponding map of population indices
(t_decomposition_compact_map), as per
SpatialCorrelation class
attributes.
carrying_capacityArray (or matrix) of carrying capacity values at each population cell (across time).
density_dependenceDensity dependence type ("competition", "logistic", or "ceiling").
growth_rate_maxMaximum growth rate (utilized by density dependence processes).
dispersal_dataList of data frames of non-zero dispersal rates and
indices for constructing a compact dispersal matrix, and optional
changing rates over time, as per class
DispersalGenerator
dispersal_data attribute.
dispersal_target_kTarget population carrying capacity threshold for density dependent dispersal.
harvestBoolean for utilizing harvesting.
harvest_maxProportion harvested per year (annual time scale - not generational).
harvest_gThe "G" parameter in the harvest function.
harvest_zThe "Z" parameter in the harvest function.
harvest_max_nMaximum density per grid cell.
human_densityMatrix of human density (fraction) ($populations rows by $time_steps columns).
abundance_thresholdAbundance threshold (that needs to be exceeded) for each population to persist.
occupancy_thresholdThreshold for the number of populations occupied (that needs to be exceeded) for all populations to persist.
results_selectionList of results selection from ("abundance", "ema", "extirpation", "harvested", "occupancy", "human_density").
attribute_aliasesA list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
template_modelNested template model for fixed (non-sampled) attributes for shallow cloning.
sample_attributesVector of sample attribute names (only).
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA vector of warning messages encountered when setting model attributes.
poems::GenericModel$get_attribute()poems::GenericModel$get_attribute_aliases()poems::SimulationModel$get_attribute_names()poems::SimulationModel$get_attributes()poems::SimulationModel$incomplete_attributes()poems::SimulationModel$inconsistent_attributes()poems::SimulationModel$initialize()poems::SimulationModel$is_complete()poems::SimulationModel$is_consistent()poems::SimulationModel$new_clone()poems::SimulationModel$set_attributes()poems::SimulationModel$set_sample_attributes()list_consistency()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent.
PaleoPopModel$list_consistency(params = NULL)
paramsOptional array of parameter/attribute names.
List of booleans (or NAs) to indicate consistency of selected/all attributes.
list_completeness()
Returns a list of booleans (or NAs) for each parameter to indicate attributes that are necessary to simulate the model have been set and are consistent/valid.
PaleoPopModel$list_completeness()
List of booleans (or NAs) for each parameter to indicate to indicate completeness (and consistency).
clone()
The objects of this class are cloneable with this method.
PaleoPopModel$clone(deep = FALSE)
deepWhether to make a deep clone.
library(poems) library(raster) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template template_model <- PaleoPopModel$new(simulation_function = "paleopop_simulator", # the default region = region, years_per_step = 25, # default: 1 year time_steps = 10) template_model$required_attributes # more requirements than the SimulationModel object in poems template_model$is_complete() # the required attributes have not been filled in template_model#is_consistent() # however, the attributes that are filled in are consistentlibrary(poems) library(raster) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template template_model <- PaleoPopModel$new(simulation_function = "paleopop_simulator", # the default region = region, years_per_step = 25, # default: 1 year time_steps = 10) template_model$required_attributes # more requirements than the SimulationModel object in poems template_model$is_complete() # the required attributes have not been filled in template_model#is_consistent() # however, the attributes that are filled in are consistent
R6 class for encapsulating and dynamically generating
spatially-explicit paleopop_simulator results, as well as optional
re-generated Generator for niche carrying capacity and/or human
density.
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::SimulationResults -> PaleoPopResults
attachedA list of dynamically attached attributes (name-value pairs).
model_attributesA vector of model attribute names.
regionA Region (or inherited class) object specifying the study region.
coordinatesData frame (or matrix) of X-Y population coordinates (WGS84) in longitude (degrees West) and latitude (degrees North).
time_stepsNumber of simulation time steps.
burn_in_stepsOptional number of initial 'burn-in' time steps to be ignored.
occupancy_maskOptional binary mask array (matrix), data frame, or raster (stack) for each cell at each time-step of the simulation including burn-in.
trend_intervalOptional time-step range (indices) for trend calculations (assumes indices begin after the burn-in when utilized).
abundanceMatrix of population abundance across simulation time-steps (populations rows by duration columns).
abundance_trendTrend or average Sen's slope of total abundance (optionally across a time-step interval).
emaMatrix of population expected minimum abundance (EMA) across simulation time-steps (populations rows by duration columns).
extirpationArray of population extirpation times.
extinction_locationThe weighted centroid of cells occupied in the time-step prior to the extirpation of all populations (if occurred).
harvestedMatrix of the number of animals harvested from each population at each time-step (populations rows by duration columns).
occupancyArray of the number of populations occupied at each time-step.
carrying_capacityOptional matrix of simulation input carrying capacity to be combined with results (populations rows by duration columns).
human_densityOptional matrix of simulation input human density to be combined with results (populations rows by duration columns).
allNested simulation results for all cells.
parentParent simulation results for individual cells.
defaultDefault value/attribute utilized when applying primitive metric functions (e.g. max) to the results.
attribute_aliasesA list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA vector of warning messages encountered when setting model attributes.
clone()
The objects of this class are cloneable with this method.
PaleoPopResults$clone(deep = FALSE)
deepWhether to make a deep clone.
library(raster) library(poems) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template model_template <- PaleoPopModel$new( region = region, time_steps = 10, years_per_step = 12, # years per generational time-step standard_deviation = 0.1, growth_rate_max = 0.6, harvest = FALSE, populations = region$region_cells, initial_abundance = seq(9000, 0, -1000), transition_rate = 1.0, carrying_capacity = rep(1000, 17), dispersal = (!diag(nrow = 17, ncol = 17))*0.05, density_dependence = "logistic", dispersal_target_k = 10, occupancy_threshold = 1, abundance_threshold = 10, results_selection = c("abundance") ) # Simulations results <- paleopop_simulator(model_template) # Results results_model <- PaleoPopResults$new(results = results, region = region, time_steps = 10) results_model$extirpation # cells where the population goes to zero are marked 1 results_model$occupancy # indicates with 0 and 1 which cells are occupied at each time step results_model$ema # expected minimum abundancelibrary(raster) library(poems) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) # Model template model_template <- PaleoPopModel$new( region = region, time_steps = 10, years_per_step = 12, # years per generational time-step standard_deviation = 0.1, growth_rate_max = 0.6, harvest = FALSE, populations = region$region_cells, initial_abundance = seq(9000, 0, -1000), transition_rate = 1.0, carrying_capacity = rep(1000, 17), dispersal = (!diag(nrow = 17, ncol = 17))*0.05, density_dependence = "logistic", dispersal_target_k = 10, occupancy_threshold = 1, abundance_threshold = 10, results_selection = c("abundance") ) # Simulations results <- paleopop_simulator(model_template) # Results results_model <- PaleoPopResults$new(results = results, region = region, time_steps = 10) results_model$extirpation # cells where the population goes to zero are marked 1 results_model$occupancy # indicates with 0 and 1 which cells are occupied at each time step results_model$ema # expected minimum abundance
R6 class representing a study region of temporally changing
spatial grid cells, defined via a RasterLayer object
(see raster) and a temporal mask indicating
which cells are included at each time step.
poems::GenericClass -> poems::Region -> PaleoRegion
attachedA list of dynamically attached attributes (name-value pairs).
coordinatesData frame (or matrix) of X-Y population (WGS84) coordinates in longitude (degrees West) and latitude (degrees North) (get and set), or distance-based coordinates dynamically returned by region raster (get only).
region_rasterA RasterLayer object (see raster) defining the region with finite values (NAs elsewhere).
use_rasterBoolean to indicate that a raster is to be used to define the region (default TRUE).
strict_consistencyBoolean to indicate that, as well as resolution, extent and CRS, consistency checks also ensure that a raster's finite/occupiable cells are the same or a subset of those defined by the region (default TRUE).
temporal_maskMatrix of booleans indicating which region cells are included at each time step.
region_cellsDynamically calculated number of region coordinates or raster cells with finite/non-NA values.
region_indicesDynamically calculated region indices for raster cells with finite/non-NA values (all if not a raster).
new()
Initialization method sets temporally changing raster layers for paleontological region.
PaleoRegion$new(template_raster = NULL, remove_zeros = FALSE, ...)
template_rasterA RasterLayer, RasterBrick, or RasterStack object (see raster) defining the paleontological region with example finite values (NAs elsewhere)
remove_zerosBoolean to indicate that cells that are zero across all layers (times) are to be removed, i.e. set to NA (default is FALSE).
...Additional parameters passed individually.
raster_from_values()
Converts an array (or matrix) of values into a raster (or stack) consistent with the region raster (matching extent, resolution, and finite/NA cells), and with the temporal mask (if any) applied.
PaleoRegion$raster_from_values(values)
valuesAn array (or matrix) of values to be placed in the raster (or stack) having dimensions consistent with the region cell number.
A RasterLayer (or RasterStack/Brick) object consistent with the region raster with temporal mask (if any) applied.
temporal_mask_raster()
Returns the temporal mask as a raster stack/brick object consistent with the region raster.
PaleoRegion$temporal_mask_raster()
A RasterStack/Brick) object with temporal mask values of 1 (true) and NA elsewhere.
clone()
The objects of this class are cloneable with this method.
PaleoRegion$clone(deep = FALSE)
deepWhether to make a deep clone.
library(poems) library(raster) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) raster::plot(region$temporal_mask_raster()[[1]], main = "Ring Island (first timestep)", xlab = "Longitude (degrees)", ylab = "Latitude (degrees)", colNA = "blue", legend = FALSE) raster::plot(region$temporal_mask_raster()[[10]], main = "Ring Island (last timestep)", xlab = "Longitude (degrees)", ylab = "Latitude (degrees)", colNA = "blue", legend = FALSE)library(poems) library(raster) # Ring Island example region coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent sealevel_raster <- template_raster template_raster[][c(7:9, 12:14, 17:19)] <- NA # make Ring Island sealevel_raster[][c(7:9, 12:14, 17:18)] <- NA raster_stack <- raster::stack(x = append(replicate(9, template_raster), sealevel_raster)) region <- PaleoRegion$new(template_raster = raster_stack) raster::plot(region$temporal_mask_raster()[[1]], main = "Ring Island (first timestep)", xlab = "Longitude (degrees)", ylab = "Latitude (degrees)", colNA = "blue", legend = FALSE) raster::plot(region$temporal_mask_raster()[[10]], main = "Ring Island (last timestep)", xlab = "Longitude (degrees)", ylab = "Latitude (degrees)", colNA = "blue", legend = FALSE)
region_subset generates a region subset of matrix values based on a subset of coordinates within the original region (using nearest spatial neighbor if coordinates differ).
region_subset(orig_coords = NULL, orig_matrix = NULL, subset_coords = NULL)region_subset(orig_coords = NULL, orig_matrix = NULL, subset_coords = NULL)
orig_coords |
Data frame (or matrix) of original/full region of X-Y coordinates (WGS84) in longitude (degrees West) and latitude (degrees North). |
orig_matrix |
Matrix of original values with rows corresponding to the original/full region coordinates. |
subset_coords |
Data frame (or matrix) of X-Y subset region coordinates (WGS84) in longitude (degrees West) and latitude (degrees North). |
A matrix of values corresponding to the subset region coordinates (using nearest spatial neighbor if original and subset coordinates differ).
coordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) values <- matrix(seq(1, 25, 1)) subset <- data.frame(x = rep(seq(-178, -178.04, -0.005), 7), y = rep(seq(19.03, 19.06, 0.005), each = 9)) region_subset(coordinates, values, subset) # nearest neighbor interpolationcoordinates <- data.frame(x = rep(seq(-178.02, -178.06, -0.01), 5), y = rep(seq(19.02, 19.06, 0.01), each = 5)) values <- matrix(seq(1, 25, 1)) subset <- data.frame(x = rep(seq(-178, -178.04, -0.005), 7), y = rep(seq(19.03, 19.06, 0.005), each = 9)) region_subset(coordinates, values, subset) # nearest neighbor interpolation
A raster dataset defining the grid cells of the Siberia study region in a temporally dynamic manner for the
bison example vignette.
siberia_rastersiberia_raster
A raster::RasterStack object:
21 rows by 180 columns by 1001 layers
2 by 2 degree grid cells
WGS84 latitude longitude
longitude -180 to 180 degrees; latitude 42 to 84 degrees
region defined by 913 cells with value of 1, surrounded by non-region NA values
TBA