Apply a fitted design schema to new data

design_newdata() applies a fitted design_fit() schema to validation, assessment, or prediction data. It builds a design_inputs object whose predictor matrix has the same columns, categorical encoding, factor levels, and column order as the training design. It does not refit the schema or learn new factor levels from newdata.

Use this function after design_fit() when new data must be encoded in the same way as the analysis data used for model training.

Usage

design_newdata(
  fit,
  newdata,
  row_index = NULL,
  outcome = c("auto", "require", "ignore"),
  weights = c("auto", "require", "ignore"),
  response_type = c("response", "ordinal_counts"),
  na_action = fit$na_action,
  novel_levels = fit$novel_levels
)

Arguments

fit: (design_fit)
Fitted design schema returned by design_fit().
newdata: (data.frame)
New data to encode. Objects that inherit from data.frame, including tibbles, are accepted.
row_index: (integer: NULL)
Optional row identity vector for newdata. If NULL, seq_len(nrow(newdata)) is used. Values must be non-missing, unique whole numbers and must have length nrow(newdata).
outcome: (Scalar character: "auto")
Response evaluation mode. Must be one of "auto", "require", or "ignore".
weights: (Scalar character: "auto")
Weight evaluation mode. Must be one of "auto", "require", or "ignore".
response_type: (Scalar character: "response")
Response output mode. Must be one of "response" or "ordinal_counts".
na_action: (Scalar character: fit$na_action)
Missing-value policy used when retaining new-data rows. Must be one of "na.pass", "na.omit", "na.fail", or "na.exclude".
novel_levels: (Scalar character: fit$novel_levels)
Handling for categorical levels in newdata that were not observed when fit was created. Must be one of "na" or "fail".

Value

A list of class "design_inputs" with elements:

x: encoded new-data design matrix with the same columns as fit$x.
y: evaluated response, weighted ordinal-count matrix, or NULL.
weights: evaluated weights, or NULL.
offset: evaluated offsets, or NULL.
case_id: evaluated case identifiers, or NULL.
row_index: retained row identities from newdata.

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

Details

Predictor schema

All predictor source variables required by the fitted schema must be present in newdata. Character and factor predictors are constrained to the levels learned by design_fit(). novel_levels = "na" converts new categorical levels to NA before row filtering and encoding. novel_levels = "fail" errors and reports the affected variables and values.

The returned x matrix has the same column names and order as fit$x. Missing one-hot columns are filled with zeros when a fitted training level is absent from newdata.

Retained rows

na_action controls row retention for evaluated predictors, responses, weights, and offsets. The default is fit$na_action. na_action = "na.pass" keeps rows with missing predictor or response values. na_action = "na.omit" and na_action = "na.exclude" keep only complete evaluated rows. na_action = "na.fail" errors if any evaluated predictor or response value is missing.

Weights and offsets are stricter. On retained rows, evaluated weights must be non-missing, finite, and non-negative. On retained rows, evaluated offsets must be non-missing and finite. Case IDs are metadata and do not participate in row filtering.

Outcome modes

outcome = "auto" evaluates y when all response source variables are present in newdata and returns NULL only when none are present. outcome = "require" errors when any response source variable is absent from newdata. outcome = "ignore" never evaluates the response.

For one-sided designs, y = NULL for all outcome modes. Use outcome = "ignore" for pure prediction data without observed outcomes. Use outcome = "require" for assessment data where the response should be present.

Weight modes

If the fitted design has no weights, all weights modes return weights = NULL. Otherwise, weights = "auto" evaluates weights when all weight source variables are present and returns NULL when none are present. weights = "require" errors when any weight source variable is absent. weights = "ignore" never evaluates weights and returns NULL.

Use weights = "ignore" for prediction data where analysis weights are not needed. Use weights = "require" for assessment data where weighted scoring or weighted likelihoods require weights.

Offsets

Offsets are required whenever the fitted design has an offset. If any required offset source variable is absent from newdata, design_newdata() errors. Offset values must be non-missing and finite on retained rows.

Case IDs

When all fitted case ID source variables are present, case_id is returned aligned to the retained rows. When none are present, case_id = NULL. When only some are present, design_newdata() errors.

Ordinal-count output

Ordinal-count output requires evaluated responses and evaluated weights. Therefore outcome = "ignore" and weights = "ignore" error. "auto" behaves like "require" for both response and weight source variables. Missing retained responses error. Response values must be contained in the fitted declared response levels.

Examples

#----------------------------------------------------------------------------
# Encode prediction data with the training design schema
#----------------------------------------------------------------------------
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",
  novel_levels = "fail"
)

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
)

prediction_data <- data.frame(
  patient_id = sprintf("V%02d", 1:3),
  age = c(55, 67, 61),
  treatment = factor(c("active", "control", "active")),
  stage = factor(c("II", "I", "III")),
  exposure = c(1.1, 0.9, 1.5)
)

prediction_inputs <- design_newdata(
  fit,
  prediction_data,
  outcome = "ignore",
  weights = "ignore"
)

linear_predictor <- drop(prediction_inputs$x %*% model$coefficients)
linear_predictor <- linear_predictor + prediction_inputs$offset
linear_predictor
#>          1          2          3 
#>  0.6553887 -0.6060177  0.6967560 

#----------------------------------------------------------------------------
# Encode assessment data with observed outcomes and weights
#----------------------------------------------------------------------------
assessment_data <- data.frame(
  patient_id = sprintf("A%02d", 1:3),
  outcome = c(0.1, -0.4, 0.7),
  age = c(58, 63, 52),
  treatment = factor(c("control", "active", "control")),
  stage = factor(c("I", "III", "II")),
  exposure = c(1.0, 1.3, 0.8),
  inverse_prob_weight = c(1.0, 0.9, 1.1)
)

assessment_inputs <- design_newdata(
  fit,
  assessment_data,
  outcome = "require",
  weights = "require"
)

assessment_inputs$y
#> [1]  0.1 -0.4  0.7
assessment_inputs$weights
#> [1] 1.0 0.9 1.1