Package 'rtemis'

Description

Schema-driven machine learning for validated, observable, auditable, and reproducible machine learning workflows.

Online Documentation and Vignettes

https://docs.rtemis.org/r/ml

Visualization

Model plots (plot_true_pred(), plot_roc(), plot_varimp(), plot_metric(), plot_learning(), plot_session(), plot_manhattan()) and present() render interactive charts through 'rtemis.draw', which also provides the ⁠draw_*()⁠ functions for data. draw_linad() draws a LINAD tree.

Supervised Learning

By convention, the last column of the data is the outcome variable, and all other columns are predictors. Convenience function set_outcome can be used to move a specified column to the end of the data. Regression and Classification is performed using train(). This function allows you to preprocess, train, tune, and test models on multiple resamples. Use available_supervised to get a list of available algorithms

Classification

For training of binary classification models, the outcome should be provided as a factor, with the second level of the factor being the 'positive' class.

Clustering

Clustering is performed using cluster(). Use available_clustering to get a list of available algorithms.

Decomposition

Decomposition is performed using decomp(). Use available_decomposition to get a list of available algorithms.

Type Documentation

Function documentation includes input type (e.g. "Character", "Integer", "Float"/"Numeric", etc). When applicable, value ranges are provided in interval notation. For example, Float: [0, 1) means floats between 0 and 1 including 0, but excluding 1. Categorical variables may include set of allowed values using curly braces. For example, Character: {"future", "mirai", "none"}.

Tabular Data

rtemis internally uses methods for efficient handling of tabular data, with support for data.frame, data.table, and tibble. If a function is documented as accepting "tabular data", it should work with any of these data structures. If a function is documented as accepting only one of these, then it should only be used with that structure. For example, some optimized data.table operations that perform in-place modifications only work with data.table objects.

Error Conditions

Errors are signalled as classed conditions that can be handled with tryCatch(). See rtemis_conditions for the class hierarchy.

Author(s)

Maintainer: E.D. Gennatas [email protected] (ORCID) [copyright holder]

Authors:

• E.D. Gennatas [email protected] (ORCID) [copyright holder]

See Also

Useful links:

• https://www.rtemis.org

• https://docs.rtemis.org/r/ml

• https://docs.rtemis.org/r/ml-api/

• Report bugs at https://github.com/rtemis-org/rtemis/issues

Description

Collapse a binary indicator matrix into a character vector of labels. For each row, the labels of all columns equal to 1 are pasted together, comma-separated. This is the inverse of multi-hot encoding: unlike one_hot2factor, which assumes a single 1 per row, ⁠%BC%⁠ supports rows with multiple 1s (multi-label data, e.g. multiple-choice survey responses, tags, or set membership). Rows of all zeros return NA.

Usage

x %BC% labels

Arguments

Value

a character vector

Author(s)

EDG

Examples

# Multi-hot matrix: each row can belong to multiple categories
x <- rbind(
  c(1, 0, 1),
  c(0, 1, 0),
  c(1, 1, 1),
  c(0, 0, 0)
)
labels <- c("apple", "banana", "cherry")
x %BC% labels
# -> "apple,cherry", "banana", "apple,banana,cherry", NA

Description

Ask a language model to write a summary, an evaluation, next steps and caveats from a review of a trained supervised model. Every statement cites the codes of the review findings it rests on, and the result keeps the review and a record of how the text was produced.

Usage

ai_review(x, llm, context = NULL, temperature = NULL, verbosity = 1L, ...)

Arguments

Details

The model receives the review as JSON and, if given, context: the question the model addresses, the costs of different errors, how its predictions will be used. It never receives the data. Without context, the assessment states that usefulness cannot be judged.

The model answers in a declared structure whose codes are restricted to the review's findings, and the answer is checked: an answer that does not match the structure, or cites a code that is not a finding of the review, is an error. The returned object records the model, the provider, the temperature, the full prompt, a SHA-256 hash of the review sent and the time, so the assessment can be audited and, as far as the model allows, reproduced.

The written assessment is an interpretation of the review, which remains the evidence; read them together. write_text writes both as Markdown.

Requires the rtemis.llm package and access to a model.

Value

AISupervisedReview object.

Author(s)

EDG

Examples

## Not run: 
# Requires a running Ollama server with the model pulled.
mod <- train(
  iris,
  hyperparameters = setup_CART(),
  outer_resampling_config = setup_KFold(5L),
  verbosity = 0L
)
llm <- rtemis.llm::create_Ollama(model_name = "gemma4:e4b")
ai_review(
  mod,
  llm = llm,
  context = "Teaching example; no decisions depend on the predictions."
)

## End(Not run)

Description

Derived from decomposition_traits and the metric registry: a metric applies to an algorithm when every trait it requires is TRUE for that algorithm.

Usage

applicable_metrics(algorithm = NULL)

Arguments

Details

Nothing here is maintained per algorithm. reconstruction_rmse requires invertible, so it is defined for PCA, ICA and NMF and undefined for tSNE, UMAP and Isomap; max_abs_component_correlation requires nothing, so it is defined everywhere. An algorithm added to decom_algorithms with a correct traits row inherits the right metric set without any edit to the metrics code.

Value

data.frame. With algorithm, the registry rows that apply to it: one row per metric, with its group, requirements, whether it needs new data, direction and range. With NULL, one row per metric and one logical column per algorithm.

Author(s)

EDG

Examples

# Every metric, and which algorithms support it
applicable_metrics()
# What can be computed for a UMAP embedding, which does not invert
applicable_metrics("UMAP")

Description

Apply a fitted decomposition to new data for algorithms that support this.

Usage

apply_decomp(decom, new_data, execution_config = NULL, verbosity = 1L)

Arguments

Details

A fit is learned on the columns decom@config@features names, so only those columns of new_data are transformed; the remaining columns are returned unchanged, alongside the learned components, in the layout ⁠[kept features, components]⁠. decomp() resolves an unset features to the numeric columns and records them, so a fit it produced always names them. A Decomposition assembled by hand with no features transforms every column of new_data and returns only the components.

Value

A data.frame of the learned components for new_data, preceded by any feature columns that were not decomposed.

Author(s)

EDG

Examples

iris_pca <- decomp(exc(iris, "Species"), algorithm = "PCA")
apply_decomp(iris_pca, exc(iris, "Species"))

Description

Apply a trained Preprocessor to new data, reusing the values learned from the training data. For example, the same mean and mode imputation values, scale centers and coefficients, one-hot levels, and removed features will be applied to the new data.

Usage

apply_preprocessor(preprocessor, new_data, verbosity = 1L)

Arguments

Details

Imputation follows the preprocessor's impute_type. "meanMode" imputes the stored training values. "missRanger" applies the forests fitted on the training data with predict(), and imputes a feature that had no missing training values with its stored mean or mode; predict() stops on a factor level of an imputed feature that is absent from the training data. A preprocessor using "micePMM" cannot be applied to new data and is refused.

Value

Preprocessed data, in the same structure as new_data.

Author(s)

EDG

See Also

preprocess, setup_Preprocessor

Examples

res <- resample(iris, setup_KFold(seed = 2026))
iris_train <- iris[res[[1]], ]
iris_test <- iris[-res[[1]], ]

# Preprocess training data
iris_pre <- preprocess(iris_train, setup_Preprocessor(scale = TRUE, center = TRUE))

# Apply the same preprocessing to test data
iris_test_pre <- apply_preprocessor(iris_pre, iris_test)

Description

Print available algorithms for supervised learning, clustering, and decomposition.

Usage

available_supervised(verbosity = 1L)

available_clustering(verbosity = 1L)

available_calibration(verbosity = 1L)

available_decomposition(verbosity = 1L, traits = FALSE)

Arguments

Details

Each algorithm is set up with ⁠setup_{Algorithm}()⁠, using the name printed here: setup_LightGBM(), setup_KMeans(), setup_PCA(). Pass the result to train, cluster, or decomp.

Value

Named list of algorithm descriptions, invisibly.

Author(s)

EDG

Examples

available_supervised()
# Train with one of them, at its default hyperparameters:
# train(iris, hyperparameters = setup_LightGBM())
available_clustering()
available_calibration()
# Calibrate with one of them:
# calibrate(mod, hyperparameters = setup_Isotonic())
available_decomposition()
available_decomposition(traits = TRUE)

Description

Decompose a learner's error into the part that comes from being systematically wrong and the part that comes from being unstable, by refitting it over many resamples of the training set and watching what its predictions do at a fixed test set.

Usage

bias_variance(
  x,
  hyperparameters,
  dat_test = NULL,
  true_values = NULL,
  resampler_config = NULL,
  test_p = 0.3,
  execution_config = setup_FutureExecution(),
  verbosity = 1L
)

Arguments

Details

For squared-error loss, the expected error at a point decomposes as

$E[(y - \hat{f}(x))^2] = \sigma^2 + (E[\hat{f}(x)] - f(x))^2 + Var[\hat{f}(x)]$

– irreducible noise, squared bias, and variance. This function estimates the second and third per test case, by fitting the model on n_resamples resamples of the training set and reading the spread and the average of the predictions each makes at the same test cases.

The test set is held out once and every resample is drawn from what is left, which is what makes the predictions comparable across resamples: a test set that moved would confound the model's variability with the sample's.

Value

BiasVariance object.

Whether the bias is really the bias

Squared bias is measured against true_values when you have them, and against the observed outcome when you do not. The difference is not cosmetic:

With true_values

bias_squared is the bias, exactly. Only simulated data has this, which is what makes a simulation study the place to ask how a learner divides its error.

Without

The observed outcome carries the irreducible noise, so what is reported is $bias^2 + \sigma^2$ and no amount of resampling separates them. It stays comparable between learners on the same data – they share the same $\sigma^2$ – so a ranking is still meaningful even though the level is inflated.

What the numbers are, exactly

variance is the sample variance across resamples (dividing by n_resamples - 1), which is unbiased for the variance of the fitted function. bias_squared is the plug-in estimate, and is inflated by roughly variance / n_resamples because the mean prediction is itself estimated – so prefer many resamples over few, and treat a bias_squared of the same order as variance / n_resamples as indistinguishable from zero.

Classification

The decomposition above is for squared error, and 0-1 loss does not decompose additively into bias and variance. For a binary outcome this function therefore decomposes the squared error of the predicted probability of the positive class, which does. true_values is then the true probability, not the class. Multiclass is not supported.

Author(s)

EDG

References

Geman S, Bienenstock E, Doursat R (1992). Neural Networks and the Bias/Variance Dilemma. Neural Computation, 4(1), 1-58. doi:10.1162/neco.1992.4.1.1

Examples

set.seed(2026)
n <- 200L
features <- data.frame(a = rnorm(n), b = rnorm(n))
dat <- data.frame(features, y = 2 * features[["a"]] + rnorm(n))
bv <- bias_variance(
  dat,
  hyperparameters = setup_CART(),
  resampler_config = setup_StratBoot(n_resamples = 10L),
  verbosity = 0L
)
bv

Description

Generic function to calibrate binary classification models.

Usage

calibrate(
  x,
  hyperparameters = NULL,
  execution_config = NULL,
  verbosity = 1L,
  ...
)

Arguments

Details

The goal of calibration is to adjust the predicted probabilities of a binary classification model so that they better reflect the true probabilities (i.e. empirical risk) of the positive class.

Value

Calibrated model object.

Method-specific parameters

For Classification objects:

• predicted_probabilities: Numeric vector of the positive class's predicted probabilities, one per case

• true_labels: Factor of true class labels

For ClassificationRes objects:

• resampler_config: ResamplerConfig object for calibration training

• train_verbosity: Integer controlling calibration model training output

Choosing a calibrator

A calibration map must be monotonic non-decreasing. A map that reorders scores changes the ranking of the predictions, and so changes AUC; a non-decreasing one cannot. available_calibration lists the algorithms that carry that guarantee. Any other Hyperparameters object is accepted and trained like any other model, but nothing then constrains the map.

• setup_Isotonic (the default) fits isotonic regression. The map is a step function, so it merges nearby scores into ties, which moves AUC slightly in either direction. Fitted probabilities are held at least 1 / (2 * n) away from 0 and 1, n being the number of calibration cases, so a block of uniformly labelled cases does not assert certainty.

• setup_MonotonicHAL fits a monotonic Highly Adaptive Lasso on the logit scale. At its default smoothness_orders = 1 the map is continuous and strictly increasing, so it preserves AUC exactly – but the constraint that achieves this also makes the map convex on the logit scale, which costs accuracy whenever the correction needed is concave. smoothness_orders = 0 with penalized = FALSE lifts that restriction, at the cost of ties and a markedly slower fit.

Isotonic is the default because no monotonic lasso configuration is uniformly better and every one of them is several times slower. data-raw/benchmark_calibrators.R reproduces the comparison.

The calibrator that ran is recorded on the returned object's ⁠@calibrator⁠ property, is shown by print(), and is serialized by to_json().

Author(s)

EDG

Examples

# --- Calibrate Classification ---
dat <- iris[51:150, ]
res <- resample(dat)
dat[["Species"]] <- factor(dat[["Species"]])
dat_train <- dat[res[[1]], ]
dat_test <- dat[-res[[1]], ]

# Train GLM on a training/test split
mod_c_glm <- train(
  x = dat_train,
  dat_test = dat_test,
  hyperparameters = setup_GLM()
)

# Calibrate the `Classification` by defining `predicted_probabilities` and `true_labels`,
# in this case using the training data, but it could be a separate calibration dataset.
mod_c_glm_cal <- calibrate(
  mod_c_glm,
  predicted_probabilities = mod_c_glm[["predicted_prob_training"]][, 1L],
  true_labels = mod_c_glm[["y_training"]]
)
mod_c_glm_cal

# --- Calibrate ClassificationRes ---

# Train GLM with cross-validation
resmod_c_glm <- train(
  x = dat,
  hyperparameters = setup_GLM(),
  outer_resampling_config = setup_KFold(n_resamples = 3L)
)

# Calibrate the `ClassificationRes` using the same resampling configuration as used for training.
resmod_c_glm_cal <- calibrate(resmod_c_glm)
resmod_c_glm_cal

Description

Check Data

Usage

check_data(
  x,
  name = NULL,
  get_duplicates = TRUE,
  get_na_case_pct = FALSE,
  get_na_feature_pct = FALSE
)

Arguments

Value

CheckData object.

Author(s)

EDG

Examples

n <- 1000
x <- rnormmat(n, 50, return_df = TRUE)
x[["char1"]] <- sample(letters, n, TRUE)
x[["char2"]] <- sample(letters, n, TRUE)
x[["fct"]] <- factor(sample(letters, n, TRUE))
x <- rbind(x, x[1, ])
x[["const"]] <- 99L
x[sample(nrow(x), 20), 3] <- NA
x[sample(nrow(x), 20), 10] <- NA
x[["fct"]][30:35] <- NA
check_data(x)

Description

Calculate class imbalance as given by:

$I = K\cdot\sum_{i=1}^K (n_i/N - 1/K)^2$

where $K$ is the number of classes, and $n_i$ is the number of instances of class $i$

Usage

class_imbalance(x)

Arguments

Value

Numeric.

Author(s)

EDG

Examples

# iris is perfectly balanced
class_imbalance(iris[["Species"]])
# Simulate imbalanced outcome
x <- factor(sample(c("A", "B"), size = 500L, replace = TRUE, prob = c(0.9, 0.1)))
class_imbalance(x)

Description

Classification Metrics

Usage

classification_metrics(
  true_labels,
  predicted_labels,
  predicted_prob = NULL,
  binclasspos = 2L,
  calc_auc = TRUE,
  calc_brier = TRUE,
  auc_method = "lightAUC",
  sample = NULL,
  verbosity = 0L
)

Arguments

Details

Note that auc_method = "pROC" is the only one that will output an AUC even if one or more predicted probabilities are NA.

Value

ClassificationMetrics object.

Author(s)

EDG

Examples

# Assume positive class is "b"
true_labels <- factor(c("a", "a", "a", "b", "b", "b", "b", "b", "b", "b"))
predicted_labels <- factor(c("a", "b", "a", "b", "b", "a", "b", "b", "b", "a"))
predicted_prob <- c(0.3, 0.55, 0.45, 0.75, 0.57, 0.3, 0.8, 0.63, 0.62, 0.39)

classification_metrics(true_labels, predicted_labels, predicted_prob)
classification_metrics(true_labels, predicted_labels, 1 - predicted_prob, binclasspos = 1L)

Description

Perform clustering on the rows (usually cases) of a dataset.

Usage

cluster(
  x,
  algorithm = "KMeans",
  config = NULL,
  execution_config = setup_FutureExecution(),
  outdir = NULL,
  verbosity = 1L
)

Arguments

Details

See docs.rtemis.org/r for detailed documentation.

Value

Clustering object.

Author(s)

EDG

Examples

iris_km <- cluster(exc(iris, "Species"), algorithm = "KMeans")

Description

A prediction interval for a regression or a set of labels for a classification, covering the truth with probability at least 1 - alpha under exchangeability alone – in finite samples, for any model, including a misspecified one.

Usage

conformal(x, newdata, calibration = NULL, config = NULL, verbosity = 1L, ...)

Arguments

Details

The guarantee is marginal. ⁠P(Y in C(X)) >= 1 - alpha⁠ averages over the draw of both the calibration set and the test case. It is not conditional: 90% marginal coverage is compatible with 99% coverage on easy cases and 60% on a hard subgroup, and averaged over everyone is not the same as guaranteed for anyone. It is also void, silently, under distribution shift – exchangeability is the whole assumption.

Width is the quality measure; coverage is the correctness check. A useless model attains valid coverage by returning intervals wide enough to be uninformative, so read the two together. The region reports its widths (or set sizes); conformal_metrics() scores coverage against outcomes the region did not see.

Which data calibrates. calibration is a tabular dataset holding the predictors and the outcome, in training shape. Left NULL, a model trained with dat_test calibrates on that split, whose residuals it already stores: train() never fits, tunes or early-stops on dat_test. Nothing else is assumed clean – a validation split may have driven early stopping, and a model chosen by its test metric has used that split for selection, which nothing in the object records.

Conformal calibration is unrelated to the probability calibration calibrate performs, and the two must not share rows. Where rtemis can see that they do, it refuses.

Which method. config NULL takes the method the object supports: split conformal for a Supervised, CV+ for a SupervisedRes. See setup_SplitConformal, setup_CVPlus and setup_CQR.

Value

PredictionInterval object for a regression, PredictionSet for a classification.

Author(s)

EDG

Examples

x <- data.frame(age = rnorm(300), bmi = rnorm(300))
x[["y"]] <- x[["age"]] * 2 + rnorm(300, sd = 0.3)
# Three splits: one fits, one calibrates, one scores what the other two did.
mod <- train(
  x[1:200, ],
  dat_test = x[201:250, ],
  hyperparameters = setup_GLM(),
  verbosity = 0L
)

# The stored test split calibrates; 90% intervals for five fresh cases.
region <- conformal(mod, x[1:5, c("age", "bmi")], verbosity = 0L)
region
region@lower
region@upper

# Coverage, against outcomes nothing in the pipeline has seen.
held_out <- x[251:300, ]
conformal_metrics(
  conformal(mod, held_out[, c("age", "bmi")], verbosity = 0L),
  held_out[["y"]]
)

Description

Empirical coverage and region size for a PredictionRegion, against the outcomes of the cases it bounds.

Usage

conformal_metrics(region, true_outcome)

Arguments

Details

Coverage on the calibration data is not a check. The threshold is chosen as the 1 - alpha empirical quantile of the calibration scores, so coverage measured back on those same cases is 1 - alpha by construction. Score against outcomes nothing in the pipeline has seen, or the number means nothing.

Read coverage and size together. A model with no signal attains valid coverage by returning intervals wide enough to be useless, so coverage alone cannot separate a good model from a wide one. Width – or set size, and the rate of singleton and empty sets – is the part that carries information about the model.

Coverage is a proportion over the cases supplied, so it carries the Monte Carlo error of that sample: 100 cases at a nominal 90% have a standard error near 3 points, and a single run landing at 87% is not evidence of a broken guarantee.

Value

One-row data.frame. coverage and n for either shape, plus mean_width and median_width for an interval, or mean_set_size, singleton_rate and empty_rate for a set.

Author(s)

EDG

Examples

x <- data.frame(age = rnorm(300), bmi = rnorm(300))
x[["y"]] <- x[["age"]] * 2 + rnorm(300, sd = 0.3)
mod <- train(
  x[1:200, ],
  dat_test = x[201:250, ],
  hyperparameters = setup_GLM(),
  verbosity = 0L
)
held_out <- x[251:300, ]
region <- conformal(mod, held_out[, c("age", "bmi")], verbosity = 0L)
conformal_metrics(region, held_out[["y"]])

Description

Computes a DataFingerprint: a content hash of x plus the structural facts (dimensions, column names) that make a mismatch between two runs diagnosable. Used to record which data a run actually used, so undocumented drift between experiments is visible.

Usage

data_fingerprint(x, method = "object", algorithm = "sha256", source = NULL)

Arguments

Value

DataFingerprint object.

Author(s)

EDG

Examples

fp <- data_fingerprint(iris)
fp
# A logically identical table in a different R container hashes differently
# under "object", which is what `@data_structure` records. FALSE:
data_fingerprint(iris)@hash ==
  data_fingerprint(data.table::as.data.table(iris))@hash

Description

Measures the facts validate_config checks a config against: dimensions, column types, distinct and missing counts per column, level counts for low-cardinality categorical columns, and the number of complete cases.

Usage

data_profile(x, n_duplicates = TRUE, fingerprint = FALSE)

Arguments

Details

One pass per column and no copy of the data, so profiling is cheap enough to do per validation.

Value

DataProfile object.

Author(s)

EDG

Examples

p <- data_profile(iris)
p@columns
p@level_counts

Description

Collect a table read with ddb_data(x, collect = FALSE)

Usage

ddb_collect(sql, progress = TRUE, returnobj = c("data.frame", "data.table"))

Arguments

Value

data.frame or data.table.

Author(s)

EDG

Examples

## Not run: 
# Requires local CSV file; replace with your own path
sql <- ddb_data("/Data/iris.csv", collect = FALSE)
ir <- ddb_collect(sql)

## End(Not run)

Description

Lazy-read a CSV file, optionally: filter rows, remove duplicates, clean column names, convert character to factor, collect.

Usage

ddb_data(
  filename,
  datadir = NULL,
  sep = ",",
  header = TRUE,
  quotechar = "",
  ignore_errors = TRUE,
  make_unique = TRUE,
  select_columns = NULL,
  filter_column = NULL,
  filter_vals = NULL,
  character2factor = FALSE,
  collect = TRUE,
  progress = TRUE,
  returnobj = c("data.table", "data.frame"),
  data.table.key = NULL,
  clean_colnames = TRUE,
  verbosity = 1L
)

Arguments

Value

data.frame or data.table if collect is TRUE, otherwise a character with the SQL query

Author(s)

EDG

Examples

## Not run: 
# Requires local CSV file; replace with your own path
ir <- ddb_data("/Data/massive_dataset.csv",
  filter_column = "ID",
  filter_vals = 8001:9999
)

## End(Not run)

Description

Perform linear or non-linear decomposition of numeric data.

Usage

decomp(
  x,
  algorithm = "ICA",
  config = NULL,
  execution_config = setup_FutureExecution(),
  outdir = NULL,
  verbosity = 1L
)

Arguments

Details

See docs.rtemis.org/r for detailed documentation.

Value

Decomposition object.

Author(s)

EDG

Examples

iris_pca <- decomp(exc(iris, "Species"), algorithm = "PCA")

Description

Quantify a fitted decomposition: how much of the data its components reconstruct, how redundant they are, and – given data the fit never saw – whether it generalizes.

Usage

decomp_metrics(
  decom,
  x,
  new_data = NULL,
  execution_config = NULL,
  verbosity = 1L
)

Arguments

Details

Which metrics are computed follows from the algorithm's traits; see applicable_metrics. A metric its algorithm cannot support is NA.

The unprefixed metrics describe the fitted data, so x must be that data: they are computed against the components decom already holds. A different number of cases is an error, and x failing to match decom@data_fingerprint is reported without raising, since scoring a fit against an altered copy of its training data is a legitimate thing to do.

decomp() already stores this on its result for the data it was fitted on, so calling this without new_data recomputes what decom@metrics holds. The reason to call it is new_data: reconstruction_gap is the difference between out-of-sample and in-sample relative reconstruction error, and it is the signal that a decomposition has fitted its training cases rather than their structure.

Reconstruction is measured in the units of the data as it was passed to decomp(), so the numbers are comparable across algorithms and across configurations of one algorithm. One caveat: ICA with row_norm = TRUE standardizes each case across features, and inverting that needs each case's own mean and standard deviation, taken from the data being reconstructed. Its reconstruction therefore draws on information the components do not carry, and its error is not comparable with an algorithm that reconstructs from components alone.

Value

DecompositionMetrics object.

Author(s)

EDG

Examples

x <- exc(iris, "Species")
iris_pca <- decomp(x, algorithm = "PCA", verbosity = 0L)
decomp_metrics(iris_pca, x, verbosity = 0L)

Description

Machine-readable properties of each decomposition algorithm available to decomp: whether the map is linear, whether it can be applied to new data, whether it inverts, and what its objective preserves.

Usage

decomposition_traits(algorithm = NULL)

Arguments

Details

The columns:

name

The name used by ⁠setup_<name>()⁠ and decomp(algorithm =).

description

Full name of the algorithm.

linear

The map from input space to component space is linear.

can_apply

A fitted result can be applied to new data with apply_decomp.

invertible

There is an inverse map from component space back to input space, so reconstruction error is defined.

orthogonal

Components are mutually orthogonal.

ordered

Components come in a meaningful order, so "the first j" is well-defined.

deterministic

The same input and configuration give the same result without setting a seed.

preserves

What the objective preserves: "variance", "global", "local", or "reconstruction".

nonneg

Requires non-negative input and produces non-negative factors.

threaded

The fit runs on as many threads as the execution config gives the algorithm (n_workers_algorithm, or the worker count). Like can_apply, it states what rtemis implements.

package

Package supplying the backend implementation.

can_apply states what rtemis implements, not what is mathematically possible. Parametric tSNE exists and Isomap admits a Nystrom-style out-of-sample extension; neither is implemented here, so both are FALSE. The column's contract is that apply_decomp on a fitted result of this algorithm returns components.

Value

data.frame: One row per algorithm, one column per trait.

Author(s)

EDG

Examples

decomposition_traits()
decomposition_traits("PCA")
# Which algorithms support out-of-sample projection?
decomposition_traits()[["name"]][decomposition_traits()[["can_apply"]]]

Description

Describe object

Usage

describe(x, verbosity = 1L, ...)

Arguments

Details

Extra arguments for factor method:

• max_n: Integer: Return counts for up to this many levels.

• return_ordered: Logical: If TRUE, return levels ordered by count, otherwise return in level order.

• verbosity: Integer: Verbosity level.

Value

Character, invisibly.

Author(s)

EDG

Examples

# --- For `Supervised` objects ---
species_cart <- train(iris, hyperparameters = setup_CART())
describe(species_cart)

# --- For `SupervisedRes` objects ---
mod <- train(
  iris,
  hyperparameters = setup_CART(),
  outer_resampling_config = setup_KFold(n_resamples = 3L)
)
describe(mod)

# --- For factors ---
# Small number of levels
describe(iris[["Species"]])

# Large number of levels: show top n by count
x <- factor(sample(letters, 1000, TRUE))
describe(x)
describe(x, 3)
describe(x, 3, return_ordered = FALSE)

Description

Move data frame column

Usage

df_movecolumn(x, colname, to = ncol(x))

Arguments

Value

data.frame

Author(s)

EDG

Examples

ir <- df_movecolumn(iris, colname = "Species", to = 1L)

Description

Get number of unique values per features

Usage

df_nunique_perfeat(x, excludeNA = FALSE)

Arguments

Value

Vector, integer of length NCOL(x) with number of unique values per column/feature

Author(s)

EDG

Examples

df_nunique_perfeat(iris)

Description

Draw a fitted LINAD model as an interactive tree: the partition as a hierarchy, each node's value on its label, and each node's linear coefficients in a table on hover.

Usage

draw_linad(
  x,
  n_leaves = NULL,
  top = 15L,
  sort_coefs = TRUE,
  direction = "UD",
  node_width = 180L,
  node_gap = 16L,
  level_separation = NULL,
  font_size = 14L,
  node_labels = TRUE,
  show_ncases = TRUE,
  show_node_value = TRUE,
  show_changes = TRUE,
  lo_col = sign_colors()[["negative"]],
  mid_col = NULL,
  hi_col = sign_colors()[["positive"]],
  root_col = NULL,
  node_col = NULL,
  leaf_col = NULL,
  hover_col = NULL,
  height = "600px",
  theme = NULL,
  verbosity = 1L
)

Arguments

Details

The coefficient tables are the point. A LINAD leaf's coefficients are the accumulated sum along its path, so the same feature can carry a different slope in each region of the data – and sometimes a different sign. That is the model's central interpretive claim, and it is only visible by comparing the table at one node against the table at another. The color scale is therefore diverging and centered on zero, and computed once across every table, so a sign change reads as a color flip.

Each node's label carries node_value, what the tree alone predicts there, while the table on hover carries what the linear model adds. The two are separate quantities in a fitted LINAD, so the plot shows them separately: with node_model = "constant" the tables are empty of slopes and the node values are the entire model, which is what a plain decision tree looks like.

The intercept is excluded from the color range. It is typically far larger than any slope and would compress every other coefficient into the middle of the scale.

This is the reference implementation for the LINAD tree plot, built on visNetwork because a tooltip carrying a real HTML table needs a backend whose tooltip is an HTML element. Plotly, which every other ⁠draw_*⁠ uses, renders hover labels as SVG and cannot express a table at all.

Value

visNetwork htmlwidget.

Author(s)

EDG

Examples

x <- data.frame(a = rnorm(300), b = rnorm(300))
x[["y"]] <- 2 * x[["a"]] + ifelse(x[["b"]] < 0, -3, 3) + rnorm(300)
mod <- train(x, hyperparameters = setup_LINAD(max_leaves = 5L))
draw_linad(mod)

Description

Describe data.table

Usage

dt_describe(x, verbosity = 1L)

Arguments

Value

List with three data.tables: Numeric, Categorical, and Date.

Author(s)

EDG

Examples

library(data.table)
origin <- as.POSIXct("2022-01-01 00:00:00", tz = "America/Los_Angeles")
x <- data.table(
  ID = paste0("ID", 1:10),
  V1 = rnorm(10),
  V2 = rnorm(10, 20, 3),
  V1_datetime = as.POSIXct(
    seq(
      1, 1e7,
      length.out = 10
    ),
    origin = origin
  ),
  V2_datetime = as.POSIXct(
    seq(
      1, 1e7,
      length.out = 10
    ),
    origin = origin
  ),
  C1 = sample(c("alpha", "beta", "gamma"), 10, TRUE),
  F1 = factor(sample(c("delta", "epsilon", "zeta"), 10, TRUE))
)

Description

Will attempt to identify columns that should be numeric but are either character or factor by running inspect_type on each column.

Usage

dt_inspect_types(x, cols = NULL, verbosity = 1L)

Arguments

Value

Character vector.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(
  id = 8001:8006,
  a = c("3", "5", "undefined", "21", "4", NA),
  b = c("mango", "banana", "tangerine", NA, "apple", "kiwi"),
  c = c(1, 2, 3, 4, 5, 6)
)
dt_inspect_types(x)

Description

Reshape a long format data.table using key-value pairs with data.table::dcast

Usage

dt_keybin_reshape(
  x,
  id_name,
  key_name,
  positive = 1,
  negative = 0,
  xname = NULL,
  verbosity = 1L
)

Arguments

Value

data.table in wide format.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(
  ID = rep(1:3, each = 2),
  Dx = c("A", "C", "B", "C", "D", "A")
)
dt_keybin_reshape(x, id_name = "ID", key_name = "Dx")

Description

Merge data.tables

Usage

dt_merge(
  left,
  right,
  on = NULL,
  left_on = NULL,
  right_on = NULL,
  how = "left",
  left_name = NULL,
  right_name = NULL,
  left_suffix = NULL,
  right_suffix = NULL,
  verbosity = 1L,
  ...
)

Arguments

Value

Merged data.table.

Author(s)

EDG

Examples

library(data.table)
xleft <- data.table(ID = 1:5, Alpha = letters[1:5])
xright <- data.table(ID = c(3, 4, 5, 6), Beta = LETTERS[3:6])
xlr_inner <- dt_merge(xleft, xright, on = "ID", how = "inner")

Description

List column names by attribute

Usage

dt_names_by_attr(x, attribute, exact = TRUE, sorted = TRUE)

Arguments

Value

Character vector.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(
  id = 1:5,
  sbp = rnorm(5, 120, 15),
  dbp = rnorm(5, 80, 10),
  paO2 = rnorm(5, 90, 10),
  paCO2 = rnorm(5, 40, 5)
)
setattr(x[["id"]], "source", "demographics")
setattr(x[["sbp"]], "source", "outpatient")
setattr(x[["dbp"]], "source", "outpatient")
setattr(x[["paO2"]], "source", "icu")
setattr(x[["paCO2"]], "source", "icu")

dt_names_by_attr(x, "source", "outpatient")

Description

Number of unique values per feature

Usage

dt_nunique_perfeat(x, excludeNA = FALSE, limit = 20L, verbosity = 1L)

Arguments

Value

Named integer vector of length NCOL(x) with number of unique values per column/feature, invisibly.

Author(s)

EDG

Examples

library(data.table)
ir <- as.data.table(iris)
dt_nunique_perfeat(ir)

Description

Get N and percent match of values between two columns of two data.tables

Usage

dt_pctmatch(x, y, on = NULL, left_on = NULL, right_on = NULL, verbosity = 1L)

Arguments

Value

list.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(ID = 1:5, Alpha = letters[1:5])
y <- data.table(ID = c(3, 4, 5, 6), Beta = LETTERS[3:6])
dt_pctmatch(x, y, on = "ID")

Description

Get percent of missing values from every column

Usage

dt_pctmissing(x, verbosity = 1L)

Arguments

Value

list

Author(s)

EDG

Examples

library(data.table)
x <- data.table(a = c(1, 2, NA, 4), b = c(NA, NA, 3, 4), c = c("A", "B", "C", NA))
dt_pctmissing(x)

Description

This function inspects a data.table and attempts to identify columns that should be numeric but have been read in as character, and fixes their type in-place. This can happen when one or more fields contain non-numeric characters, for example.

Usage

dt_set_autotypes(x, cols = NULL, verbosity = 1L)

Arguments

Value

data.table, invisibly.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(
  id = 8001:8006,
  a = c("3", "5", "undefined", "21", "4", NA),
  b = c("mango", "banana", "tangerine", NA, "apple", "kiwi"),
  c = c(1, 2, 3, 4, 5, 6)
)
str(x)
# ***in-place*** operation means no assignment is needed
dt_set_autotypes(x)
str(x)

# Try excluding column 'a' from autotyping
x <- data.table(
  id = 8001:8006,
  a = c("3", "5", "undefined", "21", "4", NA),
  b = c("mango", "banana", "tangerine", NA, "apple", "kiwi"),
  c = c(1, 2, 3, 4, 5, 6)
)
str(x)
# exclude column 'a' from autotyping
dt_set_autotypes(x, cols = setdiff(names(x), "a"))
str(x)

Description

Clean column names and factor levels in-place

Usage

dt_set_clean_all(x, prefix_digits = NA)

Arguments

Value

Nothing, modifies x in-place.

Author(s)

EDG

Examples

library(data.table)
x <- as.data.table(iris)
levels(x[["Species"]]) <- c("setosa:iris", "versicolor$iris", "virginica iris")
names(x)
levels(x[["Species"]])
# ***in-place*** operation means no assignment is needed
dt_set_clean_all(x)
names(x)
levels(x[["Species"]])

Description

Finds all factors in a data.table and cleans factor levels to include only underscore symbols

Usage

dt_set_cleanfactorlevels(x, prefix_digits = NA)

Arguments

Value

Nothing, modifies x in-place.

Author(s)

EDG

Examples

library(data.table)
x <- as.data.table(iris)
levels(x[["Species"]]) <- c("setosa:iris", "versicolor$iris", "virginica iris")
levels(x[["Species"]])
dt_set_cleanfactorlevels(x)
levels(x[["Species"]])

Description

Convert data.table logical columns to factors with custom labels in-place

Usage

dt_set_logical2factor(
  x,
  cols = NULL,
  labels = c("False", "True"),
  maintain_attributes = TRUE,
  fillNA = NULL
)

Arguments

Value

data.table, invisibly.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(a = 1:5, b = c(TRUE, FALSE, FALSE, FALSE, TRUE))
x
dt_set_logical2factor(x)
x
z <- data.table(
  alpha = 1:5,
  beta = c(TRUE, FALSE, TRUE, NA, TRUE),
  gamma = c(FALSE, FALSE, TRUE, FALSE, NA)
)
# You can usee fillNA to fill NA values with a constant
dt_set_logical2factor(z, cols = "beta", labels = c("No", "Yes"), fillNA = "No")
z
w <- data.table(mango = 1:5, banana = c(FALSE, FALSE, TRUE, TRUE, FALSE))
w
dt_set_logical2factor(w, cols = 2, labels = c("Ugh", "Huh"))
w
# Column attributes are maintained by default:
z <- data.table(
  alpha = 1:5,
  beta = c(TRUE, FALSE, TRUE, NA, TRUE),
  gamma = c(FALSE, FALSE, TRUE, FALSE, NA)
)
for (i in seq_along(z)) setattr(z[[i]], "source", "Guava")
str(z)
dt_set_logical2factor(z, cols = "beta", labels = c("No", "Yes"))
str(z)

Description

Convert data.table's factor to one-hot encoding in-place

Usage

dt_set_one_hot(x, xname = NULL, verbosity = 1L)

Arguments

Value

The input, invisibly, after it has been modified in-place.

Author(s)

EDG

Examples

ir <- data.table::as.data.table(iris)
# dt_set_one_hot operates ***in-place***; therefore no assignment is used:
dt_set_one_hot(ir)
ir

Description

Exclude columns by character or numeric vector.

Usage

exc(x, idx)

Arguments

Value

data.frame, tibble, or data.table.

Author(s)

EDG

Examples

exc(iris, "Species") |> head()
exc(iris, c(1, 3)) |> head()

Description

Per-case explanation of a fitted model: why it predicted what it did, for each case in newdata. Where get_varimp() ranks features across a whole model, this attributes one prediction – a feature can rank third overall and be the entire reason for one case.

Usage

explain(x, newdata, background = NULL, config = NULL, verbosity = 1L, ...)

Arguments

Details

background is what the contributions are measured against, and most estimators cannot work without one. A contribution says how far a feature moved this case's prediction away from E[f(x)], and that expectation is a property of the background data, and the model does not store the data it was trained on. Pass the training features, or a representative sample of them. The exceptions are the estimators that take their baseline from the model itself, such as the LightGBM family's; those ignore it, and everything else aborts without it.

Two explanations of one model against different backgrounds are not comparable, and nothing in the returned numbers says so – which is why the result carries a fingerprint of the background it used.

config chooses the method, built by setup_SHAP: setup_SHAP(perturbation = "conditional") picks the value function, setup_SHAP(estimator = "kernel") overrides the estimator the algorithm would otherwise get. explanation_methods reports which estimator applies to which algorithm, whether it is exact, and why.

A SupervisedRes additionally takes type: "avg" (the default) averages the resamples' explanations, which decomposes the averaged prediction exactly, and "all" returns one explanation per resample.

The contributions plus the baseline reconstruct the prediction exactly, on the scale they were computed on. For classification that scale is the model's margin, not the probability stats::predict() returns: probability is a nonlinear transform of the margin, so contributions do not sum to it.

Read the result with shap_case for one case, shap_long across cases, shap_by_level for the levels of a categorical, and get_varimp() for ⁠mean(|phi|)⁠ per feature.

A SHAP value is not a causal effect. It attributes a prediction under the model's own logic; intervening on a feature in the world does not move the outcome by its attribution. Correlated features split credit between themselves, and how they split it depends on the value function – so a small attribution does not show a feature to be unimportant, and this is not a feature-selection criterion.

Value

SHAP object, or a named list of them for a SupervisedRes with type = "all".

Author(s)

EDG

Examples

x <- data.frame(age = rnorm(100), bmi = rnorm(100))
x[["y"]] <- x[["age"]] * 2 + rnorm(100, sd = 0.3)
features <- x[, c("age", "bmi")]
mod <- train(x, hyperparameters = setup_GLM(), verbosity = 0L)

# `background` is what the contributions are measured against.
contributions <- explain(
  mod,
  features[1:5, ],
  background = features,
  verbosity = 0L
)
contributions

# Contributions plus the baseline reconstruct the prediction, exactly:
rowSums(contributions@phi[["outcome"]]) + contributions@baseline[, 1L]
predict(mod, features[1:5, ], verbosity = 0L)

# One case, ordered the way a waterfall reads:
shap_case(contributions, features[1:5, ], case = 1L)

# Which features mattered across these cases:
get_varimp(contributions)

# `config` chooses the method; here, a subsampled background.
explain(
  mod,
  features[1:5, ],
  background = features,
  config = setup_SHAP(background_n = 50L),
  verbosity = 0L
)

Description

What explain does to a model fitted by each supervised algorithm: which estimator setup_SHAP(estimator = "auto") resolves to, whether that answer is exact, which value function it computes, and why.

Usage

explanation_methods(algorithm = NULL)

Arguments

Details

The columns:

name

The algorithm, as named by ⁠setup_<name>()⁠.

estimator

The estimator "auto" resolves to. "KernelSHAP" is the model-agnostic fallback and applies to every algorithm; the others are exact and algorithm-specific.

exact

TRUE if the estimator returns Shapley values rather than an estimate of them, NA where that depends on the fitted model rather than on the algorithm – an ensemble whose meta-learner turned out to be linear, or a model that has one linear map for a regression or binary outcome but not for a multiclass one. An NA row explains what it did when asked, and refuses with a message naming the reason when it cannot.

perturbation

The value function computed when setup_SHAP(perturbation = ) is left NULL.

rationale

Why this estimator, in one line.

estimator = "kernel" is always available, so a row whose exact is FALSE is saying that estimator = "exact" has nothing to offer for it – not that the algorithm cannot be explained.

Value

data.frame: One row per algorithm.

Author(s)

EDG

Examples

explanation_methods()
explanation_methods("Ranger")
# Which algorithms have an exact estimator?
em <- explanation_methods()
em[["name"]][!is.na(em[["exact"]]) & em[["exact"]]]

Description

Convert a tabular dataset to a matrix, one-hot encoding factors, if present.

Usage

feature_matrix(x)

Arguments

Details

This is a convenience function that uses features(), preprocess(), as.matrix().

Value

Matrix with features. Factors are one-hot encoded, if present.

Author(s)

EDG

Examples

# reorder columns so that we have a categorical feature
x <- set_outcome(iris, "Sepal.Length")
feature_matrix(x) |> head()

Description

Returns all column names except the last one

Usage

feature_names(x)

Arguments

Details

This applied to tabular datasets used for supervised learning in rtemis, where, by convention, the last column is the outcome variable and all other columns are features.

Value

Character vector of feature names.

Author(s)

EDG

Examples

feature_names(iris)

Description

Returns all columns except the last one.

Usage

features(x)

Arguments

Details

This can be applied to tabular datasets used for supervised learning in rtemis, where, by convention, the last column is the outcome variable and all other columns are features.

Value

Object of the same class as the input, after removing the last column.

Author(s)

EDG

Examples

features(iris) |> head()

Description

Train one regression model on x and y with an algorithm named as a string, then return its predictions for newdata, their standard errors when the algorithm provides them, and the training R-squared.

Usage

fit_predict(
  x,
  y,
  newdata,
  algorithm,
  params = NULL,
  se = FALSE,
  verbosity = 0L
)

Arguments

Details

This is the bridge behind fit = "<algorithm>" in rtemis.draw::draw_scatter(), rtemis.draw::draw_fit() and rtemis.draw::draw_scatter3d(), which need a fitted curve or surface from a name alone. For full control over training, use train().

Value

Named list: fitted (Numeric predictions for newdata), se (Numeric standard errors, or NULL when se = FALSE or the algorithm has none), rsq (Numeric training R-squared), and algorithm (Character canonical algorithm name).

Author(s)

EDG

Examples

fit <- fit_predict(
  mtcars["wt"], mtcars[["mpg"]],
  newdata = data.frame(wt = c(2, 3, 4)),
  algorithm = "GLM",
  se = TRUE
)
fit[["fitted"]]
fit_predict(
  mtcars["wt"], mtcars[["mpg"]],
  newdata = data.frame(wt = c(2, 3, 4)),
  algorithm = "LINAD",
  params = list(max_leaves = 2)
)[["fitted"]]

Description

⁠@config⁠ holds what the user asked for and ⁠@values⁠ what preprocessing learned, which keeps the input intact – but re-applying to new data needs the two merged, and so does a run record, which must report the values actually used. One merge, so the two cannot disagree.

Usage

fitted_config(preprocessor)

Arguments

Details

The merged fields are settable inputs: supplying scale_centers makes preprocess() use it instead of computing one. That is why the merge is ⁠@values⁠ over ⁠@config⁠ and not the reverse – a learned value only fills a slot the user left empty.

Value

PreprocessorConfig with the learned values applied.

Author(s)

EDG

See Also

apply_preprocessor, setup_Preprocessor

Examples

iris_pre <- preprocess(iris, setup_Preprocessor(scale = TRUE, center = TRUE))
# The config as supplied carries no centers; the fitted one carries the
# centers `preprocess()` computed.
fitted_config(iris_pre)@scale_centers

Description

Get factor names

Usage

get_factor_names(x)

Arguments

Details

This applied to tabular datasets used for supervised learning in rtemis, where, by convention, the last column is the outcome variable and all other columns are features.

Value

Character vector of factor names.

Author(s)

EDG

Examples

get_factor_names(iris)

Description

The loss recorded at every step of training, as data: one row per step, with the training and validation loss where the algorithm records them.

Returns NULL for an algorithm that records no learning curve, so it is safe to call on any model.

Usage

get_learning_curve(x, ...)

Arguments

Value

data.frame with columns iteration, loss_training and loss_validation, carrying attributes unit and selected; or NULL.

Author(s)

EDG

See Also

plot_learning, which draws it

Examples

dat <- set_outcome(iris[, 1:4], "Sepal.Length")
mod <- train(
  dat[1:100, ],
  dat_validation = dat[101:150, ],
  hyperparameters = setup_LINAD(max_leaves = 12L)
)
get_learning_curve(mod)

Description

The performance metrics stored on a fitted model, clustering, or decomposition, for one sample.

Usage

get_metrics(x, sample = NULL, calibrated = FALSE)

Arguments

Details

A Supervised model stores metrics for the training sample, and for the validation and test samples when train received dat_validation and dat_test. A SupervisedRes model stores per-resample metrics for the training and test samples of each outer resample, with their mean and standard deviation. A calibrated classifier also stores the metrics of its calibrated predictions, selected with calibrated = TRUE.

A Clustering or Decomposition stores metrics for the data it was fitted on, which sample = NULL and sample = "training" both select. For a decomposition, decomp_metrics computes the metrics of new data.

Requesting a sample the object does not store raises an error that names the samples it does store.

The returned object supports $ and [[: for example, get_metrics(mod, "test")$rsq.

Value

Metrics object for a Supervised model; MetricsRes object for a SupervisedRes model; ClusteringMetrics or DecompositionMetrics object, or NULL when the object holds no metrics, for a Clustering or Decomposition.

Author(s)

EDG

Examples

x <- data.frame(age = rnorm(100), bmi = rnorm(100))
x[["y"]] <- x[["age"]] * 2 + rnorm(100, sd = 0.3)
mod <- train(
  x[1:80, ],
  dat_test = x[81:100, ],
  hyperparameters = setup_GLM(),
  verbosity = 0L
)
get_metrics(mod, "training")
get_metrics(mod, "test")$rsq

Description

Returns the mode of a factor or integer

Usage

get_mode(x, na.rm = TRUE, getlast = TRUE, retain_class = TRUE)

Arguments

Value

The mode of x

Author(s)

EDG

Examples

x <- c(9, 3, 4, 4, 0, 2, 2, NA)
get_mode(x)
x <- c(9, 3, 2, 2, 0, 4, 4, NA)
get_mode(x)
get_mode(x, getlast = FALSE)

Description

The variable importance measures a fitted model reports, or the mean absolute contribution of each predictor in a SHAP explanation.

Usage

get_varimp(x, ...)

Arguments

Details

A VariableImportance object holds its measures by name in ⁠@measures⁠. Each measure states what it quantifies (⁠@kind⁠, for example split gain, permutation, or coefficient), the cases it was computed on (⁠@computed_on⁠), whether its values can be negative (⁠@signed⁠) or depend on the units of the predictors (⁠@scale_dependent⁠), how it ranks predictors (⁠@direction⁠), and what its values are for this model (⁠@description⁠); ⁠@values⁠ holds the value for each predictor. varimp_table combines the measures into one data.frame.

Value

VariableImportance object, a list of them (one per resample) for a SupervisedRes, or NULL when the algorithm reports no importance.

Author(s)

EDG

Examples

mod <- train(iris, hyperparameters = setup_LightRF())
get_varimp(mod)

Description

Get names by string matching or class

Usage

getnames(
  x,
  pattern = NULL,
  starts_with = NULL,
  ends_with = NULL,
  ignore_case = TRUE
)

getfactornames(x)

getnumericnames(x)

getlogicalnames(x)

getcharacternames(x)

getdatenames(x)

Arguments

Details

For getnames() only: pattern, starts_with, and ends_with are applied sequentially. If more than one is provided, the result will be the intersection of all matches.

Value

Character vector of matched names.

Author(s)

EDG

Examples

getnames(iris, starts_with = "Sepal")
getnames(iris, ends_with = "Width")
getfactornames(iris)
getnumericnames(iris)

Description

Get data.frame names and types

Usage

getnamesandtypes(x)

Arguments

Value

character vector of column names with attribute "type" holding the class of each column

Author(s)

EDG

Examples

getnamesandtypes(iris)

Description

Built by tune_over() and stored in the hyperparameter it is assigned to, so that a search space is a distinct type, never inferred from a vector's length.

Usage

HyperparameterCandidates(candidates = list(), from_vector = FALSE)

Arguments

Value

HyperparameterCandidates object.

Author(s)

EDG

Examples

# Built by tune_over(), not directly.
d <- tune_over(3L, 4L, 5L)
d@candidates

Description

Select (include) columns by character or numeric vector.

Usage

inc(x, idx)

Arguments

Value

data.frame, tibble, or data.table.

Author(s)

EDG

Examples

inc(iris, c(3, 4)) |> head()
inc(iris, c("Sepal.Length", "Species")) |> head()

Description

Index columns by attribute name & value

Usage

index_col_by_attr(x, name, value, exact = TRUE)

Arguments

Value

Integer vector.

Author(s)

EDG

Examples

library(data.table)
x <- data.table(
  id = 1:5,
  sbp = rnorm(5, 120, 15),
  dbp = rnorm(5, 80, 10),
  paO2 = rnorm(5, 90, 10),
  paCO2 = rnorm(5, 40, 5)
)
setattr(x[["sbp"]], "source", "outpatient")
setattr(x[["dbp"]], "source", "outpatient")
setattr(x[["paO2"]], "source", "icu")
setattr(x[["paCO2"]], "source", "icu")
index_col_by_attr(x, "source", "icu")

Description

The first step of any pipeline. A delimited file or a spreadsheet carries no usable type information; Parquet does. Ingesting once means nothing downstream infers a type a second time, and the decisions that were made are in the config.

The config's format is checked against the file, and a mismatch is an error: a config written for a delimited file sets options a Parquet reader would ignore.

Returns a manifest describing what happened: the file in, the file out, a DataFingerprint of the data, the config, and which engine ran it. The engine is named from the start because it is unrecoverable later – once a second implementation exists, nothing else could say which produced a given Parquet.

Usage

ingest(path, outfile, config = NULL, overwrite = FALSE, verbosity = 1L)

Arguments

Value

Named list: the ingest manifest.

Author(s)

EDG

Examples

## Not run: 
ingest("data.csv", "data.parquet")
ingest("data.csv", "data.parquet", setup_DelimitedIngest(sep = ";"))

## End(Not run)

Description

Initializes Directory Structure: "R", "Data", "Results"

Usage

init_project_dir(path, output_dir = "Out", verbosity = 1L)

Arguments

Value

Character: the path where the project directory was initialized, invisibly.

Author(s)

EDG

Examples

## Not run: 
# Will create "my_project" directory with
init_project_dir("my_project")

## End(Not run)

Description

Inspect rtemis object

Usage

inspect(x)

Arguments

Value

Called for side effect of printing information to console; returns character string invisibly.

Author(s)

EDG

Examples

inspect(iris)

Description

Checks character or factor vector to determine whether it might be best to convert to numeric.

Usage

inspect_type(x, xname = NULL, verbosity = 1L, thresh = 0.5, na.omit = TRUE)

Arguments

Details

All data can be represented as a character string. A numeric variable may be read as a character variable if there are non-numeric characters in the data. It is important to be able to automatically detect such variables and convert them, which would mean introducing NA values.

Value

Character.

Author(s)

EDG

Examples

x <- c("3", "5", "undefined", "21", "4", NA)
inspect_type(x)
z <- c("mango", "banana", "tangerine", NA)
inspect_type(z)

Description

Check if vector is constant

Usage

is_constant(x, skip_missing = FALSE)

Arguments

Value

Logical.

Author(s)

EDG

Examples

x <- rep(9, 1000000)
is_constant(x)
x[10] <- NA
is_constant(x)
is_constant(x, skip_missing = TRUE)

Description

The read direction of S7_to_JSONSchema: reads each property's PropertySpec back out of the schema and assembles a live S7 class whose properties carry the same types, bounds, enums, containers, and validators as the class the schema was generated from.

Usage

JSONSchema_to_S7(
  schema,
  defaults = NULL,
  refs = NULL,
  name = NULL,
  package = NULL,
  authoring = NULL,
  declarations = NULL,
  schemas = NULL,
  decode_reference = NULL,
  parent = NULL,
  policies = NULL
)

Arguments

Details

Defaults are supplied in a separate versioned artifact keyed by schema ⁠$id⁠. The published schemas carry no default keywords. Absent declaration defaults remain absent; constructing a non-nullable property without a default requires a value.

Properties holding a nested config are published as a ⁠$ref⁠ to that config's own schema. Supply the parsed graph through schemas and the format version 1 artifact through defaults to reconstruct these references. Independently supplied S7 reference classes can be passed through refs. Reconstructed constructors use declaration defaults; input resolution policies remain separate metadata on the class.

Value

S7 class.

Author(s)

EDG

Examples

# A schema as `S7_to_JSONSchema()` emits it: standard keywords carry the
# bounds, `x-rtemis` carries the leaf type.
schema <- list(
  title = "Demo",
  properties = list(
    k = list(
      type = "integer",
      minimum = 1L,
      maximum = 10L,
      description = "Number of components.",
      `x-rtemis` = list(type = "integer")
    )
  )
)
Demo <- JSONSchema_to_S7(schema, defaults = list(k = 2L))
Demo()@k
Demo(k = 5L)@k
# The reconstructed class enforces the schema's bounds.
tryCatch(Demo(k = 99L), error = conditionMessage)

Description

Mass-univariate GLM Analysis

Usage

massGLM(x, y, scale_y = NULL, center_y = NULL, verbosity = 1L)

Arguments

Value

MassGLM object.

Author(s)

EDG

Examples

set.seed(2022)
y <- rnormmat(500, 40, return_df = TRUE)
x <- data.frame(
  x1 = y[[3]] - y[[5]] + y[[14]] + rnorm(500),
  x2 = y[[21]] + rnorm(500),
  g = factor(sample(letters[1:3], 500, replace = TRUE))
)
massmod <- massGLM(x, y)
# Print table of coefficients, p-values, etc. for all models
summary(massmod)

Description

Find one or more cases from a pool data.frame that match cases in a target data.frame. Match exactly and/or by distance (sum of squared distances).

Usage

matchcases(
  target,
  pool,
  n_matches = 1,
  target_id = NULL,
  pool_id = NULL,
  exactmatch_factors = TRUE,
  exactmatch_cols = NULL,
  distmatch_cols = NULL,
  norepeats = TRUE,
  ignore_na = FALSE,
  verbosity = 1L
)

Arguments

Value

data.frame

Author(s)

EDG

Examples

set.seed(2021)
cases <- data.frame(
  PID = paste0("PID", seq(4)),
  Sex = factor(c(1, 1, 0, 0)),
  Handedness = factor(c(1, 1, 0, 1)),
  Age = c(21, 27, 39, 24),
  Var = c(.7, .8, .9, .6),
  Varx = rnorm(4)
)
controls <- data.frame(
  CID = paste0("CID", seq(50)),
  Sex = factor(sample(c(0, 1), 50, TRUE)),
  Handedness = factor(sample(c(0, 1), 50, TRUE, c(.1, .9))),
  Age = sample(16:42, 50, TRUE),
  Var = rnorm(50),
  Vary = rnorm(50)
)

mc <- matchcases(cases, controls, 2, "PID", "CID")

Description

Get names by string matching multiple patterns

Usage

mgetnames(
  x,
  pattern = NULL,
  starts_with = NULL,
  ends_with = NULL,
  ignore_case = TRUE,
  return_index = FALSE
)

Arguments

Details

pattern, starts_with, and ends_with are applied and the union of all matches is returned. pattern can be a character vector of multiple patterns to match.

Value

Character vector of matched names or integer index.

Author(s)

EDG

Examples

mgetnames(iris, pattern = c("Sepal", "Petal"))
mgetnames(iris, starts_with = "Sepal")
mgetnames(iris, ends_with = "Width")

Description

List column names by class

Usage

names_by_class(x, sorted = TRUE, item_format = highlight, maxlength = 24)

Arguments

Value

NULL, invisibly.

Author(s)

EDG

Examples

names_by_class(iris)

Description

Returns the numeric columns among the features (all columns except the last).

Usage

numeric_features(x)

Arguments

Details

Mirrors features(): by rtemis convention the last column is the outcome variable and all other columns are features. This drops the outcome, then keeps the numeric features (both double and integer). Useful, for example, to feed only the continuous features to a decomposition: decomp(numeric_features(iris), ...).

Value

Object of the same class as the input, containing only the numeric feature columns.

Author(s)

EDG

Examples

numeric_features(iris) |> head()

Description

Convert one-hot encoded matrix to factor

Usage

one_hot2factor(x, labels = colnames(x))

Arguments

Details

If input has a single column, it will be converted to factor and returned

Value

A factor.

Author(s)

EDG

Examples

x <- data.frame(matrix(FALSE, 10, 3))
colnames(x) <- c("Dx1", "Dx2", "Dx3")
x[["Dx1"]][1:3] <- x[["Dx2"]][4:6] <- x[["Dx3"]][7:10] <- TRUE
one_hot2factor(x)

Description

Returns the last column of x, which is by convention the outcome variable.

Usage

outcome(x)

Arguments

Details

This applied to tabular datasets used for supervised learning in rtemis, where, by convention, the last column is the outcome variable and all other columns are features.

Value

Vector containing the last column of x.

Author(s)

EDG

Examples

outcome(iris)

Description

Get the name of the last column

Usage

outcome_name(x)

Arguments

Details

This applied to tabular datasets used for supervised learning in rtemis, where, by convention, the last column is the outcome variable and all other columns are features.

Value

Name of the last column.

Author(s)

EDG

Examples

outcome_name(iris)

Description