Title:	A Common API to Clustering
Version:	0.2.4
Description:	A common interface to specifying clustering models, in the same style as 'parsnip'. Creates unified interface across different functions and computational engines.
License:	MIT + file LICENSE
URL:	https://github.com/tidymodels/tidyclust, https://tidyclust.tidymodels.org/
BugReports:	https://github.com/tidymodels/tidyclust/issues
Depends:	R (≥ 3.6)
Imports:	cli (≥ 3.0.0), dials (≥ 1.3.0), dplyr (≥ 1.0.9), flexclust (≥ 1.3-6), foreach, generics (≥ 0.1.2), glue (≥ 1.6.2), hardhat (≥ 1.0.0), modelenv (≥ 0.2.0), parsnip (≥ 1.0.2), philentropy (≥ 0.9.0), prettyunits (≥ 1.1.0), rlang (≥ 1.0.6), rsample (≥ 1.0.0), stats, tibble (≥ 3.1.0), tidyr (≥ 1.2.0), tune (≥ 1.0.0), utils, vctrs (≥ 0.5.0)
Suggests:	cluster, ClusterR, clustMixType (≥ 0.3-5), covr, klaR, knitr, modeldata (≥ 1.0.0), RcppHungarian, recipes (≥ 1.0.0), rmarkdown, testthat (≥ 3.0.0), workflows (≥ 1.1.2)
Config/Needs/website:	pkgdown, tidymodels, tidyverse, palmerpenguins, patchwork, ggforce, tidyverse/tidytemplate
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-01-27 23:10:56 UTC; emilhvitfeldt
Author:	Emil Hvitfeldt [aut, cre], Kelly Bodwin [aut], Posit Software, PBC [cph, fnd]
Maintainer:	Emil Hvitfeldt <emil.hvitfeldt@posit.co>
Repository:	CRAN
Date/Publication:	2025-01-27 23:20:02 UTC

tidyclust: A Common API to Clustering

Description

A common interface to specifying clustering models, in the same style as 'parsnip'. Creates unified interface across different functions and computational engines.

Author(s)

Maintainer: Emil Hvitfeldt emil.hvitfeldt@posit.co (ORCID)

Authors:

• Kelly Bodwin kelly@bodwin.us

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://github.com/tidymodels/tidyclust

• https://tidyclust.tidymodels.org/

• Report bugs at https://github.com/tidymodels/tidyclust/issues

Helper functions to convert between formula and matrix interface

Description

Functions to take a formula interface and get the resulting objects (y, x, weights, etc) back or the other way around. The functions are intended for developer use. For the most part, this emulates the internals of lm() (and also see the notes at https://developer.r-project.org/model-fitting-functions.html).

.convert_form_to_x_fit() and .convert_x_to_form_fit() are for when the data are created for modeling. .convert_form_to_x_fit() saves both the data objects as well as the objects needed when new data are predicted (e.g. terms, etc.).

.convert_form_to_x_new() and .convert_x_to_form_new() are used when new samples are being predicted and only require the predictors to be available.

Usage

.convert_form_to_x_fit(
  formula,
  data,
  ...,
  na.action = na.omit,
  indicators = "traditional",
  composition = "data.frame",
  remove_intercept = TRUE
)

.convert_x_to_form_fit(x, weights = NULL, remove_intercept = TRUE)

.convert_form_to_x_new(
  object,
  new_data,
  na.action = stats::na.pass,
  composition = "data.frame"
)

.convert_x_to_form_new(object, new_data)

Arguments

Simple Wrapper around hclust function

Description

This wrapper prepares the data into a distance matrix to send to stats::hclust and retains the parameters num_clusters or h as an attribute.

Usage

.hier_clust_fit_stats(
  x,
  num_clusters = NULL,
  cut_height = NULL,
  linkage_method = NULL,
  dist_fun = philentropy::distance
)

Arguments

Value

A dendrogram

Simple Wrapper around ClusterR kmeans

Description

This wrapper runs ClusterR::KMeans_rcpp() and adds column names to the centroids field. And reorders the clusters.

Usage

.k_means_fit_ClusterR(
  data,
  clusters,
  num_init = 1,
  max_iters = 100,
  initializer = "kmeans++",
  fuzzy = FALSE,
  verbose = FALSE,
  CENTROIDS = NULL,
  tol = 1e-04,
  tol_optimal_init = 0.3,
  seed = 1
)

Arguments

Value

a list with the following attributes: clusters, fuzzy_clusters (if fuzzy = TRUE), centroids, total_SSE, best_initialization, WCSS_per_cluster, obs_per_cluster, between.SS_DIV_total.SS

Simple Wrapper around clustMixType kmeans

Description

This wrapper runs clustMixType::kproto() and reorders the clusters.

Usage

.k_means_fit_clustMixType(x, k, ...)

Arguments

Value

Result from clustMixType::kproto()

Simple Wrapper around klaR kmeans

Description

This wrapper runs klaR::kmodes() and reorders the clusters.

Usage

.k_means_fit_klaR(data, modes, ...)

Arguments

Value

Result from klaR::kmodes()

Simple Wrapper around stats kmeans

Description

This wrapper runs stats::kmeans() and adds a check that centers is specified. And reorders the clusters.

Usage

.k_means_fit_stats(data, centers = NULL, ...)

Arguments

Value

Result from stats::kmeans()

Augment data with predictions

Description

augment() will add column(s) for predictions to the given data.

Usage

## S3 method for class 'cluster_fit'
augment(x, new_data, ...)

Arguments

Details

For partition models, a .pred_cluster column is added.

Value

A tibble::tibble() with containing new_data with columns added depending on the mode of the model.

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

kmeans_fit %>%
  augment(new_data = mtcars)

Model Fit Object Information

Description

An object with class "cluster_fit" is a container for information about a model that has been fit to the data.

Details

The following model types are implemented in tidyclust:

• K-Means in k_means()

• Hierarchical (Agglomerative) Clustering in hier_clust()

The main elements of the object are:

• spec: A cluster_spec object.

• fit: The object produced by the fitting function.

• preproc: This contains any data-specific information required to process new a sample point for prediction. For example, if the underlying model function requires arguments x and the user passed a formula to fit, the preproc object would contain items such as the terms object and so on. When no information is required, this is NA.

As discussed in the documentation for cluster_spec, the original arguments to the specification are saved as quosures. These are evaluated for the cluster_fit object prior to fitting. If the resulting model object prints its call, any user-defined options are shown in the call preceded by a tilde (see the example below). This is a result of the use of quosures in the specification.

This class and structure is the basis for how tidyclust stores model objects after seeing the data and applying a model.

Combine metric functions

Description

cluster_metric_set() allows you to combine multiple metric functions together into a new function that calculates all of them at once.

Usage

cluster_metric_set(...)

Arguments

Details

All functions must be:

• Only cluster metrics

Value

A cluster_metric_set() object, combining the use of all input metrics.

Model Specification Information

Description

An object with class "cluster_spec" is a container for information about a model that will be fit.

Details

The following model types are implemented in tidyclust:

• K-Means in k_means()

• Hierarchical (Agglomerative) Clustering in hier_clust()

The main elements of the object are:

• args: A vector of the main arguments for the model. The names of these arguments may be different from their counterparts n the underlying model function. For example, for a k_means() model, the argument name for the number of clusters are called "num_clusters" instead of "k" to make it more general and usable across different types of models (and to not be specific to a particular model function). The elements of args can tune() with the use in tune_cluster().

For more information see https://www.tidymodels.org/start/tuning/. If left to their defaults (NULL), the arguments will use the underlying model functions default value. As discussed below, the arguments in args are captured as quosures and are not immediately executed.

• ...: Optional model-function-specific parameters. As with args, these will be quosures and can be tune().

• mode: The type of model, such as "partition". Other modes will be added once the package adds more functionality.

• method: This is a slot that is filled in later by the model's constructor function. It generally contains lists of information that are used to create the fit and prediction code as well as required packages and similar data.

• engine: This character string declares exactly what software will be used. It can be a package name or a technology type.

This class and structure is the basis for how tidyclust stores model objects prior to seeing the data.

Argument Details

An important detail to understand when creating model specifications is that they are intended to be functionally independent of the data. While it is true that some tuning parameters are data dependent, the model specification does not interact with the data at all.

For example, most R functions immediately evaluate their arguments. For example, when calling mean(dat_vec), the object dat_vec is immediately evaluated inside of the function.

tidyclust model functions do not do this. For example, using

  k_means(num_clusters = ncol(mtcars) / 5)

does not execute ncol(mtcars) / 5 when creating the specification. This can be seen in the output:

  > k_means(num_clusters = ncol(mtcars) / 5)
  K Means Cluster Specification (partition)

  Main Arguments:
    num_clusters = ncol(mtcars)/5

  Computational engine: stats

The model functions save the argument expressions and their associated environments (a.k.a. a quosure) to be evaluated later when either fit.cluster_spec() or fit_xy.cluster_spec() are called with the actual data.

The consequence of this strategy is that any data required to get the parameter values must be available when the model is fit. The two main ways that this can fail is if:

1. The data have been modified between the creation of the model specification and when the model fit function is invoked.

2. If the model specification is saved and loaded into a new session where those same data objects do not exist.

The best way to avoid these issues is to not reference any data objects in the global environment but to use data descriptors such as .cols(). Another way of writing the previous specification is

  k_means(num_clusters = .cols() / 5)

This is not dependent on any specific data object and is evaluated immediately before the model fitting process begins.

One less advantageous approach to solving this issue is to use quasiquotation. This would insert the actual R object into the model specification and might be the best idea when the data object is small. For example, using

  k_means(num_clusters = ncol(!!mtcars) - 1)

would work (and be reproducible between sessions) but embeds the entire mtcars data set into the num_clusters expression:

 > k_means(num_clusters = ncol(!!mtcars) / 5)
 K Means Cluster Specification (partition)

 Main Arguments:
   num_clusters = ncol(structure(list(mpg = c(21, 21, 22.8, 21.4, 18.7,<snip>

 Computational engine: stats

However, if there were an object with the number of columns in it, this wouldn't be too bad:

 > num_clusters_val <- ncol(mtcars) / 5
 > num_clusters_val
 [1] 10
 > k_means(num_clusters = !!num_clusters_val)
 K Means Cluster Specification (partition)

 Main Arguments:
   num_clusters = 2.2

More information on quosures and quasiquotation can be found at https://adv-r.hadley.nz/quasiquotation.html.

Control the fit function

Description

Options can be passed to the fit.cluster_spec() function that control the output and computations.

Usage

control_cluster(verbosity = 1L, catch = FALSE)

Arguments

Value

An S3 object with class "control_cluster" that is a named list with the results of the function call

Examples

control_cluster()

control_cluster(catch = TRUE)

Cut Height

Description

Used in most tidyclust::hier_clust() models.

Usage

cut_height(range = c(0, dials::unknown()), trans = NULL)

Arguments

Examples

cut_height()

Hierarchical (Agglomerative) Clustering via stats

Description

hier_clust() creates Hierarchical (Agglomerative) Clustering model.

Details

For this engine, there is a single mode: partition

Tuning Parameters

This model has 1 tuning parameters:

• num_clusters: # Clusters (type: integer, default: no default)

Translation from tidyclust to the original package (partition)

hier_clust(num_clusters = integer(1)) %>% 
  set_engine("stats") %>% 
  set_mode("partition") %>% 
  translate_tidyclust()

## Hierarchical Clustering Specification (partition)
## 
## Main Arguments:
##   num_clusters = integer(1)
##   linkage_method = complete
## 
## Computational engine: stats 
## 
## Model fit template:
## tidyclust::.hier_clust_fit_stats(data = missing_arg(), num_clusters = integer(1), 
##     linkage_method = "complete")

Preprocessing requirements

Factor/categorical predictors need to be converted to numeric values (e.g., dummy or indicator variables) for this engine. When using the formula method via fit(), tidyclust will convert factor columns to indicators.

References

• Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). The New S Language. Wadsworth & Brooks/Cole. (S version.)

• Everitt, B. (1974). Cluster Analysis. London: Heinemann Educ. Books.

• Hartigan, J.A. (1975). Clustering Algorithms. New York: Wiley.

• Sneath, P. H. A. and R. R. Sokal (1973). Numerical Taxonomy. San Francisco: Freeman.

• Anderberg, M. R. (1973). Cluster Analysis for Applications. Academic Press: New York.

• Gordon, A. D. (1999). Classification. Second Edition. London: Chapman and Hall / CRC

• Murtagh, F. (1985). “Multidimensional Clustering Algorithms”, in COMPSTAT Lectures 4. Wuerzburg: Physica-Verlag (for algorithmic details of algorithms used).

• McQuitty, L.L. (1966). Similarity Analysis by Reciprocal Pairs for Discrete and Continuous Data. Educational and Psychological Measurement, 26, 825–831. doi:10.1177/001316446602600402.

• Legendre, P. and L. Legendre (2012). Numerical Ecology, 3rd English ed. Amsterdam: Elsevier Science BV.

• Murtagh, Fionn and Legendre, Pierre (2014). Ward’s hierarchical agglomerative clustering method: which algorithms implement Ward’s criterion? Journal of Classification, 31, 274–295. doi:10.1007/s00357-014-9161-z.

K-means via ClusterR

Description

k_means() creates K-means model. This engine uses the classical definition of a K-means model, which only takes numeric predictors.

Details

For this engine, there is a single mode: partition

Tuning Parameters

This model has 1 tuning parameters:

• num_clusters: # Clusters (type: integer, default: no default)

Translation from tidyclust to the original package (partition)

k_means(num_clusters = integer(1)) %>% 
  set_engine("ClusterR") %>% 
  set_mode("partition") %>% 
  translate_tidyclust()

## K Means Cluster Specification (partition)
## 
## Main Arguments:
##   num_clusters = integer(1)
## 
## Computational engine: ClusterR 
## 
## Model fit template:
## tidyclust::.k_means_fit_ClusterR(data = missing_arg(), clusters = missing_arg(), 
##     clusters = integer(1))

Preprocessing requirements

Factor/categorical predictors need to be converted to numeric values (e.g., dummy or indicator variables) for this engine. When using the formula method via fit(), tidyclust will convert factor columns to indicators.

Predictors should have the same scale. One way to achieve this is to center and scale each so that each predictor has mean zero and a variance of one.

References

• Forgy, E. W. (1965). Cluster analysis of multivariate data: efficiency vs interpretability of classifications. Biometrics, 21, 768–769.

• Hartigan, J. A. and Wong, M. A. (1979). Algorithm AS 136: A K-means clustering algorithm. Applied Statistics, 28, 100–108. doi:10.2307/2346830.

• Lloyd, S. P. (1957, 1982). Least squares quantization in PCM. Technical Note, Bell Laboratories. Published in 1982 in IEEE Transactions on Information Theory, 28, 128–137.

• MacQueen, J. (1967). Some methods for classification and analysis of multivariate observations. In Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability, eds L. M. Le Cam & J. Neyman, 1, pp. 281–297. Berkeley, CA: University of California Press.

K-means via clustMixType

Description

k_means() creates K-prototypes model. A K-prototypes is the middle ground between a K-means and K-modes model, in the sense that it can be used with data that contains both numeric and categorical predictors.

Details

Both numeric and categorical predictors are requires for this engine.

For this engine, there is a single mode: partition

Tuning Parameters

This model has 1 tuning parameters:

• num_clusters: # Clusters (type: integer, default: no default)

Translation from tidyclust to the original package (partition)

k_means(num_clusters = integer(1)) %>% 
  set_engine("clustMixType") %>% 
  set_mode("partition") %>% 
  translate_tidyclust()

## K Means Cluster Specification (partition)
## 
## Main Arguments:
##   num_clusters = integer(1)
## 
## Computational engine: clustMixType 
## 
## Model fit template:
## tidyclust::.k_means_fit_clustMixType(x = missing_arg(), k = missing_arg(), 
##     keep.data = missing_arg(), k = integer(1), keep.data = TRUE, 
##     verbose = FALSE)

Preprocessing requirements

Both categorical and numeric predictors are required.

References

• Szepannek, G. (2018): clustMixType: User-Friendly Clustering of Mixed-Type Data in R, The R Journal 10/2, 200-208, doi:10.32614/RJ-2018-048.

• Aschenbruck, R., Szepannek, G., Wilhelm, A. (2022): Imputation Strategies for Clustering Mixed‑Type Data with Missing Values, Journal of Classification, doi:10.1007/s00357-022-09422-y.

• Z.Huang (1998): Extensions to the k-Means Algorithm for Clustering Large Data Sets with Categorical Variables, Data Mining and Knowledge Discovery 2, 283-304.

K-means via klaR

Description

k_means() creates K-Modes model. This model is intended to be used with categorical predictors. Although it will accept numeric predictors if they contain a few number of unique values. The numeric predictors will then be treated like categorical.

Details

For this engine, there is a single mode: partition

Tuning Parameters

This model has 1 tuning parameters:

• num_clusters: # Clusters (type: integer, default: no default)

Translation from tidyclust to the original package (partition)

k_means(num_clusters = integer(1)) %>% 
  set_engine("klaR") %>% 
  set_mode("partition") %>% 
  translate_tidyclust()

## K Means Cluster Specification (partition)
## 
## Main Arguments:
##   num_clusters = integer(1)
## 
## Computational engine: klaR 
## 
## Model fit template:
## tidyclust::.k_means_fit_klaR(data = missing_arg(), modes = missing_arg(), 
##     modes = integer(1))

Preprocessing requirements

Only categorical variables are accepted, along with numerics with few unique values.

References

• Huang, Z. (1997) A Fast Clustering Algorithm to Cluster Very Large Categorical Data Sets in Data Mining. in KDD: Techniques and Applications (H. Lu, H. Motoda and H. Luu, Eds.), pp. 21-34, World Scientific, Singapore.

• MacQueen, J. (1967) Some methods for classification and analysis of multivariate observations. In Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability, eds L. M. Le Cam & J. Neyman, 1, pp. 281-297. Berkeley, CA: University of California Press.

K-means via stats

Description

k_means() creates K-means model. This engine uses the classical definition of a K-means model, which only takes numeric predictors.

Details

For this engine, there is a single mode: partition

Tuning Parameters

This model has 1 tuning parameters:

• num_clusters: # Clusters (type: integer, default: no default)

Translation from tidyclust to the original package (partition)

k_means(num_clusters = integer(1)) %>% 
  set_engine("stats") %>% 
  set_mode("partition") %>% 
  translate_tidyclust()

## K Means Cluster Specification (partition)
## 
## Main Arguments:
##   num_clusters = integer(1)
## 
## Computational engine: stats 
## 
## Model fit template:
## tidyclust::.k_means_fit_stats(x = missing_arg(), centers = missing_arg(), 
##     centers = integer(1))

Preprocessing requirements

Factor/categorical predictors need to be converted to numeric values (e.g., dummy or indicator variables) for this engine. When using the formula method via fit(), tidyclust will convert factor columns to indicators.

Predictors should have the same scale. One way to achieve this is to center and scale each so that each predictor has mean zero and a variance of one.

References

• Forgy, E. W. (1965). Cluster analysis of multivariate data: efficiency vs interpretability of classifications. Biometrics, 21, 768–769.

• Hartigan, J. A. and Wong, M. A. (1979). Algorithm AS 136: A K-means clustering algorithm. Applied Statistics, 28, 100–108. doi:10.2307/2346830.

• Lloyd, S. P. (1957, 1982). Least squares quantization in PCM. Technical Note, Bell Laboratories. Published in 1982 in IEEE Transactions on Information Theory, 28, 128–137.

• MacQueen, J. (1967). Some methods for classification and analysis of multivariate observations. In Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability, eds L. M. Le Cam & J. Neyman, 1, pp. 281–297. Berkeley, CA: University of California Press.

Extract elements of a tidyclust model object

Description

These functions extract various elements from a clustering object. If they do not exist yet, an error is thrown.

• extract_fit_engine() returns the engine specific fit embedded within a tidyclust model fit. For example, when using k_means() with the "lm" engine, this returns the underlying kmeans object.

• extract_parameter_set_dials() returns a set of dials parameter objects.

Usage

## S3 method for class 'cluster_fit'
extract_fit_engine(x, ...)

## S3 method for class 'cluster_spec'
extract_parameter_set_dials(x, ...)

Arguments

Details

Extracting the underlying engine fit can be helpful for describing the model (via print(), summary(), plot(), etc.) or for variable importance/explainers.

However, users should not invoke the predict() method on an extracted model. There may be preprocessing operations that tidyclust has executed on the data prior to giving it to the model. Bypassing these can lead to errors or silently generating incorrect predictions.

Good:

   tidyclust_fit %>% predict(new_data)

Bad:

   tidyclust_fit %>% extract_fit_engine() %>% predict(new_data)

Value

The extracted value from the tidyclust object, x, as described in the description section.

Examples

kmeans_spec <- k_means(num_clusters = 2)
kmeans_fit <- fit(kmeans_spec, ~., data = mtcars)

extract_fit_engine(kmeans_fit)

Extract clusters from model

Description

When applied to a fitted cluster specification, returns a tibble with cluster location. When such locations doesn't make sense for the model, a mean location is used.

Usage

extract_centroids(object, ...)

Arguments

Details

Some model types such as K-means as seen in k_means() stores the centroid in the object itself. leading the use of this function to act as an simple extract. Other model types such as Hierarchical (Agglomerative) Clustering as seen in hier_clust(), are fit in such a way that the number of clusters can be determined at any time after the fit. Setting the num_clusters or cut_height in this function will be used to determine the clustering when reported.

Further more, some models like hier_clust(), doesn't have a notion of "centroids". The mean of the observation within each cluster assignment is returned as the centroid.

The ordering of the clusters is such that the first observation in the training data set will be in cluster 1, the next observation that doesn't belong to cluster 1 will be in cluster 2, and so on and forth. As the ordering of clustering doesn't matter, this is done to avoid identical sets of clustering having different labels if fit multiple times.

Related functions

extract_centroids() is a part of a trio of functions doing similar things:

• extract_cluster_assignment() returns the cluster assignments of the training observations

• extract_centroids() returns the location of the centroids

• predict() returns the cluster a new observation belongs to

Value

A tibble::tibble() with 1 row for each centroid and their position. .cluster denotes the cluster name for the centroid. The remaining variables match variables passed into model.

See Also

extract_cluster_assignment() predict.cluster_fit()

Examples

set.seed(1234)
kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

kmeans_fit %>%
  extract_centroids()

# Some models such as `hier_clust()` fits in such a way that you can specify
# the number of clusters after the model is fit.
# A Hierarchical (Agglomerative) Clustering method doesn't technically have
# clusters, so the center of the observation within each cluster is returned
# instead.
hclust_spec <- hier_clust() %>%
  set_engine("stats")

hclust_fit <- fit(hclust_spec, ~., mtcars)

hclust_fit %>%
  extract_centroids(num_clusters = 2)

hclust_fit %>%
  extract_centroids(cut_height = 250)

Extract cluster assignments from model

Description

When applied to a fitted cluster specification, returns a tibble with cluster assignments of the data used to train the model.

Usage

extract_cluster_assignment(object, ...)

Arguments

Details

Some model types such as K-means as seen in k_means() stores the cluster assignments in the object itself. leading the use of this function to act as an simple extract. Other model types such as Hierarchical (Agglomerative) Clustering as seen in hier_clust(), are fit in such a way that the number of clusters can be determined at any time after the fit. Setting the num_clusters or cut_height in this function will be used to determine the clustering when reported.

The ordering of the clusters is such that the first observation in the training data set will be in cluster 1, the next observation that doesn't belong to cluster 1 will be in cluster 2, and so on and forth. As the ordering of clustering doesn't matter, this is done to avoid identical sets of clustering having different labels if fit multiple times.

Related functions

extract_cluster_assignment() is a part of a trio of functions doing similar things:

• extract_cluster_assignment() returns the cluster assignments of the training observations

• extract_centroids() returns the location of the centroids

• predict() returns the cluster a new observation belongs to

Value

A tibble::tibble() with 1 column named .cluster. This tibble will correspond the the training data set.

See Also

extract_centroids() predict.cluster_fit()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

kmeans_fit %>%
  extract_cluster_assignment()

kmeans_fit %>%
  extract_cluster_assignment(prefix = "C_")

# Some models such as `hier_clust()` fits in such a way that you can specify
# the number of clusters after the model is fit
hclust_spec <- hier_clust() %>%
  set_engine("stats")

hclust_fit <- fit(hclust_spec, ~., mtcars)

hclust_fit %>%
  extract_cluster_assignment(num_clusters = 2)

hclust_fit %>%
  extract_cluster_assignment(cut_height = 250)

S3 method to get fitted model summary info depending on engine

Description

S3 method to get fitted model summary info depending on engine

Usage

extract_fit_summary(object, ...)

Arguments

Details

The elements cluster_names and cluster_assignments will be factors.

Value

A list with various summary elements

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

kmeans_fit %>%
  extract_fit_summary()

Splice final parameters into objects

Description

The ⁠finalize_*⁠ functions take a list or tibble of tuning parameter values and update objects with those values.

Usage

finalize_model_tidyclust(x, parameters)

finalize_workflow_tidyclust(x, parameters)

Arguments

Value

An updated version of x.

Examples

kmeans_spec <- k_means(num_clusters = tune())
kmeans_spec

best_params <- data.frame(num_clusters = 5)
best_params

finalize_model_tidyclust(kmeans_spec, best_params)

Fit a Model Specification to a Data Set

Description

fit() and fit_xy() take a model specification, translate_tidyclust the required code by substituting arguments, and execute the model fit routine.

Usage

## S3 method for class 'cluster_spec'
fit(object, formula, data, control = control_cluster(), ...)

## S3 method for class 'cluster_spec'
fit_xy(object, x, case_weights = NULL, control = control_cluster(), ...)

Arguments

Details

fit() and fit_xy() substitute the current arguments in the model specification into the computational engine's code, check them for validity, then fit the model using the data and the engine-specific code. Different model functions have different interfaces (e.g. formula or x/y) and these functions translate_tidyclust between the interface used when fit() or fit_xy() was invoked and the one required by the underlying model.

When possible, these functions attempt to avoid making copies of the data. For example, if the underlying model uses a formula and fit() is invoked, the original data are references when the model is fit. However, if the underlying model uses something else, such as x/y, the formula is evaluated and the data are converted to the required format. In this case, any calls in the resulting model objects reference the temporary objects used to fit the model.

If the model engine has not been set, the model's default engine will be used (as discussed on each model page). If the verbosity option of control_cluster() is greater than zero, a warning will be produced.

If you would like to use an alternative method for generating contrasts when supplying a formula to fit(), set the global option contrasts to your preferred method. For example, you might set it to: options(contrasts = c(unordered = "contr.helmert", ordered = "contr.poly")). See the help page for stats::contr.treatment() for more possible contrast types.

Value

A cluster_fit object that contains several elements:

• spec: The model specification object (object in the call to fit)

• fit: when the model is executed without error, this is the model object. Otherwise, it is a try-error object with the error message.

• preproc: any objects needed to convert between a formula and non-formula interface (such as the terms object)

The return value will also have a class related to the fitted model (e.g. "_kmeans") before the base class of "cluster_fit".

A fitted cluster_fit object.

See Also

set_engine(), control_cluster(), cluster_spec, cluster_fit

Examples

library(dplyr)

kmeans_mod <- k_means(num_clusters = 5)

using_formula <-
  kmeans_mod %>%
  set_engine("stats") %>%
  fit(~., data = mtcars)

using_x <-
  kmeans_mod %>%
  set_engine("stats") %>%
  fit_xy(x = mtcars)

using_formula
using_x

Computes distance from observations to centroids

Description

Computes distance from observations to centroids

Usage

get_centroid_dists(
  new_data,
  centroids,
  dist_fun = function(x, y) {
     philentropy::dist_many_many(x, y, method =
    "euclidean")
 }
)

Arguments

Get colors for tidyclust text.

Description

Get colors for tidyclust text.

Usage

get_tidyclust_colors()

Value

a list of cli functions.

Construct a single row summary "glance" of a model, fit, or other object

Description

This method glances the model in a tidyclust model object, if it exists.

Usage

## S3 method for class 'cluster_fit'
glance(x, ...)

Arguments

Value

a tibble

Hierarchical (Agglomerative) Clustering

Description

hier_clust() defines a model that fits clusters based on a distance-based dendrogram

There are different ways to fit this model, and the method of estimation is chosen by setting the model engine. The engine-specific pages for this model are listed below.

• stats

Usage

hier_clust(
  mode = "partition",
  engine = "stats",
  num_clusters = NULL,
  cut_height = NULL,
  linkage_method = "complete"
)

Arguments

Details

What does it mean to predict?

To predict the cluster assignment for a new observation, we find the closest cluster. How we measure “closeness” is dependent on the specified type of linkage in the model:

• single linkage: The new observation is assigned to the same cluster as its nearest observation from the training data.

• complete linkage: The new observation is assigned to the cluster with the smallest maximum distances between training observations and the new observation.

• average linkage: The new observation is assigned to the cluster with the smallest average distances between training observations and the new observation.

• centroid method: The new observation is assigned to the cluster with the closest centroid, as in prediction for k_means.

• Ward’s method: The new observation is assigned to the cluster with the smallest increase in error sum of squares (ESS) due to the new addition. The ESS is computed as the sum of squared distances between observations in a cluster, and the centroid of the cluster.

Value

A hier_clust cluster specification.

Examples

# Show all engines
modelenv::get_from_env("hier_clust")

hier_clust()

K-Means

Description

k_means() defines a model that fits clusters based on distances to a number of centers. This definition doesn't just include K-means, but includes models like K-prototypes.

There are different ways to fit this model, and the method of estimation is chosen by setting the model engine. The engine-specific pages for this model are listed below.

• stats: Classical K-means

• ClusterR: Classical K-means

• klaR: K-Modes

• clustMixType: K-prototypes

Usage

k_means(mode = "partition", engine = "stats", num_clusters = NULL)

Arguments

Details

What does it mean to predict?

For a K-means model, each cluster is defined by a location in the predictor space. Therefore, prediction in tidyclust is defined by calculating which cluster centroid an observation is closest too.

Value

A k_means cluster specification.

Examples

# Show all engines
modelenv::get_from_env("k_means")

k_means()

Knit engine-specific documentation

Description

Knit engine-specific documentation

Usage

knit_engine_docs(pattern = NULL)

Arguments

Value

A tibble with column file for the file name and result (a character vector that echos the output file name or, when there is a failure, the error message).

The agglomeration Linkage method

Description

The agglomeration Linkage method

Usage

linkage_method(values = values_linkage_method)

values_linkage_method

Arguments

Format

An object of class character of length 8.

Details

This parameter is used in tidyclust models for hier_clust().

Examples

values_linkage_method
linkage_method()

Locate and show errors/warnings in engine-specific documentation

Description

Locate and show errors/warnings in engine-specific documentation

Usage

list_md_problems()

Value

A tibble with column file for the file name, line indicating the line where the error/warning occurred, and problem showing the error/warning message.

Quietly load package namespace

Description

For one or more packages, load the namespace. This is used during parallel processing since the different parallel backends handle the package environments differently.

Usage

## S3 method for class 'cluster_spec'
load_pkgs(x, infra = TRUE, ...)

Arguments

Value

An invisible NULL.

Prepend a new class

Description

This adds an extra class to a base class of "cluster_spec".

Usage

make_classes_tidyclust(prefix)

Arguments

Value

A character vector.

Determine the minimum set of model fits

Description

Determine the minimum set of model fits

Usage

## S3 method for class 'cluster_spec'
min_grid(x, grid, ...)

Arguments

Value

A tibble with the minimum tuning parameters to fit and an additional list column with the parameter combinations used for prediction.

Construct a new clustering metric function

Description

These functions provide convenient wrappers to create the one type of metric functions in celrry: clustering metrics. They add a metric-specific class to fn. These features are used by cluster_metric_set() and by tune_cluster() when tuning.

Usage

new_cluster_metric(fn, direction)

Arguments

Value

A cluster_metric object.

Functions required for tidyclust-adjacent packages

Description

These functions are helpful when creating new packages that will register new cluster specifications.

Usage

new_cluster_spec(cls, args, eng_args, mode, method, engine)

Value

A cluster_spec object made to work with tidyclust.

Model predictions

Description

Apply to a model to create different types of predictions. predict() can be used for all types of models and uses the "type" argument for more specificity.

Usage

## S3 method for class 'cluster_fit'
predict(object, new_data, type = NULL, opts = list(), ...)

## S3 method for class 'cluster_fit'
predict_raw(object, new_data, opts = list(), ...)

Arguments

Details

If "type" is not supplied to predict(), then a choice is made:

• type = "cluster" for clustering models

predict() is designed to provide a tidy result (see "Value" section below) in a tibble output format.

The ordering of the clusters is such that the first observation in the training data set will be in cluster 1, the next observation that doesn't belong to cluster 1 will be in cluster 2, and so on and forth. As the ordering of clustering doesn't matter, this is done to avoid identical sets of clustering having different labels if fit multiple times.

What does it mean to predict?

Prediction is not always formally defined for clustering models. Therefore, each cluster_spec method will have their own section on how "prediction" is interpreted, and done if implemented.

Related functions

predict() when used with tidyclust objects is a part of a trio of functions doing similar things:

• extract_cluster_assignment() returns the cluster assignments of the training observations

• extract_centroids() returns the location of the centroids

• predict() returns the cluster a new observation belongs to

Value

With the exception of type = "raw", the results of predict.cluster_fit() will be a tibble as many rows in the output as there are rows in new_data and the column names will be predictable.

For clustering results the tibble will have a .pred_cluster column.

Using type = "raw" with predict.cluster_fit() will return the unadulterated results of the prediction function.

When the model fit failed and the error was captured, the predict() function will return the same structure as above but filled with missing values. This does not currently work for multivariate models.

See Also

extract_cluster_assignment() extract_centroids()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

kmeans_fit %>%
  predict(new_data = mtcars)

# Some models such as `hier_clust()` fits in such a way that you can specify
# the number of clusters after the model is fit
hclust_spec <- hier_clust() %>%
  set_engine("stats")

hclust_fit <- fit(hclust_spec, ~., mtcars)

hclust_fit %>%
  predict(new_data = mtcars[4:6, ], num_clusters = 2)

hclust_fit %>%
  predict(new_data = mtcars[4:6, ], cut_height = 250)

Other predict methods.

Description

These are internal functions not meant to be directly called by the user.

Usage

predict_cluster(object, ...)

## S3 method for class 'cluster_fit'
predict_cluster(object, new_data, ...)

Arguments

Value

A tibble::tibble().

A tibble::tibble().

Prepares data and distance matrices for metric calculation

Description

Prepares data and distance matrices for metric calculation

Usage

prep_data_dist(
  object,
  new_data = NULL,
  dists = NULL,
  dist_fun = philentropy::distance
)

Arguments

Value

A list

Relabels clusters to match another cluster assignment

Description

When forcing one-to-one, the user needs to decide what to prioritize:

• "accuracy": optimize raw count of all observations with the same label across the two assignments

• "precision": optimize the average percent of each alt cluster that matches the corresponding primary cluster

Usage

reconcile_clusterings_mapping(
  primary,
  alternative,
  one_to_one = TRUE,
  optimize = "accuracy"
)

Arguments

Details

Retains the cluster labels of the primary assignment, and relabel the alternate assignment to match as closely as possible. The user must decide whether clusters are forced to be "one-to-one"; that is, are we allowed to assign multiple labels from the alternate assignment to the same primary label?

Value

A tibble with 3 columns; primary, alt, alt_recoded

Examples

factor1 <- c("Apple", "Apple", "Carrot", "Carrot", "Banana", "Banana")
factor2 <- c("Dog", "Dog", "Cat", "Dog", "Fish", "Fish")
reconcile_clusterings_mapping(factor1, factor2)

factor1 <- c("Apple", "Apple", "Carrot", "Carrot", "Banana", "Banana")
factor2 <- c("Dog", "Dog", "Cat", "Dog", "Fish", "Parrot")
reconcile_clusterings_mapping(factor1, factor2, one_to_one = FALSE)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

%>%

generics

augment, fit, fit_xy, glance, min_grid, required_pkgs, tidy

hardhat

extract_fit_engine, extract_fit_parsnip, extract_parameter_set_dials, extract_preprocessor, extract_spec_parsnip, tune

parsnip

predict_raw, set_args, set_engine, set_mode

tune

load_pkgs

Change arguments of a cluster specification

Description

Change arguments of a cluster specification

Usage

## S3 method for class 'cluster_spec'
set_args(object, ...)

Arguments

Value

An updated cluster_spec object.

Change engine of a cluster specification

Description

Change engine of a cluster specification

Usage

## S3 method for class 'cluster_spec'
set_engine(object, engine, ...)

Arguments

Value

An updated cluster_spec object.

Change mode of a cluster specification

Description

Change mode of a cluster specification

Usage

## S3 method for class 'cluster_spec'
set_mode(object, mode, ...)

Arguments

Value

An updated cluster_spec object.

Measures silhouette between clusters

Description

Measures silhouette between clusters

Usage

silhouette(
  object,
  new_data = NULL,
  dists = NULL,
  dist_fun = philentropy::distance
)

Arguments

Details

silhouette_avg() is the corresponding cluster metric function that returns the average of the values given by silhouette().

Value

A tibble giving the silhouette for each observation.

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

dists <- mtcars %>%
  as.matrix() %>%
  dist()

silhouette(kmeans_fit, dists = dists)

Measures average silhouette across all observations

Description

Measures average silhouette across all observations

Usage

silhouette_avg(object, ...)

## S3 method for class 'cluster_spec'
silhouette_avg(object, ...)

## S3 method for class 'cluster_fit'
silhouette_avg(object, new_data = NULL, dists = NULL, dist_fun = NULL, ...)

## S3 method for class 'workflow'
silhouette_avg(object, new_data = NULL, dists = NULL, dist_fun = NULL, ...)

silhouette_avg_vec(
  object,
  new_data = NULL,
  dists = NULL,
  dist_fun = philentropy::distance,
  ...
)

Arguments

Details

Not to be confused with silhouette() that returns a tibble with silhouette for each observation.

Value

A double; the average silhouette.

See Also

Other cluster metric: sse_ratio(), sse_total(), sse_within_total()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

dists <- mtcars %>%
  as.matrix() %>%
  dist()

silhouette_avg(kmeans_fit, dists = dists)

silhouette_avg_vec(kmeans_fit, dists = dists)

Compute the ratio of the WSS to the total SSE

Description

Compute the ratio of the WSS to the total SSE

Usage

sse_ratio(object, ...)

## S3 method for class 'cluster_spec'
sse_ratio(object, ...)

## S3 method for class 'cluster_fit'
sse_ratio(object, new_data = NULL, dist_fun = NULL, ...)

## S3 method for class 'workflow'
sse_ratio(object, new_data = NULL, dist_fun = NULL, ...)

sse_ratio_vec(
  object,
  new_data = NULL,
  dist_fun = function(x, y) {
     philentropy::dist_many_many(x, y, method =
    "euclidean")
 },
  ...
)

Arguments

Value

A tibble with 3 columns; .metric, .estimator, and .estimate.

See Also

Other cluster metric: silhouette_avg(), sse_total(), sse_within_total()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

sse_ratio(kmeans_fit)

sse_ratio_vec(kmeans_fit)

Compute the total sum of squares

Description

Compute the total sum of squares

Usage

sse_total(object, ...)

## S3 method for class 'cluster_spec'
sse_total(object, ...)

## S3 method for class 'cluster_fit'
sse_total(object, new_data = NULL, dist_fun = NULL, ...)

## S3 method for class 'workflow'
sse_total(object, new_data = NULL, dist_fun = NULL, ...)

sse_total_vec(
  object,
  new_data = NULL,
  dist_fun = function(x, y) {
     philentropy::dist_many_many(x, y, method =
    "euclidean")
 },
  ...
)

Arguments

Value

A tibble with 3 columns; .metric, .estimator, and .estimate.

See Also

Other cluster metric: silhouette_avg(), sse_ratio(), sse_within_total()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

sse_total(kmeans_fit)

sse_total_vec(kmeans_fit)

Calculates Sum of Squared Error in each cluster

Description

Calculates Sum of Squared Error in each cluster

Usage

sse_within(
  object,
  new_data = NULL,
  dist_fun = function(x, y) {
     philentropy::dist_many_many(x, y, method =
    "euclidean")
 }
)

Arguments

Details

sse_within_total() is the corresponding cluster metric function that returns the sum of the values given by sse_within().

Value

A tibble with two columns, the cluster name and the SSE within that cluster.

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

sse_within(kmeans_fit)

Compute the sum of within-cluster SSE

Description

Compute the sum of within-cluster SSE

Usage

sse_within_total(object, ...)

## S3 method for class 'cluster_spec'
sse_within_total(object, ...)

## S3 method for class 'cluster_fit'
sse_within_total(object, new_data = NULL, dist_fun = NULL, ...)

## S3 method for class 'workflow'
sse_within_total(object, new_data = NULL, dist_fun = NULL, ...)

sse_within_total_vec(
  object,
  new_data = NULL,
  dist_fun = function(x, y) {
     philentropy::dist_many_many(x, y, method =
    "euclidean")
 },
  ...
)

Arguments

Details

Not to be confused with sse_within() that returns a tibble with within-cluster SSE, one row for each cluster.

Value

A tibble with 3 columns; .metric, .estimator, and .estimate.

See Also

Other cluster metric: silhouette_avg(), sse_ratio(), sse_total()

Examples

kmeans_spec <- k_means(num_clusters = 5) %>%
  set_engine("stats")

kmeans_fit <- fit(kmeans_spec, ~., mtcars)

sse_within_total(kmeans_fit)

sse_within_total_vec(kmeans_fit)

Turn a tidyclust model object into a tidy tibble

Description

This method tidies the model in a tidyclust model object, if it exists.

Usage

## S3 method for class 'cluster_fit'
tidy(x, ...)

Arguments

Value

a tibble

Resolve a Model Specification for a Computational Engine

Description

translate_tidyclust() will translate_tidyclust a model specification into a code object that is specific to a particular engine (e.g. R package). It translate tidyclust generic parameters to their counterparts.

Usage

translate_tidyclust(x, ...)

## Default S3 method:
translate_tidyclust(x, engine = x$engine, ...)

Arguments

Details

translate_tidyclust() produces a template call that lacks the specific argument values (such as data, etc). These are filled in once fit() is called with the specifics of the data for the model. The call may also include tune() arguments if these are in the specification. To handle the tune() arguments, you need to use the tune package. For more information see https://www.tidymodels.org/start/tuning/

It does contain the resolved argument names that are specific to the model fitting function/engine.

This function can be useful when you need to understand how tidyclust goes from a generic model specific to a model fitting function.

Note: this function is used internally and users should only use it to understand what the underlying syntax would be. It should not be used to modify the cluster specification.

Value

Prints translated code.

Model tuning via grid search

Description

tune_cluster() computes a set of performance metrics (e.g. accuracy or RMSE) for a pre-defined set of tuning parameters that correspond to a model or recipe across one or more resamples of the data.

Usage

tune_cluster(object, ...)

## S3 method for class 'cluster_spec'
tune_cluster(
  object,
  preprocessor,
  resamples,
  ...,
  param_info = NULL,
  grid = 10,
  metrics = NULL,
  control = tune::control_grid()
)

## S3 method for class 'workflow'
tune_cluster(
  object,
  resamples,
  ...,
  param_info = NULL,
  grid = 10,
  metrics = NULL,
  control = tune::control_grid()
)

Arguments

Value

An updated version of resamples with extra list columns for .metrics and .notes (optional columns are .predictions and .extracts). .notes contains warnings and errors that occur during execution.

Examples

library(recipes)
library(rsample)
library(workflows)
library(tune)

rec_spec <- recipe(~., data = mtcars) %>%
  step_normalize(all_numeric_predictors()) %>%
  step_pca(all_numeric_predictors())

kmeans_spec <- k_means(num_clusters = tune())

wflow <- workflow() %>%
  add_recipe(rec_spec) %>%
  add_model(kmeans_spec)

grid <- tibble(num_clusters = 1:3)

set.seed(4400)
folds <- vfold_cv(mtcars, v = 2)

res <- tune_cluster(
  wflow,
  resamples = folds,
  grid = grid
)
res

collect_metrics(res)

Update a cluster specification

Description

If parameters of a cluster specification need to be modified, update() can be used in lieu of recreating the object from scratch.

Usage

## S3 method for class 'hier_clust'
update(
  object,
  parameters = NULL,
  num_clusters = NULL,
  cut_height = NULL,
  linkage_method = NULL,
  fresh = FALSE,
  ...
)

## S3 method for class 'k_means'
update(object, parameters = NULL, num_clusters = NULL, fresh = FALSE, ...)

Arguments

Value

An updated cluster specification.

Examples

kmeans_spec <- k_means(num_clusters = 5)
kmeans_spec
update(kmeans_spec, num_clusters = 1)
update(kmeans_spec, num_clusters = 1, fresh = TRUE)

param_values <- tibble::tibble(num_clusters = 10)

kmeans_spec %>% update(param_values)