---
title: "Clustering Analysis Workflow"
subtitle: "Biostat 212A"
author: "Dr. Jin Zhou @ UCLA"
date: today
format:
  html:
    theme: cosmo
    embed-resources: true
    number-sections: true
    toc: true
    toc-depth: 4
    toc-location: left
    code-fold: false
engine: knitr
knitr:
  opts_chunk: 
    fig.align: 'center'
    # fig.width: 6
    # fig.height: 4
    message: FALSE
    cache: false
---

Display system information for reproducibility.

::: {.panel-tabset}
#### R

```{r}
sessionInfo()
library(workflows)
library(parsnip)
library(tidyclust)
library(tidyverse)
library(tidymodels)
library(RcppHungarian)
set.seed(838383)
```


:::


# K-means clustering

## Acknoledgement 
This document is adapted from the [tidyclust k_means](https://tidyclust.tidymodels.org/articles/k_means.html) package vignette.

## Load and clean a dataset: penguins
```{r}
data("penguins", package = "modeldata")

penguins <- penguins %>%
  select(bill_length_mm, bill_depth_mm) %>%
  drop_na()


# shuffle rows
penguins <- penguins %>%
  sample_n(nrow(penguins))
```

## k-means specification in {tidyclust}
```{r}
kmeans_spec <- k_means(num_clusters = 3)

kmeans_spec
```
There are currently two engines: `stats::kmeans (default)` and `ClusterR::KMeans_rcpp`.

It is also possible to change the algorithmic details of the implementation, by changing the engine and/or using the corresponding arguments from the engine functions:

```{r}
kmeans_spec_lloyd <- k_means(num_clusters = 3) %>%
  parsnip::set_engine("stats", algorithm = "Lloyd")

kmeans_spec_cr <- k_means(num_clusters = 3) %>%
  parsnip::set_engine("ClusterR", initializer = "random")
```

Note that the `stats::kmeans` and the `ClusterR::KMeans_rcpp` implementations have very different default settings for the algorithmic details, so it is recommended to be deliberate and explicit in choosing these options, check [here](https://tidyclust.tidymodels.org/articles/k_means.html#a-brief-introduction-to-the-k-means-algorithm). 

## Fit the k-means model
Once specified, a model may be "fit" to a dataset by providing a formula and data frame in the same manner as a tidymodels model fit.
Note that unlike in supervised modeling, the formula should not include a response variable.

```{r}
kmeans_fit <- kmeans_spec %>%
  fit(~ bill_length_mm + bill_depth_mm,
    data = penguins
  )

kmeans_fit %>%
  summary()
```

`tidyclust` also provides a function, extract_fit_summary(), to produce a list of model summary information in a format that is consistent across all cluster model specifications and engines

```{r}
kmeans_summary <- kmeans_fit %>%
  extract_fit_summary()

kmeans_summary %>% str()
```

## Cluster assignments and centers
```{r}
kmeans_fit %>%
  extract_cluster_assignment()
```

Note that this function renames clusters in accordance with the standard tidyclust naming convention and ordering: clusters are named "Cluster_1", "Cluster_2", etc. and are numbered by the order they appear in the rows of the training dataset.

## Centroids
A secondary output of interest is often the characterization of the clusters; i.e., what data feature trends does each cluster seem to represent? Most commonly, clusters are characterized by their mean values in the predictor space, a.k.a. the centroids.

These can be accessed from the full summary:
```{r}
kmeans_summary$centroids
```

They can also be accessed directly from the fitted model with:
```{r}
kmeans_fit %>%
  extract_centroids()
```

Based on the above output, we might say that Cluster_1 is penguins with smaller bill lengths, Cluster_2 has smaller bill depths, and Cluster_3 is penguins with large bills in both dimensions.



## Sum of squared error
One simple metric is the within cluster sum-of-squared error (WSS), which measures the sum of all distances from observations to their cluster center. This is sometimes scaled with the total sum-of-squared error (TSS), the distance from all observations to the global centroid; in particular, the ratio WSS/TSS is often computed. In principle, small values of WSS or of the WSS/TSS ratio suggest that the observations within clusters are closer (more similar) to each other than they are to the other clusters.

The WSS and TSS come "for free" with the model fit summary, or they can be accessed directly from the model fit:

```{r}
kmeans_summary$sse_within_total_total
kmeans_summary$sse_total

kmeans_fit %>% sse_within_total()
kmeans_fit %>% sse_total()

kmeans_fit %>% sse_ratio()
```

We can also see the within sum-of-squares by cluster, rather than totalled, with `sse_within()`:
```{r}
kmeans_fit %>%
  sse_within()
```

## Silhouette
Another common measure of cluster structure is called the **silhouette**. The silhouette of a single observation is proportional to the average distance from that observation to within-cluster observations minus the average distance to outside-cluster observations; normalized by the greater of these two average.
In principle, a large silhouette (close to 1) suggests that an observation is more similar to those within its cluster than those outside its cluster.

We can average all silhouettes to get a metric for the full clustering fit. Because the computation of the silhouette depends on the original observation values, a dataset must also be supplied to the function
```{r}
kmeans_fit %>%
  silhouette_avg(penguins)
```

## Changing distance measures

These metrics all depend on measuring the distance between points and/or centroids. By default, ordinary Euclidean distance is used. However, it is possible to select a different distance function.

For sum of squares metrics, the distance function supplied must take two arguments (i.e., the observation locations and the centroid locations). For the sihouette metric, the distance function must find pairwise distances from a single matrix (i.e., all pairwise distances between observations).

```{r}
my_dist_1 <- function(x) {
  Rfast::Dist(x, method = "manhattan")
}

my_dist_2 <- function(x, y) {
  Rfast::dista(x, y, method = "manhattan")
}

kmeans_fit %>% sse_ratio(dist_fun = my_dist_2)

kmeans_fit %>% silhouette_avg(penguins, dist_fun = my_dist_1)
```

## Workflows

The workflow structure of tidymodels is also usable with tidyclust objects. In the following example, we try two recipes for clustering penguins by bill dimensions. In the second recipe, we log-scale both predictors before clustering.

```{r}
penguins_recipe_1 <- recipe(~ bill_length_mm + bill_depth_mm,
  data = penguins
)

penguins_recipe_2 <- recipe(~ bill_length_mm + bill_depth_mm,
  data = penguins
) %>%
  step_log(all_numeric_predictors())

wflow_1 <- workflow() %>%
  add_model(kmeans_spec) %>%
  add_recipe(penguins_recipe_1)

wflow_2 <- workflow() %>%
  add_model(kmeans_spec) %>%
  add_recipe(penguins_recipe_2)

wflow_1 %>%
  fit(penguins) %>%
  extract_centroids()

wflow_2 %>%
  fit(penguins) %>%
  extract_centroids()
```

# Hierarchical clustering
Load and clean a dataset:

```{r}
data("penguins", package = "modeldata")

penguins <- penguins %>%
  select(bill_length_mm, bill_depth_mm) %>%
  drop_na()

# shuffle rows
penguins <- penguins %>%
  sample_n(nrow(penguins))


```

If you have not yet read the `k_means` vignette, we recommend reading that first;
functions that are used in this vignette are explained in more detail there.



## A brief introduction to hierarchical clustering

*Hierarchical Clustering*, sometimes called *Agglomerative Clustering*, is a 
method of *unsupervised* learning that produces a *dendrogram*, which can be used
to partition observations into clusters.  

The hierarchical clustering process begins with each observation in it's own
cluster; i.e., *n* clusters for *n* observations.

```{r, echo = FALSE}
#| fig-alt: "scatter chart. 5 circles are randomly located, and labeled a, b, c, d, and e."
fake_dat <- tibble(
  x = sort(runif(5)),
  y = runif(5),
  lab = letters[1:5]
)

fake_dat %>%
  ggplot(aes(x, y)) +
  geom_point(shape = fake_dat$lab, size = 4) +
  geom_point(shape = 1, size = 7, stroke = 1, color = "dark grey") +
  theme_minimal() +
  ylim(c(-0.1, 1.1)) +
  xlim(c(-0.1, 1.1))
```

The closest two observations are then joined together into a single cluster.


```{r, echo = FALSE}
#| fig-alt: "scatter chart. 5 circles are randomly located, and labeled a, b, c, d, and e. One of the circles are replacing 2 of the previous circles."
fake_dat_2 <- bind_rows(
  fake_dat[-c(1:2), -3],
  summarize_all(fake_dat[1:2, -3], mean)
) %>%
  mutate(
    size = c(rep(1, 3), suppressWarnings(dist(fake_dat)[1]))
  )

fake_dat %>%
  ggplot(aes(x, y)) +
  geom_point(shape = fake_dat$lab, size = 4) +
  geom_point(
    data = fake_dat_2,
    aes(x = x, y = y),
    shape = 1,
    size = 7 / fake_dat_2$size,
    stroke = 1,
    color = "dark grey"
  ) +
  theme_minimal() +
  theme(legend.position = "none") +
  ylim(c(-0.1, 1.1)) +
  xlim(c(-0.1, 1.1))
```

This process continues, with the closest two clusters being joined (or 
"aggolermated") at each step.


```{r, echo = FALSE}
#| fig-alt: "scatter chart. 5 circles are randomly located, and labeled a, b, c, d, and e. One of the circles are replacing 2 of the previous circles."
fake_dat_3 <- bind_rows(
  fake_dat[-c(1:3), -3],
  summarize_all(fake_dat[1:3, -3], mean)
) %>%
  mutate(
    size = c(rep(1, 2), 0.09)
  )

p1 <- fake_dat %>%
  ggplot(aes(x, y)) +
  geom_point(shape = fake_dat$lab, size = 4) +
  geom_point(
    data = fake_dat_3,
    aes(x = x, y = y),
    shape = 1,
    size = 7 / fake_dat_3$size,
    stroke = 1,
    color = "dark grey"
  ) +
  theme_minimal() +
  theme(legend.position = "none") +
  ylim(c(-0.1, 1.1)) +
  xlim(c(-0.1, 1.1))


fake_dat_4 <- bind_rows(
  summarize_all(fake_dat[1:3, -3], mean),
  summarize_all(fake_dat[4:5, -3], mean),
) %>%
  mutate(
    size = c(0.09, 0.09)
  )

p2 <- fake_dat %>%
  ggplot(aes(x, y)) +
  geom_point(shape = fake_dat$lab, size = 4) +
  geom_point(
    data = fake_dat_4,
    aes(x = x, y = y),
    shape = 1,
    size = 7 / fake_dat_4$size,
    stroke = 1,
    color = "dark grey"
  ) +
  theme_minimal() +
  theme(legend.position = "none") +
  ylim(c(-0.1, 1.1)) +
  xlim(c(-0.1, 1.1))

library(patchwork)
p1 + p2
```


The result of the process is a **dendrogram**, which shows the joining of clusters
in tree form:

```{r, echo = FALSE}
#| fig-alt: "Dendrogram chart. With 5 observations."
hc <- hclust(dist(fake_dat))

plot(hc, labels = fake_dat$lab)
```

### Clusters from dendrogram

To produce a partition-style cluster assignment from the dendrogram, one must
"cut" the tree at a chosen height:

```{r, echo = FALSE}
#| fig-alt: "Dendrogram chart. With 5 observations. A horizontal like at 0.6 cuts the dendrogram into 3 clusters."
plot(hc, labels = fake_dat$lab)
abline(h = 0.6, lty = 2, col = "dark grey")
```

The observations that remain joined in the dendrogram below the cut height are
considered to be in a cluster together:

```{r, echo = FALSE}
tibble(
  observation = fake_dat$lab,
  cluster_assignment = cutree(hc, h = 0.6)
)
```


### Methods of aggolmeration

At every step of the agglomeration, we measure distances between current
clusters.  With each cluster containing (possibly) multiple points, what does
it mean to measure distance?

There are four common approaches to cluster-cluster distancing, aka "linkage":

1. **single linkage:** The distance between two clusters is the distance between
the two **closest** observations.

2. **average linkage:** The distance between two clusters is the average of all
distances between observations in one cluster and observations in the other.

3. **complete linkage:** The distance between two clusters is the distance between
the two **furthest** observations.

4. **centroid method:** The distance between two clusters is the distance between
their centroids (geometric mean or median).

5. **Ward's method:** The distance between two clusters is proportional to the 
increase in **error sum of squares (ESS)** that would result from joining them.
The ESS is computed as the sum of squared distances between observations in a
cluster, and the centroid of the cluster.


It is also worth mentioning the **McQuitty method**, which retains information
about previously joined clusters to measure future linkage distance.  This 
method is currently supported for model fitting, but not for prediction, in
`tidyclust`.


## `hier_clust` specification in {tidyclust}

To specify a hierarchical clustering model in `tidyclust`, 
simply choose a value of `num_clusters` and (optionally) a linkage method:

```{r}
hc_spec <- hier_clust(
  num_clusters = 3,
  linkage_method = "average"
)

hc_spec
```

Currently, the only supported engine is `stats::hclust()`.  The default linkage
<!-- method of this method is *complete linkage*. -->

<!-- Note that the hierarchical clustering algorithm does not need a number of clusters -->
<!-- specified to perform the aggomeration and produce a dendrogram, only to determine -->
<!-- a cut of the tree, so this parameter -->
<!-- does not actually need to be specified in advance. -->


<!-- ```{r} -->
<!-- hc_spec_blank <- hier_clust()  -->

<!-- hc_spec_blank -->
<!-- ``` -->


## Fitting `hier_clust` models

We fit the model to data in the usual way:

```{r}
hc_fit <- hc_spec %>%
  fit(~ bill_length_mm + bill_depth_mm,
    data = penguins
  )

hc_fit %>%
  summary()
```

To produce a dendrogram plot, access the engine fit:
(Although as we see below, dendrograms are often not very informative for moderate
to large size datasets.)

```{r}
#| fig-alt: "Dendrogram chart. With too many observations to be able to clearly see anything"
hc_fit$fit %>% plot()
```

We can also extract the standard `tidyclust` summary list:

```{r}
hc_summary <- hc_fit %>% extract_fit_summary()

hc_summary %>% str()
```

Note that, although the hierarchical clustering algorithm is not focused on 
cluster centroids in the same way $k$-means is, we are still able to compute
the geometric mean over the predictors for each cluster:

```{r}
hc_fit %>% extract_centroids()
```


## Prediction

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.

```{r}
hc_preds <- hc_fit %>% predict(penguins)

hc_preds
```

It's important to note that there is no guarantee that `predict()` on the 
training data will produce the same results as `extract_cluster_assignments()`.
The process by which clusters are created during the aggolmerations results in
a particular partition; but if a training observation is treated as new data, it
is predicted in the same manner as truly new information.

```{r}
bind_cols(
  hc_preds,
  extract_cluster_assignment(hc_fit)
)
```


<!-- Overriding cluster partition: -->

<!-- ```{r} -->
<!-- hc_fit %>% extract_cluster_assignment(num_clusters = 5) -->
<!-- hc_fit %>% extract_cluster_assignment(cut_height = 5) -->
<!-- ``` -->


## Reconciling partitions

Suppose we have produced cluster assignments from two models:  a hierarchical
clustering model with three clusters (as above) and a $k$-means clustering model
 with five clusters (below).  How can we combine these assignments?

```{r}
km_spec <- k_means(num_clusters = 5)
km_fit <- km_spec %>%
  fit(~., data = penguins)

km_preds <- predict(km_fit, penguins, prefix = "KM_")
hc_preds <- predict(hc_fit, penguins, prefix = "HC_")
```

We notice that the three-cluster assignments from `hier_clust` do not line up
perfectly with the five-cluster assignments from `k_means`.  

```{r}
tibble(
  hc = hc_preds$.pred_cluster,
  km = km_preds$.pred_cluster
) %>%
  count(hc, km)
```

However, they are not fully unrelated assignments.  For example, all of 
`KM_2` in the $k$-means assignment fell inside `HC_1` for the hierarchical
assignments.

Our goal is to relabel the five $k$-means clusters to match the three cluster names
in the hierarchical output.  This can be accomplished with `reconcile_clusterings_mapping()`.

This function expects two vectors of cluster labels as input.  The first is the
label that will be matched, and the second is the label that will be recoded
to the first.

If we are not trying to simply match names across two same-size clusterings,
the option `one_to_one` must be set to `FALSE`.

```{r}
reconcile_clusterings_mapping(
  primary = hc_preds$.pred_cluster,
  alternative = km_preds$.pred_cluster,
  one_to_one = FALSE
)
```

In this example, we can see that `KM_1`, `KM_2`, `KM_5` have been matched to 
`HC_1`; and `KM_3` and `KM_4` have been matched to `HC_2`.  Notice that no
clusters from the `KM` set were matched to `HC_3`; evidently, this is a small
cluster that did not manifest clearly in the $k$-means clustering.
