Predict from a fitted gllvmTMB model

Returns the linear predictor or inverse-link response at each observation in the training data, or at user-supplied newdata. For mixed-family fits, type = "response" uses the row's own trait/family inverse link rather than the first trait's link.

Usage

# S3 method for class 'gllvmTMB_multi'
predict(
  object,
  newdata = NULL,
  type = c("link", "response"),
  re_form = ~.,
  se.fit = FALSE,
  ...
)

Arguments

object

A fit returned by gllvmTMB().

newdata

Optional new data frame. If NULL, predictions are produced for the training rows. A missing covariate stays NA in that row; the other rows keep their own predictions. Data-dependent transforms in the fixed formula (scale(), poly(), ns()) reuse the training centre, scale, and basis, so a row's value does not depend on which other rows travel with it. Character predictors use the training levels, and user-set factor contrasts (for example contr.sum) are copied onto the restored factor.

type

One of "link" (default) or "response".

"response" includes the row's offset, so on a fit with an effort or support offset it returns an expected count at that effort, or a detection probability at that support – not a relative intensity. For a map or any effort-free comparison, set the offset variable to zero in newdata (e.g. newdata$log_support <- 0) and predict from that; the offset is re-evaluated against newdata, so this is exact rather than an approximation.

On a mixed-family fit the returned est column mixes scales by design (expected counts beside probabilities). The fit's family/source column is returned alongside it so each row's scale is identifiable.

re_form

Random-effect formula controlling which random effects are included in the predicted linear predictor. The default ~ . includes them; ~ 0, NA, and numeric 0 all request the fixed-effects-only / population-mean prediction. Any other value is not a supported form and warns rather than silently including the random effects. Honoured on both the training-row and the newdata path (before 0.7.1 it was read only on the newdata path, and there only as the literal ~ 0). For newdata with sites/species not present in the training data the random effects cannot be drawn, so those rows are fixed-effects-only regardless of re_form.

On newdata, predict() rebuilds the linear predictor in R and can re-add only some of the model's random-effect tiers (the unit-level rr/diag terms, propto, and the spatial SPDE field). Structured intercepts also include their shared and folded Psi effects at known source levels; ancestral prediction is not added. A fit carrying any other active tier gets a warning naming exactly what was omitted; newdata = NULL always returns the full conditional predictor.

se.fit

Logical, default FALSE. If TRUE, add an se.fit column: a conditional, fixed-effect-only, delta-method (Wald) standard error of est. "Conditional" means the random-effect contributions to the linear predictor are held fixed at their predicted (conditional-mode) values – their own uncertainty is not propagated, only the fixed-effect coefficients' sdreport() covariance is. This is a smaller quantity than a full marginal SE would be; it is also not a claim about coverage, which has not been measured for this quantity. type = "link" returns the SE of the linear predictor directly; type = "response" multiplies it by the local derivative of the per-row inverse link (the standard delta-method transform), so it approximates the SE of the inverse-link fitted value, not an exact one. Currently only supported for newdata = NULL (training rows), non-multinomial() fits, fits without an active mi() missing-covariate model, and fits with unit likelihood weights. A non-unit weighted objective has no certified prediction-standard-error route.

...

Unused. An argument passed here is ignored with a warning; in particular re.form (use re_form) and se_fit (use se.fit).

Value

A data frame with the original row identifiers plus an est column on the requested link or response scale, and (if se.fit = TRUE) an se.fit column carrying the conditional delta-method standard error described above.