genetic simulation

getpophist2.cells

R Documentation

getpophist2.cells

Description

Run a forward demographic simulation that creates a recolonization history of a species across a grid landscape.

Usage

getpophist2.cells(
  h = 225,
  xdim = 15,
  ydim = 15,
  maxtime = 1000,
  distance.fun = distancePDF,
  shortscale = 0.35,
  longmean = 3,
  shortshape = 1,
  mix = 0.01,
  lambda = 1.01,
  deltLambda = rep(0, h),
  CVn = NULL,
  pois.var = FALSE,
  extFUN = NULL,
  hab_suit = NULL,
  landscape = NULL,
  K = 10000,
  deltK = rep(1, h),
  refs = c(2),
  refsz = c(1000),
  popDispInfl = function(x) {     return(x) },
  ysz = 1,
  xsz = 1,
  enmstep = NULL,
  numcolonists = 1
)

Arguments

`h`	integer defining the total number of cells in the landscape matrix (pulled from `landscape`, if not NULL).
`xdim`	integer indicating the number of cells in the x-axis of the landscape grid (pulled from `landscape`, if not NULL).
`ydim`	integer indicating the number of cells in the y-axis of the landscape grid (pulled from `landscape`, if not NULL).
`maxtime`	the maximum number of generations in the forward demographic simulation. Required if `enmstep` is specified, defined by dimensions of `landscape$hab_suit` if `enmstep` is NULL.
`distance.fun`	a function describing the dispersal kernel for the simulation.
`shortscale`	scale parameter of the Weibull probability density function (i.e., short-distance component of species' dispersal kernel).
`longmean`	mean of the Normal probability density function (i.e., long-distance component of species' dispersal kernel).
`shortshape`	shape parameter of the Weibull probability density function (i.e., short-distance component of species' dispersal kernel).
`mix`	proportion of long-distance dispersal events out of the total number of dispersal events.
`lambda`	population growth rate (discrete rate of increase). It can be a fixed value or drawn from the prior distribution of the lambda parameter.
`deltLambda`	a vector (one entry per cell) that allows cell-specific growth rates to be modeled. The default (0) implies no variation in growth across populations, while 0.1 increases growth rate by 10 percent and -0.1 reduces growth rate by 10 percent (set to 0 if `landscape` is specified).
`CVn`	the coefficient of variation in population size, if demographic stochasticity is modeled.
`pois.var`	if TRUE, population size in each time step is drawn from a Poisson distribution (to incorporate demographic stochasticity).
`extFUN`	a function that describes the probability of local extinction as a function of cell-specific population size.
`hab_suit`	unused, replaced by landscape but maintained here for backward compatibility with early simulation scripts
`landscape`	a landscape object as produced by `ashSetupLandscape`, includes the following elements: `details` Data frame with the spatial extent of the landscape grid `occupied` Vector of population IDs for occupied cells in the landscape grid `empty` Vector of population IDs for empty cells in the landscape grid `sampled` Vector of population IDs for sampled populations in the landscape grid `hab_suit` Matrix with species habitat suitability (ranging from zero to one) through time. Rows in the matrix correspond to discrete time units and columns correspond to cells in the landscape `sumrast` Raster that stores the extent and resolution of the simulation landscape `samplocsrast` Raster showing the locations of cells that correspond to sampled populations `samplocs` Simple feature encoding spatial vector data related to the sampling populations and a data frame with metadata of the sampling populations (population id, number of individuals, type of spatial data and coordinates) `sampdf` Data frame with the spatial location of the sampling populations in the landscape grid `NAmask` A RasterBrick object used to mask cells that are unsuitable (e.g., covered by glaciers, out of the study region, in large lakes or oceans)
`K`	maximum population size in each grid cell (i.e., carrying capacity) scaled by habitat suitability in the cell.
`deltK`	per-population adjustment to carrying capacity of a cell (set to 1 if `landscape` is specified).
`refs`	vector of integers identifying the cells occupied at the beginning of the forward demographic simulations (i.e., species refugia).
`refsz`	vector of integers indicating the maximum possible effective population size for each cell occupied at the beginning of the forward demographic simulation. Adjusted by habitat suitability of the cell, if a suitability surface is defined. Each value is drawn from the prior distribution of the ancestral effective population size parameter.
`popDispInfl`	during the forward simulation, the probability of a population serving as a source for a newly colonized cell is directly related to population size. Through this argument, the user can specify a function (possibly non-linear) to describe this relationship.
`ysz`	height of cells in the landscape grid.
`xsz`	width of cells in the landscape grid.
`enmstep`	specifies the number of generations over which each habitat suitability layer should be applied.
`numcolonists`	the number of individuals that colonize a new population.

Details

Conducts forward simulation of landscape colonization from a set of refugial populations. Requires parameters related to refugial locations, maximum possible population size, dispersal, habitat suitability through time, and population growth rate.

Value

Returns a pophist object with the following elements:

pophist a data frame describing the population history (source of colonists, time of colonization, etc.).
Nvecs a matrix that records cell-specific population size at each time step in the forward demographic simulation. Rows correspond to individual cells and columns correspond to time steps in the simulation.
tmat migration matrix showing probabilities of moving between populations in the landscape.
struct A numeric vector with information about spatial extent of the landscape grid: number of generations, dispersal parameters, population carrying capacity, refugia location and size.
hab_suit List of ten objects including information on the spatial extent of the landscape grid, number of occupied and empty cells, spatial location and metadata of sampling populations, and habitat suitability across the landscape grid
coalhist a data frame that recodes colonization history in pophist for coalescent simulation (e.g., backward in time).
popslst the colonization history of populations in the landscape in list format. Records information on timing of extinction events, if extinction is allowed in the simulation.

Examples

library(holoSimCell)
parms <- drawParms(control = system.file("extdata/ashpaper","Ash_priors.csv",package="holoSimCell"))
load(file=paste0(system.file(package="holoSimCell"),"/extdata/landscapes/",pollenPulls[[1]]$file))
refpops <- pollenPulls[[1]]$refs
avgCellsz <- mean(c(res(landscape$sumrast)))

ph = getpophist2.cells(h = landscape$details$ncells, xdim = landscape$details$x.dim, ydim = landscape$details$y.dim,
                       landscape=landscape,
                       refs=refpops,   
                       refsz=parms$ref_Ne,
                       lambda=parms$lambda,
                       mix=parms$mix,  
                       shortscale=parms$shortscale*avgCellsz,  
                       shortshape=parms$shortshape, 
                       longmean=parms$longmean*avgCellsz,  
                       ysz=res(landscape$sumrast)[2], 
                       xsz=res(landscape$sumrast)[1], 
                       K = parms$Ne)

stranda/holoSimCell documentation built on Aug. 4, 2023, 1:12 p.m.