Reversible Names for Calibrated Workflows

Explicitly encode input columns and outcome classes before constructing a base workflow, and decode native results into separate roles. These helpers learn no preprocessing, statistics, or calibration.

Usage

venn_abers_schema(data, outcome, classification = "binary", event_level = "first")
venn_abers_encode(data, schema)
venn_abers_decode(x, schema)

Arguments

data

A data frame containing exactly the selected input columns. At schema construction the outcome must be a factor with exactly two declared levels for "binary", at least two for "ovo"/"ovr", or a finite numeric vector for regression (including numeric 0/1). Encoding accepts new data without the outcome, but requires every predictor.

outcome

One exact original outcome name, including reserved or nonsyntactic names.

classification

Exactly "binary", "ovo", or "ovr" for factor outcomes. Must be omitted for numeric regression outcomes.

event_level

Exactly "first" or "second", selecting the event from the original factor levels in their stored order. Only binary classification accepts an explicit event option; omit it for OvO/OvR and regression.

schema

The fixed object returned by venn_abers_schema(). Pass the same schema to encoding, calibrated_workflow() or calibrate_workflow, and decoding.

x

A native probability, class or numeric prediction data frame, an unsummarized tune::collect_predictions() table, or a venn_abers_details() result.

Value

venn_abers_schema() returns a vennabers_schema metadata list. version is the format version; outcome and encoded_outcome are the original and technical target names. columns maps original column names to codes, in original_columns order. classes maps original class names to codes, in class_levels order. ordered records whether the original target is ordered. mode, classification, event_level, and original event_class define the task. Multiclass schemas have NULL event fields; regression has NULL class levels, classification and event fields, and an empty class map. No observation values or additional calibration data are retained in the schema.

venn_abers_encode() returns a data frame in schema column order with encoded column names and, when present, encoded target levels. Predictor values, types, attributes, factor levels, row order, and row names are preserved. The target is aligned to the saved class order even if incoming levels are reordered or known levels are absent. Missing factor target values stay missing; numeric targets must be finite; the fitting boundary rejects missing truth.

venn_abers_decode() returns a list with outcome (the original outcome name as metadata), and only the result roles available in x: probability (a numeric matrix with original class columns in schema order), class (an original-level factor), truth (an original-level factor or numeric regression truth), prediction (numeric regression points), identity (available .row, id, id2, further numbered id columns, and .config), details (existing binary, multiclass or regression diagnostics), and aggregate (existing Cross regression mean bounds). Multiclass details decode class_1/class_2 for OvO, class for OvR, and event_class; fold, row and subproblem identities remain unchanged. It preserves numbers, dimensions, row order, and identities, including zero and one row. No class is inferred from probabilities, and no truth or details are inferred from a prediction table. Regression never adds class or probability roles. Multiclass ties favor the first maximum in the stored class order, also with two classes. The decoder preserves decisions already made by the predictor; it does not recompute them.

Details

Select the intended columns before creating the schema. All selected names and all declared outcome levels get deterministic, collision-free technical codes. Mapping uses exact names, never name repair, Unicode normalization, case folding, or frequency sorting. Even original names that resemble codes remain distinct. Empty, missing or duplicate names, unknown columns or classes, missing predictors, and damaged or incomplete schema mappings are errors. The schema is fixed across folds, prediction batches and processes; do not edit it after construction.

Build formulas, recipes, variable selections, and outer resamples explicitly on the encoded data. Use schema$encoded_outcome in the workflow constructor. Existing recipes are not rewritten. To retain prescribed outer memberships, rebuild their splits on the encoded data with the same row positions and IDs. Inner plan functions receive local encoded data; the exact local plan/data comparison and all training, calibration and assessment separation rules remain.

For a frozen workflow originally trained on encoded data, pass that original schema to calibrate_workflow(), with encoded calibration data and schema$encoded_outcome. Encode new prediction data with the same schema. The stored workflow is never renamed or refitted. Without encoded training, keep original input names and schema = NULL; a new schema cannot repair an old workflow's failed complete prediction path. See examples/frozen-schema.R for the four frozen Inductive methods.

Native predictions remain encoded. Separate decoded roles avoid collisions between an original class class, outcome .pred_class, and external id/id2. The decoder does not flatten or repair these names. Probability columns must cover every schema class exactly once; named columns are reordered to schema order. Unknown encoded output names or class codes fail.

Encoded data, native predictions, and details carry a vennabers_schema attribute. Existing foreign bindings are rejected. Ordinary table operations or collectors may drop attributes: detached tables therefore require the actually associated schema supplied by the caller. Matching codes alone cannot establish provenance. Decode unsummarized predictions to preserve repetitions; the decoder cannot recover rows already summarized or dropped. Collect notes and unsummarized metrics separately, audit completeness, and explicitly extract fitted states when inner models or diagnostics are needed. Match control_resamples()'s event_level to binary schemas; no control is silently changed.

Schema helpers use base R and do not load optional integration packages. The schema and fitted pure R workflow state survive RDS restoration in a fresh process with the required engine namespaces loaded. Outer workers require pkgs = c("vennabers", "stats") for GLM/LM examples (add "nnet" for the installed multinomial example), parallel_over = "resamples", and consistent seeds and thread settings.

See also

calibrated_workflow, local_calibration_splits

Examples

source(system.file("examples", "encoded-binary.R", package = "vennabers"))
# Shared OvO/OvR and regression with Inductive and Cross calibration:
script <- system.file("examples", "encoded-multiclass-regression.R", package = "vennabers")
# source(script)