Extract model-ready inputs from a fitted design schema

design_data() extracts the retained training inputs from a fitted design_fit() object. It reuses cached x, y, weights, offset, case_id, and row_index. It does not rebuild the design matrix and does not re-evaluate any formula.

Use this function after design_fit() when passing analysis data to a model fitter, scoring function, or diagnostic routine. Use design_newdata() when encoding validation or prediction data.

Usage

design_data(fit, response_type = c("response", "ordinal_counts"))

Arguments

fit: (design_fit)
Fitted design schema returned by design_fit().
response_type: (Scalar character: "response")
Response output mode. Must be one of "response" or "ordinal_counts".

Value

A list of class "design_inputs" with elements:

x: retained training design matrix.
y: retained response, weighted ordinal-count matrix, or NULL for one-sided designs.
weights: retained analysis weights, or NULL.
offset: retained offset values, or NULL.
case_id: retained case identifiers, or NULL.
row_index: retained row identities from the fitted design.

All non-NULL elements are aligned to the rows of x.

Details

Standard response output

response_type = "response" returns the response and row roles as they were evaluated and retained by design_fit(). The returned x matrix already has the fitted predictor columns, categorical encoding, row filtering, and column order. The returned y, weights, offset, case_id, and row_index are aligned row-for-row with x.

Ordinal-count output

response_type = "ordinal_counts" returns a weighted count matrix in y and weights = NULL. This output is useful for ordinal or categorical likelihoods that take a count matrix instead of a factor response plus case weights.

This mode requires the response formula to have a bare-symbol left-hand side that references a factor or ordered-factor column. It also requires non-NULL weights, at least two declared response levels, and non-missing retained responses. Ordinal-count rows place the row's observation weight in the observed response column and zero in all other columns. Declared but unobserved response levels are retained as zero-count columns. See ordinal_matrix_to_factor() for converting the count matrix back to factor responses and row weights.

Examples

#----------------------------------------------------------------------------
# Extract training inputs for a weighted linear model
#----------------------------------------------------------------------------
library(bkmodel)

set.seed(1L)
analysis <- data.frame(
  patient_id = sprintf("P%02d", 1:12),
  outcome = rnorm(12),
  age = round(rnorm(12, mean = 60, sd = 8)),
  treatment = factor(rep(c("control", "active"), 6)),
  stage = factor(rep(c("I", "II", "III"), each = 4)),
  exposure = runif(12, min = 0.5, max = 2),
  inverse_prob_weight = runif(12, min = 0.8, max = 1.2),
  chart_score = rnorm(12)
)

spec <- design_spec(
  outcome ~ .,
  weights = ~ inverse_prob_weight,
  offset = ~ log(exposure),
  case_id = ~ patient_id,
  exclude = ~ chart_score,
  encoding = "dummy",
  intercept = TRUE,
  na_action = "na.omit"
)

fit <- design_fit(spec, analysis)
inputs <- design_data(fit)

model <- stats::lm.wfit(
  x = inputs$x,
  y = inputs$y,
  w = inputs$weights,
  offset = inputs$offset
)
model$coefficients
#>      (Intercept)              age treatmentcontrol          stageII 
#>      0.156073030     -0.009539819     -0.017562419      0.928695544 
#>         stageIII 
#>      0.717146802 

#----------------------------------------------------------------------------
# Extract weighted ordinal-count responses
#----------------------------------------------------------------------------
ordinal_data <- data.frame(
  response = ordered(
    c("low", "medium", "high", "low", "medium", "high"),
    levels = c("low", "medium", "high")
  ),
  marker = c(0.2, 0.4, 1.1, 0.3, 0.8, 1.4),
  sampling_weight = c(1.0, 0.5, 1.5, 1.2, 0.8, 1.1)
)

ordinal_spec <- design_spec(
  response ~ marker,
  weights = ~ sampling_weight
)

ordinal_fit <- design_fit(ordinal_spec, ordinal_data)
ordinal_inputs <- design_data(
  ordinal_fit,
  response_type = "ordinal_counts"
)
ordinal_inputs$y
#>      low medium high
#> [1,] 1.0    0.0  0.0
#> [2,] 0.0    0.5  0.0
#> [3,] 0.0    0.0  1.5
#> [4,] 1.2    0.0  0.0
#> [5,] 0.0    0.8  0.0
#> [6,] 0.0    0.0  1.1
rowSums(ordinal_inputs$y)
#> [1] 1.0 0.5 1.5 1.2 0.8 1.1