Skip to contents

Control parameters for gllvmTMB()

Source: R/gllvmTMB.R
gllvmTMBcontrol.Rd

Control parameters for gllvmTMB()

Usage

gllvmTMBcontrol(
  d_B = NULL,
  d_W = NULL,
  spde_mode = c("per_trait", "shared"),
  n_init = 1L,
  optimizer = c("nlminb", "optim"),
  optArgs = list(),
  init_jitter = 0.3,
  verbose = FALSE,
  ...
)

Arguments

d_B, d_W

Latent dimensions for the between-unit and within-unit reduced-rank components. Set to a positive integer to enable latent() / unique() covariance structures at the corresponding tier.

spde_mode

"per_trait" (default) fits one independent SPDE field per trait when a spatial() term is present; "shared" fits one shared SPDE field with trait-specific scalar loadings.

n_init

Number of random-start replicates. Reduced-rank GLLVMs are often multimodal because the latent-factor likelihood has many equivalent local maxima; running several restarts with different starting values and keeping the fit with the lowest -logLik reduces the risk of settling on a suboptimal solution. Default 1 (single fit). Increase to 5–10 for two-level rr models.

optimizer

One of "nlminb" (default) or "optim". Use the latter together with optArgs for finicky two-level rr fits.

optArgs

A list of arguments passed to the optimiser. For optim the most useful is list(method = "BFGS").

init_jitter

Standard deviation of N(0, σ) jitter applied to the starting parameter vector across the n_init restarts. Default 0.3.

verbose

If TRUE, prints a one-line summary per restart so the user can see which seed led to the winning fit. Default FALSE.

...

Reserved for future use. Currently ignored with a warning.

Value

A gllvmTMBcontrol list.

Details

Recommended workflow for two-level latent models. Reduced-rank likelihoods are notoriously multimodal in two-level fits like value ~ 0 + trait + latent(0+trait|ID, d_B) + latent(0+trait|obs_ID, d_W). The recommended workflow is:

  1. Run several restarts (n_init = 5 to 10) and keep the one with the lowest -logLik.

  2. If that fails to converge cleanly, switch the optimiser to optim with BFGS: gllvmTMBcontrol(optimizer = "optim", optArgs = list(method = "BFGS")).

  3. For very complex models, fit a simpler version first (e.g. drop one rr term) and warm-start the full fit by passing start_from = simpler_fit (planned; not yet implemented).

The earlier start_method = "res" (gllvm-style residual seeding) was tested empirically and does not improve two-level rr fits; it is intended for non-Gaussian responses only.