A record states what a run actually did: every value resolved, where each one came from, and what produced it. Deliberately a separate function rather than an argument to write_config – the two artifacts answer different questions, and a caller should have to say which it wants.
Arguments
- x
Fitted model object, or a record list from record.
- file
Character: Path to write to.
- overwrite
Logical: If TRUE, overwrite an existing file.
- verbosity
Integer: Verbosity level.
Details
Three things distinguish a record from the config it came from:
Every field is present and resolved. A config omits what the user did not set, so a reader applies defaults; a record leaves nothing to them, and writes an unset field as an explicit
null.Each value says where it came from, in a parallel
originmap:user,default,derived(computed from the data),tuned, orunsetfor a field a failed run never reached.provenancerecords the rtemis and R versions, platform, timing, outcome, and a fingerprint of the data.
For a supervised run the top level is what was asked for and folds is
what ran, one entry per model fitted – outer resampling resolves different
values in each fold, so a single resolved value at the top level would state
something no fold did.
A supervised record also states what the run scored. metrics holds each
sample's headline row as a flat metric-to-value map, averaged across outer
resamples, with metrics_sd beside it for the spread (null for a single
fit, which has none). The full metrics – the confusion matrix, the per-class
rows – are in each fold's own metrics. The flat block exists so that "was
this model any good?" is one lookup in one file, with no averaging and no R,
which is what makes a directory of records rankable.
train, decomp and cluster call this automatically when given an
outdir. A record is not a config: feeding one to read_config is an error,
since its resolved values would silently pin settings the new call should
decide for itself.
Unlike a config, a record is not compacted: an unset field is written as
an explicit null rather than omitted, so nothing in it falls back to a
reader's defaults. That is the whole claim a record makes.
Examples
if (FALSE) { # \dontrun{
mod <- train(iris, hyperparameters = setup_CART())
write_record(mod, "train_CART.record.json")
} # }