dendrofan 0.1.1__tar.gz

dendrofan-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dendrofan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dendrofan-0.1.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: dendrofan
+Version: 0.1.1
+Summary: Circular ("fan") dendrograms for Python, in the visual style of R's ape package
+Author: Rafael Magallanes Quintanar
+License: MIT
+Project-URL: Homepage, https://github.com/tiquis/dendrofan
+Project-URL: Issues, https://github.com/tiquis/dendrofan/issues
+Keywords: dendrogram,hierarchical-clustering,circular-plot,fan-plot,phylogenetics,data-visualization,scipy,matplotlib
+Classifier: Development Status :: 4 - Beta
+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 :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Requires-Dist: matplotlib>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-mpl; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# dendrofan
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21251841.svg)](https://doi.org/10.5281/zenodo.21251841)
+
+Circular ("fan") dendrograms for Python, in the visual style of R's
+[`ape`](https://cran.r-project.org/package=ape) package
+(`plot.phylo(type = "fan")`, Paradis & Schliep, 2019) — computed and
+rendered entirely with NumPy, SciPy, and Matplotlib. No R dependency,
+no reimplementation of clustering.
+
+## Why this exists
+
+`scipy.cluster.hierarchy` has no circular/fan layout. The usual
+workaround is a one-off script: call
+`scipy.cluster.hierarchy.dendrogram(..., no_plot=True)`, take its
+rectangular `icoord`/`dcoord` output, and manually re-project it into
+polar coordinates with Matplotlib. That works for one figure, but it
+tends to:
+
+- assume a full 360° circle with no gap for labels at the seam,
+- divide by `dcoord.max()` without checking for a degenerate,
+  all-zero-height tree,
+- hardcode SciPy's 10-units-per-leaf spacing convention,
+- have no story for trees with 1 or 2 leaves,
+- mix clustering, geometry, and plotting into a single script, so
+  none of it is reusable for the next dataset.
+
+dendrofan factors the actually-reusable idea — the rectangular-to-polar
+coordinate transform — into a small, tested, documented library, and
+builds a real plotting API on top of it.
+
+## Install
+
+```bash
+pip install -e .          # from a source checkout
+pip install -e ".[dev]"   # + pytest, for running the test suite
+```
+
+## Quick start
+
+```python
+import numpy as np
+from dendrofan import circular_dendrogram
+
+rng = np.random.default_rng(0)
+data = rng.normal(size=(20, 6))
+labels = [f"sample_{i:02d}" for i in range(20)]
+
+result = circular_dendrogram(
+    data,
+    labels=labels,
+    method="ward",       # forwarded to scipy.cluster.hierarchy.linkage
+    span=350,             # leave a small angular gap at the seam
+    inner_radius=0.15,    # small central gap, ape's fan style
+)
+result.fig.savefig("tree.png", dpi=200, bbox_inches="tight")
+```
+
+`circular_dendrogram` accepts the same three kinds of input as SciPy's
+own `dendrogram`: raw observations (`data=...`), a precomputed linkage
+matrix (`Z=...`), or a precomputed condensed distance vector
+(`condensed_distances=...`).
+
+See [`examples/quickstart.py`](examples/quickstart.py) and
+[`examples/reproduce_station_dendrogram.py`](examples/reproduce_station_dendrogram.py)
+(a fully worked, colored-by-group example) for more.
+
+## What it handles that the ad hoc version didn't
+
+| Case | Ad hoc script | dendrofan |
+|---|---|---|
+| Angular gap at the seam (for label room) | not supported (full circle only) | `span=350` (or any value `<= 360`) |
+| All-merge-heights-equal-zero tree | `ZeroDivisionError` / silent NaNs | falls back to placing all nodes at the leaf radius |
+| 1 or 2 leaves | untested, breaks silently | validated; raises `DegenerateTreeError` for < 2, works for 2 |
+| Mismatched label count | silent misalignment | raises `LabelMismatchError` |
+| Invalid linkage matrix / distance vector | undefined behavior | raises `InvalidLinkageError` before plotting |
+| Root at centre vs. rim, radius scale | hardcoded linear, root-at-centre | `inner_radius`/`outer_radius`/`invert_radius`, plus optional `"sqrt"` area-preserving radius scale |
+| Per-clade coloring | manual, one-off | `color_threshold`/`link_color_func` forwarded to SciPy, or a `label_colors` dict/callable |
+| Scale reference / clade highlighting | not present | `dendrofan.annotations.add_scale_ring`, `highlight_sector` |
+| Reuse across datasets | copy-paste the script | one function call |
+
+## API overview
+
+- `dendrofan.circular_dendrogram(...)` — the main entry point; draws
+  the tree and returns a `CircularDendrogramResult` (figure, axes,
+  layout, and the `PolarTransform` used, for further annotation).
+- `dendrofan.geometry.PolarTransform` — the reusable rectangular-to-polar
+  coordinate map, if you want to bend your own geometry onto the same
+  annulus (e.g. a custom decoration).
+- `dendrofan.clustering.build_layout(...)` — validated wrapper around
+  `scipy.cluster.hierarchy.linkage` / `dendrogram`, decoupled from
+  plotting.
+- `dendrofan.styling.resolve_leaf_colors`, `legend_handles` — color and
+  legend helpers.
+- `dendrofan.annotations.add_scale_ring`, `highlight_sector` — optional
+  decorations (a distance-reference ring; shaded clade sectors).
+
+Every public function and class has a full docstring; `help(...)` in a
+Python session is the fastest way to see the complete parameter
+reference.
+
+## Scope
+
+dendrofan draws circular dendrograms from hierarchical clustering
+(SciPy linkage matrices) — it does not parse Newick/phylogenetic tree
+files or handle unequal-tip-depth phylogenies the way `ape` itself
+does. If you need that, `ape` (R) or `ete3`/`Bio.Phylo` (Python) are a
+better fit; dendrofan specifically fills the "I have a SciPy
+dendrogram and want it circular" gap.
+
+## Testing
+
+```bash
+pytest
+```
+
+The test suite specifically exercises the edge cases listed above
+(degenerate trees, mismatched labels, invalid linkage matrices, partial
+spans, single/two-leaf trees).
+
+## Citation
+
+If you use dendrofan in a manuscript, please cite the software itself
+via its Zenodo DOI (see [`CITATION.cff`](CITATION.cff), or use GitHub's
+"Cite this repository" button):
+
+> Magallanes Quintanar, R. (2026). dendrofan v0.1.0 [Software]. Zenodo.
+> https://doi.org/10.5281/zenodo.21251841
+
+Please also cite the underlying methods it wraps:
+
+- Virtanen, P. et al. (2020). SciPy 1.0: fundamental algorithms for
+  scientific computing in Python. *Nature Methods*, 17, 261-272.
+  *(hierarchical clustering / linkage, which dendrofan builds on)*
+- Paradis, E. & Schliep, K. (2019). ape 5.0: an environment for modern
+  phylogenetics and evolutionary analyses in R. *Bioinformatics*,
+  35(3), 526-528. *(for the fan-plot visual convention dendrofan follows)*
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dendrofan-0.1.1/README.md

@@ -0,0 +1,141 @@
+# dendrofan
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21251841.svg)](https://doi.org/10.5281/zenodo.21251841)
+
+Circular ("fan") dendrograms for Python, in the visual style of R's
+[`ape`](https://cran.r-project.org/package=ape) package
+(`plot.phylo(type = "fan")`, Paradis & Schliep, 2019) — computed and
+rendered entirely with NumPy, SciPy, and Matplotlib. No R dependency,
+no reimplementation of clustering.
+
+## Why this exists
+
+`scipy.cluster.hierarchy` has no circular/fan layout. The usual
+workaround is a one-off script: call
+`scipy.cluster.hierarchy.dendrogram(..., no_plot=True)`, take its
+rectangular `icoord`/`dcoord` output, and manually re-project it into
+polar coordinates with Matplotlib. That works for one figure, but it
+tends to:
+
+- assume a full 360° circle with no gap for labels at the seam,
+- divide by `dcoord.max()` without checking for a degenerate,
+  all-zero-height tree,
+- hardcode SciPy's 10-units-per-leaf spacing convention,
+- have no story for trees with 1 or 2 leaves,
+- mix clustering, geometry, and plotting into a single script, so
+  none of it is reusable for the next dataset.
+
+dendrofan factors the actually-reusable idea — the rectangular-to-polar
+coordinate transform — into a small, tested, documented library, and
+builds a real plotting API on top of it.
+
+## Install
+
+```bash
+pip install -e .          # from a source checkout
+pip install -e ".[dev]"   # + pytest, for running the test suite
+```
+
+## Quick start
+
+```python
+import numpy as np
+from dendrofan import circular_dendrogram
+
+rng = np.random.default_rng(0)
+data = rng.normal(size=(20, 6))
+labels = [f"sample_{i:02d}" for i in range(20)]
+
+result = circular_dendrogram(
+    data,
+    labels=labels,
+    method="ward",       # forwarded to scipy.cluster.hierarchy.linkage
+    span=350,             # leave a small angular gap at the seam
+    inner_radius=0.15,    # small central gap, ape's fan style
+)
+result.fig.savefig("tree.png", dpi=200, bbox_inches="tight")
+```
+
+`circular_dendrogram` accepts the same three kinds of input as SciPy's
+own `dendrogram`: raw observations (`data=...`), a precomputed linkage
+matrix (`Z=...`), or a precomputed condensed distance vector
+(`condensed_distances=...`).
+
+See [`examples/quickstart.py`](examples/quickstart.py) and
+[`examples/reproduce_station_dendrogram.py`](examples/reproduce_station_dendrogram.py)
+(a fully worked, colored-by-group example) for more.
+
+## What it handles that the ad hoc version didn't
+
+| Case | Ad hoc script | dendrofan |
+|---|---|---|
+| Angular gap at the seam (for label room) | not supported (full circle only) | `span=350` (or any value `<= 360`) |
+| All-merge-heights-equal-zero tree | `ZeroDivisionError` / silent NaNs | falls back to placing all nodes at the leaf radius |
+| 1 or 2 leaves | untested, breaks silently | validated; raises `DegenerateTreeError` for < 2, works for 2 |
+| Mismatched label count | silent misalignment | raises `LabelMismatchError` |
+| Invalid linkage matrix / distance vector | undefined behavior | raises `InvalidLinkageError` before plotting |
+| Root at centre vs. rim, radius scale | hardcoded linear, root-at-centre | `inner_radius`/`outer_radius`/`invert_radius`, plus optional `"sqrt"` area-preserving radius scale |
+| Per-clade coloring | manual, one-off | `color_threshold`/`link_color_func` forwarded to SciPy, or a `label_colors` dict/callable |
+| Scale reference / clade highlighting | not present | `dendrofan.annotations.add_scale_ring`, `highlight_sector` |
+| Reuse across datasets | copy-paste the script | one function call |
+
+## API overview
+
+- `dendrofan.circular_dendrogram(...)` — the main entry point; draws
+  the tree and returns a `CircularDendrogramResult` (figure, axes,
+  layout, and the `PolarTransform` used, for further annotation).
+- `dendrofan.geometry.PolarTransform` — the reusable rectangular-to-polar
+  coordinate map, if you want to bend your own geometry onto the same
+  annulus (e.g. a custom decoration).
+- `dendrofan.clustering.build_layout(...)` — validated wrapper around
+  `scipy.cluster.hierarchy.linkage` / `dendrogram`, decoupled from
+  plotting.
+- `dendrofan.styling.resolve_leaf_colors`, `legend_handles` — color and
+  legend helpers.
+- `dendrofan.annotations.add_scale_ring`, `highlight_sector` — optional
+  decorations (a distance-reference ring; shaded clade sectors).
+
+Every public function and class has a full docstring; `help(...)` in a
+Python session is the fastest way to see the complete parameter
+reference.
+
+## Scope
+
+dendrofan draws circular dendrograms from hierarchical clustering
+(SciPy linkage matrices) — it does not parse Newick/phylogenetic tree
+files or handle unequal-tip-depth phylogenies the way `ape` itself
+does. If you need that, `ape` (R) or `ete3`/`Bio.Phylo` (Python) are a
+better fit; dendrofan specifically fills the "I have a SciPy
+dendrogram and want it circular" gap.
+
+## Testing
+
+```bash
+pytest
+```
+
+The test suite specifically exercises the edge cases listed above
+(degenerate trees, mismatched labels, invalid linkage matrices, partial
+spans, single/two-leaf trees).
+
+## Citation
+
+If you use dendrofan in a manuscript, please cite the software itself
+via its Zenodo DOI (see [`CITATION.cff`](CITATION.cff), or use GitHub's
+"Cite this repository" button):
+
+> Magallanes Quintanar, R. (2026). dendrofan v0.1.0 [Software]. Zenodo.
+> https://doi.org/10.5281/zenodo.21251841
+
+Please also cite the underlying methods it wraps:
+
+- Virtanen, P. et al. (2020). SciPy 1.0: fundamental algorithms for
+  scientific computing in Python. *Nature Methods*, 17, 261-272.
+  *(hierarchical clustering / linkage, which dendrofan builds on)*
+- Paradis, E. & Schliep, K. (2019). ape 5.0: an environment for modern
+  phylogenetics and evolutionary analyses in R. *Bioinformatics*,
+  35(3), 526-528. *(for the fan-plot visual convention dendrofan follows)*
+
+## License
+
+MIT — see [LICENSE](LICENSE).

dendrofan-0.1.1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dendrofan"
+version = "0.1.1"
+description = "Circular (\"fan\") dendrograms for Python, in the visual style of R's ape package"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "Rafael Magallanes Quintanar" },
+]
+keywords = [
+    "dendrogram",
+    "hierarchical-clustering",
+    "circular-plot",
+    "fan-plot",
+    "phylogenetics",
+    "data-visualization",
+    "scipy",
+    "matplotlib",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.20",
+    "scipy>=1.7",
+    "matplotlib>=3.4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-mpl", "build"]
+
+[project.urls]
+Homepage = "https://github.com/tiquis/dendrofan"
+Issues = "https://github.com/tiquis/dendrofan/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dendrofan-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dendrofan-0.1.1/src/dendrofan/__init__.py

@@ -0,0 +1,62 @@
+"""
+dendrofan: circular ("fan") dendrograms for Python.
+
+dendrofan draws dendrograms bent onto an annulus, in the visual style
+of ``ape::plot.phylo(type = "fan")`` in R (Paradis & Schliep, 2019),
+using only NumPy, SciPy, and Matplotlib -- no R dependency, no
+reimplementation of clustering. It exists because
+``scipy.cluster.hierarchy`` has no circular layout mode: the usual
+workaround is a one-off script that manually re-projects
+``dendrogram()``'s rectangular ``icoord``/``dcoord`` output into polar
+coordinates. dendrofan generalizes that idea into a small, tested
+library: a documented coordinate transform
+(:class:`dendrofan.geometry.PolarTransform`) plus a plotting API that
+handles the edge cases a one-off script usually skips (single-leaf and
+two-leaf trees, all-zero merge heights, mismatched labels, partial fans
+with an angular gap, inward vs. outward root, etc).
+
+Quick start
+-----------
+>>> import numpy as np
+>>> from dendrofan import circular_dendrogram
+>>> rng = np.random.default_rng(0)
+>>> data = rng.normal(size=(12, 5))
+>>> result = circular_dendrogram(data, labels=[f"s{i}" for i in range(12)])
+>>> result.fig.savefig("tree.png", dpi=200)
+
+See :func:`circular_dendrogram` for the full parameter reference, and
+the ``examples/`` directory in the source distribution for worked
+examples, including one that reproduces a colored-by-group station
+dendrogram end to end.
+"""
+from ._version import __version__
+from .annotations import add_scale_ring, highlight_sector
+from .clustering import DendrogramLayout, build_layout
+from .exceptions import (
+    DegenerateTreeError,
+    DendrofanError,
+    InvalidLinkageError,
+    LabelMismatchError,
+)
+from .geometry import PolarTransform, arc_points, radial_label_alignment
+from .plotting import CircularDendrogramResult, circular_dendrogram
+from .styling import legend_handles, resolve_leaf_colors
+
+__all__ = [
+    "__version__",
+    "circular_dendrogram",
+    "CircularDendrogramResult",
+    "build_layout",
+    "DendrogramLayout",
+    "PolarTransform",
+    "arc_points",
+    "radial_label_alignment",
+    "add_scale_ring",
+    "highlight_sector",
+    "resolve_leaf_colors",
+    "legend_handles",
+    "DendrofanError",
+    "InvalidLinkageError",
+    "LabelMismatchError",
+    "DegenerateTreeError",
+]

dendrofan-0.1.1/src/dendrofan/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

dendrofan-0.1.1/src/dendrofan/annotations.py

@@ -0,0 +1,109 @@
+"""Optional decorations for a circular dendrogram: scale rings and sector highlights.
+
+These operate on the ``ax``/``transform`` pair returned by
+:func:`dendrofan.plotting.circular_dendrogram`, so they can be added or
+omitted independently of the tree itself.
+"""
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+import numpy as np
+from matplotlib.axes import Axes
+
+from .geometry import PolarTransform
+
+
+def add_scale_ring(
+    ax: Axes,
+    transform: PolarTransform,
+    heights: Sequence[float],
+    *,
+    color: str = "gray",
+    linewidth: float = 0.6,
+    linestyle: str = "--",
+    label_heights: bool = True,
+    label_fontsize: float = 8,
+    label_angle: float = 90.0,
+) -> None:
+    """Draw concentric guide circles at the given linkage heights.
+
+    The circular analogue of the distance axis ``ape::axisPhylo()``
+    draws on a rectangular/fan tree: a light dashed ring at each height
+    in ``heights``, optionally labeled with the height value, so
+    readers can gauge merge distances even though a circular layout
+    has no literal axis line to read off.
+
+    Parameters
+    ----------
+    heights : sequence of float
+        Linkage heights (in the original units of the tree, i.e. of
+        ``dcoord`` / the linkage matrix) at which to draw a ring.
+        Heights outside ``[0, transform.y_max]`` are skipped.
+    label_angle : float, default 90
+        Angle, in degrees, at which each ring's height label is placed
+        (90 = top of the circle, matching ``start_angle``'s default).
+    """
+    theta = np.radians(label_angle)
+    for h in heights:
+        if h < 0 or h > transform.y_max:
+            continue
+        r = float(transform.radius(h))
+        circle = np.linspace(0, 2 * np.pi, 200)
+        ax.plot(
+            r * np.cos(circle),
+            r * np.sin(circle),
+            color=color,
+            linewidth=linewidth,
+            linestyle=linestyle,
+            zorder=0,
+        )
+        if label_heights:
+            ax.text(
+                r * np.cos(theta),
+                r * np.sin(theta),
+                f"{h:g}",
+                fontsize=label_fontsize,
+                color=color,
+                ha="center",
+                va="bottom",
+            )
+
+
+def highlight_sector(
+    ax: Axes,
+    transform: PolarTransform,
+    theta_start: float,
+    theta_end: float,
+    *,
+    r_inner: Optional[float] = None,
+    r_outer: Optional[float] = None,
+    color: str = "gray",
+    alpha: float = 0.15,
+    n_points: int = 100,
+    zorder: float = -1,
+) -> None:
+    """Shade a wedge of the plot behind a clade, the way ``ape``'s clade
+    highlighting (e.g. via ``ape::ring`` or manually drawn background
+    wedges) marks a group of related leaves.
+
+    Parameters
+    ----------
+    theta_start, theta_end : float
+        Angular bounds of the wedge, in radians (e.g. from
+        ``CircularDendrogramResult.leaf_theta_by_index``).
+    r_inner, r_outer : float, optional
+        Radial bounds of the wedge. Default to
+        ``transform.inner_radius`` and ``transform.outer_radius``
+        respectively, i.e. the whole tree depth.
+    """
+    r_inner = transform.inner_radius if r_inner is None else r_inner
+    r_outer = transform.outer_radius if r_outer is None else r_outer
+
+    thetas = np.linspace(theta_start, theta_end, n_points)
+    outer_x, outer_y = r_outer * np.cos(thetas), r_outer * np.sin(thetas)
+    inner_x, inner_y = r_inner * np.cos(thetas[::-1]), r_inner * np.sin(thetas[::-1])
+
+    xs = np.concatenate([outer_x, inner_x])
+    ys = np.concatenate([outer_y, inner_y])
+    ax.fill(xs, ys, color=color, alpha=alpha, linewidth=0, zorder=zorder)