Missing-data control for gllvmTMB()

Configures how gllvmTMB() treats missing responses and missing predictors. Pass the result to the missing = argument of gllvmTMB().

Usage

miss_control(
  response = c("drop", "include"),
  predictor = c("fail", "model"),
  engine = "laplace"
)

Arguments

response

How to treat rows whose response value is NA. "drop" (default) omits each missing response cell before the likelihood is built. In long format one row is one (unit, trait) cell, and the wide traits() route drops the same cells, so a unit keeps every trait it does have – this is cell-wise omission, not case-wise deletion. "include" keeps those rows, builds an observed-response mask (is_y_observed), and contributes nothing to the likelihood for the masked rows – the frequentist observed-data likelihood. For the supported routes, the observed-response likelihood contribution matches the corresponding observed rows, while cell identity is preserved for predict_missing().

predictor

How to treat missing predictors (covariates). "fail" (the default): a missing value in the fixed-effect design matrix is an error, exactly as today. "model" treats a missing predictor declared with mi(x) as a latent variable integrated out by the Laplace approximation, with its covariate model supplied via the impute = argument of gllvmTMB(). The current routes fit one modelled predictor at a time: Gaussian fixed-effect, grouped-intercept, or phylogenetic- intercept covariate models, plus fixed-effect binary, ordered, and unordered discrete predictors.

engine

The estimation engine. The supported value is "laplace" (TMB Laplace approximation). "em" (the Gaussian-only EM special case) and "profile" are reserved names, not yet supported.

Value

A named list with elements response, predictor, and engine.

Details

There is deliberately no estimator argument in miss_control(): estimator choice belongs to gllvmTMB(). The default gllvmTMB() fit uses ML; gllvmTMB(REML = TRUE) is a Gaussian-only pilot. It combines with either missing-response policy – including miss_control(response = "include"), where the restricted likelihood is formed over the observed rows – but not yet with mi() predictor models. There is no MI ("multiple imputation") engine here; multiple imputation is a separate workflow.

Under the default miss_control(response = "drop", predictor = "fail", engine = "laplace") the missing-data layer is an exact no-op: a complete- data fit is byte-identical to a fit built before this layer existed.

See also

gllvmTMB() for the missing = argument; gllvmTMBcontrol() for optimiser / initialisation control.

Examples

miss_control()                          # defaults: drop / fail / laplace
#> $response
#> [1] "drop"
#> 
#> $predictor
#> [1] "fail"
#> 
#> $engine
#> [1] "laplace"
#> 
miss_control(response = "include")      # keep missing-response rows (masked)
#> $response
#> [1] "include"
#> 
#> $predictor
#> [1] "fail"
#> 
#> $engine
#> [1] "laplace"
#>