clustelia 0.0.0__tar.gz

clustelia-0.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,51 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clustelia"
+version = "0.0.0"
+description = "Cluster-label diagnostics and an evolving foundation for clustering analysis."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Jaime Vera-Jaramillo" }]
+keywords = ["clustering", "cluster-analysis", "unsupervised-learning", "machine-learning"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jaimevera1107/clustelia"
+Repository = "https://github.com/jaimevera1107/clustelia"
+Issues = "https://github.com/jaimevera1107/clustelia/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

clustelia-0.0.0/setup.cfg

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

clustelia-0.0.0/src/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-0.0.0/src/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/src/clustelia.egg-info/PKG-INFO

@@ -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/src/clustelia.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/clustelia/__init__.py
+src/clustelia/_summary.py
+src/clustelia.egg-info/PKG-INFO
+src/clustelia.egg-info/SOURCES.txt
+src/clustelia.egg-info/dependency_links.txt
+src/clustelia.egg-info/top_level.txt
+tests/test_summary.py

clustelia-0.0.0/src/clustelia.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clustelia-0.0.0/src/clustelia.egg-info/top_level.txt

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

clustelia-0.0.0/tests/test_summary.py

@@ -0,0 +1,31 @@
+import unittest
+
+from clustelia import __version__, summarize_clusters
+
+
+class SummarizeClustersTests(unittest.TestCase):
+    def test_standard_labels_and_noise(self):
+        result = summarize_clusters([0, 0, 1, -1])
+        self.assertEqual(result.n_samples, 4)
+        self.assertEqual(result.n_clusters, 2)
+        self.assertEqual(result.n_noise, 1)
+        self.assertEqual(result.counts, {0: 2, 1: 1, -1: 1})
+        self.assertEqual(result.shares[0], 0.5)
+
+    def test_custom_noise_and_generator(self):
+        result = summarize_clusters((x for x in ["A", "A", "B", "NA"]), noise_label="NA")
+        self.assertEqual(result.n_clusters, 2)
+        self.assertEqual(result.n_noise, 1)
+
+    def test_empty(self):
+        result = summarize_clusters([])
+        self.assertEqual(result.n_samples, 0)
+        self.assertEqual(result.n_clusters, 0)
+        self.assertEqual(result.shares, {})
+
+    def test_version(self):
+        self.assertEqual(__version__, "0.0.0")
+
+
+if __name__ == "__main__":
+    unittest.main()