Package 'moveMMPP'

Define specifics for model structure and fitting control

Description

Define specifics for model structure and fitting control

Usage

mmpp_model(form = ~1, link = "soft_plus", a = 1, L = 0, U = 0)

mmpp_control(
  lambda = mmpp_model(),
  q_r = mmpp_model(),
  q_m = mmpp_model(),
  struc = "mult",
  norm = TRUE
)

Arguments

form	Model formula for MMPP model components, residency, movement, and detection
link	A link function for the model component. One of "soft_plus", "log", or "logit".
a	Scale parameter for the "soft_plus" link function. Ignored for link="log" or "logit". The a parameter determines the approximation to a hard plus function, i.e., as a becomes large the soft plus function converges to g^{-1}(x) = max(0,x). For this specification, a must be greater than or equal to 1.
L	Lover bound for general logit link.
U	Upper bound for general logit link.
lambda	A named list for the detection portion of the model. See ⁠\link{mmpp_model}⁠
q_r	A named list for the residency model. Must contain elements: form, link, and a. The easiest way to construct this is the ⁠\link{mmpp_model}⁠ function.
q_m	A named list for the movement portion of the model. See q_r and ⁠\link{mmpp_model}⁠.
struc	The form of the rate matrix entries. Can be one of: "mult" for residency times movement, i.e., q_ij = q_r(i) * pi_m(i,j) or "add" for a model of the form q_ij = q_r(i) + pi_m(i,j).
norm	Should the movement portion be adjusted to sum to 1. This is the parameterization suggested by Hewitt et al. (2023).

References

Hewitt, J., Gelfand, A. E., & Schick, R. S. (2023). Time-discretization approximation enriches continuous-time discrete-space models for animal movement. The Annals of Applied Statistics, 17:740-760.

---

Create sparse representations of design matrices for movement and resight models

Description

Create sparse representations of design matrices for movement and resight models

Usage

dm_lambda(formula, ddl)

dm_q_m(formula, ddl)

dm_q_r(formula, ddl)

Arguments

formula	An R formula object for the paramter vector.
ddl	Design data list

Details

This function is not designed for end-users but is exported for posterity.

---

Fit MMPP movement model to resight data

Description

Fit MMPP movement model to resight data

Usage

fit_mmpp(
  data,
  ddl,
  model_parameters = mmpp_control(),
  pen_fun = NULL,
  hessian = TRUE,
  start = NULL,
  method = "nlminb",
  fit = TRUE,
  eq_prec = 1e-08,
  debug = 0,
  ...
)

Arguments

data	A processed data frame produced by the function process_data
ddl	A design data list produced by the function make_design_data.
model_parameters	Model formula for the detection and movement portions of the MMPP model. See ⁠\link{mmpp_control}⁠
pen_fun	An optional penalty function. Should be on the scale of a log-prior distribution.
hessian	Logical. Should the Hessian matrix be calculated to obtain the parameter variance-covariance matrix.
start	Optional starting values for the parameter must be a list of the form list(beta_l=c(), beta_q_r=c(), beta_q_r=c()).
method	Optimization method. See optimr
fit	Logical. Should the likelihood be optimized?
eq_prec	Precision of the matrix exponential approximation.
debug	Integer from 1-4. Opens browser() at various points in the function call. Mostly for package developers.
...	Additional arguments passed to the optimization function optimr from the optimx-package.

Details

Two model forms are available list(lambda=list(form=~1, offset=NULL), q=list(form=~1, offset=~log(1.num_neigh))). For the q model you must use offset=0 to not have one. If it is left off, offset=~log(1.num_neigh))) will be used. To use the movement rate form of Hewitt et al. (2023), one must use, e.g., q = list(res_form = ~from_var, mov_form=~to_var, offset=...), where from_var is a variable

Author(s)

Devin S. Johnson

References

Hewitt, J., Gelfand, A. E., & Schick, R. S. (2023). Time-discretization approximation enriches continuous-time discrete-space models for animal movement. The Annals of Applied Statistics, 17:740-760.

---

Summarize beta parameter values

Description

Takes fitted model and produces a summary of the beta estimates.

Usage

get_betas(par, V = NULL, data_list)

Arguments

par	Model estimated parameters
V	Optional variance-covariance matrix for the parameters. If none is given no standard errors will be provided for the real parameter estimates
data_list	The data list from a fitted model object

Author(s)

Devin S. Johnson

---

Get the limiting utilization distribution of the CTMC movement process

Description

Get the limiting utilization distribution of the CTMC movement process

Usage

get_lim_ud(fit = NULL, hpd = NULL, method = "lu", ...)

Arguments

fit	A moveMMPP fitted model object from ⁠\link{fit_mmpp_dir}⁠.
hpd	A vector of probabilities. Will return columns with highest probability area for each specified probability. E.g., hpd=c(0.5, 0.95) will return 2 extra columns with 50 and 95% HPD densities.
method	Method used for eigen decomposition. One of "lu" or "arpack".
...	Extra arguments to pass to eigs

Author(s)

Devin S. Johnson

---

Get movement transition matrix from fitted moveMMP object

Description

Get movement transition matrix from fitted moveMMP object

Usage

get_Q(fit, sparse = TRUE)

Arguments

fit	A moveMMPP fitted model object from ⁠\link{fit_mmpp}⁠.
sparse	Logical. Should the matrix be returned in a sparse format from the Matrix package. Defaults to sparse = TRUE.

Author(s)

Devin S. Johnson

---

Produce design data for use in fitting MMPP movement models

Description

Produce design data for use in fitting MMPP movement models

Usage

make_design_data(
  sighting_data = NULL,
  cell_data,
  rast_mask = NULL,
  debug = 0,
  ...
)

Arguments

sighting_data	—.
cell_data	—.
rast_mask	Raster mask for inaccessible cells when cell_data is of type SpatRaster from the terra package. This is ignored if cell_data is an POLYGON data frame from the sf package.
debug	Debugging level: 1-3 mainly for package developers.
...	Ignored arguments.

---

Create model data necessary for MMPP simulation

Description

Create model data necessary for MMPP simulation

Usage

make_sim_dm(ddl, model_parameters = mmpp_control())

Arguments

ddl	Design data list created from make_design_data.
model_parameters	Model formula for the detection and movement portions of the MMPP model.

Author(s)

Devin S. Johnson

---

Create Q and L matrices for MMPP simulation

Description

Create Q and L matrices for MMPP simulation

Usage

make_sim_par(sim_dm, par)

Arguments

sim_dm	A list of design matrices resulting from a call to make_sim_dm
par	A list corresponding to the coefficients for lambda, Q_m, and Q_r. It must match the lengths in sim_dm$par_map.

---

Evaluate movement MMPP log-likelihood

Description

Evaluate movement MMPP log-likelihood

Usage

mmpp_ll(par, data_list, debug = 0, ...)

Arguments

par	Parameter vector
data_list	List of required data objects to evaluate likelihood
debug	For developers only, leave in the default setting.
...	Extra wiggle room for ignored arguments.

Author(s)

Devin S. Johnson

---

Process MMPP movement detection data for model fitting

Description

Process MMPP movement detection data for model fitting

Usage

process_data(data, cell_name = NULL, aug_timestamp = NULL, time_unit = "days")

Arguments

data	Detection data. Must contain columns timestamp and cell to indicate time and place of detection. Also, must contain column named id to indicate different individuals.
cell_name	Character. The column name in the data representing the discrete spatial cells on which the animal moves.
aug_timestamp	Augmented times for modeling temporally dynamic movement or detection. See 'Details'
time_unit	—.

Details

(aug_timestamp can be either passed as a separate vector of POSIXct or process_data can derive a sequence of regularly spaced augmentation times from the original data. This is specified by providing a character string that corresponds to the by argument of the seq.POSIXt function (e.g. '1 year', '1 month').

---

Simulate a Markov Modulated Poisson Process

Description

Simulate a Markov Modulated Poisson Process

Usage

sim_mmpp(n = 1, max_time, min_obs, Q, L, start_loc = NULL)

Arguments

n	Number of independent simulations
max_time	...
min_obs	...
Q	A movement rate matrix
L	A detection rate vector
start_loc	Starting location of the path. If not specified, the limiting distribution implied by Q will be used to randomly select a starting location.

Author(s)

Devin S. Johnson

---