# tidyclust The goal of tidyclust is to provide a tidy, unified interface to clustering models. The package is closely modeled after the [parsnip](https://parsnip.tidymodels.org/) package. ## Available models | Model | Function | Engines | |----|----|----| | K-Means | [`k_means()`](https://tidyclust.tidymodels.org/reference/k_means.md) | stats, ClusterR, klaR, clustMixType | | Hierarchical | [`hier_clust()`](https://tidyclust.tidymodels.org/reference/hier_clust.md) | stats | | Density-based | [`db_clust()`](https://tidyclust.tidymodels.org/reference/db_clust.md) | dbscan, hdbscan | | Gaussian mixture | [`gm_clust()`](https://tidyclust.tidymodels.org/reference/gm_clust.md) | mclust | | Mean shift | [`mean_shift()`](https://tidyclust.tidymodels.org/reference/mean_shift.md) | LPCM, meanShiftR | ## Installation You can install the released version of tidyclust from [CRAN](https://CRAN.R-project.org) with: ``` r install.packages("tidyclust") ``` and the development version of tidyclust from [GitHub](https://github.com/) with: ``` r # install.packages("pak") pak::pak("tidymodels/tidyclust") ``` ## Example The first thing you do is to create a `cluster specification`. For this example we are creating a K-means model, using the `stats` engine. ``` r library(tidyclust) set.seed(1234) kmeans_spec <- k_means(num_clusters = 3) |> set_engine("stats") kmeans_spec #> K Means Cluster Specification (partition) #> #> Main Arguments: #> num_clusters = 3 #> #> Computational engine: stats ``` This specification can then be fit using data. ``` r kmeans_spec_fit <- kmeans_spec |> fit(~., data = mtcars) kmeans_spec_fit #> tidyclust cluster object #> #> K-means clustering with 3 clusters of sizes 7, 11, 14 #> #> Cluster means: #> mpg cyl disp hp drat wt qsec vs #> 1 19.74286 6 183.3143 122.28571 3.585714 3.117143 17.97714 0.5714286 #> 3 26.66364 4 105.1364 82.63636 4.070909 2.285727 19.13727 0.9090909 #> 2 15.10000 8 353.1000 209.21429 3.229286 3.999214 16.77214 0.0000000 #> am gear carb #> 1 0.4285714 3.857143 3.428571 #> 3 0.7272727 4.090909 1.545455 #> 2 0.1428571 3.285714 3.500000 #> #> Clustering vector: #> Mazda RX4 Mazda RX4 Wag Datsun 710 Hornet 4 Drive #> 1 1 2 1 #> Hornet Sportabout Valiant Duster 360 Merc 240D #> 3 1 3 2 #> Merc 230 Merc 280 Merc 280C Merc 450SE #> 2 1 1 3 #> Merc 450SL Merc 450SLC Cadillac Fleetwood Lincoln Continental #> 3 3 3 3 #> Chrysler Imperial Fiat 128 Honda Civic Toyota Corolla #> 3 2 2 2 #> Toyota Corona Dodge Challenger AMC Javelin Camaro Z28 #> 2 3 3 3 #> Pontiac Firebird Fiat X1-9 Porsche 914-2 Lotus Europa #> 3 2 2 2 #> Ford Pantera L Ferrari Dino Maserati Bora Volvo 142E #> 3 1 3 2 #> #> Within cluster sum of squares by cluster: #> [1] 13954.34 11848.37 93643.90 #> (between_SS / total_SS = 80.8 %) #> #> Available components: #> #> [1] "cluster" "centers" "totss" "withinss" "tot.withinss" #> [6] "betweenss" "size" "iter" "ifault" ``` Once you have a fitted tidyclust object, you can do a number of things. [`predict()`](https://rdrr.io/r/stats/predict.html) returns the cluster a new observation belongs to ``` r predict(kmeans_spec_fit, mtcars[1:4, ]) #> # A tibble: 4 × 1 #> .pred_cluster #> #> 1 Cluster_1 #> 2 Cluster_1 #> 3 Cluster_2 #> 4 Cluster_1 ``` [`extract_cluster_assignment()`](https://tidyclust.tidymodels.org/reference/extract_cluster_assignment.md) returns the cluster assignments of the training observations ``` r extract_cluster_assignment(kmeans_spec_fit) #> # A tibble: 32 × 1 #> .cluster #> #> 1 Cluster_1 #> 2 Cluster_1 #> 3 Cluster_2 #> 4 Cluster_1 #> 5 Cluster_3 #> 6 Cluster_1 #> 7 Cluster_3 #> 8 Cluster_2 #> 9 Cluster_2 #> 10 Cluster_1 #> # ℹ 22 more rows ``` and [`extract_centroids()`](https://tidyclust.tidymodels.org/reference/extract_centroids.md) returns the locations of the clusters ``` r extract_centroids(kmeans_spec_fit) #> # A tibble: 3 × 12 #> .cluster mpg cyl disp hp drat wt qsec vs am gear carb #> #> 1 Cluster_1 19.7 6 183. 122. 3.59 3.12 18.0 0.571 0.429 3.86 3.43 #> 2 Cluster_2 26.7 4 105. 82.6 4.07 2.29 19.1 0.909 0.727 4.09 1.55 #> 3 Cluster_3 15.1 8 353. 209. 3.23 4.00 16.8 0 0.143 3.29 3.5 ``` ## Visual comparison of clustering methods Below is a visualization of the available models and how they compare using 2 dimensional toy data sets. ![Mock comparison for different clustering methods for different data sets. Each row correspods to a clustering method, each column corresponds to a data set type.](reference/figures/README-comparison-1.svg) ## Contributing This project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. - For questions and discussions about tidymodels packages, modeling, and machine learning, please [post on RStudio Community](https://forum.posit.co/new-topic?category_id=15&tags=tidymodels,question). - If you think you have encountered a bug, please [submit an issue](https://github.com/tidymodels/tidyclust/issues). - Either way, learn how to create and share a [reprex](https://reprex.tidyverse.org/articles/articles/learn-reprex.html) (a minimal, reproducible example), to clearly communicate about your code. - Check out further details on [contributing guidelines for tidymodels packages](https://www.tidymodels.org/contribute/) and [how to get help](https://www.tidymodels.org/help/). Footer # Package index ## Specifications These cluster specification functions are used to specify the type of model you want to do. These functions work in a similar fashion to the [model specification function from parsnip](https://parsnip.tidymodels.org/reference/index.html#models). - [`k_means()`](https://tidyclust.tidymodels.org/reference/k_means.md) : K-Means - [`hier_clust()`](https://tidyclust.tidymodels.org/reference/hier_clust.md) : Hierarchical (Agglomerative) Clustering - [`db_clust()`](https://tidyclust.tidymodels.org/reference/db_clust.md) : Density-Based Spatial Clustering of Applications with Noise (DBSCAN) - [`gm_clust()`](https://tidyclust.tidymodels.org/reference/gm_clust.md) : Gaussian Mixture Models (GMM) - [`mean_shift()`](https://tidyclust.tidymodels.org/reference/mean_shift.md) : Mean Shift Clustering - [`cluster_spec`](https://tidyclust.tidymodels.org/reference/cluster_spec.md) : Model Specification Information - [`cluster_fit`](https://tidyclust.tidymodels.org/reference/cluster_fit.md) : Model Fit Object Information ## Fit and Inspect These functions are the generics that are supported for specifications created with tidyclust. - [`fit(`*``*`)`](https://tidyclust.tidymodels.org/reference/fit.md) [`fit_xy(`*``*`)`](https://tidyclust.tidymodels.org/reference/fit.md) : Fit a Model Specification to a Data Set - [`set_args(`*``*`)`](https://tidyclust.tidymodels.org/reference/set_args.cluster_spec.md) : Change arguments of a cluster specification - [`set_engine(`*``*`)`](https://tidyclust.tidymodels.org/reference/set_engine.cluster_spec.md) : Change engine of a cluster specification - [`set_mode(`*``*`)`](https://tidyclust.tidymodels.org/reference/set_mode.cluster_spec.md) : Change mode of a cluster specification - [`augment(`*``*`)`](https://tidyclust.tidymodels.org/reference/augment.md) : Augment data with predictions - [`glance(`*``*`)`](https://tidyclust.tidymodels.org/reference/glance.cluster_fit.md) : Construct a single row summary "glance" of a model, fit, or other object - [`tidy(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidy.cluster_fit.md) : Turn a tidyclust model object into a tidy tibble - [`extract_fit_engine(`*``*`)`](https://tidyclust.tidymodels.org/reference/extract-tidyclust.md) [`extract_parameter_set_dials(`*``*`)`](https://tidyclust.tidymodels.org/reference/extract-tidyclust.md) : Extract elements of a tidyclust model object - [`axe_call.cluster_fit()`](https://tidyclust.tidymodels.org/reference/axe-cluster_fit.md) [`axe_ctrl.cluster_fit()`](https://tidyclust.tidymodels.org/reference/axe-cluster_fit.md) [`axe_data.cluster_fit()`](https://tidyclust.tidymodels.org/reference/axe-cluster_fit.md) [`axe_env.cluster_fit()`](https://tidyclust.tidymodels.org/reference/axe-cluster_fit.md) [`axe_fitted.cluster_fit()`](https://tidyclust.tidymodels.org/reference/axe-cluster_fit.md) : Axing a cluster_fit. ## Prediction Once the cluster specification have been fit, you are likely to want to look at where the clusters are and which observations are associated with which cluster. - [`predict(`*``*`)`](https://tidyclust.tidymodels.org/reference/predict.cluster_fit.md) [`predict_raw(`*``*`)`](https://tidyclust.tidymodels.org/reference/predict.cluster_fit.md) : Model predictions - [`extract_cluster_assignment()`](https://tidyclust.tidymodels.org/reference/extract_cluster_assignment.md) : Extract cluster assignments from model - [`extract_centroids()`](https://tidyclust.tidymodels.org/reference/extract_centroids.md) : Extract clusters from model ## Model based performance metrics These metrics use the fitted clustering model to extract values denoting how well the model works. - [`cluster_metric_set()`](https://tidyclust.tidymodels.org/reference/cluster_metric_set.md) : Combine metric functions - [`silhouette_avg()`](https://tidyclust.tidymodels.org/reference/silhouette_avg.md) [`silhouette_avg_vec()`](https://tidyclust.tidymodels.org/reference/silhouette_avg.md) : Measures average silhouette across all observations - [`sse_ratio()`](https://tidyclust.tidymodels.org/reference/sse_ratio.md) [`sse_ratio_vec()`](https://tidyclust.tidymodels.org/reference/sse_ratio.md) : Compute the ratio of the WSS to the total SSE - [`sse_total()`](https://tidyclust.tidymodels.org/reference/sse_total.md) [`sse_total_vec()`](https://tidyclust.tidymodels.org/reference/sse_total.md) : Compute the total sum of squares - [`sse_within_total()`](https://tidyclust.tidymodels.org/reference/sse_within_total.md) [`sse_within_total_vec()`](https://tidyclust.tidymodels.org/reference/sse_within_total.md) : Compute the sum of within-cluster SSE - [`silhouette()`](https://tidyclust.tidymodels.org/reference/silhouette.md) : Measures silhouette between clusters - [`sse_within()`](https://tidyclust.tidymodels.org/reference/sse_within.md) : Calculates Sum of Squared Error in each cluster ## Tuning Functions to allow multiple cluster specifications to be fit at once. - [`control_cluster()`](https://tidyclust.tidymodels.org/reference/control_cluster.md) [`print(`*``*`)`](https://tidyclust.tidymodels.org/reference/control_cluster.md) : Control the fit function - [`update(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidyclust_update.md) [`update(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidyclust_update.md) [`update(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidyclust_update.md) [`update(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidyclust_update.md) [`update(`*``*`)`](https://tidyclust.tidymodels.org/reference/tidyclust_update.md) : Update a cluster specification - [`finalize_model_tidyclust()`](https://tidyclust.tidymodels.org/reference/finalize_model_tidyclust.md) [`finalize_workflow_tidyclust()`](https://tidyclust.tidymodels.org/reference/finalize_model_tidyclust.md) **\[deprecated\]** : Splice final parameters into objects - [`tune_cluster()`](https://tidyclust.tidymodels.org/reference/tune_cluster.md) : Model tuning via grid search ## Tuning Objects Dials objects. - [`bandwidth()`](https://tidyclust.tidymodels.org/reference/bandwidth.md) : Bandwidth - [`cut_height()`](https://tidyclust.tidymodels.org/reference/cut_height.md) : Cut Height - [`circular()`](https://tidyclust.tidymodels.org/reference/gm_clust_params.md) [`zero_covariance()`](https://tidyclust.tidymodels.org/reference/gm_clust_params.md) [`shared_orientation()`](https://tidyclust.tidymodels.org/reference/gm_clust_params.md) [`shared_shape()`](https://tidyclust.tidymodels.org/reference/gm_clust_params.md) [`shared_size()`](https://tidyclust.tidymodels.org/reference/gm_clust_params.md) : Gaussian mixture covariance structure parameters - [`linkage_method()`](https://tidyclust.tidymodels.org/reference/linkage_method.md) [`values_linkage_method`](https://tidyclust.tidymodels.org/reference/linkage_method.md) : The agglomeration Linkage method - [`min_points()`](https://tidyclust.tidymodels.org/reference/min_points.md) : Minimum number of points - [`radius()`](https://tidyclust.tidymodels.org/reference/radius.md) : Radius ## Developer tools - [`contr_one_hot()`](https://tidyclust.tidymodels.org/reference/contr_one_hot.md) : One-hot contrast matrix - [`extract_fit_summary()`](https://tidyclust.tidymodels.org/reference/extract_fit_summary.md) : S3 method to get fitted model summary info depending on engine - [`get_centroid_dists()`](https://tidyclust.tidymodels.org/reference/get_centroid_dists.md) : Computes distance from observations to centroids - [`new_cluster_metric()`](https://tidyclust.tidymodels.org/reference/new_cluster_metric.md) : Construct a new clustering metric function - [`prep_data_dist()`](https://tidyclust.tidymodels.org/reference/prep_data_dist.md) : Prepares data and distance matrices for metric calculation - [`reconcile_clusterings_mapping()`](https://tidyclust.tidymodels.org/reference/reconcile_clusterings_mapping.md) : Relabels clusters to match another cluster assignment - [`translate_tidyclust()`](https://tidyclust.tidymodels.org/reference/translate_tidyclust.md) : Resolve a Model Specification for a Computational Engine - [`min_grid(`*``*`)`](https://tidyclust.tidymodels.org/reference/min_grid.cluster_spec.md) : Determine the minimum set of model fits # Articles ### All vignettes - [Density-Based Clustering](https://tidyclust.tidymodels.org/articles/db_clust.md): - [Gaussian Model Clustering](https://tidyclust.tidymodels.org/articles/gm_clust.md): - [Hierarchical Clustering](https://tidyclust.tidymodels.org/articles/hier_clust.md): - [k-means](https://tidyclust.tidymodels.org/articles/k_means.md): - [Getting started with tidyclust](https://tidyclust.tidymodels.org/articles/tidyclust.md): - [Tuning Cluster Models](https://tidyclust.tidymodels.org/articles/tuning_and_metrics.md):