Analysis-aware multiple imputation for narrow regression models

Generate multiple imputations conditional on a specified downstream regression model. All routes rely on missing at random (MAR) and a correctly specified conditional imputation model. The glm and lmer routes use SMCFCS and jomo, respectively, so their sampler convergence must also be checked. The lm route uses a separate Bayesian Normal-regression sampler. This experimental interface is deliberately narrow: exactly one continuous covariate may contain missing values, while the outcome, all other predictors, auxiliary variables, and any grouping variable must be fully observed.

Usage

multi_impute_analysis(
  data,
  formula,
  missing,
  model = c("lm", "glm", "lmer"),
  m = 50L,
  auxiliary = character(),
  seed = NULL,
  control = list()
)

# S3 method for class 'pigauto_analysis_mi'
print(x, ...)

Arguments

data: A data frame containing the analysis variables.
formula: A two-sided additive model formula. For model = "lmer", exactly one random-intercept term of the form (1 | group) is required.
missing: A single character string naming the double-precision continuous covariate to impute. Integer storage is rejected: for a scientifically continuous whole-number measurement, convert it first with data$x <- as.numeric(data$x). It must occur as a main-effect predictor in formula and be the only column containing missing values.
model: One of "lm", "glm", or "lmer". The "glm" route is restricted to binomial-logit regression. The "lmer" route is restricted to a Gaussian random-intercept model.
m: Integer number of completed datasets. Must be at least two.
auxiliary: Character vector naming fully observed numeric columns used only by the imputation model. They cannot duplicate formula variables. Derived terms must be created explicitly in data before calling this function.
seed: Optional integer random seed. When supplied, makes the imputation draws reproducible; the default NULL uses the current RNG stream.
control: Named list of engine controls. The "lm" route accepts no controls. The "glm" route accepts numit (default 20) and rjlimit (default 100000). The "lmer" route accepts nburn (default 1000) and nbetween (default 100).
x: An analysis-aware MI object.
...: Ignored. Included for compatibility with the base print() generic.

Value

An object with classes "pigauto_analysis_mi" and "pigauto_mi". Its datasets component is a list of m completed data frames compatible with with_imputations() and pool_mi(). The object also records the analysis model, formula, engine, controls, engine version, seed, runtime provenance, and imputed-variable metadata. For the "glm" and "lmer" routes, any engine warning aborts the call instead of returning an object. The "lm" route does not apply this rule. mi_workflow is a stable analysis-aware provenance marker propagated by with_imputations() and checked by pool_mi().

The print method returns x invisibly.

Experimental scope

This function does not fit pigauto's phylogenetic baseline or graph neural network and does not propagate posterior-tree uncertainty. The "lm" route uses proper Bayesian Normal-regression draws. The "glm" route requires the optional smcfcs package, and the "lmer" route requires the optional jomo and lme4 packages. Interactions, transformed terms, random slopes, nested or crossed random effects, multiple incomplete variables, missing outcomes, and pooling of variance components or BLUPs are unsupported.

Printing

Prints the dataset count, engine, formula and metadata. This display does not validate an analysis. The ... argument is currently unused.

Examples

set.seed(11)
dat <- data.frame(
  y = stats::rnorm(80),
  x = stats::rnorm(80),
  z = stats::rnorm(80)
)
dat$x[seq(4, 80, by = 5)] <- NA_real_
mi <- multi_impute_analysis(
  dat, y ~ x + z, missing = "x", model = "lm", m = 5, seed = 12
)
fits <- with_imputations(
  mi, function(d) stats::lm(y ~ x + z, data = d), .progress = FALSE
)
pool_mi(fits)
#> Pooled estimates from 5 multiply-imputed fits (Rubin's rules)
#> Confidence level: 95%
#> 
#>         term estimate std.error    df statistic p.value conf.low conf.high
#>  (Intercept)  -0.1106    0.1001 5024.    -1.105  0.2691  -0.3067   0.08558
#>            x  -0.1751    0.1131 63.40    -1.548  0.1266  -0.4011   0.05092
#>            z  -0.1428    0.1128 1935.    -1.266  0.2057  -0.3641   0.07846
#>      fmi     riv
#>  0.02860 0.02904
#>   0.2737  0.3354
#>  0.04645 0.04763