`R/define_implementation.R`

, `R/utils-dom-states.R`

, `R/utils-export.R`

`define_star.Rd`

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
)
```

- 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

`NA`

s from`trait_distrib`

. If`FALSE`

and`trait_values`

contains`NA`

s, returns a`NA`

with a warning

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.

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_rule`

s 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.

```
# 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)
```