Metadata-Version: 2.4
Name: hclust-teach
Version: 0.1.0
Summary: Hierarchical Cluster Analysis (Learning Didactically)
Author-email: Heitor Cavalcante <heitorc62@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/heitorc62/hclust-teach
Project-URL: Repository, https://github.com/heitorc62/hclust-teach
Project-URL: Bug Tracker, https://github.com/heitorc62/hclust-teach/issues
Keywords: hierarchical,clustering,linkage,dendrogram,teaching
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# hclust-teach

Hierarchical Cluster Analysis (Learning Didactically).

A Python port of the R package [`hclustTeach`](https://cran.r-project.org/package=hclustTeach)
(v0.1.0, MIT License) by Gualberto Segundo Agamez Montalvo. It implements
agglomerative hierarchical clustering with **stepwise printing** of the
algorithm and **dendrogram** plots, for didactic purposes.

## Installation

```bash
pip install hclust-teach
```

Requires Python >= 3.9 and `numpy`, `scipy`, `matplotlib`.

## Methods

| Function            | Linkage |
|---------------------|---------|
| `hclust_single`     | Single linkage |
| `hclust_complete`   | Complete linkage |
| `hclust_average`    | Average linkage (UPGMA) |
| `hclust_centroid`   | Centroid linkage (UPGMC) |

Supported distance metrics (same names as R's `dist()`): `euclidean`,
`maximum`, `manhattan`, `canberra`, `binary`, `minkowski`.

## Usage

```python
import numpy as np
import hclust_teach as ht

y1 = np.array([1, 2, 1, 0])
y2 = np.array([2, 1, 0, 2])
y3 = np.array([8, 8, 9, 7])
y4 = np.array([6, 9, 8, 9])
Y = np.vstack([y1, y2, y3, y4])

res = ht.hclust_single(Y)
```

By default the algorithm's steps are printed (initial clusters, the cluster
distance matrix at each step, and each merge):

```
Start: each observation is a cluster
 [-1] members: (y1)
 [-2] members: (y2)
 [-3] members: (y3)
 [-4] members: (y4)

... Step 1 ...
Minimum distance matrix:
                    -1          -2          -3          -4
        -1    0.000000    2.645751   14.071247   14.282857
        -2    2.645751    0.000000   13.820275   13.892444
        -3   14.071247   13.820275    0.000000    3.162278
        -4   14.282857   13.892444    3.162278    0.000000
 -> Merging clusters -2 (y2) and -1 (y1), dist = 2.64575
...
```

and a dendrogram is drawn with matplotlib. The returned
[`HClusterResult`](#hclusterresult) mirrors the R `hclust` object:

```python
res.merge    # (n-1, 2) int array, R hclust merge format
res.height   # (n-1,) linkage heights
res.order    # leaf order that avoids crossing branches
res.labels   # observation labels
res.method   # e.g. "single linkage (euclidean)"
```

To disable the printing or the plot:

```python
res = ht.hclust_complete(Y, print_steps=False, plot=False)
fig, ax = res.dendrogram()  # draw it later
```

With a `pandas.DataFrame` the index is used as observation labels; otherwise
pass `labels=[...]` explicitly:

```python
import pandas as pd
df = pd.DataFrame(Y, index=["obs1", "obs2", "obs3", "obs4"])
res = ht.hclust_average(df)
```

A non-default metric is passed through `metric`, with the Minkowski exponent
via `p`:

```python
res = ht.hclust_single(Y, metric="manhattan")
res = ht.hclust_single(Y, metric="minkowski", p=3)
```

## HClusterResult

`dataclass` with the attributes described above plus a `dendrogram(title=None)`
method. Mirrors the structure R's `stats::hclust` returns.

## License

MIT. The algorithm and stepwise printing follow the R package
[`hclustTeach`](https://cran.r-project.org/package=hclustTeach) (MIT).
