Helpers for IPM construction

define_impl(proto_ipm, kernel_impl_list)

make_impl_args_list(kernel_names, int_rule, state_start, state_end)

define_domains(proto_ipm, ...)

define_pop_state(proto_ipm, ..., pop_vectors = list())

define_env_state(proto_ipm, ..., data_list = list())

discretize_pop_vector(
  trait_values,
  n_mesh,
  pad_low = NULL,
  pad_high = NULL,
  normalize = TRUE,
  na.rm = TRUE
)

Arguments

proto_ipm: The name of the model.
kernel_impl_list: A named list. Names correspond to kernel names. Each kernel should have 3 slots defined - the int_rule (integration rule), the state_start (the domain the kernel begins on), and the state_end (the domain the kernel ends on). For more complicated models, it is usually safest to use make_impl_args_list to generate this.
kernel_names: A character vector with the names of the kernels that parameters are being defined for.
int_rule: The integration rule to be used for the kernel. The default is "midpoint". "b2b" (bin to bin) and "cdf" (cumulative density functions) will be implemented as well.
state_start: The name of the state variable for the kernel that the kernel acts on at time t.
state_end: The name of the state variable that the kernel produces at time t+1.
...: Named expressions. See Details for more information on their usage in each define_* function.
pop_vectors: If the population vectors are already pre-defined (i.e. are not defined by a function passed to ...), then they can be passed as a named list here.
data_list: A list of named values that contain data used in the expressions in ... in define_env_state().
trait_values: A numeric vector of trait values.
n_mesh: The number of meshpoints to use when integrating the trait distribution.
pad_low: The amount to pad the smallest value by, expressed as a proportion. For example, 0.8 would shrink the smallest value by 20%.
pad_high: The amount to pad the largest value by, expressed as a proportion. For example, 1.2 would increase the largest value by 20%.
normalize: A logical indicating whether to normalize the result to sum to 1.
na.rm: A logical indicating whether to remove NAs from trait_distrib. If FALSE and trait_values contains NAs, returns a NA with a warning

Value

All define_* functions return a proto_ipm. make_impl_args_list returns a list, and so must be used within a call to define_impl or before initiating the model creation procedure.

Details

These are helper functions to define IPMs. They are used after defining the kernels, but before calling make_ipm() They are meant to be called in the following order:

define_impl()
define_domains()
define_pop_state()
define_env_state()

The order requirement is so that information is correctly matched to each kernel. Below are specific details on the way each works.

define_impl

This has two arguments - proto_ipm (the model object you wish to work with), and the kernel_impl_list. The format of the kernel_impl_list is: names of the list should be kernel names, and each kernel should have 3 entries: int_rule, state_start, and state_end. See examples.

define_domains

If the int_rule = "midpoint", the ... entries are vectors of length 3 where the name corresponds to the state variable, the first entry is the lower bound of the domain, the second is the upper bound of the domain, and the third entry is the number of meshpoints. Other int_rules are not yet implemented, so for now this is the only format they can take. See examples.

define_pop_state

This takes either calls to functions in the ..., or a pre-generated list of vectors in the pop_vectors. The names used for each entry in ... and/or for the pop_vectors should be n_<state_variable>. See examples.

define_env_state

Takes expressions that generate values for environmental covariates at each iteration of the model in .... The data_list should contain any parameters that the function uses, as well as the function itself. The functions should return named lists. Names in that list can be referenced in vital rate expressions and/or kernel formulas.

discretize_pop_vec

This takes a numeric vector of a trait distribution and computes the relative frequency of trait values. By default, it integrates the kernel density estimate of the trait using the midpoint rule with n_mesh mesh points. This is helpful for creating an initial population state vector that corresponds to an observed trait distribution.

Examples


# Example with kernels named "P" and "F", and a domain "z"

kernel_impl_list <- list(P = list(int_rule = "midpoint",
                                  state_start = "z",
                                  state_end = "z"),
                         F = list(int_rule = "midpoint",
                                  state_start = "z",
                                  state_end = "z"))

# an equivalent version using make_impl_args_list

kernel_impl_list <- make_impl_args_list(
     kernel_names = c("P", "F"),
     int_rule     = c("midpoint", "midpoint"),
     state_start  = c("z", "z"),
     state_end    = c("z", "z")
)

data(sim_di_det_ex)

proto_ipm <- sim_di_det_ex$proto_ipm

# define_domains

lower_bound <- 1
upper_bound <- 100
n_meshpoints <- 50


define_domains(proto_ipm, c(lower_bound, upper_bound, n_meshpoints))
#> A simple, density independent, deterministic proto_ipm with 2 kernels defined:
#>  P, F 
#> 
#> Kernel formulae:
#> 
#> P: s * g
#> F: f_r * f_s * f_d
#> 
#> Vital rates:
#> 
#> s: inv_logit(s_int, s_slope, dbh_1)
#> g: dnorm(dbh_2, mu_g, sd_g)
#> mu_g: g_int + g_slope * dbh_1
#> f_r: inv_logit(f_r_int, f_r_slope, dbh_1)
#> f_s: exp(f_s_int + f_s_slope * dbh_1)
#> f_d: dnorm(dbh_2, mu_fd, sd_fd)
#> 
#> Parameter names:
#> 
#>  [1] "s_int"     "s_slope"   "g_int"     "g_slope"   "sd_g"      "f_r_int"  
#>  [7] "f_r_slope" "f_s_int"   "f_s_slope" "mu_fd"     "sd_fd"    
#> 
#> All parameters in vital rate expressions found in 'data_list':  TRUE
#> 
#> Domains for state variables:
#> 
#> dbh: lower_bound = 1, upper_bound = 100, n_meshpoints = 50
#> 
#> Population states defined:
#> 
#> n_dbh: runif(100)
#> 
#> Internally generated model iteration procedure:
#> 
#> n_dbh_t_1: right_mult(kernel = P, vectr = n_dbh_t) + right_mult(kernel = F, 
#>     vectr = n_dbh_t)
#> 

# define_pop_state with a state variable named "z". Note that "n_" is prefixed
# to denote that it is a population state function!

define_pop_state(proto_ipm, n_z = runif(100))
#> A simple, density independent, deterministic proto_ipm with 2 kernels defined:
#>  P, F 
#> 
#> Kernel formulae:
#> 
#> P: s * g
#> F: f_r * f_s * f_d
#> 
#> Vital rates:
#> 
#> s: inv_logit(s_int, s_slope, dbh_1)
#> g: dnorm(dbh_2, mu_g, sd_g)
#> mu_g: g_int + g_slope * dbh_1
#> f_r: inv_logit(f_r_int, f_r_slope, dbh_1)
#> f_s: exp(f_s_int + f_s_slope * dbh_1)
#> f_d: dnorm(dbh_2, mu_fd, sd_fd)
#> 
#> Parameter names:
#> 
#>  [1] "s_int"     "s_slope"   "g_int"     "g_slope"   "sd_g"      "f_r_int"  
#>  [7] "f_r_slope" "f_s_int"   "f_s_slope" "mu_fd"     "sd_fd"    
#> 
#> All parameters in vital rate expressions found in 'data_list':  TRUE
#> 
#> Domains for state variables:
#> 
#> dbh: lower_bound = 0, upper_bound = 50, n_meshpoints = 100
#> 
#> Population states defined:
#> 
#> n_z: runif(100)
#> 
#> Internally generated model iteration procedure:
#> 
#> n_dbh_t_1: right_mult(kernel = P, vectr = n_dbh_t) + right_mult(kernel = F, 
#>     vectr = n_dbh_t)
#> 

# alternative, we can make a list before starting to make the IPM

pop_vecs <- list(n_z = runif(100))

define_pop_state(proto_ipm, pop_vectors = pop_vecs)
#> A simple, density independent, deterministic proto_ipm with 2 kernels defined:
#>  P, F 
#> 
#> Kernel formulae:
#> 
#> P: s * g
#> F: f_r * f_s * f_d
#> 
#> Vital rates:
#> 
#> s: inv_logit(s_int, s_slope, dbh_1)
#> g: dnorm(dbh_2, mu_g, sd_g)
#> mu_g: g_int + g_slope * dbh_1
#> f_r: inv_logit(f_r_int, f_r_slope, dbh_1)
#> f_s: exp(f_s_int + f_s_slope * dbh_1)
#> f_d: dnorm(dbh_2, mu_fd, sd_fd)
#> 
#> Parameter names:
#> 
#>  [1] "s_int"     "s_slope"   "g_int"     "g_slope"   "sd_g"      "f_r_int"  
#>  [7] "f_r_slope" "f_s_int"   "f_s_slope" "mu_fd"     "sd_fd"    
#> 
#> All parameters in vital rate expressions found in 'data_list':  TRUE
#> 
#> Domains for state variables:
#> 
#> dbh: lower_bound = 0, upper_bound = 50, n_meshpoints = 100
#> 
#> Population states defined:
#> 
#> n_z: Pre-defined population state.
#> 
#> Internally generated model iteration procedure:
#> 
#> n_dbh_t_1: right_mult(kernel = P, vectr = n_dbh_t) + right_mult(kernel = F, 
#>     vectr = n_dbh_t)
#> 

# define_env_state. Generates a random draw from a known distribution
# of temperatures.

env_sampler <- function(env_pars) {

  temp <- rnorm(1, env_pars$temp_mean, env_pars$temp_sd)

  return(list(temp = temp))

}

env_pars <- list(temp_mean = 12, temp_sd = 2)

define_env_state(
 proto_ipm,
 env_values = env_sampler(env_pars),
 data_list  = list(env_sampler = env_sampler,
                   env_pars    = env_pars)

)
#> A simple, density independent, deterministic proto_ipm with 2 kernels defined:
#>  P, F 
#> 
#> Kernel formulae:
#> 
#> P: s * g
#> F: f_r * f_s * f_d
#> 
#> Vital rates:
#> 
#> s: inv_logit(s_int, s_slope, dbh_1)
#> g: dnorm(dbh_2, mu_g, sd_g)
#> mu_g: g_int + g_slope * dbh_1
#> f_r: inv_logit(f_r_int, f_r_slope, dbh_1)
#> f_s: exp(f_s_int + f_s_slope * dbh_1)
#> f_d: dnorm(dbh_2, mu_fd, sd_fd)
#> 
#> Parameter names:
#> 
#>  [1] "s_int"     "s_slope"   "g_int"     "g_slope"   "sd_g"      "f_r_int"  
#>  [7] "f_r_slope" "f_s_int"   "f_s_slope" "mu_fd"     "sd_fd"    
#> 
#> All parameters in vital rate expressions found in 'data_list':  TRUE
#> 
#> Domains for state variables:
#> 
#> dbh: lower_bound = 0, upper_bound = 50, n_meshpoints = 100
#> 
#> Population states defined:
#> 
#> n_dbh: runif(100)
#> 
#> Internally generated model iteration procedure:
#> 
#> n_dbh_t_1: right_mult(kernel = P, vectr = n_dbh_t) + right_mult(kernel = F, 
#>     vectr = n_dbh_t)
#> 

data(iceplant_ex)

z <- c(iceplant_ex$log_size, iceplant_ex$log_size_next)

pop_vecs <- discretize_pop_vector(z,
                                  n_mesh = 100,
                                  pad_low = 1.2,
                                  pad_high = 1.2)