Metadata-Version: 2.4
Name: linkage2df
Version: 1.0.0
Summary: Convert SciPy linkage matrices to plot-ready DataFrames — used for ggplot/Plotnine dendrograms.
License-File: LICENSE
Author: GabrielClave
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotnine
Requires-Dist: scipy
Description-Content-Type: text/markdown

# linkage2df

### Easily plot SciPy dendrograms using the Grammar of Graphics in Python

`linkage2df` is a  tool that converts SciPy linkage matrices (typically used for hierarchical clustering) into tidy DataFrames. By transforming the dendrogram tree into a set of segments with (x, y) coordinates, you can leverage the full power of **Plotnine** (or any `ggplot2` clone) to create highly customizable dendrograms.

![Penguin Dendrogram](dendrogram_penguins.png)


## Features

* **Tidy Data Output**: Converts hierarchical trees into a simple DataFrame of segments with `x_start`, `y_start`, `x_end`, and `y_end` columns.
* **Cluster Propagation**: Automatically assigns clusters to higher-level branches based on their children, allowing for intuitive coloring of the tree.
* **Plotnine Ready**: Designed specifically to work with `geom_segment()` in the Grammar of Graphics.

---

## Installation

You can install the package directly from your local directory:

```bash
pip install .
```

## Quick start
```
import numpy as np
import pandas as pd
from scipy.cluster.hierarchy import linkage, fcluster
from plotnine import ggplot, aes, geom_segment, theme_minimal
from linkage2df import linkage_to_segments

# 1. Generate some dummy data
np.random.seed(42)
X = np.random.rand(15, 4)

# 2. Compute linkage matrix & clusters
linkage_matrix = linkage(X, method="ward")
clusters = fcluster(linkage_matrix, t=0.7, criterion='distance')

# 3. Convert linkage matrix to a tidy segments DataFrame
df = linkage_to_segments(linkage_matrix, clusters=clusters)

# 4. Plot using Plotnine
p = (
    ggplot(df) +
    geom_segment(aes(x='x_start', y='y_start', xend='x_end', yend='y_end'), size=0.75) +
    theme_minimal()
)

print(p)
```
