Skip to contents

Extract fitted missing-predictor summaries

Source: R/missing-data.R
imputed.Rd

imputed() reports the fitted values used for explicitly modelled missing predictors, for two readers: applied users inspecting a fit, and downstream packages (for example drmSEM) that build effect intervals directly on these values and need to know, row by row, whether std_error is usable.

Usage

imputed(object, ...)

# S3 method for class 'drmTMB'
imputed(object, variable = NULL, rows = c("missing", "all"), se = TRUE, ...)

Arguments

object

A drmTMB fit.

...

Reserved for future extractor options.

variable

Optional missing-predictor name. The default uses the only modelled missing predictor in the fit.

rows

Which rows to return. "missing" returns only fitted missing predictor values. "all" returns retained model rows, with observed predictor values labelled as observed.

se

Logical; include conditional standard errors when the fit contains a successful TMB::sdreport() result. se = FALSE reports std_error = NA and uncertainty_status = "ok" throughout, because nothing was requested.

Value

A data frame with variable, original_row, model_row, observed, estimate, std_error, source, and uncertainty_status. uncertainty_status takes the values "ok", "sdreport_skipped", "sdreport_failed", "sdreport_non_pd_hessian", "sdreport_unavailable", or "route_conditional_se_unavailable"; see Details.

Details

Gaussian missing predictor values are reported as conditional modes from the fitted TMB likelihood, a genuine random effect; their std_error comes from TMB::sdreport()'s conditional covariance. Every other fitted route already stores a normalized posterior probability vector or matrix over a finite-state or quadrature grid, and the reported value is already the posterior mean of that grid: binary missing predictor values are fitted conditional probabilities (Bernoulli/logit predictor model), ordered categorical values are fitted conditional expected scores (cumulative-logit predictor model), beta/proportion, zero-one beta boundary-proportion, and denominator-aware beta-binomial values are fitted conditional means (quadrature or exact summation over the reported proportion), count values are fitted conditional expected counts (Poisson, negative-binomial, or zero-truncated negative-binomial predictor models), and lognormal, Gamma, and Tweedie values are fitted conditional quadrature means. For all of these, std_error is the posterior standard deviation over that same grid, sqrt(sum(p * (x - mean)^2)), computed directly from the stored grid with no additional TMB computation. The one exception is unordered categorical missing predictor values, reported as fitted conditional modal category scores from the baseline-category softmax predictor model: the reported value is a mode over unordered nominal codes, and no metrically meaningful variance exists over categories that carry no order, so std_error stays NA for this route.

uncertainty_status tells a consumer why std_error is NA when it is, and what to do about it:

  • "ok": std_error is a usable standard error (or the row is an observed value, which never carries one). Use it.

  • "sdreport_skipped": the fit used drm_control(se = FALSE). Refit with se = TRUE (the default) to get standard errors.

  • "sdreport_failed" or "sdreport_non_pd_hessian": TMB::sdreport() ran but did not return a usable covariance. Standard errors are unavailable for this fit; diagnose with check_drm() before trusting point estimates either.

  • "sdreport_unavailable": the fit has no TMB::sdreport() object at all (for example, refitted without keep_tmb_object). Refit to get one.

  • "route_conditional_se_unavailable": the fit and sdreport() are both fine, but this specific missing-predictor row has no well-defined posterior standard error — currently only the unordered categorical route. Do not treat the missing std_error as zero or impute one; the point estimate (the modal category) remains usable on its own.

This is not multiple imputation: the output does not contain posterior means, posterior intervals, credible intervals, or pooled-imputation summaries.

Examples

set.seed(20260532)
n <- 48
dat <- data.frame(
  moisture = seq(-1.5, 1.5, length.out = n),
  canopy = cos(seq_len(n) / 5)
)
dat$body_mass_full <- 0.2 + 0.7 * dat$moisture - 0.2 * dat$canopy +
  rnorm(n, sd = 0.08)
dat$growth <- 0.6 + 1.1 * dat$body_mass_full - 0.3 * dat$moisture +
  rnorm(n, sd = 0.20)
dat$body_mass <- dat$body_mass_full
dat$body_mass[c(7, 19, 34, 43)] <- NA_real_

fit <- drmTMB(
  bf(growth ~ moisture + mi(body_mass), sigma ~ 1),
  family = gaussian(),
  data = dat,
  impute = list(body_mass = body_mass ~ moisture + canopy),
  missing = miss_control(predictor = "model")
)
imputed(fit)
#>    variable original_row model_row observed   estimate  std_error
#> 1 body_mass            7         7    FALSE -0.5977605 0.06694746
#> 2 body_mass           19        19    FALSE  0.1231306 0.06692574
#> 3 body_mass           34        34    FALSE  0.4920806 0.06762266
#> 4 body_mass           43        43    FALSE  1.1676661 0.06729265
#>             source uncertainty_status
#> 1 conditional_mode                 ok
#> 2 conditional_mode                 ok
#> 3 conditional_mode                 ok
#> 4 conditional_mode                 ok