Package {tidylearn}

tidylearn: A Unified Tidy Interface to R's Machine Learning Ecosystem

Description

Provides a unified tidyverse-compatible interface to R's machine learning ecosystem - from data ingestion to model publishing. The tl_read() family reads data from files ('CSV', 'Excel', 'Parquet', 'JSON'), databases ('SQLite', 'PostgreSQL', 'MySQL', 'BigQuery'), and cloud sources ('S3', 'GitHub', 'Kaggle'). The tl_model() function wraps established implementations from 'glmnet', 'randomForest', 'xgboost', 'e1071', 'rpart', 'gbm', 'nnet', 'cluster', 'dbscan', and others with consistent function signatures and tidy tibble output. Results flow into unified 'ggplot2'-based visualization and optional formatted 'gt' tables via the tl_table() family. The underlying algorithms are unchanged; 'tidylearn' simply makes them easier to use together. Access raw model objects via the $fit slot for a supervised method, or $fit$model for an unsupervised one. Methods include random forests Breiman (2001) doi:10.1023/A:1010933404324, LASSO regression Tibshirani (1996) doi:10.1111/j.2517-6161.1996.tb02080.x, elastic net Zou and Hastie (2005) doi:10.1111/j.1467-9868.2005.00503.x, support vector machines Cortes and Vapnik (1995) doi:10.1007/BF00994018, and gradient boosting Friedman (2001) doi:10.1214/aos/1013203451.

Details

tidylearn wraps established R machine learning packages behind one consistent interface. The main entry points are:

tl_read

Read data from files, databases and cloud sources into a tidy tibble.

tl_model

Fit any supported supervised or unsupervised method.

tl_evaluate

Score a fitted model.

tl_table

Render results as formatted gt tables.

tl_auto_ml

Search across methods automatically.

Every fitted model keeps the underlying package's own object in its $fit slot, so package-specific functionality remains available.

See vignette("getting-started", package = "tidylearn") for a walkthrough.

Author(s)

Maintainer: Cesaire Tobias cesaire@sheetsolved.com

See Also

Useful links:

• https://tidylearn.sheetsolved.com

• https://github.com/ces0491/tidylearn

• Report bugs at https://github.com/ces0491/tidylearn/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

lhs %>% rhs

Arguments

Value

The result of applying rhs to lhs.

Augment Data with DBSCAN Cluster Assignments

Description

Augment Data with DBSCAN Cluster Assignments

Usage

augment_dbscan(dbscan_obj, data)

Arguments

Value

A tibble containing the original data with additional columns cluster (factor), is_noise (logical), and is_core (logical).

Examples

db <- tidy_dbscan(iris[, 1:4], eps = 0.5, minPts = 5)
augmented <- augment_dbscan(db, iris)

Augment Data with Hierarchical Cluster Assignments

Description

Add cluster assignments to original data

Usage

augment_hclust(hclust_obj, data, k = NULL, h = NULL)

Arguments

Value

A tibble containing the original data with an additional cluster integer column indicating cluster assignments.

Examples

hc <- tidy_hclust(USArrests, method = "ward.D2")
augmented <- augment_hclust(hc, USArrests, k = 3)

Augment Data with K-Means Cluster Assignments

Description

Augment Data with K-Means Cluster Assignments

Usage

augment_kmeans(kmeans_obj, data)

Arguments

Value

A tibble containing the original data with an additional cluster factor column indicating cluster assignments.

Examples

km <- tidy_kmeans(iris[, 1:4], k = 3)
augmented <- augment_kmeans(km, iris)

Augment Data with PAM Cluster Assignments

Description

Augment Data with PAM Cluster Assignments

Usage

augment_pam(pam_obj, data)

Arguments

Value

A tibble containing the original data with an additional cluster factor column indicating cluster assignments.

Examples

pm <- tidy_pam(iris[, 1:4], k = 3)
augmented <- augment_pam(pm, iris)

Augment Original Data with PCA Scores

Description

Add PC scores to the original dataset

Usage

augment_pca(pca_obj, data, n_components = NULL)

Arguments

Value

A tibble containing the original data with additional columns for each principal component score (named PC1, PC2, etc.).

Examples

pca <- tidy_pca(USArrests)
augmented <- augment_pca(pca, USArrests, n_components = 2)

Calculate Cluster Validation Metrics

Description

Comprehensive validation metrics for a clustering result

Usage

calc_validation_metrics(clusters, data = NULL, dist_mat = NULL)

Arguments

Value

A single-row tibble with columns k, min_size, max_size, avg_size, n_noise, and optionally avg_silhouette, min_silhouette (if dist_mat provided; NA for a single cluster), and total_wss (if data provided).

Examples

km <- kmeans(iris[, 1:4], centers = 3, nstart = 25)
d <- dist(iris[, 1:4])
metrics <- calc_validation_metrics(km$cluster, iris[, 1:4], d)

Calculate Within-Cluster Sum of Squares for Different k

Description

Used for elbow method to determine optimal k

Usage

calc_wss(data, max_k = 10, nstart = 25)

Arguments

Value

A tibble with columns k (number of clusters) and tot_withinss (total within-cluster sum of squares).

Examples

wss <- calc_wss(iris[, 1:4], max_k = 6)
plot(wss$k, wss$tot_withinss, type = "b")

Compare Multiple Clustering Results

Description

Compare Multiple Clustering Results

Usage

compare_clusterings(cluster_list, data, dist_mat = NULL)

Arguments

Value

A tibble with one row per clustering method and columns for each validation metric (see calc_validation_metrics), plus a method column identifying the clustering.

Examples

km3 <- kmeans(iris[, 1:4], 3, nstart = 25)$cluster
km4 <- kmeans(iris[, 1:4], 4, nstart = 25)$cluster
compare_clusterings(list(k3 = km3, k4 = km4), iris[, 1:4])

Compare Distance Methods

Description

Compute distances using multiple methods for comparison

Usage

compare_distances(data, methods = c("euclidean", "manhattan", "maximum"))

Arguments

Value

A named list of dist objects, one per method.

Examples

dists <- compare_distances(
  iris[, 1:4], methods = c("euclidean", "manhattan")
)

Create Summary Dashboard

Description

Generate a multi-panel summary of clustering results

Usage

create_cluster_dashboard(
  data,
  cluster_col = "cluster",
  validation_metrics = NULL
)

Arguments

Value

Invisibly returns a named list of the ggplot objects drawn: clusters, the scatter plot, when the data has two numeric columns besides cluster_col; sizes; and metrics, when validation_metrics is given. The combined plot grid is drawn as a side effect via grid.arrange.

Examples

df <- iris[, 1:4]
df$cluster <- kmeans(df, 3)$cluster
create_cluster_dashboard(df)

Explore DBSCAN Parameters

Description

Test multiple eps and minPts combinations

Usage

explore_dbscan_params(data, eps_values, minPts_values)

Arguments

Value

A tibble with columns eps, minPts, n_clusters, n_noise, and prop_noise for each parameter combination.

Examples

params <- explore_dbscan_params(iris[, 1:4],
  eps_values = c(0.3, 0.5, 0.8), minPts_values = c(3, 5))

Filter Rules by Item

Description

Subset rules containing specific items

Usage

filter_rules_by_item(rules_obj, item, where = "both")

Arguments

Value

A tibble of rules containing the specified item in the requested position.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  filter_rules_by_item(res, "whole milk", where = "rhs")
}

Find Related Items

Description

Find items frequently purchased with a given item

Usage

find_related_items(rules_obj, item, min_lift = 1.5, top_n = 10)

Arguments

Value

A tibble of rules involving the specified item, filtered by min_lift and sorted by lift in descending order.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  find_related_items(res, "whole milk", min_lift = 1.5)
}

Get PCA Loadings in Wide Format

Description

Get PCA Loadings in Wide Format

Usage

get_pca_loadings(pca_obj, n_components = NULL)

Arguments

Value

A tibble with one row per variable and one column per principal component, containing the loading values.

Examples

pca <- tidy_pca(USArrests)
get_pca_loadings(pca, n_components = 2)

Get Variance Explained Summary

Description

Get Variance Explained Summary

Usage

get_pca_variance(pca_obj)

Arguments

Value

A tibble with columns component, sdev, variance, prop_variance, and cum_variance.

Examples

pca <- tidy_pca(USArrests)
get_pca_variance(pca)

# The same accessor works on a tl_model() PCA fit
get_pca_variance(tl_model(USArrests, method = "pca"))

Inspect Association Rules

Description

View rules sorted by various quality measures

Usage

inspect_rules(rules_obj, by = "lift", n = 10, decreasing = TRUE)

Arguments

Value

A tibble of the n rules ranked highest (or, with decreasing = FALSE, lowest) by the quality measure by.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  inspect_rules(res, by = "lift", n = 5)
}

Find Optimal Number of Clusters

Description

Use multiple methods to suggest optimal k

Usage

optimal_clusters(data, max_k = 10, methods = c("silhouette", "gap", "wss"))

Arguments

Value

A list of class "optimal_k_results" containing one or more of:

• wss: tibble from calc_wss (if "wss" method used)

• silhouette: tibble from tidy_silhouette_analysis (if "silhouette" method used)

• gap: a tidy_gap object from tidy_gap_stat (if "gap" method used)

Examples

opt <- optimal_clusters(iris[, 1:4], max_k = 6, methods = "wss")

Determine Optimal Number of Clusters for Hierarchical Clustering

Description

Use silhouette or gap statistic to find optimal k

Usage

optimal_hclust_k(hclust_obj, method = "silhouette", max_k = 10)

Arguments

Value

A list containing:

• optimal_k: the recommended number of clusters

• method: the evaluation method used

• values: numeric vector of evaluation scores (for silhouette)

• k_range: integer vector of k values tested (for silhouette)

If method = "gap", returns a tidy_gap object instead.

Examples

hc <- tidy_hclust(USArrests, method = "ward.D2")
opt <- optimal_hclust_k(hc, method = "silhouette", max_k = 6)

Plot EDA results

Description

Plot EDA results

Usage

## S3 method for class 'tidylearn_eda'
plot(x, ...)

Arguments

Value

The input object x, returned invisibly. Called for its side effect of plotting a PCA scatter plot coloured by cluster.

Examples

eda <- tl_explore(iris, response = "Species")
plot(eda)

Plot method for tidylearn models

Description

Plot method for tidylearn models

Usage

## S3 method for class 'tidylearn_model'
plot(x, type = "auto", ...)

Arguments

Value

A ggplot object. The specific plot depends on the model paradigm and type argument.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
plot(model, type = "actual_predicted")

Create Cluster Comparison Plot

Description

Compare multiple clustering results side-by-side

Usage

plot_cluster_comparison(data, cluster_cols, x_col, y_col)

Arguments

Value

The return value of grid.arrange, a gtable drawn as a side effect.

Examples

df <- iris[, 1:4]
df$km3 <- kmeans(df, 3)$cluster
df$km4 <- kmeans(df, 4)$cluster
plot_cluster_comparison(df, c("km3", "km4"), "Sepal.Length", "Sepal.Width")

Plot Cluster Size Distribution

Description

Create bar plot of cluster sizes

Usage

plot_cluster_sizes(clusters, title = "Cluster Size Distribution")

Arguments

Value

A ggplot object.

Examples

clusters <- kmeans(iris[, 1:4], 3)$cluster
plot_cluster_sizes(clusters)

Plot Clusters in 2D Space

Description

Visualize clustering results using first two dimensions or specified dimensions

Usage

plot_clusters(
  data,
  cluster_col = "cluster",
  x_col = NULL,
  y_col = NULL,
  centers = NULL,
  title = "Cluster Plot",
  color_noise_black = TRUE
)

Arguments

Value

A ggplot object.

Examples

km <- tidy_kmeans(iris[, 1:4], k = 3)
clustered <- augment_kmeans(km, iris[, 1:4])
plot_clusters(clustered)

Plot Dendrogram with Cluster Highlights

Description

Enhanced dendrogram with colored cluster rectangles

Usage

plot_dendrogram(
  hclust_obj,
  k = NULL,
  title = "Hierarchical Clustering Dendrogram"
)

Arguments

Value

Invisibly returns the hclust object. The dendrogram is drawn as a side effect.

Examples

hc <- hclust(dist(iris[, 1:4]))
plot_dendrogram(hc, k = 3)

Create Distance Heatmap

Description

Visualize distance matrix as heatmap

Usage

plot_distance_heatmap(
  dist_mat,
  cluster_order = NULL,
  title = "Distance Heatmap"
)

Arguments

Value

A ggplot object.

Examples

d <- dist(iris[1:20, 1:4])
plot_distance_heatmap(d)

Create Elbow Plot for K-Means

Description

Plot total within-cluster sum of squares vs number of clusters

Usage

plot_elbow(wss_data, add_line = FALSE, suggested_k = NULL)

Arguments

Value

A ggplot object.

Examples

wss <- data.frame(k = 2:6, tot_withinss = c(150, 90, 60, 50, 45))
plot_elbow(wss)

Plot Gap Statistic

Description

Plot Gap Statistic

Usage

plot_gap_stat(gap_obj, show_methods = FALSE)

Arguments

Value

A ggplot object.

Examples

gap <- tidy_gap_stat(iris[, 1:4], max_k = 6, B = 10)
plot_gap_stat(gap)

Plot k-NN Distance Plot

Description

Visualize k-NN distances to help choose eps

Usage

plot_knn_dist(data, k = 4, add_suggestion = TRUE, percentile = 0.95)

Arguments

Value

A ggplot object.

Examples

plot_knn_dist(iris[, 1:4], k = 5)

Plot MDS Configuration

Description

Visualize MDS results

Usage

plot_mds(mds_obj, color_by = NULL, label_points = TRUE, dim_x = 1, dim_y = 2)

Arguments

Value

A ggplot object.

Examples

mds <- tidy_mds(USArrests, method = "classical")
plot_mds(mds)

Plot Silhouette Analysis

Description

Plot Silhouette Analysis

Usage

plot_silhouette(sil_obj)

Arguments

Value

A ggplot object.

Examples

km <- kmeans(iris[, 1:4], centers = 3, nstart = 25)
d <- dist(iris[, 1:4])
sil <- tidy_silhouette(km$cluster, d)
plot_silhouette(sil)

Plot Variance Explained (PCA)

Description

Create combined scree plot showing individual and cumulative variance

Usage

plot_variance_explained(variance_tbl, threshold = 0.8)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(iris[, 1:4], method = "pca")
plot_variance_explained(model$fit$variance_explained)

Predict using a tidylearn model

Description

Unified prediction interface for both supervised and unsupervised models

Usage

## S3 method for class 'tidylearn_model'
predict(object, new_data = NULL, type = "response", ...)

Arguments

Value

For supervised models, a tibble with a .pred column; with type = "prob", one column per class instead. It has one row per row of new_data, in order, and zero rows for zero-row new_data. For unsupervised models, the method's natural output: an .obs_id column, the row names of the data predicted on, plus component scores for "pca" and "mds" (as many as the model keeps), or plus a cluster column for the clustering methods.

Unsupervised models differ in whether they can handle new data. "pca" projects it and "kmeans" assigns it to the nearest centre; "pam", "clara", "dbscan", "mds" and "hclust" have no out-of-sample projection and error if new_data is supplied. For hierarchical clustering, cut the tree with tidy_cutree() instead.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
predict(model)
predict(model, new_data = mtcars[1:5, ])

Predict from stratified models

Description

Predict from stratified models

Usage

## S3 method for class 'tidylearn_stratified'
predict(object, new_data = NULL, ...)

Arguments

Value

A tibble of the columns each cluster's model returns for the requested type – .pred by default, one column per class for type = "prob" – and a .cluster column with cluster assignments. Rows of a single-class cluster are predicted as that class, with probability 1.

Examples

models <- tl_stratified_models(mtcars, mpg ~ .,
  cluster_method = "kmeans", k = 2, supervised_method = "linear")
preds <- predict(models)

Predict with transfer learning model

Description

Predict with transfer learning model

Usage

## S3 method for class 'tidylearn_transfer'
predict(object, new_data, ...)

Arguments

Value

A tibble with a .pred column containing predictions.

Examples

model <- tl_transfer_learning(iris, Species ~ .,
  pretrain_method = "pca", supervised_method = "tree")
preds <- predict(model, iris[1:5, ])

Print Method for tidy_apriori

Description

Print Method for tidy_apriori

Usage

## S3 method for class 'tidy_apriori'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  print(res)
}

Print Method for tidy_dbscan

Description

Print Method for tidy_dbscan

Usage

## S3 method for class 'tidy_dbscan'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

db <- tidy_dbscan(iris[, 1:4], eps = 0.5, minPts = 5)
print(db)

Print Method for tidy_gap

Description

Print Method for tidy_gap

Usage

## S3 method for class 'tidy_gap'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

gap <- tidy_gap_stat(iris[, 1:4], max_k = 6, B = 10)
print(gap)

Print Method for tidy_hclust

Description

Print Method for tidy_hclust

Usage

## S3 method for class 'tidy_hclust'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

hc <- tidy_hclust(USArrests, method = "ward.D2")
print(hc)

Print Method for tidy_kmeans

Description

Print Method for tidy_kmeans

Usage

## S3 method for class 'tidy_kmeans'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

km <- tidy_kmeans(iris[, 1:4], k = 3)
print(km)

Print Method for tidy_mds

Description

Print Method for tidy_mds

Usage

## S3 method for class 'tidy_mds'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

mds <- tidy_mds(USArrests, method = "classical")
print(mds)

Print Method for tidy_pam

Description

Print Method for tidy_pam

Usage

## S3 method for class 'tidy_pam'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

pm <- tidy_pam(iris[, 1:4], k = 3)
print(pm)

Print Method for tidy_pca

Description

Print Method for tidy_pca

Usage

## S3 method for class 'tidy_pca'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

pca <- tidy_pca(USArrests)
print(pca)

Print Method for tidy_silhouette

Description

Print Method for tidy_silhouette

Usage

## S3 method for class 'tidy_silhouette'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

km <- kmeans(iris[, 1:4], centers = 3, nstart = 25)
d <- dist(iris[, 1:4])
sil <- tidy_silhouette(km$cluster, d)
print(sil)

Print auto ML results

Description

Print auto ML results

Usage

## S3 method for class 'tidylearn_automl'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

result <- tl_auto_ml(iris, Species ~ .,
  time_budget = 10,
  use_reduction = FALSE,
  use_clustering = FALSE,
  cv_folds = 2)

# The leaderboard, the winner and the metric it was ranked on
print(result)

Print method for tidylearn_compute_advice objects

Description

Print method for tidylearn_compute_advice objects

Usage

## S3 method for class 'tidylearn_compute_advice'
print(x, ...)

Arguments

Value

The input x, invisibly.

Examples

# Runtime, peak memory and cost per tier, before committing to a fit
advice <- tl_compute_advisor("forest", data = iris, formula = Species ~ .)
print(advice)

Print a tidylearn_data object

Description

Print a tidylearn_data object

Usage

## S3 method for class 'tidylearn_data'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

f <- tempfile(fileext = ".csv")
write.csv(iris, f, row.names = FALSE)
d <- tl_read(f)
print(d)
unlink(f)

Print EDA results

Description

Print EDA results

Usage

## S3 method for class 'tidylearn_eda'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

eda <- tl_explore(iris, response = "Species")
print(eda)

Print method for tidylearn_gpu_check objects

Description

Print method for tidylearn_gpu_check objects

Usage

## S3 method for class 'tidylearn_gpu_check'
print(x, ...)

Arguments

Value

The input x, invisibly.

Examples

# Reports no GPU rather than failing on a machine without one
print(tl_check_gpu())

Print method for tidylearn models

Description

Print method for tidylearn models

Usage

## S3 method for class 'tidylearn_model'
print(x, ...)

Arguments

Value

The input object x, returned invisibly.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
print(model)

Print a tidylearn pipeline

Description

Print a tidylearn pipeline

Usage

## S3 method for class 'tidylearn_pipeline'
print(x, ...)

Arguments

Value

The input pipeline object x, returned invisibly.

Examples

pipe <- tl_pipeline(iris, Species ~ .)
print(pipe)

Generate Product Recommendations

Description

Get product recommendations based on basket contents

Usage

recommend_products(rules_obj, basket, top_n = 5, min_confidence = 0.5)

Arguments

Value

A tibble with columns rhs (recommended item), confidence, lift, and support, sorted by lift in descending order. A rule is used when the basket holds its whole left-hand side and none of its right-hand side, and each product is listed once, from its highest-lift rule.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  # The basket has to cover the whole left-hand side of a rule, so a
  # basket of very common items usually matches nothing above the
  # confidence floor
  recommend_products(res, basket = c("flour", "baking powder"))
}

Standardize Data

Description

Center and/or scale numeric variables

Usage

standardize_data(data, center = TRUE, scale = TRUE)

Arguments

Value

A tibble with numeric variables centered and/or scaled as specified; non-numeric columns are returned unchanged. A grouped tibble is standardised within each group, as dplyr::mutate() works on it; a rowwise tibble is standardised over its whole columns, since a single value has no spread. Grouping and rowwise identifier columns are left as they are.

Examples

std <- standardize_data(iris[, 1:4])

Suggest eps Parameter for DBSCAN

Description

Use k-NN distance plot to suggest eps value

Usage

suggest_eps(data, minPts = 5, method = "percentile", percentile = 0.95)

Arguments

Value

A list containing:

• eps: suggested epsilon value

• knn_distances: full tibble of k-NN distances

• method: method used

Examples

eps_info <- suggest_eps(iris, minPts = 5)
eps_info$eps

Summarize Association Rules

Description

Get summary statistics about rules

Usage

summarize_rules(rules_obj)

Arguments

Value

A list with n_rules and summary statistics (min, max, mean, median) for support, confidence, and lift.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  res <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)
  summarize_rules(res)
}

Summary method for tidylearn models

Description

Summary method for tidylearn models

Usage

## S3 method for class 'tidylearn_model'
summary(object, ...)

Arguments

Value

The input object, returned invisibly. Called for its side effect of printing model summary and training performance.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
summary(model)

Summarize a tidylearn pipeline

Description

Summarize a tidylearn pipeline

Usage

## S3 method for class 'tidylearn_pipeline'
summary(object, ...)

Arguments

Value

The input pipeline object, returned invisibly. Called for its side effect of printing detailed pipeline and model results.

Examples

pipe <- tl_pipeline(iris, Species ~ .)
summary(pipe)

Tidy Apriori Algorithm

Description

Mine association rules using the Apriori algorithm with tidy output

Usage

tidy_apriori(
  transactions,
  support = 0.01,
  confidence = 0.5,
  minlen = 2,
  maxlen = 10,
  target = "rules",
  control = list(verbose = FALSE),
  ...
)

Arguments

Value

A list of class "tidy_apriori" containing:

• rules_tbl: tibble of rules, as tidy_rules returns it, or NULL for an itemset target

• rules: original arules object, rules or itemsets

• parameters: parameters used

• n_rules: number of rules, or of itemsets for an itemset target

• itemsets_tbl: for an itemset target only, a tibble with itemset_id, itemset (its label), size, the quality measures, and items, a list column holding each itemset's items

Examples

if (requireNamespace("arules", quietly = TRUE)) {
data("Groceries", package = "arules")

# Basic apriori
rules <- tidy_apriori(Groceries, support = 0.001, confidence = 0.5)

# Access rules
rules$rules_tbl
}

Tidy CLARA (Clustering Large Applications)

Description

Performs CLARA clustering (scalable version of PAM)

Usage

tidy_clara(data, k, metric = "euclidean", samples = 50, sampsize = NULL, ...)

Arguments

Value

A list of class "tidy_clara" containing:

• clusters: tibble with observation IDs and cluster assignments

• medoids: tibble of medoid values

• silhouette_avg: average silhouette width

• model: original clara object

Examples

# CLARA for large datasets
large_data <- iris[rep(1:nrow(iris), 10), 1:4]
clara_result <- tidy_clara(large_data, k = 3, samples = 50)
print(clara_result)

Cut Hierarchical Clustering Tree

Description

Cut dendrogram to obtain cluster assignments

Usage

tidy_cutree(hclust_obj, k = NULL, h = NULL)

Arguments

Value

A tibble with columns .obs_id (observation identifier) and cluster (integer cluster assignment).

Examples

hc <- tidy_hclust(USArrests, method = "ward.D2")
clusters <- tidy_cutree(hc, k = 3)

Tidy DBSCAN Clustering

Description

Performs density-based clustering with tidy output

Usage

tidy_dbscan(data, eps, minPts = 5, cols = NULL, distance = "euclidean")

Arguments

Value

A list of class "tidy_dbscan" containing:

• clusters: tibble with observation IDs, cluster assignments (0 = noise), and the logical flags is_noise and is_core

• summary: tibble with each cluster's size and number of core points

• n_clusters: number of clusters (excluding noise)

• n_noise: number of noise points

• eps, minPts: the parameters used

• model: original dbscan object

Examples

# Basic DBSCAN
db_result <- tidy_dbscan(iris, eps = 0.5, minPts = 5)

# With suggested eps from k-NN distance plot
eps_suggestion <- suggest_eps(iris, minPts = 5)
db_result <- tidy_dbscan(iris, eps = eps_suggestion$eps, minPts = 5)

Plot Dendrogram

Description

Create dendrogram visualization

Usage

tidy_dendrogram(hclust_obj, k = NULL, hang = 0.01, cex = 0.7)

Arguments

Value

The hclust object, returned invisibly. The dendrogram is plotted as a side effect.

Examples

hc <- tidy_hclust(USArrests, method = "ward.D2")
tidy_dendrogram(hc, k = 3)

Tidy Distance Matrix Computation

Description

Compute distance matrices with tidy output

Usage

tidy_dist(data, method = "euclidean", cols = NULL, ...)

Arguments

Value

A dist object containing the computed distance matrix.

Examples

d <- tidy_dist(iris[, 1:4], method = "euclidean")

Tidy Gap Statistic

Description

Compute gap statistic for determining optimal number of clusters

Usage

tidy_gap_stat(data, FUN_cluster = NULL, max_k = 10, B = 50, nstart = 25)

Arguments

Value

A list of class "tidy_gap" containing:

• gap_data: tibble with gap statistics for each k

• k_firstSEmax: optimal k via maxSE's firstSEmax method, the smallest k within one standard error of the first local maximum (most conservative)

• k_globalmax: optimal k via the globalmax method, the k with the largest gap (most liberal)

• k_firstmax: optimal k via the firstmax method, the first local maximum of the gap

• recommended_k: recommended k (uses firstSEmax)

• model: the clusGap result

Examples

gap <- tidy_gap_stat(iris[, 1:4], max_k = 6, B = 10)
gap$recommended_k

Gower Distance Calculation

Description

Computes Gower distance for mixed data types (numeric, factor, ordered)

Usage

tidy_gower(data, weights = NULL)

Arguments

Details

Gower distance handles mixed data types:

• Numeric: range-normalized Manhattan distance

• Factor/Character: 0 if same, 1 if different

• Ordered: treated as numeric ranks

Formula: d_ij = sum(w_k * d_ijk) / sum(w_k) where d_ijk is the dissimilarity for variable k between obs i and j

Value

A dist object containing Gower distances, with the method attribute set to "gower". A pair of rows with no variable observed in both has no defined distance and is NA, as in daisy.

Examples

# Create example data with mixed types
car_data <- data.frame(
  horsepower = c(130, 250, 180),
  weight = c(1200, 1650, 1420),
  color = factor(c("red", "black", "blue"))
)

# Compute Gower distance
gower_dist <- tidy_gower(car_data)

Tidy Hierarchical Clustering

Description

Performs hierarchical clustering with tidy output

Usage

tidy_hclust(data, method = "average", distance = "euclidean", cols = NULL)

Arguments

Value

A list of class "tidy_hclust" containing:

• model: hclust object

• dist: distance matrix used

• method: linkage method used

• distance_method: distance metric used

• data: original data (for plotting)

Examples

# Basic hierarchical clustering
hc_result <- tidy_hclust(USArrests, method = "average")

# With specific distance
hc_result <- tidy_hclust(mtcars, method = "complete", distance = "manhattan")

Tidy K-Means Clustering

Description

Performs k-means clustering with tidy output

Usage

tidy_kmeans(
  data,
  k,
  cols = NULL,
  nstart = 25,
  iter_max = 100,
  algorithm = "Hartigan-Wong"
)

Arguments

Value

A list of class "tidy_kmeans" containing:

• clusters: tibble with observation IDs and cluster assignments

• centers: tibble of cluster centers

• metrics: tibble with clustering quality metrics

• sizes: integer vector of cluster sizes

• model: original kmeans object

Examples

# Basic k-means
km_result <- tidy_kmeans(iris, k = 3)

Compute k-NN Distances

Description

Calculate distances to k-th nearest neighbor for each point

Usage

tidy_knn_dist(data, k = 4, cols = NULL)

Arguments

Value

A tibble with columns .obs_id (observation identifier), knn_dist (distance to k-th nearest neighbor), and rank (rank of the k-NN distance).

Examples

knn <- tidy_knn_dist(iris[, 1:4], k = 5)

Tidy Multidimensional Scaling

Description

Unified interface for MDS methods with tidy output

Usage

tidy_mds(data, method = "classical", ndim = 2, distance = "euclidean", ...)

Arguments

Value

A list of class "tidy_mds" containing:

• config: tibble of MDS configuration (coordinates)

• stress: goodness-of-fit measure (if applicable)

• method: character string of method used

• model: original model object

Examples

# Classical MDS
mds_result <- tidy_mds(eurodist, method = "classical")
print(mds_result)

Classical (Metric) MDS

Description

Performs classical multidimensional scaling using cmdscale()

Usage

tidy_mds_classical(dist_mat, ndim = 2, add_rownames = TRUE)

Arguments

Value

A list of class "tidy_mds" containing:

• config: tibble of MDS coordinates

• stress: NA (not applicable for classical MDS)

• gof: goodness-of-fit (proportion of variance retained)

• eigenvalues: numeric vector of eigenvalues

• method: "Classical MDS"

• model: the cmdscale result

Examples

d <- dist(USArrests)
mds <- tidy_mds_classical(d)
print(mds)

Kruskal's Non-metric MDS

Description

Performs Kruskal's isoMDS

Usage

tidy_mds_kruskal(dist_mat, ndim = 2, ...)

Arguments

Value

A list of class "tidy_mds" containing:

• config: tibble of MDS coordinates

• stress: Kruskal stress value

• method: "Kruskal's isoMDS"

• model: the isoMDS result

Examples

d <- dist(USArrests)
mds <- tidy_mds_kruskal(d)

Sammon Mapping

Description

Performs Sammon's non-linear mapping

Usage

tidy_mds_sammon(dist_mat, ndim = 2, ...)

Arguments

Value

A list of class "tidy_mds" containing:

• config: tibble of MDS coordinates

• stress: Sammon stress value

• method: "Sammon Mapping"

• model: the sammon result

Examples

d <- dist(USArrests)
mds <- tidy_mds_sammon(d)

SMACOF MDS (Metric or Non-metric)

Description

Performs MDS using SMACOF algorithm from the smacof package

Usage

tidy_mds_smacof(dist_mat, ndim = 2, type = "ratio", ...)

Arguments

Value

A list of class "tidy_mds" containing:

• config: tibble of MDS coordinates

• stress: stress value from the SMACOF algorithm

• method: character string describing the MDS type

• model: the mds result

Examples

d <- dist(USArrests)
mds <- tidy_mds_smacof(d, type = "ratio")

Tidy PAM (Partitioning Around Medoids)

Description

Performs PAM clustering with tidy output

Usage

tidy_pam(data, k, metric = "euclidean", cols = NULL, ...)

Arguments

Value

A list of class "tidy_pam" containing:

• clusters: tibble with observation IDs and cluster assignments

• medoids: tibble with one row per cluster: the medoid's row position in the data (medoid_index, an integer) and, unless data was a dist object, its values

• silhouette_avg: average silhouette width

• silhouette_data: the silhouette information pam() returns (its silinfo)

• model: original pam object

Examples

# PAM with Euclidean distance
pam_result <- tidy_pam(iris, k = 3)

# PAM with Gower distance for mixed data
pam_result <- tidy_pam(mtcars, k = 3, metric = "gower")

Tidy Principal Component Analysis

Description

Performs PCA on a dataset using tidyverse principles. Returns a tidy list containing scores, loadings, variance explained, and the original model.

Usage

tidy_pca(data, cols = NULL, scale = TRUE, center = TRUE, method = "prcomp")

Arguments

Value

A list of class "tidy_pca" containing:

• scores: tibble of PC scores with observation identifiers

• loadings: tibble of variable loadings in long format

• variance: tibble of variance explained by each PC

• model: the original prcomp/princomp object

• settings: list of scale, center, method used

Examples

# Basic PCA
pca_result <- tidy_pca(USArrests)


# Access components
pca_result$scores
pca_result$loadings
pca_result$variance

Create PCA Biplot

Description

Visualize both observations and variables in PC space

Usage

tidy_pca_biplot(
  pca_obj,
  pc_x = 1,
  pc_y = 2,
  color_by = NULL,
  arrow_scale = 1,
  label_obs = FALSE,
  label_vars = TRUE
)

Arguments

Value

A ggplot object.

Examples

pca <- tidy_pca(USArrests)
tidy_pca_biplot(pca)

Create PCA Scree Plot

Description

Visualize variance explained by each principal component

Usage

tidy_pca_screeplot(pca_obj, type = "proportion", add_line = TRUE)

Arguments

Value

A ggplot object.

Examples

pca <- tidy_pca(USArrests)
tidy_pca_screeplot(pca)

Convert Association Rules to Tidy Tibble

Description

Convert Association Rules to Tidy Tibble

Usage

tidy_rules(rules)

Arguments

Value

A tibble with columns rule_id, lhs, rhs, the quality measures (e.g., support, confidence, lift), and the list columns lhs_items and rhs_items, each rule's items on that side as a character vector. The lhs and rhs labels are for reading; the helpers that match items read the lists, since an item name can hold the comma that separates items in a label. An empty rule set gives a zero-row tibble with the same columns.

Examples

if (requireNamespace("arules", quietly = TRUE)) {
  data("Groceries", package = "arules")
  rules_obj <- arules::apriori(Groceries,
    parameter = list(supp = 0.001, conf = 0.5))
  rules_tbl <- tidy_rules(rules_obj)
}

Tidy Silhouette Analysis

Description

Compute silhouette statistics for cluster validation

Usage

tidy_silhouette(clusters, dist_mat)

Arguments

Value

A list of class "tidy_silhouette" containing:

• silhouette_data: tibble with silhouette values for each observation

• avg_width: average silhouette width

• cluster_avg: average silhouette width by cluster

Examples

km <- kmeans(iris[, 1:4], centers = 3, nstart = 25)
d <- dist(iris[, 1:4])
sil <- tidy_silhouette(km$cluster, d)

Silhouette Analysis Across Multiple k Values

Description

Silhouette Analysis Across Multiple k Values

Usage

tidy_silhouette_analysis(
  data,
  max_k = 10,
  method = "kmeans",
  nstart = 25,
  dist_method = "euclidean",
  linkage_method = "average"
)

Arguments

Value

A tibble with columns k and avg_sil_width. The "optimal_k" attribute contains the k with the highest average silhouette width.

Examples

sil_analysis <- tidy_silhouette_analysis(iris[, 1:4], max_k = 6)

Classification Functions for tidylearn

Description

Logistic regression and classification metrics functionality

Cloud data-egress consent for tidylearn

Description

The consent gate that stands between a compute = "cloud" call and any training data leaving the user's machine.

Cost controls for tidylearn cloud compute

Description

Bounding what a cloud fit can cost, and keeping in-flight jobs visible.

Cloud endpoint resolution for tidylearn

Description

Resolving and validating the Modal Web Function endpoint that compute = "cloud" submits to.

Model serialisation for tidylearn cloud compute

Description

Converting a fitted tidylearn model to bytes and back, so it can cross the boundary between a remote worker and the caller's R session.

Coefficient Inference for tidylearn

Description

Coefficients, standard errors and confidence intervals as a tibble, for the methods that have them. tl_table_coefficients() formats the same numbers as a gt table.

tidylearn: A Unified Tidy Interface to R's Machine Learning Ecosystem

Description

Core functionality for tidylearn. This package provides a unified tidyverse-compatible interface to established R machine learning packages including glmnet, randomForest, xgboost, e1071, rpart, gbm, nnet, cluster, and dbscan. The underlying algorithms are unchanged - tidylearn wraps them with consistent function signatures, tidy tibble output, and unified ggplot2-based visualization. Supervised models keep the wrapped object at model$fit; unsupervised ones put it at model$fit$model, alongside the tidied components.

Deep Learning for tidylearn

Description

Deep learning functionality using Keras/TensorFlow

Advanced Diagnostics Functions for tidylearn

Description

Functions for advanced model diagnostics, assumption checking, and outlier detection

Interaction Analysis Functions for tidylearn

Description

Functions for testing, visualizing, and analyzing interactions

Metrics Functionality for tidylearn

Description

Functions for calculating model evaluation metrics

Model Selection Functions for tidylearn

Description

Functions for stepwise model selection, cross-validation, and hyperparameter tuning

Neural Networks for tidylearn

Description

Neural network functionality for classification and regression

Model Pipeline Functions for tidylearn

Description

Functions for creating end-to-end model pipelines

Data Reading Functions for tidylearn

Description

Functions for reading data from diverse sources into tidy tidylearn_data objects. The main dispatcher tl_read() auto-detects the format from the file extension and routes to the appropriate reader. All readers return a tidylearn_data object, which is a tibble subclass carrying metadata about the data source.

Details

Supported file formats:

• CSV: .csv files via readr (with base R fallback), and .txt files named directly

• TSV: .tsv files via readr (with base R fallback)

• Excel: .xls, .xlsx, .xlsm files via readxl

• Parquet: .parquet files via nanoparquet

• JSON: .json files, and newline-delimited .ndjson files, via jsonlite

• RDS: .rds files via base readRDS()

• RData: .rdata, .rda files via base load()

CSV and TSV files compressed with gzip, bzip2 or xz (data.csv.gz) are recognised by the extension under the compression one.

Supported databases (via DBI):

• SQLite: .sqlite, .db files via RSQLite

• PostgreSQL: via RPostgres

• MySQL/MariaDB: via RMariaDB

• BigQuery: bigquery://project/dataset URIs via bigrquery

Supported cloud/API sources:

• S3: s3:// URIs via paws.storage

• GitHub: raw file download from repositories

• Kaggle: dataset download via Kaggle CLI

A file:// URL is read as the local path it names. Other web URLs, and URLs with any other scheme such as ftp://, are not read; download the file first.

Multi-file reading:

• Multiple paths: pass a character vector to tl_read()

• Directories: tl_read_dir() scans for data files with optional pattern/format filtering and recursive scanning

• Zip archives: tl_read_zip() extracts and reads from .zip files

When combining multiple files, a source_file column is added to identify the origin of each row: the file's path below the directory or archive it came from, or, for paths given directly, below the deepest folder they share. Files in one folder are labelled by their bare names.

Directory and archive scans read the extensions listed above except .txt, which in a folder is as likely to hold notes as data. Name a .txt file directly, or select it with pattern, to read it.

Data Reading Backends for tidylearn

Description

Backend readers for databases and cloud/API sources. All backends are optional dependencies checked at call time via tl_check_packages().

Details

Database backends (via DBI):

• SQLite: via RSQLite

• PostgreSQL: via RPostgres

• MySQL/MariaDB: via RMariaDB

• BigQuery: via bigrquery

Cloud/API backends:

• S3: via paws.storage

• GitHub: via base download.file()

• Kaggle: via Kaggle CLI

Regression Functions for tidylearn

Description

Linear and polynomial regression functionality

Regularization Functions for tidylearn

Description

Ridge, Lasso, and Elastic Net regularization functionality

Support Vector Machines for tidylearn

Description

SVM functionality for classification and regression

Table Functions for tidylearn

Description

Functions for producing formatted gt tables from tidylearn models. Provides a parallel interface to the plot functions: tl_table(model, type) dispatches to the appropriate table formatter based on model type. Requires the gt package (suggested dependency).

Tree-based Methods for tidylearn

Description

Decision trees, random forests, and boosting functionality

Hyperparameter Tuning Functions for tidylearn

Description

Functions for automatic hyperparameter tuning and selection

Visualization Functions for tidylearn

Description

General visualization functions for tidylearn models

High-Level Workflows for Common Machine Learning Patterns

Description

Functions providing end-to-end workflows that showcase tidylearn's ability to seamlessly combine multiple learning paradigms

XGBoost Functions for tidylearn

Description

XGBoost-specific implementation for gradient boosting

Cluster-Based Features

Description

Add cluster assignments as features for supervised learning. This semi-supervised approach can capture non-linear patterns.

Usage

tl_add_cluster_features(data, response = NULL, method = "kmeans", ...)

Arguments

Value

The original data frame with an additional factor column named cluster_<method> containing cluster assignments. The fitted cluster model is stored as an attribute "cluster_model".

Examples

# Add cluster features before supervised learning
data_with_clusters <- tl_add_cluster_features(iris, response = "Species",
                                                method = "kmeans", k = 3)
model <- tl_model(data_with_clusters, Species ~ ., method = "forest")

Anomaly-Aware Supervised Learning

Description

Detect outliers using DBSCAN or other methods, then optionally remove them or down-weight them before supervised learning.

Usage

tl_anomaly_aware(
  data,
  formula,
  response,
  anomaly_method = "dbscan",
  action = "flag",
  supervised_method = "tree",
  ...
)

Arguments

Details

DBSCAN runs on the predictors the formula names, on their own scale: its eps and minPts (defaults 0.5 and 5, passed through ...) are a distance and a count in those units. If every row comes out as noise the call stops, since no normal data would be left to model.

Value

A tidylearn model object with additional class "tidylearn_anomaly_aware". The model includes an anomaly_info element with anomaly_model, is_anomaly (logical vector), n_anomalies, and action.

Examples

model <- tl_anomaly_aware(iris, Species ~ ., response = "Species",
                           anomaly_method = "dbscan", action = "flag")

Find important interactions automatically

Description

Find important interactions automatically

Usage

tl_auto_interactions(
  data,
  formula,
  top_n = 3,
  min_r2_change = 0.01,
  max_p_value = 0.05,
  exclude_vars = NULL
)

Arguments

Value

A tidylearn model object (class "tidylearn_model") fitted with the top significant interaction terms added to the formula. The interaction test results and selected interactions are stored as attributes "interaction_tests" and "selected_interactions", data frames in the layout tl_test_interactions returns. Both are present when no interaction is added, with no rows where there is nothing to report.

Examples

model <- tl_auto_interactions(mtcars, mpg ~ wt + hp + cyl, top_n = 2)

Auto ML: Automated Machine Learning Workflow

Description

Automatically explores multiple modeling approaches including dimensionality reduction, clustering, and various supervised methods. Returns the best performing model, scored by cross-validation where the time budget allows.

Usage

tl_auto_ml(
  data,
  formula,
  task = "auto",
  use_reduction = TRUE,
  use_clustering = TRUE,
  time_budget = 300,
  cv_folds = 5,
  metric = NULL
)

Arguments

Details

The PCA and cluster variants are built from the formula's predictors only, so a column the formula leaves out (y ~ . - id) reaches no candidate. The cluster variants add the cluster assignment to the formula's terms.

Value

A list with class "tidylearn_automl" containing:

best_model

The best tidylearn model object

models

Named list of all successfully trained models

leaderboard

Tibble ranking models by the chosen metric, with columns model, score and evaluation. The evaluation column records how each score was obtained – "cv" for cross-validated, "train" for training-set metrics, which are optimistic. Scores of different kinds are not directly comparable; a mixed leaderboard means the budget ran short of cross-validating every model.

task

Detected or specified task type

metric

Metric used for ranking

runtime

Total elapsed time as a difftime object

Examples

# Quick run with fast models only (< 30s budget skips forest/SVM/XGBoost)
result <- tl_auto_ml(iris, Species ~ .,
  time_budget = 10,
  use_reduction = FALSE,
  use_clustering = FALSE,
  cv_folds = 2)
result$leaderboard

Calculate classification metrics

Description

Scores predicted classes, and optionally class probabilities, against observed classes.

Usage

tl_calc_classification_metrics(
  actuals,
  predicted,
  predicted_probs = NULL,
  metrics = c("accuracy", "precision", "recall", "f1", "auc"),
  thresholds = NULL,
  ...
)

Arguments

Details

The classes, in order, are the levels of predicted when it is a factor of two or more levels – which is how predict() returns them, in the model's order – and otherwise the classes present in actuals. Any other class found in actuals or predicted follows them. For two classes the second is the positive class. tl_evaluate instead leaves out rows of a class the model was never trained on, since it knows the model's classes.

A row missing its observed class, its prediction or one of its probabilities is dropped before anything is computed, so every metric describes the same rows. With no row left – actuals empty, or every row incomplete – there is nothing to score, and it is an error of class tidylearn_no_scored_rows.

Value

A tibble with columns metric (character) and value (numeric), one row per requested metric. For more than two classes, "auc" is followed by an auc_<class> row for each class.

"auc" and "pr_auc" need at least two classes among the scored rows, and are NA, with a warning, when there is only one. A class with no scored row has no one-vs-rest area: its auc_<class> row is NA, the averages cover the other classes, and a warning names it.

With thresholds, six rows per cut-off follow – for a cut-off of 0.5, accuracy_t0.5, precision_t0.5, recall_t0.5, f1_t0.5, f2_t0.5 and f0.5_t0.5 – and the tibble gains a threshold column, NA on the other rows.

Examples

model <- tl_model(iris, Species ~ ., method = "forest")
preds <- predict(model)
tl_calc_classification_metrics(iris$Species, preds$.pred)

Calculate the area under the precision-recall curve

Description

Reads the area off a curve ROCR built, and agrees with yardstick::pr_auc(). ROCR's curve starts at recall 0, where nothing is yet called positive and precision is 0/0. The area has to start there too, at precision 1 as yardstick's does: integrating from the first finite point lost everything before it, so a perfect ranking of 5 positives in 20 scored 0.8, a tree on two iris species 0.07, and constant scores left no area at all.

Usage

tl_calculate_pr_auc(perf)

Arguments

Value

The area under the precision-recall curve, or NA when the curve has fewer than two points

Check model assumptions

Description

Check model assumptions

Usage

tl_check_assumptions(model, test = TRUE, verbose = TRUE)

Arguments

Value

A named list with one element per assumption checked (linearity, independence, homoscedasticity, normality, multicollinearity, outliers), each containing assumption (character label), check (logical, NA when the test could not decide, or NULL when no test was run), details (character), and recommendation (character). An additional overall element summarises the number of assumptions checked, violated, and satisfied; an NA or NULL check counts as neither.

Logistic regression assumes neither normal residuals nor a constant variance, so for a logistic model normality and homoscedasticity have a NULL check and a note saying so. For a factor, multicollinearity is judged on GVIF^(1/Df), the generalised VIF on the scale of an ordinary one.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
tl_check_assumptions(model)

Detect local GPU availability for tidylearn methods

Description

Reports whether the local machine has a CUDA-capable GPU and which tidylearn backends (xgboost, keras, tensorflow) are positioned to use it. Detection is intentionally cheap: it parses nvidia-smi output, giving up with a warning if nvidia-smi has not answered within 10 seconds, and reads which R packages are installed from the library without loading them, so it neither starts Python nor fits a model. A backend reported as gpu_likely_works = TRUE may still fall back to CPU if it was not compiled or configured with CUDA support — confirm with a small real fit before relying on it for production workloads.

Usage

tl_check_gpu(verbose = FALSE)

Arguments

Details

Apple MPS (Metal Performance Shaders) is intentionally not detected in this iteration; see the issue tracker for the MPS feature request.

Value

An object of class tidylearn_gpu_check: a list with components any_gpu (logical), cuda (driver info list with driver_present, device_count, device_names, driver_version), backends (per-backend status list each containing installed, gpu_likely_works, notes), and messages (character vector). A print() method is provided.

Examples

# Safe to call anywhere: probes for nvidia-smi on the PATH and checks
# which backend packages are installed. Reports no GPU rather than
# failing when there isn't one.
gpu <- tl_check_gpu()
gpu$any_gpu

if (gpu$any_gpu && gpu$backends$xgboost$gpu_likely_works) {
  # xgboost with GPU is worth trying for this workload
}

Allow an additional host for cloud uploads in this R session

Description

tidylearn uploads training data only to Modal's own hosts (⁠*.modal.run⁠, ⁠*.modal.com⁠). Modal customers serving Web Functions from a custom domain can add that domain here.

Usage

tl_cloud_allow_host(host)

Arguments

Details

This widens the set of destinations your data may be sent to, so it is deliberately a per-session call rather than an option or an environment variable: a shared .Rprofile or an inherited environment should not be able to add a destination without you writing the call. Additions are never persisted and are forgotten when the session ends.

Hosts match themselves and their subdomains. Adding "fits.example.com" accepts ⁠https://fits.example.com⁠ and ⁠https://a.fits.example.com⁠, and nothing else.

Give the endpoint's full host name. A name of fewer than three labels, such as "example.com" or "co.uk", is refused: two labels can be a public suffix, under which anyone can register a site, and allowing one would admit all of them.

Value

The full allowlist after the change, invisibly.

See Also

tl_cloud_allowed_hosts(), and T9 in system.file("security/threat-model.md", package = "tidylearn").

Examples

tl_cloud_allow_host("fits.example.com")
tl_cloud_allowed_hosts()
tl_cloud_allow_host(NULL)

Hosts tidylearn will currently upload to

Description

Modal's own hosts, plus anything added with tl_cloud_allow_host() during this session.

Usage

tl_cloud_allowed_hosts()

Value

A character vector of host names.

See Also

tl_cloud_allow_host()

Examples

tl_cloud_allowed_hosts()

Grant or revoke cloud upload consent for this R session

Description

Fitting with compute = "cloud" uploads your training data to your own Modal account, which is a third party. tidylearn will not do that without explicit consent on every call.

Usage

tl_cloud_consent(consent = TRUE)

Arguments

Details

There are two ways to give it. Pass confirm_upload = TRUE to each tl_model() call, or call tl_cloud_consent() once to opt in for the rest of the session. The session lock exists for batch and non-interactive work, where a per-call argument is repetitive.

The lock is not persisted. It is forgotten when the R session ends, and it is never written to disk. Revoke it early with tl_cloud_consent(FALSE).

tidylearn never prompts interactively for consent, so scripts, CI and Rscript behave the same as an interactive session.

Value

The previous consent state, invisibly.

See Also

The full contract is in system.file("security/threat-model.md", package = "tidylearn").

Examples

# Opt in for the session, then revoke.
old <- tl_cloud_consent(TRUE)
tl_cloud_consent(FALSE)

Cloud jobs submitted in this R session

Description

Every cloud submission is recorded here so that no job runs invisibly. A job disappears from this list when its result is collected or it is cancelled.

Usage

tl_cloud_jobs()

Details

A submitted job runs on Modal whatever this R session does. If the session ends while a job is still listed here, that job keeps running and keeps billing until it finishes or its timeout kills it — this list cannot survive the session, but the timeout does.

Value

A tibble with one row per in-flight job: call_id, method, submitted_at, timeout_seconds and worst_case_cost. Zero rows when nothing is in flight.

Examples

# Nothing in flight in a fresh session
tl_cloud_jobs()

Model coefficients as a tibble

Description

Returns the coefficients of a fitted tidylearn model as a tibble, with standard errors, test statistics, p-values and – on request – confidence intervals. Available for "linear", "polynomial", "logistic", "ridge", "lasso" and "elastic_net". Other methods have no coefficients; use tl_table_importance for those.

Usage

tl_coefficients(
  model,
  conf_int = FALSE,
  level = 0.95,
  exponentiate = FALSE,
  lambda = "1se"
)

Arguments

Details

Intervals are Wald intervals, computed from the same standard errors as the statistic and p_value columns beside them, so the interval and the p-value always agree about whether zero is excluded. For "linear" and "polynomial" that means t quantiles on the residual degrees of freedom, which is exactly what confint returns for an lm. For "logistic" it means z quantiles, which is what the reported z statistic implies but not what confint() gives – that profiles the likelihood, which is the better interval when the sample is small or a class is nearly separated. Call stats::confint(model$fit) when you want it.

A rank-deficient fit – two perfectly collinear predictors, or an interaction of factors with a combination no row has – cannot estimate every term. Those terms are returned with an NA estimate rather than dropped, so a term named in the formula never disappears from the output without saying so.

Value

A tibble, one row per model term. For "linear", "polynomial" and "logistic": term, estimate, std_error, statistic, p_value, plus conf_low and conf_high when conf_int = TRUE. For regularised methods: term, estimate and the lambda the estimate came from – glmnet reports no standard errors, so there is nothing to test or bound. A multiclass regularised model has one set of coefficients per class, so its rows are led by a class column; exponentiate is not available for it, because glmnet's multinomial coefficients are not relative to a reference class.

See Also

tl_table_coefficients for the same numbers as a formatted table.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
tl_coefficients(model)
tl_coefficients(model, conf_int = TRUE)

# Odds ratios from a logistic fit
am_data <- transform(mtcars, am = factor(am))
model <- tl_model(am_data, am ~ wt, method = "logistic")
tl_coefficients(model, conf_int = TRUE, exponentiate = TRUE)

Compare models using cross-validation

Description

Each model is refitted on every fold from its formula, method and fitting arguments. A model a refit would not reproduce is refused: one built by tl_semisupervised or tl_anomaly_aware, or one of tl_auto_ml's candidates fitted on features it engineered.

Usage

tl_compare_cv(data, models, folds = 5, metrics = NULL, ...)

Arguments

Value

A list with two elements:

$fold_metrics

A data frame with columns metric, value, fold, and model containing per-fold results for every model. A metric undefined on a fold – "auc" on a fold holding one class – is NA there, and so is every metric of a fold none of whose rows can be scored, with a warning naming the fold.

$summary

A data frame with columns model, metric, mean_value, sd_value, min_value, and max_value summarizing cross-validation performance over the folds with a value. A metric with no value on any fold is NA throughout.

Examples

m1 <- tl_model(mtcars, mpg ~ wt, method = "linear")
m2 <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
cv <- tl_compare_cv(mtcars, list(simple = m1, full = m2), folds = 3)
cv$summary

Compare models from a pipeline

Description

Compare models from a pipeline

Usage

tl_compare_pipeline_models(pipeline, metrics = NULL)

Arguments

Value

A ggplot object showing a faceted bar chart comparing metric values across models, with the best model highlighted.

Examples

pipe <- tl_pipeline(iris, Species ~ .,
  models = list(
    tree = list(method = "tree"),
    forest = list(method = "forest", ntree = 100)
  ),
  evaluation = list(validation = "cv", cv_folds = 3))
pipe <- tl_run_pipeline(pipe, verbose = FALSE)

tl_compare_pipeline_models(pipe)

# Restrict the comparison to one metric
tl_compare_pipeline_models(pipe, metrics = "accuracy")

Advise on the best compute tier for a tidylearn fit

Description

Estimates runtime and feasibility on local CPU, local GPU (when available and applicable), and cloud GPU (stubbed until cloud integration lands), then returns a structured recommendation. Useful before kicking off a long fit — call this first to see whether the problem is laptop-sized, GPU-sized, or cloud-sized.

Usage

tl_compute_advisor(x, ...)

## S3 method for class 'character'
tl_compute_advisor(
  x,
  data,
  formula = NULL,
  hyperparams = list(),
  gpu_check = NULL,
  ...
)

## S3 method for class 'tidylearn_supervised'
tl_compute_advisor(
  x,
  data = NULL,
  formula = NULL,
  hyperparams = list(),
  gpu_check = NULL,
  ...
)

## Default S3 method:
tl_compute_advisor(x, ...)

Arguments

Details

Estimates are deliberately rough — order-of-magnitude, not bills. Per-method scaling constants are calibrated against typical hardware and will be off by 2-3x in either direction for any individual job. Treat the recommendation as a starting point, not gospel.

Value

An object of class tidylearn_compute_advice containing problem, local_cpu, local_gpu, cloud, recommendation, and reasoning. A print() method is provided.

Examples

# Estimating from a method name needs neither a GPU nor the backend
# package -- it is arithmetic over the problem dimensions
advice <- tl_compute_advisor("xgboost", iris, Species ~ .,
                             hyperparams = list(nrounds = 1000))
advice$recommendation
print(advice)


# Dispatching on a fitted model requires the backend to be installed.
# CRAN asks examples to use at most two threads.
if (requireNamespace("xgboost", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "xgboost", nthread = 2)
  tl_compute_advisor(model)
}

Cross-validation for tidylearn models

Description

Each fold's model is scored with tl_evaluate, so the response is read as that function reads it: a transformed left-hand side on its own scale, and classes against the fold model's.

Usage

tl_cv(data, formula, method, folds = 5, metrics = NULL, transform = NULL, ...)

Arguments

Value

A list with two elements:

$folds

A list of per-fold evaluation tibbles, each with metric and value columns.

$summary

A tibble with columns metric, mean, and sd summarizing performance across folds. A metric undefined on a fold – auc on a fold holding one class – is NA there and left out of the mean and sd. So is every metric of a fold none of whose rows can be scored, with a warning giving the reason. A metric with no value on any fold has NA mean and sd.

Examples

cv <- tl_cv(mtcars, mpg ~ wt + hp, method = "linear", folds = 3)
cv$summary

Create interactive visualization dashboard for a model

Description

Create interactive visualization dashboard for a model

Usage

tl_dashboard(model, new_data = NULL, ...)

Arguments

Value

A shinyApp object.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
app <- tl_dashboard(model)

Create pre-defined parameter grids for common models

Description

Create pre-defined parameter grids for common models

Usage

tl_default_param_grid(method, size = "medium", is_classification = TRUE)

Arguments

Value

A named list of parameter values suitable for passing to tl_tune_grid or tl_tune_random. Each element is a numeric or character vector of candidate values for that hyperparameter, or for "deep"'s hidden_layers a list of layer-size vectors. The grid is built without the data, so a "forest" mtry can exceed the number of predictors; the tuners cap it. "polynomial" tunes degree. The "xgboost" grids draw on the values tl_tune_xgboost searches by default, and add nrounds, which that function chooses by early stopping and tl_tune_grid has to tune. "linear" and "logistic" have no tuneable hyperparameter and return an empty list with a warning, as does an unknown method.

Examples

grid <- tl_default_param_grid("tree", size = "small")
grid <- tl_default_param_grid("forest", size = "medium")
grid <- tl_default_param_grid("svm", is_classification = FALSE)

Detect outliers in the data

Description

Detect outliers in the data

Usage

tl_detect_outliers(
  data,
  variables = NULL,
  method = "iqr",
  threshold = NULL,
  plot = TRUE
)

Arguments

Value

A list with outlier detection results:

method

The detection method used (character).

method_name

Human-readable method name (character).

threshold

The threshold value used (numeric).

threshold_label

Formatted threshold description (character).

outlier_flags

A logical matrix (observations x variables), NA where a value is missing. For "cook" and "mahalanobis" a row's flags are the same in every column, and NA when any of its values is missing.

any_outlier

Logical vector indicating if each observation is an outlier in any variable. Missing flags are ignored, so a row with no flag at all is FALSE.

outlier_counts

List with total, by_variable, and by_observation counts.

outlier_indices

Integer vector of outlier row indices.

plot

A ggplot object, or NULL if plot = FALSE.

Examples

tl_detect_outliers(mtcars, variables = c("mpg", "wt"), method = "iqr")

Create a comprehensive diagnostic dashboard

Description

Create a comprehensive diagnostic dashboard

Usage

tl_diagnostic_dashboard(
  model,
  include_influence = TRUE,
  include_assumptions = TRUE,
  include_performance = TRUE,
  arrange_plots = "grid"
)

Arguments

Value

A grid.arrange object (a grob) containing the arranged diagnostic plots.

Examples

if (requireNamespace("gridExtra")) {
  model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
  tl_diagnostic_dashboard(model)
}

Evaluate a tidylearn model

Description

Scores a supervised model's predictions against the observed response.

Usage

tl_evaluate(object, new_data = NULL, metrics = NULL, ...)

Arguments

Details

The observed response is the formula's left-hand side evaluated on the scored rows, so a model of log(mpg) is scored against log(mpg), the scale it predicts on. For classification, the observed classes are read against the classes the model was trained on, whose second is the positive class; rows of a class the model never saw are left out with a warning. Rows missing the response or a prediction are dropped. tl_calc_classification_metrics describes "auc" and "pr_auc" when the scored rows hold a single class or lack one.

With no row left to score – new_data has no rows, or every row is dropped – it is an error of class tidylearn_no_scored_rows, naming the reason. tl_cv catches that class and leaves the fold out.

Value

A tibble with columns metric (character) and value (numeric), containing one row per requested metric, and for "auc" on more than two classes an auc_<class> row per class as well. An unsupervised model has no response to score against and returns the single row metric = "completed", value = 1.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
tl_evaluate(model)
tl_evaluate(model, metrics = c("rmse", "mape"))

Evaluate metrics at different thresholds

Description

Evaluate metrics at different thresholds

Usage

tl_evaluate_thresholds(actuals, probs, thresholds, pos_class)

Arguments

Value

A tibble of metrics at different thresholds

Positive-class argument for yardstick binary metrics

Description

tidylearn's positive class is the second factor level. yardstick's default is the first, and its event_level argument only applies to the binary case – passing it for a multiclass problem warns.

Usage

tl_event_level_args(actuals)

Arguments

Value

A list to splice into a yardstick call: event_level = "second" for a two-level factor, empty otherwise

Exploratory Data Analysis Workflow

Description

Comprehensive EDA combining unsupervised learning techniques to understand data structure before modeling

Usage

tl_explore(data, response = NULL, max_components = 5, k_range = 2:6)

Arguments

Value

A list with class "tidylearn_eda" containing:

data

The original data frame.

response

The response variable name, or NULL.

pca

The fitted PCA model, keeping the first max_components components, as prcomp(rank. = max_components) would.

optimal_k

List with optimal cluster count results.

kmeans

The fitted k-means model.

hclust

The fitted hierarchical clustering model.

summary

List with n_obs, n_vars, n_components (the number kept), and best_k.

Examples

eda <- tl_explore(iris, response = "Species")
plot(eda)

Extract importance from a tree-based model

Description

Extract importance from a tree-based model

Usage

tl_extract_importance(model)

Arguments

Value

A data frame with feature importance values, rescaled so the largest is 100. Empty for a tree with no splits.

Fit a gradient boosting model

Description

Fit a gradient boosting model

Usage

tl_fit_boost(
  data,
  formula,
  is_classification = FALSE,
  n.trees = 100,
  interaction.depth = 3,
  shrinkage = 0.1,
  n.minobsinnode = 10,
  cv.folds = 0,
  ...
)

Arguments

Details

The distribution follows the response: "gaussian" for regression, "bernoulli" for two classes and "multinomial" for more. gbm describes its multinomial distribution as currently broken, kept only for backwards compatibility, and warns to that effect on every multiclass fit. For three or more classes, method = "forest" or method = "xgboost" are the better supported choices.

Value

A fitted gradient boosting model

Fit a deep learning model

Description

Fit a deep learning model

Usage

tl_fit_deep(
  data,
  formula,
  is_classification = FALSE,
  hidden_layers = c(32, 16),
  activation = "relu",
  dropout = 0.2,
  epochs = 30,
  batch_size = 32,
  validation_split = 0.2,
  learning_rate = NULL,
  verbose = 0,
  ...,
  compute = "cpu"
)

Arguments

Value

A fitted deep learning model

Fit an Elastic Net regression model

Description

Fit an Elastic Net regression model

Usage

tl_fit_elastic_net(
  data,
  formula,
  is_classification = FALSE,
  alpha = 0.5,
  lambda = NULL,
  cv_folds = 5,
  ...
)

Arguments

Value

A fitted Elastic Net regression model

Fit a random forest model

Description

Fit a random forest model

Usage

tl_fit_forest(
  data,
  formula,
  is_classification = FALSE,
  ntree = 500,
  mtry = NULL,
  importance = TRUE,
  ...
)

Arguments

Value

A fitted random forest model

Fit a Lasso regression model

Description

Fit a Lasso regression model

Usage

tl_fit_lasso(
  data,
  formula,
  is_classification = FALSE,
  alpha = 1,
  lambda = NULL,
  cv_folds = 5,
  ...
)

Arguments

Value

A fitted Lasso regression model

Fit a linear regression model

Description

Fit a linear regression model

Usage

tl_fit_linear(data, formula, ...)

Arguments

Value

A fitted linear regression model

Fit a logistic regression model

Description

Fit a logistic regression model

Usage

tl_fit_logistic(data, formula, ...)

Arguments

Value

A fitted logistic regression model

Fit a neural network model

Description

Fit a neural network model

Usage

tl_fit_nn(
  data,
  formula,
  is_classification = FALSE,
  size = 5,
  decay = 0,
  maxit = 100,
  trace = FALSE,
  ...
)

Arguments

Value

A fitted neural network model

Fit a polynomial regression model

Description

Fit a polynomial regression model

Usage

tl_fit_polynomial(data, formula, degree = 2, ...)

Arguments

Value

A fitted polynomial regression model

Fit a regularized regression model

Description

Fits Ridge, Lasso, or Elastic Net regularization.

Usage

tl_fit_regularized(
  data,
  formula,
  is_classification = FALSE,
  alpha = 0,
  lambda = NULL,
  cv_folds = 5,
  ...,
  weights = NULL,
  foldid = NULL,
  subset = NULL,
  offset = NULL
)

Arguments

Value

A fitted regularized regression model

Fit a Ridge regression model

Description

Fit a Ridge regression model

Usage

tl_fit_ridge(
  data,
  formula,
  is_classification = FALSE,
  alpha = 0,
  lambda = NULL,
  cv_folds = 5,
  ...
)

Arguments

Value

A fitted Ridge regression model

Fit a support vector machine model

Description

Fit a support vector machine model

Usage

tl_fit_svm(
  data,
  formula,
  is_classification = FALSE,
  kernel = "radial",
  cost = 1,
  gamma = NULL,
  degree = 3,
  tune = FALSE,
  tune_folds = 5,
  ...
)

Arguments

Value

A fitted SVM model

Fit a decision tree model

Description

Fit a decision tree model

Usage

tl_fit_tree(
  data,
  formula,
  is_classification = FALSE,
  cp = 0.01,
  minsplit = 20,
  maxdepth = 30,
  ...
)

Arguments

Value

A fitted decision tree model

Fit an XGBoost model

Description

Fit an XGBoost model

Usage

tl_fit_xgboost(
  data,
  formula,
  is_classification = FALSE,
  nrounds = 100,
  max_depth = 6,
  eta = 0.3,
  subsample = 1,
  colsample_bytree = 1,
  min_child_weight = 1,
  gamma = 0,
  alpha = 0,
  lambda = 1,
  early_stopping_rounds = NULL,
  nthread = NULL,
  verbose = 0,
  ...,
  compute = "cpu"
)

Arguments

Value

A fitted XGBoost model

Get the best model from a pipeline

Description

Get the best model from a pipeline

Usage

tl_get_best_model(pipeline)

Arguments

Value

The best tidylearn_model object from the pipeline, selected by the metric specified in evaluation$best_metric. The model was fitted on the preprocessed training data, so under the default preprocessing it expects predictors imputed and standardised the same way. Predict through tl_predict_pipeline, which replays that preprocessing on raw rows; predict() on the model itself reads raw values as if they were already standardised, and returns wrong predictions without a warning.

Examples

pipe <- tl_pipeline(iris, Species ~ .,
  models = list(tree = list(method = "tree")),
  evaluation = list(metrics = "accuracy", validation = "cv",
    cv_folds = 2, best_metric = "accuracy"))
pipe <- tl_run_pipeline(pipe, verbose = FALSE)
best <- tl_get_best_model(pipe)
best$spec$method

# Predict through the pipeline, which preprocesses the new rows first
tl_predict_pipeline(pipe, iris[c(1, 51, 101), ])

Extract importance from a regularized regression model

Description

Extract importance from a regularized regression model

Usage

tl_get_importance_regularized(model, lambda = "1se")

Arguments

Value

A data frame with feature importance values: each coefficient's absolute value times its predictor's standard deviation, so the ranking does not depend on units, rescaled to a maximum of 100. For a multiclass model a predictor takes its largest value across classes.

Calculate influence measures for a linear model

Description

Calculate influence measures for a linear model

Usage

tl_influence_measures(
  model,
  threshold_cook = NULL,
  threshold_leverage = NULL,
  threshold_dffits = NULL
)

Arguments

Value

A data frame with one row per observation containing influence measures: cooks_distance, leverage, dffits, std_residual, stud_residual, boolean flags for each threshold (is_cook_influential, is_leverage_influential, is_dffits_influential, is_outlier), per-coefficient dfbetas_* columns, and an overall is_influential flag. Threshold values are stored as attributes.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
tl_influence_measures(model)

Calculate partial effects based on a model with interactions

Description

Calculate partial effects based on a model with interactions

Usage

tl_interaction_effects(model, var, by_var, at_values = NULL, intervals = TRUE)

Arguments

Value

For numeric var: a list with effects (data frame of predicted values across the variable range for each value of by_var) and slopes (data frame with the slope of var at each value of by_var). For categorical var: a data frame of predicted values at each factor level for each level of by_var. A numeric by_var is evaluated at its quartiles; quartiles that tie are evaluated once, with a label naming each quartile they stand for, such as "Q0/Q25". A factor, character or logical variable is categorical, and is evaluated at the values the data holds: a level no row uses, and a missing value, are left out. A factor is returned as a factor with the model's levels.

fit, lower, upper and slope are on the response scale whatever intervals is set to. For a classification model that is the predicted probability of the second class, so the response must have two classes. slope is the slope of a straight line fitted to fit across the range of var, so for a non-linear link it is an average rate of change over that range. A model variable named fit, by_value or by_label, or with intervals lower or upper, would be overwritten by these columns and is refused.

slopes$slope_se is the standard error of a straight line fitted to the prediction grid, not the sampling uncertainty of the marginal effect. For a linear model the grid is exactly linear in var, so this is near zero by construction and should not be read as a precise estimate. Use summary(model$fit) for inference on the interaction coefficient itself.

Examples

model <- tl_model(mtcars, mpg ~ wt * hp, method = "linear")

# How the effect of weight changes across horsepower
effects <- tl_interaction_effects(model, var = "wt", by_var = "hp")
head(effects$effects)
effects$slopes

# slopes$slope_se describes the fitted grid, not the sampling
# uncertainty of the marginal effect -- for that, read the coefficient
summary(model$fit)$coefficients["wt:hp", ]

Load a pipeline from disk

Description

Load a pipeline from disk

Usage

tl_load_pipeline(file)

Arguments

Value

A tidylearn_pipeline object previously saved with tl_save_pipeline.

Examples

pipe <- tl_pipeline(iris, Species ~ .)
f <- tempfile(fileext = ".rds")
tl_save_pipeline(pipe, f)
pipe2 <- tl_load_pipeline(f)

Create a tidylearn model

Description

Unified interface for creating machine learning models by wrapping established R packages. This function dispatches to the appropriate underlying package based on the method.

Usage

tl_model(data, formula = NULL, method = "linear", ..., compute = "cpu")

Arguments

Details

The wrapped packages include: stats (lm, glm, prcomp, kmeans, hclust), glmnet, randomForest, xgboost, gbm, e1071, nnet, rpart, cluster, and dbscan. The underlying algorithms are unchanged - this function provides a consistent interface and returns tidy output.

For a supervised method, model$fit is the object the wrapped function returned. An unsupervised method returns tidied components as well, so the wrapped object sits at model$fit$model and model$fit is the list holding both.

For classification, the response is reduced to the classes it actually contains: subsetting a data frame keeps every factor level, and a level no row uses would otherwise be reported as a class, given its own (zero) probability column, and counted when deciding whether the problem is binary. The fit is unaffected.

Whether a supervised model is a classification or a regression is decided by the response the formula computes, so factor(cyl) ~ wt is a classification even though cyl is numeric. A factor or text response is a classification. A logical response is a regression for every method but "logistic" – with "linear", a linear probability model – so write factor(y) ~ ... to classify it.

A categorical predictor stored as text, as tl_read() returns it, is made a factor before the fit and stored as one in $data, so every method treats it as a category. At predict(), categorical columns in new data are read against the levels seen in training: new data may hold only some of them, and a level the model was not trained on is an error that names the column.

Value

A tidylearn_model object (S3) containing the fitted model ($fit, or $fit$model for an unsupervised method), model specification ($spec), and training data ($data). update() and step() on $fit refit on the training rows and weights, whatever is in the calling environment. The object also inherits from a method-specific class (e.g., tidylearn_linear) and a paradigm class (tidylearn_supervised or tidylearn_unsupervised).

Method arguments

Arguments in ... are passed to the function the method wraps, except for these, which tidylearn takes itself:

"polynomial"

degree (default 2). Each numeric main effect is replaced by poly(term, degree, raw = TRUE) and the result fitted with lm(). A numeric term is one that computes a numeric vector, such as wt or log(wt), or a one-column matrix, such as scale(wt). One that is also part of an interaction keeps its own term and gains I(x^2) up to I(x^degree), so the interaction is coded as written. Factor and other non-numeric terms, interactions, I() terms, bases such as poly() or a spline's, the response as written, an offset() and a removed intercept are kept as they are.

"ridge", "lasso", "elastic_net"

alpha, glmnet's mixing parameter (by default 0, 1 and 0.5); lambda, a single penalty to fit at, a sequence of penalties for glmnet::cv.glmnet() to choose from, or NULL (the default) to let it choose its own; and cv_folds (default 5), the number of folds for that cross-validation, which takes the place of glmnet's nfolds. predict() uses the lambda.1se penalty. tidylearn sets x, y, family and nfolds itself and refuses them, along with any argument glmnet does not take.

"svm"

tune (default FALSE) and tune_folds (default 5), to choose cost by cross-validation before the fit, with gamma for a non-linear kernel and degree for a polynomial one.

"deep"

hidden_layers, activation, dropout, epochs, batch_size, validation_split and learning_rate.

"pca"

scale and center (both TRUE).

"mds"

mds_method, the variant: "classical" (the default, stats::cmdscale()), "metric" or "nonmetric" (smacof), or "sammon" or "kruskal" (MASS). k, or its alias ndim, is the number of dimensions (default 2).

"kmeans", "pam", "clara"

k, the number of clusters (default 3); for "pam", metric as well (default "euclidean").

"hclust"

hclust_method, the linkage: "average" (the default), "ward.D", "ward.D2", "single", "complete", "mcquitty", "median" or "centroid"; and distance (default "euclidean").

"dbscan"

eps (default 0.5), minPts (default 5) and distance (default "euclidean").

Some defaults differ from the wrapped function's: "forest" computes importance (importance = TRUE), "boost" grows trees of interaction.depth = 3, and "nn" fits size = 5 hidden units with trace = FALSE.

weights and subset take values, one per row of data (such as weights = data$w), not column names. A subset is applied before the fit, and $data holds only the rows it selects. Case weights are applied by every supervised method except "svm" and "deep", which refuse them. An offset, written as offset() in the formula, is applied by "linear", "polynomial" and "logistic"; the other methods refuse one, because their predict() would not add it back.

Examples

# Classification -> wraps randomForest::randomForest()
model <- tl_model(iris, Species ~ ., method = "forest")
model$fit  # Access the raw randomForest object

# Regression -> wraps stats::lm()
model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
model$fit  # Access the raw lm object

# PCA -> wraps stats::prcomp()
model <- tl_model(iris, ~ ., method = "pca")
model$fit$model  # The raw prcomp object, alongside tidied components

# Clustering -> wraps stats::kmeans()
model <- tl_model(iris, method = "kmeans", k = 3)
model$fit$model  # The raw kmeans object

Create a modeling pipeline

Description

Create a modeling pipeline

Usage

tl_pipeline(
  data,
  formula,
  preprocessing = NULL,
  models = NULL,
  evaluation = NULL,
  ...
)

Arguments

Value

A tidylearn_pipeline object (S3 list) with components $formula, $data, $preprocessing, $models, $evaluation, and $results (initially NULL; populated after tl_run_pipeline).

Examples

pipe <- tl_pipeline(iris, Species ~ .,
  models = list(tree = list(method = "tree")))
print(pipe)

Plot actual vs predicted values for a regression model

Description

Plot actual vs predicted values for a regression model

Usage

tl_plot_actual_predicted(model, new_data = NULL, ...)

Arguments

Value

A ggplot object

Plot calibration curve for a classification model

Description

Plot calibration curve for a classification model

Usage

tl_plot_calibration(model, new_data = NULL, bins = 10, ...)

Arguments

Value

A ggplot object with calibration curve

Plot confusion matrix for a classification model

Description

Plot confusion matrix for a classification model

Usage

tl_plot_confusion(model, new_data = NULL, ...)

Arguments

Value

A ggplot object with confusion matrix

Plot comparison of cross-validation results

Description

Plot comparison of cross-validation results

Usage

tl_plot_cv_comparison(cv_results, metrics = NULL)

Arguments

Value

A ggplot object showing boxplots of cross-validation metric distributions for each model.

Examples

m1 <- tl_model(mtcars, mpg ~ wt, method = "linear")
m2 <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
cv <- tl_compare_cv(mtcars, list(simple = m1, full = m2), folds = 3)
tl_plot_cv_comparison(cv)

Plot cross-validation results

Description

Plot cross-validation results

Usage

tl_plot_cv_results(cv_results, metrics = NULL)

Arguments

Value

A ggplot object.

Examples

cv <- tl_cv(mtcars, mpg ~ wt + hp, method = "linear", folds = 5)
tl_plot_cv_results(cv)

# One metric rather than every one the folds scored
tl_plot_cv_results(cv, metrics = "rmse")

Plot deep learning model architecture

Description

Plot deep learning model architecture

Usage

tl_plot_deep_architecture(model, ...)

Arguments

Value

NULL, invisibly. Called for its side effect: keras draws the architecture diagram on the current graphics device, or writes it to to_file. keras renders it through the Python packages pydot and graphviz, and errors saying so when they are not installed.

Examples

## Not run: 
if (requireNamespace("keras", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "deep", epochs = 5)
  tl_plot_deep_architecture(model)
}

## End(Not run)

Plot deep learning model training history

Description

Plot deep learning model training history

Usage

tl_plot_deep_history(model, metrics = c("loss", "val_loss"), ...)

Arguments

Value

A ggplot object.

Examples

## Not run: 
if (requireNamespace("keras", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "deep", epochs = 5)
  tl_plot_deep_history(model)
}

## End(Not run)

Plot diagnostics for a regression model

Description

Plot diagnostics for a regression model

Usage

tl_plot_diagnostics(model, which = 1:4, ...)

Arguments

Value

A ggplot object (or list of ggplot objects)

Plot gain chart for a classification model

Description

Plot gain chart for a classification model

Usage

tl_plot_gain(model, new_data = NULL, bins = 10, ...)

Arguments

Value

A ggplot object.

Examples

iris_bin <- iris[iris$Species != "setosa", ]
iris_bin$Species <- factor(iris_bin$Species)
model <- tl_model(iris_bin, Species ~ ., method = "logistic")
tl_plot_gain(model)

Plot variable importance for tree-based models

Description

Plot variable importance for tree-based models

Usage

tl_plot_importance(model, top_n = 20, ...)

Arguments

Value

A ggplot object

Plot feature importance across multiple models

Description

Each model's importance is rescaled on its own: its largest value becomes 100, or, when no value is positive (a forest's permutation importance can be negative throughout), its largest magnitude becomes -100. A factor predictor appears once, under its own name, for every model: the largest of its design columns stands for it where a method ranks those columns separately (ridge, lasso, elastic net and xgboost). A predictor a model was given but did not use scores zero for that model; one it was never given has no bar for it. Tree, forest and boost models are given the variables of an interaction such as wt:hp rather than the interaction itself, so it has no bar for them. Features are ranked on their mean importance over the models that were given them.

Usage

tl_plot_importance_comparison(..., top_n = 10, names = NULL)

Arguments

Value

A ggplot object.

Examples

m1 <- tl_model(iris, Sepal.Length ~ ., method = "forest")
m2 <- tl_model(iris, Sepal.Length ~ ., method = "boost")
tl_plot_importance_comparison(m1, m2, names = c("Forest", "Boost"))

Plot variable importance for a regularized model

Description

Plot variable importance for a regularized model

Usage

tl_plot_importance_regularized(model, lambda = "1se", top_n = 20, ...)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(mtcars, mpg ~ ., method = "lasso")
tl_plot_importance_regularized(model)

Plot influence diagnostics

Description

Plot influence diagnostics

Usage

tl_plot_influence(
  model,
  plot_type = "cook",
  threshold_cook = NULL,
  threshold_leverage = NULL,
  threshold_dffits = NULL,
  n_labels = 3,
  label_size = 3
)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
tl_plot_influence(model, plot_type = "cook")

Plot interaction effects

Description

Plot interaction effects

Usage

tl_plot_interaction(
  model,
  var1,
  var2,
  n_points = 100,
  fixed_values = NULL,
  confidence = TRUE,
  ...
)

Arguments

Value

A ggplot object. Two numeric variables are drawn as a filled contour of the prediction; a numeric and a categorical variable as one line per category; two categorical variables as dodged bars. A factor, character or logical variable is categorical, and only the values the data holds are drawn. For a classification model the prediction is the probability of the second class, so the response must have two classes. The plot's data holds the prediction in a column named prediction, and a band in .lower and .upper, so a model variable with one of those names is refused.

Examples

model <- tl_model(mtcars, mpg ~ wt * hp, method = "linear")

# Two numeric variables are drawn as a filled contour over both ranges
tl_plot_interaction(model, var1 = "wt", var2 = "hp")

# A numeric by categorical interaction is drawn as one line per level,
# each with a confidence band
am_model <- tl_model(transform(mtcars, am = factor(am)), mpg ~ wt * am,
  method = "linear")
tl_plot_interaction(am_model, var1 = "wt", var2 = "am")

# Coarser grid, no band
tl_plot_interaction(am_model, var1 = "wt", var2 = "am",
  n_points = 20, confidence = FALSE)

Create confidence and prediction interval plots

Description

Create confidence and prediction interval plots

Usage

tl_plot_intervals(model, new_data = NULL, level = 0.95, ...)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(mtcars, mpg ~ wt, method = "linear")
tl_plot_intervals(model)

Plot lift chart for a classification model

Description

Plot lift chart for a classification model

Usage

tl_plot_lift(model, new_data = NULL, bins = 10, ...)

Arguments

Value

A ggplot object.

Examples

iris_bin <- iris[iris$Species != "setosa", ]
iris_bin$Species <- factor(iris_bin$Species)
model <- tl_model(iris_bin, Species ~ ., method = "logistic")
tl_plot_lift(model)

Plot a supervised tidylearn model

Description

Dispatches to the appropriate plotting function based on model type and requested plot type.

Usage

tl_plot_model(model, type = "auto", ...)

Arguments

Value

A ggplot2 object (invisibly for base-graphics plots)

Plot model comparison

Description

Plot model comparison

Usage

tl_plot_model_comparison(..., new_data = NULL, metrics = NULL, names = NULL)

Arguments

Value

A ggplot object.

Examples

m1 <- tl_model(mtcars, mpg ~ wt + hp, method = "linear")
m2 <- tl_model(mtcars, mpg ~ wt + hp, method = "lasso")
tl_plot_model_comparison(m1, m2, names = c("Linear", "Lasso"))

Plot neural network architecture

Description

Plot neural network architecture

Usage

tl_plot_nn_architecture(model, ...)

Arguments

Value

The return value of plotnet, called for its side effect of drawing the network diagram, or NULL if the NeuralNetTools package is not installed.

Examples

if (requireNamespace("NeuralNetTools", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "nn", size = 3)
  tl_plot_nn_architecture(model)
}

Plot a neural network tuning grid

Description

Draws the size-by-decay grid as a heatmap of cross-validated error.

Usage

tl_plot_nn_tuning(model, ...)

Arguments

Value

A ggplot object.

Examples

tuned <- tl_tune_nn(iris, Species ~ .,
  is_classification = TRUE,
  sizes = c(2, 5), decays = c(0, 0.01), folds = 3)

# The tuning result itself, not tuned$model
tl_plot_nn_tuning(tuned)

Plot partial dependence for tree-based models

Description

Plot partial dependence for tree-based models

Usage

tl_plot_partial_dependence(model, var, n.pts = 20, ...)

Arguments

Value

A ggplot object. Its data has a var_value column and the mean prediction over the model's training rows, y, at each value. For classification, y is a mean class probability and a class column says which class: the positive class (the second level) alone for a two-class model, and every class, one line each, for more.

Examples

model <- tl_model(mtcars, mpg ~ ., method = "forest")
tl_plot_partial_dependence(model, var = "wt")

Plot precision-recall curve for a classification model

Description

Plot precision-recall curve for a classification model

Usage

tl_plot_precision_recall(model, new_data = NULL, ...)

Arguments

Value

A ggplot object with precision-recall curve

Plot cross-validation results for a regularized model

Description

Shows the cross-validation error as a function of lambda for ridge, lasso, or elastic net models fitted with cv.glmnet.

Usage

tl_plot_regularization_cv(model, ...)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(mtcars, mpg ~ ., method = "ridge")
tl_plot_regularization_cv(model)

Plot regularization path for a regularized model

Description

Plot regularization path for a regularized model

Usage

tl_plot_regularization_path(model, label_n = 5, ...)

Arguments

Value

A ggplot object.

Examples

model <- tl_model(mtcars, mpg ~ ., method = "lasso")
tl_plot_regularization_path(model)

Plot residuals for a regression model

Description

Plot residuals for a regression model

Usage

tl_plot_residuals(model, type = "fitted", ...)

Arguments

Value

A ggplot object

Plot ROC curve for a classification model

Description

Plot ROC curve for a classification model

Usage

tl_plot_roc(model, new_data = NULL, ...)

Arguments

Value

A ggplot object with ROC curve

Plot SVM decision boundary

Description

Plot SVM decision boundary

Usage

tl_plot_svm_boundary(model, x_var = NULL, y_var = NULL, grid_size = 100, ...)

Arguments

Value

A ggplot object. The other predictors are held at their mean, or their most frequent level. A two-class model fitted with probabilities also gets the 0.5 probability contour.

Examples

if (requireNamespace("e1071", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "svm")
  tl_plot_svm_boundary(model,
    x_var = "Sepal.Length", y_var = "Sepal.Width")
}

Plot SVM tuning results

Description

Plot SVM tuning results

Usage

tl_plot_svm_tuning(model, ...)

Arguments

Value

A ggplot object.

Examples

if (requireNamespace("e1071", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "svm",
    kernel = "linear", tune = TRUE, tune_folds = 2)
  tl_plot_svm_tuning(model)
}

Plot a decision tree

Description

Plot a decision tree

Usage

tl_plot_tree(model, ...)

Arguments

Value

The return value of rpart.plot, called for its side effect of drawing the tree.

Examples

model <- tl_model(iris, Species ~ ., method = "tree")
tl_plot_tree(model)

Plot hyperparameter tuning results

Description

Plot hyperparameter tuning results

Usage

tl_plot_tuning_results(
  model,
  top_n = 5,
  param1 = NULL,
  param2 = NULL,
  plot_type = "scatter"
)

Arguments

Details

A parameter whose candidates are not single values, such as hidden_layers = list(c(10), c(20, 10)) or a parms list, is drawn as a categorical one, each value labelled as the verbose messages print it. The importance of a numeric parameter is the absolute correlation of its values with the score; that of a categorical one is eta squared from a one-way ANOVA of the score, and 0 when the sets that were scored all share one value.

Value

A ggplot object.

Examples

model <- tl_tune_grid(iris, Species ~ ., method = "tree",
  param_grid = list(cp = c(0.01, 0.1), minsplit = c(10, 20)),
  folds = 2, verbose = FALSE)
tl_plot_tuning_results(model)

Plot an unsupervised tidylearn model

Description

Dispatches to the appropriate plotting function based on the unsupervised model method.

Usage

tl_plot_unsupervised(model, type = "auto", ...)

Arguments

Value

A ggplot2 object or invisible result

Plot feature importance for an XGBoost model

Description

Plot feature importance for an XGBoost model

Usage

tl_plot_xgboost_importance(model, top_n = 10, importance_type = "gain", ...)

Arguments

Value

A ggplot object. Its data holds the top_n features and their importance, relative to the most important feature's.

Examples

if (requireNamespace("xgboost", quietly = TRUE)) {
  model <- tl_model(mtcars, mpg ~ ., method = "xgboost", nthread = 2)
  tl_plot_xgboost_importance(model)
}

Plot SHAP dependence for a specific feature

Description

Plot SHAP dependence for a specific feature

Usage

tl_plot_xgboost_shap_dependence(
  model,
  feature,
  interaction_feature = NULL,
  data = NULL,
  n_samples = 100
)

Arguments

Value

A ggplot object. A multiclass model is drawn one panel per class, from that class's SHAP values.

Examples

if (requireNamespace("xgboost", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "xgboost", nrounds = 10,
    nthread = 2)

  # One panel per class
  tl_plot_xgboost_shap_dependence(model, feature = "Petal.Length")

  # Colour the points by a second feature to read the interaction
  tl_plot_xgboost_shap_dependence(model,
    feature = "Petal.Length",
    interaction_feature = "Petal.Width")
}

Plot SHAP summary for XGBoost model

Description

Plot SHAP summary for XGBoost model

Usage

tl_plot_xgboost_shap_summary(model, data = NULL, top_n = 10, n_samples = 100)

Arguments

Value

A ggplot object. Features are ranked by mean absolute SHAP value; a multiclass model is drawn one panel per class.

Examples

if (requireNamespace("xgboost", quietly = TRUE)) {
  model <- tl_model(mtcars, mpg ~ ., method = "xgboost", nthread = 2)
  tl_plot_xgboost_shap_summary(model, n_samples = 20)
}

Plot XGBoost tree visualization

Description

Plot XGBoost tree visualization

Usage

tl_plot_xgboost_tree(model, tree_index = 0, ...)

Arguments

Value

The return value of xgb.plot.tree, a tree diagram rendered via the DiagrammeR package.

Examples

if (requireNamespace("xgboost", quietly = TRUE) &&
    requireNamespace("DiagrammeR", quietly = TRUE)) {
  model <- tl_model(iris, Species ~ ., method = "xgboost", nrounds = 10,
    nthread = 2)

  # tree_index is zero-based, so this is the first tree
  tl_plot_xgboost_tree(model, tree_index = 0)
}

Predict using a gradient boosting model

Description

Predict using a gradient boosting model

Usage

tl_predict_boost(model, new_data, type = "response", n.trees = NULL, ...)

Arguments

Value

Predictions

Predict using a deep learning model

Description

Predict using a deep learning model

Usage

tl_predict_deep(model, new_data, type = "response", ...)

Arguments

Value

Predictions

Predict using a random forest model

Description

Predict using a random forest model

Usage

tl_predict_forest(model, new_data, type = "response", ...)

Arguments

Value

Predictions

Predict using a logistic regression model

Description

Predict using a logistic regression model

Usage

tl_predict_logistic(model, new_data, type = "prob", ...)

Arguments

Value

Predictions

Predict using a neural network model

Description

Predict using a neural network model

Usage

tl_predict_nn(model, new_data, type = "response", ...)

Arguments

Value

Predictions

Make predictions using a pipeline

Description

Make predictions using a pipeline

Usage

tl_predict_pipeline(
  pipeline,
  new_data,
  type = "response",
  model_name = NULL,
  ...
)

Arguments

Value

A tibble with a .pred column containing predictions from the selected (or best) pipeline model, after applying the same preprocessing steps used during training.

Examples

train <- iris[c(1:40, 51:90, 101:140), ]
test <- iris[c(41:50, 91:100, 141:150), ]

pipe <- tl_pipeline(train, Species ~ .,
  models = list(
    tree = list(method = "tree"),
    forest = list(method = "forest", ntree = 100)
  ),
  evaluation = list(validation = "cv", cv_folds = 3))
pipe <- tl_run_pipeline(pipe, verbose = FALSE)

# The best model, with the preprocessing learned on the training rows
tl_predict_pipeline(pipe, test)

# Or a named candidate instead of the winner
tl_predict_pipeline(pipe, test, model_name = "tree")

Predict using a support vector machine model

Description

Predict using a support vector machine model

Usage

tl_predict_svm(model, new_data, type = "response", ...)

Arguments

Value

Predictions

Predict using a decision tree model

Description

Predict using a decision tree model

Usage

tl_predict_tree(model, new_data, type = "response", ...)

Arguments

Value

Predictions

Predict using an XGBoost model

Description

Predict using an XGBoost model

Usage

tl_predict_xgboost(
  model,
  new_data,
  type = "response",
  iterationrange = NULL,
  ntreelimit = NULL,
  ...
)

Arguments

Value

Predictions

Data Preprocessing for tidylearn

Description

Unified preprocessing functions that work with both supervised and unsupervised workflows Prepare Data for Machine Learning

Usage

tl_prepare_data(
  data,
  formula = NULL,
  impute_method = "mean",
  scale_method = "standardize",
  encode_categorical = TRUE,
  remove_zero_variance = TRUE,
  remove_correlated = FALSE,
  correlation_cutoff = 0.95
)

Arguments

Details

Comprehensive preprocessing pipeline including imputation, scaling, encoding, and feature engineering

The statistics are learned from, and applied to, the data passed in. Preparing a whole dataset and then splitting it lets the test rows shape the imputation values and scaling their own scores are measured against. To evaluate a model, split first, or use tl_pipeline, which learns its preprocessing inside each resampling fold.

Value

A list with components:

data

The processed data frame.

original_data

The original unprocessed data frame.

preprocessing_steps

A record of each step applied (imputation values, encoding maps, scaling parameters, etc.). It is for inspection: no function applies it to new data.

formula

The formula passed in (or NULL).

Examples

processed <- tl_prepare_data(iris, Species ~ ., scale_method = "standardize")
model <- tl_model(processed$data, Species ~ ., method = "tree")

Read data from diverse sources

Description

Auto-detects the data format from the file extension or source pattern and dispatches to the appropriate reader. All readers return a tidylearn_data object, which is a tibble subclass carrying metadata about the data source.

Usage

tl_read(source, ..., format = NULL, .quiet = FALSE)

Arguments