Package 'tidylearn'

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)

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)

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)

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)

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)

Description

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)

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")

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])

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")
)

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)

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))

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")
}

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)
}

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)

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"))

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)
}

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")

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)

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")

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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")

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, ])

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)

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, ])

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)
}

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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())

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)

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)

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"))
}

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])

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

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)
}

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)

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)

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
}

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)

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)

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)

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)

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")

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

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)

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")

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)

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)

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)

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)

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)

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)

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")

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")

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

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)

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)

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)
}

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)

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)

Description

Logistic regression and classification metrics functionality

Description

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

Description

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

Description

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

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.

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.

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.

Description

Deep learning functionality using Keras/TensorFlow

Description

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

Description

Functions for testing, visualizing, and analyzing interactions

Description

Functions for calculating model evaluation metrics

Description

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

Description

Neural network functionality for classification and regression

Description

Functions for creating end-to-end model pipelines

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.

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

Description

Linear and polynomial regression functionality

Description

Ridge, Lasso, and Elastic Net regularization functionality

Description

SVM functionality for classification and regression

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).

Description

Decision trees, random forests, and boosting functionality

Description

Functions for automatic hyperparameter tuning and selection

Description

General visualization functions for tidylearn models

Description

End-to-end workflows that combine supervised and unsupervised learning.

Description

XGBoost-specific implementation for gradient boosting

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")

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")

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)

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

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)

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. A check is NA when the fit leaves it nothing to read: on a perfect fit the residuals are rounding error, so every check of them is.

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)

Description

Reports whether the local machine has a CUDA-capable GPU and which tidylearn backends (xgboost, keras3, 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
}

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)

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()

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)

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()

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. tl_table_importance covers "tree", "forest", "boost" and "xgboost".

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)

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

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")

Description

Estimates runtime and feasibility on local CPU, local GPU (when available and applicable), and cloud (planning figures only, since cloud submission does not exist yet), 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. Each method's runtime constant comes from timing fits of three sizes on one laptop, where the estimates land within about a factor of 3 of those fits. Two runs on that laptop differed by up to 2.5x, and other hardware or differently shaped data can be further off, so treat the recommendation as a starting point. The memory multiples and GPU speedups are assumptions with no measurement behind them.

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)
}

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

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)

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)

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")

Description

Create a 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)
}

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.