Package 'mpmm'

mpmm

Description

fit movement persistence mixed-effects models to animal location data

Author(s)

Ian Jonsen

References

Jonsen ID, McMahon CR, Patterson TA, et al. (2019) Movement responses to environment: fast inference of variation among southern elephant seals with a mixed effects model. Ecology. 100(1):e02566 https://doi.org/10.1002/ecy.2566

See Also

mpmm

---

anova tables

Description

perform likelihood ratio tests on 2 or more mpmm fit objects

Usage

## S3 method for class 'mpmm'
anova(object, ...)

Arguments

object	an mpmm fit object
...	additional mpmm fit objects

---

foieGras-filtered Southern elephant seal Argos satellite data with environmental covariates (11 individuals)

Description

Example elephant seal Argos tracking data with environmental covariates. Data were sourced from the Integrated Marine Observing System (IMOS) - IMOS is supported by the Australian Government through the National Collaborative Research Infrastructure Strategy and the Super Science Initiative.

Format

.RData

---

foieGras-filtered Southern elephant seal Argos satellite data with environmental covariates (4 individuals)

Description

Example elephant seal Argos tracking data with environmental covariates. Data were sourced from the Integrated Marine Observing System (IMOS) - IMOS is supported by the Australian Government through the National Collaborative Research Infrastructure Strategy and the Super Science Initiative.

Format

.RData

---

Control Values for mpmm

Description

inner_control allows specification of control parameters for the inner optimization used by mpmm

Usage

inner_control(...)

Arguments

...	control parameters for the inner optimizer

Details

See MakeADFun and newton for details and available options. Adapted from S. Wotherspoon https://github.com/SWotherspoon/RWalc/blob/master/R/RWalc.R

Value

Returns a list with components:

control

list of control parameters for inner optimizer

See Also

MakeADFun, newton

Examples

fit <- mpmm(~ ice + (ice | id),
data = ellie.ice.short,
inner.control = inner_control(tol = 1e-03))

---

Extract log-likelihood

Description

extract log-likelihood from an mpmm fit object

Usage

## S3 method for class 'mpmm'
logLik(object, ...)

Arguments

object	an mpmm model fit object
...	additional arguments to be ignored

---

Move Persistence Mixed-Effects Model

Description

Fit a move persistence random walk via TMB to a pre-filtered/regularized animal track and estimate gamma as a linear function of covariates

Usage

mpmm(
  formula = NA,
  data = NULL,
  map = NULL,
  control = mpmm_control(),
  inner.control = inner_control()
)

Arguments

formula	a right-hand-side regression formula (no response variable)
data	a data frame of observations (see details)
map	a named list of parameters as factors that are to be fixed during estimation, e.g., list(rho = factor(NA))
control	a list of control parameters for the outer optimization (see mpmm_control)
inner.control	a list of control parameters for the inner optimization (see MakeADFun and newton)

Details

The input track is given as a dataframe where each row is an observed location and columns

'id'

individual animal identifier,

'date'

observation time (POSIXct,GMT),

'lon'

observed longitude,

'lat'

observed latitude,

'tid'

identifier for tracks if there are more than one track per individual (optional),

'...'

named covariates appended to track

Value

a list with components

states	a dataframe of estimated states
fitted	a dataframe of fitted locations
par	model parameter summmary
data	input dataframe
tmb	the tmb object
opt	the object returned by the optimizer

Examples

data(ellie.ice.short)
fit <- mpmm(~ ice + (1 | id), data = ellie.ice.short)
summary(fit)

---

Control Values for mpmm.

Description

mpmm_control selects the numerical minimizer, method, associated control parameters, parameter bounds, and likelihood estimation (REML or ML) used by mpmm.

Usage

mpmm_control(
  optim = c("nlminb", "optim"),
  method = c("BFGS", "L-BFGS-B"),
  lower = NULL,
  upper = NULL,
  REML = FALSE,
  profile = FALSE,
  verbose = 2,
  ...
)

Arguments

optim	the numerical optimizer used in the fit
method	optimization method to be used - one of "BFGS" or "L-BFGS-B" for bounded optimization (default lower and upper bounds are used if not specified
lower	a list of named parameter lower bounds, if NULL then built in defaults are used when method = "L-BFGS-B", otherwise ignored
upper	a list of named parameter upper bounds, if NULL then built in defaults are used when method = "L-BFGS-B", otherwise ignored
REML	logical; whether to use REML (TRUE) or maximum likelihood
profile	logical; option to improve speed and convergence by using REML parameter estimates as initial values for ML optimization
verbose	integer; report progress during minimization: 0 = silent; 1 = optimizer trace; 2 = parameter trace (default))
...	control parameters for the chosen optimizer

Details

The optimizer used to minimize the objective function is selected by the optim argument. Additional control parameters specific to the chosen optimizer are specified via the dots argument. See nlminb and optim for available options. Adapted from S. Wotherspoon https://github.com/SWotherspoon/RWalc/blob/master/R/RWalc.R

Value

Returns a list with components

optim	the name of the numerical optimizer as a string, "nlminb" or "optim"
method	optimization method to be used
lower	named list of lower parameter bounds
upper	named list of upper parameter bounds
REML	whether REML is to be used in place of ML
profile	whether to enhance convergence robustness
verbose	level of tracing information to be reported
control	list of control parameters for the optimizer

See Also

nlminb, optim.

Examples

fit <- mpmm(~ ice + (ice | id),
data = ellie.ice.short,
control = mpmm_control(
    optim = "nlminb",
    REML = FALSE,
    eval.max = 2000)
    )

---

plot

Description

Visualise fixed and random covariate relationships from an mpmm fit object

Usage

## S3 method for class 'mpmm'
plot(x, label = FALSE, lwd = c(0.25, 0.75), ...)

Arguments

x	an mpmm fit object
label	add id labels to random effects
lwd	a vector of regression line widths (random effect, fixed effects)
...	additional arguments to be ignored

---

residuals

Description

Extract one-step-ahead residuals

Usage

## S3 method for class 'mpmm'
residuals(
  object,
  method = "oneStepGaussianOffMode",
  trace = FALSE,
  parallel = TRUE,
  ncores = detectCores() - 1,
  ...
)

Arguments

object	an mpmm fit object
method	character naming the method to calculate one-step-ahead residuals
trace	logical; print progress to console
parallel	logical; compute in parallel
ncores	integer; number of cores to use (default = total cores detected - 1)
...	additional arguments to be ignored

Details

Wrapper function for modified oneStepPredict that calculates one-step-ahead residuals, which are residuals that account for temporal correlation in latent states. The modification allows easier parallel computation.

Value

a list with components

res	a tibble with one-step-ahead residuals for longitude and latitude

References

Thygesen, U. H., C. M. Albertsen, C. W. Berg, K. Kristensen, and A. Neilsen. 2017. Validation of ecological state space models using the Laplace approximation. Environmental and Ecological Statistics 24:317–339.

Examples

## Not run: 
data(ellie.ice)
fit <- mpmm(~ ice + (1 | id), data = ellie.ice)
summary(fit)
residuals(fit)

## End(Not run)

---

object summaries

Description

return a summary of an mpmm fit object

Usage

## S3 method for class 'mpmm'
summary(object, ...)

Arguments

object	an mpmm fit object
...	additional arguments to be ignored

---