Skip to contents

Predict the masked (missing) response cells of a gllvmTMB fit

Source: R/methods-gllvmTMB.R
predict_missing.Rd

For a model fitted with missing = miss_control(response = "include") (see miss_control()), gllvmTMB() keeps the rows / cells whose response was missing, masks them out of the likelihood, and predicts them from the fitted model. predict_missing() returns those masked response cells with their model-based predictions and the original-row / cell accounting from fit$missing_data.

Usage

predict_missing(
  object,
  type = c("link", "response"),
  se = FALSE,
  se_route = c("quad", "joint", "joint_load", "sim", "boot"),
  n_sim = 2000L,
  sim_seed = NULL,
  n_boot = 200L,
  boot_seed = NULL,
  boot_dgp = c("ml", "reml"),
  ...
)

Arguments

object

A fit returned by gllvmTMB().

type

One of "link" (default; the linear predictor) or "response" (the inverse-link conditional mean; for ordinal_probit() / ordinal_logit() traits, the expected category instead – see Details).

se

EXPERIMENTAL, internal-only. If TRUE, appends se_confidence (delta-method SE of the reconstructed mean) and se_prediction (se_confidence combined with the family noise variance) columns. Gaussian fits only in this slice; see Details. Default FALSE.

se_route

EXPERIMENTAL, internal-only. One of "quad" (default; R1-quad), "joint" (R1-joint), "joint_load" (R1-joint+loadings), "sim" (R2, simulation-based), or "boot" (R3, parametric bootstrap – see Details). Ignored unless se = TRUE.

n_sim

EXPERIMENTAL, internal-only. Number of Monte Carlo replicates drawn per masked cell when se_route = "sim". Ignored for every other route. Default 2000.

sim_seed

EXPERIMENTAL, internal-only. Integer RNG seed for se_route = "sim". Default NULL, which derives a fixed seed from the fitted parameter vector so repeated calls on the same fit reproduce identical draws; the caller's global RNG state is always saved and restored, never disturbed. Ignored for every other route.

n_boot

EXPERIMENTAL, internal-only. Number of full-refit bootstrap replicates when se_route = "boot". Ignored for every other route. Default 200.

boot_seed

EXPERIMENTAL, internal-only. Integer RNG seed for se_route = "boot". Default NULL, which derives a fixed seed from the fitted parameter vector (same convention as sim_seed); the caller's global RNG state is always saved and restored. Ignored for every other route.

boot_dgp

EXPERIMENTAL, internal-only. One of "ml" (default) or "reml" – see Details. Ignored unless se_route = "boot".

...

Unused.

Value

A data frame with one row per masked response cell, with columns: original_row (the supplied long-data row, the supplied wide-data row before traits() stacking, or – for a multinomial() fit – the pre-expansion row of the user's data that the K-1 category-contrast pseudo-row belongs to), model_row (the row index into the fitted long-format data / response), the unit / cluster / trait identifier columns, est (the prediction on the requested scale), and, when se = TRUE, se_confidence and se_prediction (see Details – EXPERIMENTAL, not a calibrated interval). When se = TRUE and se_route is "sim" or "boot", also q_lo_conf/q_hi_conf, q_lo_pred/q_hi_pred (empirical 2.5%/97.5% quantiles / bootstrap interval endpoints) and q_lo_conf90/q_hi_conf90, q_lo_pred90/q_hi_pred90 (the nominal 90% companions). When se_route = "boot", also n_boot_ok (the number of the n_boot refits that converged and entered the pivot sample). A complete-data fit (no masked cells) returns a zero-row data frame with the same columns.

Details

Missing responses are predicted / reconstructed as fitted values, not latent covariates. The separate imputed() extractor returns modelled missing predictors from supported mi() fits. The point predictions here are the fitted linear predictor (type = "link") or its inverse-link response (type = "response"). Reconstruction standard errors and prediction intervals are not currently returned by default.

se = TRUE is experimental: no repeated-sampling coverage evidence exists for se_confidence or se_prediction, and neither is an interval claim of any kind. It is currently implemented for gaussian fits only (other families abort). Five routes exist (se_route): "quad" (default) omits the b_fix/latent-score cross-covariance and any diag_B ("unique"/Psi) or within-unit (rr_W) random-effect contribution and OVER-covers se_confidence; "joint" computes the exact joint-precision variance for the b_fix and latent-score blocks but omits the loading-uncertainty block entirely and UNDER-covers; "joint" and "quad" BRACKET nominal coverage. "joint_load" adds that third block; it is the best-calibrated delta-method route measured and still falls short of nominal coverage. "sim" is a Monte Carlo route: it draws the same gradient-relevant parameter subvector "joint_load" uses from its exact joint-precision marginal normal, forms n_sim EXACT (non-linearised) draws of eta* = x'b* + lambda_t*'u_i*, and adds one gaussian family draw per replicate for y*. Unlike the delta-method routes it makes NO normality assumption about the predictive distribution – se_confidence / se_prediction are the empirical sd of eta* / y*, and it ALSO returns empirical-quantile columns (q_lo_conf/q_hi_conf, q_lo_pred/q_hi_pred at nominal 95%, and their *90 companions at nominal 90%) that a normal-quantile route cannot produce. It still holds every parameter at its estimate (a plug-in simulation), so it does not address hyperparameter uncertainty. "boot" is a parametric bootstrap: it simulates a complete dataset at the fitted parameters (fresh latent scores AND a fresh family draw for every cell), masks the same cells, and REFITS the model n_boot times. Because every replicate is a full refit, it is the only route that propagates parameter (and dispersion) uncertainty rather than holding it fixed at the plug-in estimate; it is also by far the most expensive route (n_boot model fits per call) and, in this slice, only supports gaussian fits with a single ordinary loadings-only latent() term (see Details in the source for the derivation and the scope guard). A refit that errors or fails to converge is dropped from the pivot sample and counted in n_boot_ok; if fewer than half the refits survive, se_confidence/se_prediction/the quantile columns are NA for that fit (with a warning) rather than reporting an interval built from a thin sample.

boot_dgp controls what parameters generate the n_boot complete-data worlds. A bootstrap with boot_dgp = "ml" can under-cover at the same level as "joint_load". "ml" (default, byte-identical to the pre-sec.7e route) simulates from the SAME ML fit being intervalised – so at small n its known downward variance/loading bias is "re-imported" into the bootstrap world, making the pivots systematically narrow. "reml" fits ONE auxiliary REML model on the same (masked) data/formula first and simulates from ITS parameters instead – REML's own known bias direction (larger, less biased at small n, converging to ML as n grows) targets exactly that gap. The quantity being pivoted (the point estimate the interval is centred on, and every inner refit) stays ML either way; only the generative world changes. Ignored unless se_route = "boot".

Do not surface se_confidence / se_prediction / the quantile columns as calibrated uncertainty in any user-facing output until a route and family have direct coverage evidence.

For ordinal_probit() / ordinal_logit() traits, type = "response" is the expected category \(E[k] = \sum_k k \cdot P(\mathrm{category}\ k \mid \eta, \tau)\), computed from the fitted cutpoints (Hadfield 2015 convention: \(\tau_1 = 0\) fixed, \(\tau_2, \ldots, \tau_{K-1}\) estimated; see extract_cutpoints()) – not a probability. It is not an elementwise pnorm(eta) / plogis(eta), which is not a category quantity once \(K > 2\). type = "link" is unchanged: the probit- or logit-scale linear predictor (per the trait's own family).

See also

gllvmTMB(), miss_control(), predict.gllvmTMB_multi().