README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(mlr3cluster)
library(mlr3misc)
lrn_clust = as.data.table(mlr3::mlr_learners)[task_type == "clust", .(key, label, packages)]
msr_clust = as.data.table(mlr3::mlr_measures)[task_type == "clust", .(key, label, packages)]
lrn_clust = lrn_clust[key != c("clust.bico", "clust.birch")] # remove after cran release
```

# mlr3cluster

Package website: [release](https://mlr3cluster.mlr-org.com/) \| [dev](https://mlr3cluster.mlr-org.com/dev/)

Cluster analysis for **[mlr3](https://github.com/mlr-org/mlr3/)**.

<!-- badges: start -->
[![r-cmd-check](https://github.com/mlr-org/mlr3cluster/actions/workflows/r-cmd-check.yml/badge.svg)](https://github.com/mlr-org/mlr3cluster/actions/workflows/r-cmd-check.yml)
[![CRAN status](https://www.r-pkg.org/badges/version/mlr3cluster)](https://CRAN.R-project.org/package=mlr3cluster)
[![StackOverflow](https://img.shields.io/badge/stackoverflow-mlr3-orange.svg)](https://stackoverflow.com/questions/tagged/mlr3)
[![Mattermost](https://img.shields.io/badge/chat-mattermost-orange.svg)](https://lmmisld-lmu-stats-slds.srv.mwn.de/mlr_invite/)
<!-- badges: end -->

**mlr3cluster** is an extension package for cluster analysis within the **[mlr3](https://github.com/mlr-org/mlr3)** ecosystem. It is a successor of clustering capabilities of **[mlr2](https://github.com/mlr-org/mlr)**.

## Installation

Install the last release from CRAN:

```{r, eval = FALSE}
install.packages("mlr3cluster")
```

Install the development version from GitHub:

```{r, eval = FALSE}
# install.packages("pak")
pak::pak("mlr-org/mlr3cluster")
```

## Feature Overview

The current version of **mlr3cluster** contains:

- A selection of `r nrow(lrn_clust)` clustering learners that represent a wide variety of clusterers: partitional, hierarchical, fuzzy, etc.
- A selection of `r nrow(msr_clust)` performance measures
- Two built-in tasks to get started with clustering

Also, the package is integrated with **[mlr3viz](https://github.com/mlr-org/mlr3viz)** which enables you to create great visualizations with just one line of code!

## Cluster Analysis

### Cluster Learners

```{r, echo = FALSE}
cran_pkg = function(pkgs) {
  pkgs = ifelse(
    pkgs %in% c("stats", "graphics", "datasets"), pkgs, sprintf("[%1$s](https://cran.r-project.org/package=%1$s)", pkgs)
  )
  toString(pkgs)
}

lrn_clust[, packages := map(packages, function(x) setdiff(x, c("mlr3", "mlr3cluster")))]
lrn_clust[, `:=`(
  key = sprintf("[%1$s](https://mlr3cluster.mlr-org.com/reference/mlr_learners_%1$s)", key),
  packages = map_chr(packages, cran_pkg)
)]
knitr::kable(lrn_clust, format = "markdown", col.names = tools::toTitleCase(names(lrn_clust)))
```

### Cluster Measures

```{r, echo = FALSE}
msr_clust[, packages := map(packages, function(x) setdiff(x, c("mlr3", "mlr3cluster")))]
msr_clust[, `:=`(
  key = sprintf("[%1$s](https://mlr3cluster.mlr-org.com/reference/mlr_measures_%1$s)", key),
  packages = map_chr(packages, cran_pkg)
)]
knitr::kable(msr_clust, format = "markdown", col.names = tools::toTitleCase(names(msr_clust)))
```


## Example

```{r, eval = FALSE}
library(mlr3)
library(mlr3cluster)

task = tsk("usarrests")
learner = lrn("clust.kmeans")
learner$train(task)
prediction = learner$predict(task = task)
```

## More Resources

Check out the **[blogpost](https://www.r-bloggers.com/2020/10/introducing-mlr3cluster-cluster-analysis-package/)** for a more detailed introduction to the package.
Also, **[mlr3book](https://mlr3book.mlr-org.com/chapters/chapter13/beyond_regression_and_classification.html#sec-cluster)** has a section on clustering.

## Future Plans

- Add more learners and measures
- Integrate the package with **[mlr3pipelines](https://github.com/mlr-org/mlr3pipelines)** (work in progress)

If you have any questions, feedback or ideas, feel free to open an issue [here](https://github.com/mlr-org/mlr3cluster/issues).