writeup: Write the Methods and Results sections for a trained model

In rtemis: Schema-Driven Machine Learning and Visualization

Write the Methods and Results sections for a trained model

Description

Describe a trained supervised model as the Methods and Results sections of a paper: the data, preprocessing, algorithm and settings, tuning, evaluation design, performance measures and statistical methods, and software, then the sample, performance with its uncertainty, the comparison with a baseline, and the hyperparameters tuning selected.

Two tables report the hyperparameters. The main table lists the algorithm's primary hyperparameters, every hyperparameter that was tuned or specified, and the values selected during fitting (such as a number of boosting rounds chosen by early stopping); the supplementary table lists every hyperparameter that applied to the fit, its value, how it was chosen and the values tuning evaluated. A hyperparameter left unset is reported with what that means for the fit. ⁠@hyperparameters⁠ holds the rows of both tables.

Usage

writeup(x, confidence_level = NULL, include_hyperparameters = NULL, ...)

Arguments

x	Supervised or SupervisedRes object: A trained model, as returned by train.
confidence_level	Optional Numeric (0, 1): Confidence level of the intervals of a single-split model. NULL uses 0.95.
include_hyperparameters	Optional Character: Hyperparameters the main hyperparameter table lists in place of the algorithm's primary hyperparameters, beside those that were tuned or specified and the values selected during fitting. NULL uses the primary hyperparameters; character(0) adds none.
...	Not used.

Details

The text is assembled from the model and its review, so it states only what rtemis recorded. Every number in the text is read from the model or the review: the returned object holds each one in ⁠@values⁠ with the path of the field it came from, and the paragraphs in ⁠@sections⁠ are templates in which each number is a {key} token naming a row of ⁠@values⁠. Statistical methods are those review() used, cited in ⁠@references⁠ together with R, rtemis and the packages that fitted the model, at the versions recorded when the model was trained.

A Methods section also states the source of the data, the study design, how the outcome and predictors were measured, and anything done to the data before it was passed to rtemis. The model does not record these, so the writeup lists them in ⁠@not_reported⁠ for the author to add.

Print the result to read it; write_text writes it as Markdown.

Value

SupervisedWriteup object.

Author(s)

EDG

References

Clopper CJ, Pearson ES (1934). The use of confidence or fiducial limits illustrated in the case of the binomial. Biometrika, 26(4), 404-413.

DeLong ER, DeLong DM, Clarke-Pearson DL (1988). Comparing the areas under two or more correlated receiver operating characteristic curves: a nonparametric approach. Biometrics, 44(3), 837-845.

McNemar Q (1947). Note on the sampling error of the difference between correlated proportions or percentages. Psychometrika, 12(2), 153-157.

Examples

idx <- c(1:40, 51:90, 101:140)
mod <- train(
  iris[idx, ],
  dat_test = iris[-idx, ],
  hyperparameters = setup_CART(),
  verbosity = 0L
)
writeup(mod)

# Resampled
mod_res <- train(
  iris,
  hyperparameters = setup_CART(),
  outer_resampling_config = setup_KFold(5L),
  verbosity = 0L
)
writeup(mod_res)

rtemis documentation built on Oct. 20, 2026, 1:06 a.m.