clustelia 0.0.0__py3-none-any.whl

clustelia/__init__.py

@@ -0,0 +1,6 @@
+"""Clustelia: tools for clustering analysis and validation."""
+
+from ._summary import ClusterSummary, summarize_clusters
+
+__version__ = "0.0.0"
+__all__ = ["ClusterSummary", "summarize_clusters", "__version__"]

clustelia/_summary.py

@@ -0,0 +1,62 @@
+"""Lightweight, dependency-free cluster-label diagnostics."""
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import Hashable, Iterable
+
+
+@dataclass(frozen=True)
+class ClusterSummary:
+    """Summary of assigned cluster labels.
+
+    ``counts`` and ``shares`` include the noise label, when present.
+    ``shares`` are relative to all observations, including noise.
+    """
+
+    n_samples: int
+    n_clusters: int
+    n_noise: int
+    counts: dict[Hashable, int]
+    shares: dict[Hashable, float]
+
+
+def summarize_clusters(
+    labels: Iterable[Hashable], *, noise_label: Hashable = -1
+) -> ClusterSummary:
+    """Summarize a sequence of cluster assignments.
+
+    Parameters
+    ----------
+    labels:
+        Hashable cluster labels. Iterators are consumed once. Empty input is
+        accepted. Labels may be strings, integers, or other hashable values.
+    noise_label:
+        Label interpreted as unassigned/noise (default ``-1``, common in
+        DBSCAN/HDBSCAN). Noise does not count toward ``n_clusters``.
+
+    Returns
+    -------
+    ClusterSummary
+        Counts, fractions and sample/cluster/noise totals. No fitted model
+        or input data matrix is required.
+
+    Examples
+    --------
+    >>> s = summarize_clusters([0, 0, 1, -1])
+    >>> (s.n_samples, s.n_clusters, s.n_noise)
+    (4, 2, 1)
+    >>> s.shares[0]
+    0.5
+    """
+    counts = dict(Counter(labels))
+    n_samples = sum(counts.values())
+    n_noise = counts.get(noise_label, 0)
+    n_clusters = len(counts) - int(noise_label in counts)
+    shares = {label: count / n_samples for label, count in counts.items()}
+    return ClusterSummary(
+        n_samples=n_samples,
+        n_clusters=n_clusters,
+        n_noise=n_noise,
+        counts=counts,
+        shares=shares,
+    )

clustelia-0.0.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: clustelia
+Version: 0.0.0
+Summary: Cluster-label diagnostics and an evolving foundation for clustering analysis.
+Author: Jaime Vera-Jaramillo
+Project-URL: Homepage, https://github.com/jaimevera1107/clustelia
+Project-URL: Repository, https://github.com/jaimevera1107/clustelia
+Project-URL: Issues, https://github.com/jaimevera1107/clustelia/issues
+Keywords: clustering,cluster-analysis,unsupervised-learning,machine-learning
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Clustelia
+
+**Clustelia** is a Python project for clustering analysis and, over time, automated clustering and model selection.
+
+## Current scope — 0.0.0
+
+This is an **early, functional preview**, not a completed AutoML toolkit. It provides a dependency-free utility to summarize cluster assignments (sizes, proportions, number of clusters, and noise count). Fitting clustering models, model selection and advanced stability analysis are planned, not available in this release.
+
+### Install
+
+```bash
+pip install clustelia==0.0.0
+```
+
+### Use
+
+```python
+from clustelia import summarize_clusters
+
+summary = summarize_clusters([0, 0, 1, -1])
+print(summary.n_clusters)  # 2
+print(summary.counts)      # {0: 2, 1: 1, -1: 1}
+print(summary.shares)      # {0: 0.5, 1: 0.25, -1: 0.25}
+```
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## Releasing
+
+PyPI publishes automatically through GitHub Actions and Trusted Publishing when a GitHub Release is **published** with a version tag matching `pyproject.toml` (e.g., `v0.0.0`). The workflow checks the version, runs tests, builds source and wheel distributions and uploads them to PyPI.
+
+For the **first publication**, register a PyPI pending trusted publisher first:
+
+- PyPI project: `clustelia`
+- GitHub owner: `jaimevera1107`
+- Repository: `clustelia`
+- Workflow: `publish.yml`
+- Environment: `pypi`
+
+Then publish a GitHub Release for tag `v0.0.0`.
+
+**Important:** A pending trusted publisher does not reserve a PyPI project name. The first successful upload creates the project. Releasing a version twice is not possible on PyPI; update the version before creating each new release.
+
+## License
+
+A project license has not yet been selected. Choose and add one before broad distribution if you want to grant explicit open-source reuse rights.

clustelia-0.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+clustelia/__init__.py,sha256=S0uA8DKCknGGvNb-BO1-3tPhvIjV-R-YnYen97kFzVM,210
+clustelia/_summary.py,sha256=P3wo-cKLl9HA054pM2jQeG0qv-KtERLfEQlV2-lr-TY,1783
+clustelia-0.0.0.dist-info/METADATA,sha256=mMxjrCU35qGanAtBIRV2cF6tBDwMEJMVyN60zhbTMkk,2628
+clustelia-0.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+clustelia-0.0.0.dist-info/top_level.txt,sha256=nAzKyvREPAO3pcSVeJu-HjTpK0fZUyDh-Zjm2L5t7qk,10
+clustelia-0.0.0.dist-info/RECORD,,

clustelia-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clustelia-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clustelia