carve-validate 1.0.0__tar.gz

carve_validate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kai Wycik
+
+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.

carve_validate-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: carve-validate
+Version: 1.0.0
+Summary: Cluster Analysis with Resampling for Validation and Exploration: stability- and generalizability-based clustering validation.
+Author-email: Kai Wycik <kai.wycik@columbia.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DataSlingers/CARVE
+Project-URL: Repository, https://github.com/DataSlingers/CARVE
+Project-URL: Issues, https://github.com/DataSlingers/CARVE/issues
+Keywords: clustering,validation,stability,consensus,scRNA-seq,scikit-learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.1,>=2.0
+Requires-Dist: scipy<1.17,>=1.16
+Requires-Dist: scikit-learn<1.8,>=1.7.2
+Requires-Dist: pandas<2.3,>=2.2
+Requires-Dist: joblib<1.6,>=1.5
+Requires-Dist: tqdm<5,>=4.67
+Requires-Dist: numba<0.61,>=0.60
+Requires-Dist: llvmlite<0.44,>=0.43
+Requires-Dist: umap-learn>=0.5.6
+Requires-Dist: pynndescent<0.6,>=0.5.10
+Requires-Dist: matplotlib>=3.9.4
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: notebooks
+Requires-Dist: jupyterlab<5,>=4.2; extra == "notebooks"
+Requires-Dist: ipykernel<7,>=6.29; extra == "notebooks"
+Requires-Dist: ipywidgets>=8.1.7; extra == "notebooks"
+Requires-Dist: plotly>=6.3.0; extra == "notebooks"
+Requires-Dist: rpy2>=3.6.3; extra == "notebooks"
+Requires-Dist: pyreadr>=0.5.3; extra == "notebooks"
+Requires-Dist: scanpy>=1.11.4; extra == "notebooks"
+Requires-Dist: scikit-misc>=0.5.1; extra == "notebooks"
+Requires-Dist: anywidget>=0.9.18; extra == "notebooks"
+Requires-Dist: igraph>=1.0.0; extra == "notebooks"
+Requires-Dist: leidenalg>=0.11.0; extra == "notebooks"
+Requires-Dist: pyteomics>=4.7.5; extra == "notebooks"
+Requires-Dist: lxml>=6.0.2; extra == "notebooks"
+Requires-Dist: scvi>=0.6.8; extra == "notebooks"
+Requires-Dist: cmap>=0.7.0; extra == "notebooks"
+Requires-Dist: glasbey>=0.3.0; extra == "notebooks"
+Dynamic: license-file
+
+[![CI](https://github.com/DataSlingers/CARVE/actions/workflows/ci.yml/badge.svg)](https://github.com/DataSlingers/CARVE/actions/workflows/ci.yml)
+[![R CMD check](https://github.com/DataSlingers/CARVE/actions/workflows/r-ci.yml/badge.svg)](https://github.com/DataSlingers/CARVE/actions/workflows/r-ci.yml)
+![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)
+![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)
+
+# CARVE
+
+**Cluster Analysis with Resampling for Validation and Exploration**
+
+Choosing the number of clusters is hard, especially for high-dimensional biological data where standard internal clustering validation indices (CVIs) are often unreliable. CARVE measures clustering robustness through two resampling-based concepts: **stability** (reproducibility of cluster assignments under data subsampling) and **generalizability** (agreement between held-out cluster labels and predictions from a classifier trained on a subsample of the data). CARVE reports global, cluster-level, and sample-level diagnostics with visualizations, all through a scikit-learn-compatible API.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DataSlingers/CARVE/main/carve_overview.png" width="700" alt="CARVE overview">
+</p>
+
+## Features
+
+- Scikit-learn-compatible API: `CARVE` extends `BaseEstimator` with a `fit` / `get_labels` / `get_k` workflow
+- Stability (ARI on subsample overlap) and generalizability (ARI on held-out predictions) metrics
+- Diagnostics at the global, per-cluster, and per-sample level
+- Metrics: stability and generalizability ARIs, consensus PAC, Gini, cross-entropy, and predictive accuracy
+- Selection rules: `max`, `1se` (one-standard-error), and `quantile`
+- Custom spectral clustering with self-tuning affinity (based on Zelnik-Manor & Perona, *Self-Tuning Spectral Clustering*, NeurIPS 2004)
+- Plots: metric-over-*k* curves, consensus heatmaps, box plots, violin plots, and scatter plots
+- Parallel resampling via joblib (`n_jobs`)
+
+## Installation
+
+CARVE requires **Python 3.12**.
+
+```bash
+pip install carve-validate
+```
+
+The distribution is named `carve-validate`; the import name is `carve`:
+
+```python
+from carve import CARVE
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/DataSlingers/CARVE.git
+cd CARVE
+pip install -e ".[dev]"        # linting + testing
+pip install -e ".[notebooks]"  # Jupyter, Scanpy, scVI, etc.
+```
+
+## Quick Start
+
+```python
+from carve import CARVE
+from sklearn.datasets import make_blobs
+
+# Generate synthetic data
+X, y_true = make_blobs(n_samples=500, n_features=10, centers=5, random_state=42)
+
+# Fit CARVE
+carve = CARVE(n_clusters=10, n_resamples=120, subsample_ratio=0.7, n_jobs=4)
+carve.fit(X)
+
+# Select best k and retrieve labels
+k = carve.get_k(measure="generalizability", rule="1se")
+labels = carve.get_labels(measure="generalizability", rule="1se")
+print(f"Selected k={k}")
+```
+
+See [`notebooks/Tutorial.ipynb`](notebooks/Tutorial.ipynb) for a walkthrough, and [`notebooks/case_studies/`](notebooks/case_studies/) for real-world analyses on scRNA-seq and mass cytometry datasets.
+
+## Visualization
+
+```python
+# Metric curves across k
+carve.plot_metric_over_n_clusters(measure="stability", rule="1se")
+
+# Consensus heatmap for the selected solution
+carve.plot_consensus_matrix(measure="generalizability", rule="1se")
+
+# Per-cluster stability violin plot
+carve.plot_cluster_violin(source="gini", measure="generalizability", rule="1se")
+
+# 2D scatter with score-encoded marker size and opacity
+carve.plot_cluster_scatter(source="gini", measure="generalizability", rule="1se")
+```
+
+All plotting methods return a matplotlib `Axes` object and accept `save` and `dpi` parameters for export.
+
+## Citation
+
+If you use CARVE in your research, please cite:
+
+> Wycik, K. R., Tang, T. M., Zikry, T. M., & Allen, G. I. (2026). *CARVE: Cluster
+> Analysis with Resampling for Validation and Exploration.* Zenodo.
+> https://doi.org/10.5281/zenodo.20448965
+
+```bibtex
+@software{wycik2026carve,
+  author    = {Wycik, Kai R. and Tang, Tiffany M. and Zikry, Tarek M. and Allen, Genevera I.},
+  title     = {{CARVE}: Cluster Analysis with Resampling for Validation and Exploration},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.20448965},
+  url       = {https://doi.org/10.5281/zenodo.20448965}
+}
+```
+
+## Authors
+
+- [Kai R. Wycik](mailto:kai.wycik@columbia.edu) — Columbia University
+- Tiffany M. Tang — University of Notre Dame
+- Tarek M. Zikry — UNC Chapel Hill
+- Genevera I. Allen — Columbia University
+
+## Contributing
+
+Contributions are welcome! Please open an [issue](https://github.com/DataSlingers/CARVE/issues) or submit a pull request.
+
+This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [pytest](https://docs.pytest.org/) for testing:
+
+```bash
+ruff check src/       # lint
+ruff format src/      # format
+pytest -v             # run tests
+```

carve_validate-1.0.0/README.md

@@ -0,0 +1,125 @@
+[![CI](https://github.com/DataSlingers/CARVE/actions/workflows/ci.yml/badge.svg)](https://github.com/DataSlingers/CARVE/actions/workflows/ci.yml)
+[![R CMD check](https://github.com/DataSlingers/CARVE/actions/workflows/r-ci.yml/badge.svg)](https://github.com/DataSlingers/CARVE/actions/workflows/r-ci.yml)
+![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)
+![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)
+
+# CARVE
+
+**Cluster Analysis with Resampling for Validation and Exploration**
+
+Choosing the number of clusters is hard, especially for high-dimensional biological data where standard internal clustering validation indices (CVIs) are often unreliable. CARVE measures clustering robustness through two resampling-based concepts: **stability** (reproducibility of cluster assignments under data subsampling) and **generalizability** (agreement between held-out cluster labels and predictions from a classifier trained on a subsample of the data). CARVE reports global, cluster-level, and sample-level diagnostics with visualizations, all through a scikit-learn-compatible API.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DataSlingers/CARVE/main/carve_overview.png" width="700" alt="CARVE overview">
+</p>
+
+## Features
+
+- Scikit-learn-compatible API: `CARVE` extends `BaseEstimator` with a `fit` / `get_labels` / `get_k` workflow
+- Stability (ARI on subsample overlap) and generalizability (ARI on held-out predictions) metrics
+- Diagnostics at the global, per-cluster, and per-sample level
+- Metrics: stability and generalizability ARIs, consensus PAC, Gini, cross-entropy, and predictive accuracy
+- Selection rules: `max`, `1se` (one-standard-error), and `quantile`
+- Custom spectral clustering with self-tuning affinity (based on Zelnik-Manor & Perona, *Self-Tuning Spectral Clustering*, NeurIPS 2004)
+- Plots: metric-over-*k* curves, consensus heatmaps, box plots, violin plots, and scatter plots
+- Parallel resampling via joblib (`n_jobs`)
+
+## Installation
+
+CARVE requires **Python 3.12**.
+
+```bash
+pip install carve-validate
+```
+
+The distribution is named `carve-validate`; the import name is `carve`:
+
+```python
+from carve import CARVE
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/DataSlingers/CARVE.git
+cd CARVE
+pip install -e ".[dev]"        # linting + testing
+pip install -e ".[notebooks]"  # Jupyter, Scanpy, scVI, etc.
+```
+
+## Quick Start
+
+```python
+from carve import CARVE
+from sklearn.datasets import make_blobs
+
+# Generate synthetic data
+X, y_true = make_blobs(n_samples=500, n_features=10, centers=5, random_state=42)
+
+# Fit CARVE
+carve = CARVE(n_clusters=10, n_resamples=120, subsample_ratio=0.7, n_jobs=4)
+carve.fit(X)
+
+# Select best k and retrieve labels
+k = carve.get_k(measure="generalizability", rule="1se")
+labels = carve.get_labels(measure="generalizability", rule="1se")
+print(f"Selected k={k}")
+```
+
+See [`notebooks/Tutorial.ipynb`](notebooks/Tutorial.ipynb) for a walkthrough, and [`notebooks/case_studies/`](notebooks/case_studies/) for real-world analyses on scRNA-seq and mass cytometry datasets.
+
+## Visualization
+
+```python
+# Metric curves across k
+carve.plot_metric_over_n_clusters(measure="stability", rule="1se")
+
+# Consensus heatmap for the selected solution
+carve.plot_consensus_matrix(measure="generalizability", rule="1se")
+
+# Per-cluster stability violin plot
+carve.plot_cluster_violin(source="gini", measure="generalizability", rule="1se")
+
+# 2D scatter with score-encoded marker size and opacity
+carve.plot_cluster_scatter(source="gini", measure="generalizability", rule="1se")
+```
+
+All plotting methods return a matplotlib `Axes` object and accept `save` and `dpi` parameters for export.
+
+## Citation
+
+If you use CARVE in your research, please cite:
+
+> Wycik, K. R., Tang, T. M., Zikry, T. M., & Allen, G. I. (2026). *CARVE: Cluster
+> Analysis with Resampling for Validation and Exploration.* Zenodo.
+> https://doi.org/10.5281/zenodo.20448965
+
+```bibtex
+@software{wycik2026carve,
+  author    = {Wycik, Kai R. and Tang, Tiffany M. and Zikry, Tarek M. and Allen, Genevera I.},
+  title     = {{CARVE}: Cluster Analysis with Resampling for Validation and Exploration},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.20448965},
+  url       = {https://doi.org/10.5281/zenodo.20448965}
+}
+```
+
+## Authors
+
+- [Kai R. Wycik](mailto:kai.wycik@columbia.edu) — Columbia University
+- Tiffany M. Tang — University of Notre Dame
+- Tarek M. Zikry — UNC Chapel Hill
+- Genevera I. Allen — Columbia University
+
+## Contributing
+
+Contributions are welcome! Please open an [issue](https://github.com/DataSlingers/CARVE/issues) or submit a pull request.
+
+This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [pytest](https://docs.pytest.org/) for testing:
+
+```bash
+ruff check src/       # lint
+ruff format src/      # format
+pytest -v             # run tests
+```

carve_validate-1.0.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "carve-validate"
+version = "1.0.0"
+description = "Cluster Analysis with Resampling for Validation and Exploration: stability- and generalizability-based clustering validation."
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Kai Wycik", email = "kai.wycik@columbia.edu" },
+]
+keywords = [
+  "clustering",
+  "validation",
+  "stability",
+  "consensus",
+  "scRNA-seq",
+  "scikit-learn",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "numpy>=2.0,<2.1",
+  "scipy>=1.16,<1.17",
+  "scikit-learn>=1.7.2,<1.8",
+  "pandas>=2.2,<2.3",
+  "joblib>=1.5,<1.6",
+  "tqdm>=4.67,<5",
+  "numba>=0.60,<0.61",
+  "llvmlite>=0.43,<0.44",
+  "umap-learn>=0.5.6",
+  "pynndescent>=0.5.10,<0.6",
+  "matplotlib>=3.9.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/DataSlingers/CARVE"
+Repository = "https://github.com/DataSlingers/CARVE"
+Issues = "https://github.com/DataSlingers/CARVE/issues"
+
+[project.optional-dependencies]
+dev = [
+  "ruff",
+  "pytest",
+  "pytest-cov",
+]
+notebooks = [
+  "jupyterlab>=4.2,<5",
+  "ipykernel>=6.29,<7",
+  "ipywidgets>=8.1.7",
+  "plotly>=6.3.0",
+  "rpy2>=3.6.3",
+  "pyreadr>=0.5.3",
+  "scanpy>=1.11.4",
+  "scikit-misc>=0.5.1",
+  "anywidget>=0.9.18",
+  "igraph>=1.0.0",
+  "leidenalg>=0.11.0",
+  "pyteomics>=4.7.5",
+  "lxml>=6.0.2",
+  "scvi>=0.6.8",
+  "cmap>=0.7.0",
+  "glasbey>=0.3.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["carve.sim", "carve.sim.*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["carve"]
+omit = ["*/carve/sim/*"]
+
+[tool.coverage.report]
+show_missing = true
+
+[dependency-groups]
+dev = [
+    "optuna>=4.8.0",
+]

carve_validate-1.0.0/setup.cfg

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

carve_validate-1.0.0/src/carve/__init__.py

@@ -0,0 +1,8 @@
+"""CARVE: Cluster Analysis with Resampling for Validation and Exploration."""
+
+__version__ = "1.0.0"
+
+from .api import CARVE
+from .cluster import SpectralClusteringCARVE
+
+__all__ = ["__version__", "CARVE", "SpectralClusteringCARVE"]

carve_validate-1.0.0/src/carve/_accuracy.py

@@ -0,0 +1,42 @@
+"""Accuracy-based generalizability metrics."""
+
+import numpy as np
+
+from ._utils import align_cluster_labels
+
+# (sample_indices, true_labels, predicted_labels) triple from a prediction run
+PredictionRun = tuple[np.ndarray, np.ndarray, np.ndarray]
+
+
+def compute_generalizability_scores(
+    n_samples: int,
+    runs: list[PredictionRun],
+) -> np.ndarray:
+    """Compute per-sample generalizability from prediction runs.
+
+    Parameters
+    ----------
+    n_samples : int
+        Total number of samples in the original dataset.
+    runs : list of tuple
+        Each run is (sample_indices, true_labels, predicted_labels).
+
+    Returns
+    -------
+    scores : ndarray of shape (n_samples,)
+        Per-sample accuracy across available runs. Samples never evaluated
+        receive score 0.
+    """
+    correct = np.zeros(n_samples, int)
+    total = np.zeros(n_samples, int)
+
+    for sample_idx, true_labels, predicted_labels in runs:
+        aligned_predictions = align_cluster_labels(true_labels, predicted_labels)
+        correct_mask = (true_labels == aligned_predictions).astype(int)
+        np.add.at(correct, sample_idx, correct_mask)
+        np.add.at(total, sample_idx, 1)
+
+    out = np.zeros(n_samples, float)
+    valid = total > 0
+    out[valid] = correct[valid] / total[valid]
+    return out

carve_validate-1.0.0/src/carve/_consensus.py

@@ -0,0 +1,213 @@
+"""Consensus matrix utilities and stability metrics.
+
+This module builds consensus matrices from repeated clustering runs and
+derives stability statistics such as Gini, cross-entropy, and PAC.
+"""
+
+import numpy as np
+from scipy.cluster.hierarchy import linkage, leaves_list
+from scipy.spatial.distance import squareform
+
+# (sample_indices, labels) pair from a single clustering run
+SampledLabels = tuple[np.ndarray, np.ndarray]
+
+
+def compute_consensus_matrix(
+    n_samples: int,
+    runs: list[SampledLabels],
+    *,
+    return_counts: bool = False,
+) -> np.ndarray | tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Compute a consensus matrix from resampled clustering runs.
+
+    Parameters
+    ----------
+    n_samples : int
+        Total number of samples in the original dataset.
+    runs : list of tuple of (ndarray, ndarray)
+        Each run is (sample_indices, labels), where ``sample_indices`` are
+        integer indices into the original dataset and ``labels`` are cluster
+        assignments for those indices.
+    return_counts : bool, default=False
+        If True, also return raw co-cluster and co-sample counts.
+
+    Returns
+    -------
+    consensus_matrix : ndarray of shape (n_samples, n_samples)
+        Fraction of times each sample pair co-clustered when co-sampled.
+        Pairs never co-sampled are set to NaN.
+    co_cluster_counts : ndarray of shape (n_samples, n_samples)
+        Raw counts of co-clustering across runs (only if ``return_counts``).
+    co_sample_counts : ndarray of shape (n_samples, n_samples)
+        Raw counts of co-sampling across runs (only if ``return_counts``).
+    """
+    # co_cluster_counts = np.zeros((n_samples, n_samples), dtype=float)
+    # co_sample_counts = np.zeros((n_samples, n_samples), dtype=float)
+
+    # for sample_idx, labels in runs:
+    # co_sample_counts[np.ix_(sample_idx, sample_idx)] += 1
+
+    # for label in np.unique(labels):
+    #     label_idx = sample_idx[labels == label]
+    #     co_cluster_counts[np.ix_(label_idx, label_idx)] += 1
+
+    N = sum(len(np.unique(labels)) for _, labels in runs)
+
+    S = np.zeros((n_samples, len(runs)), dtype=np.float32)
+    B = np.zeros((n_samples, N), dtype=np.float32)
+
+    col = 0
+    for r, (sample_idx, labels) in enumerate(runs):
+        S[sample_idx, r] = 1
+        for label in np.unique(labels):
+            members = sample_idx[labels == label]
+            B[members, col] = 1
+            col += 1
+
+    co_sample_counts = S @ S.T
+    co_cluster_counts = B @ B.T
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        consensus_matrix = co_cluster_counts / co_sample_counts
+    consensus_matrix[co_sample_counts == 0] = np.nan
+
+    if return_counts:
+        return consensus_matrix, co_cluster_counts, co_sample_counts
+    else:
+        return consensus_matrix
+
+
+def reorder_consensus_matrix(
+    consensus_matrix: np.ndarray,
+    *,
+    fill_nan_for_order: float = 0.0,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Reorder a consensus matrix by hierarchical clustering of distances.
+
+    Parameters
+    ----------
+    consensus_matrix : ndarray of shape (n_samples, n_samples)
+        Consensus matrix with values in [0, 1] and NaNs for never-sampled pairs.
+    fill_nan_for_order : float, default=0.0
+        Value used to replace NaNs when computing the clustering order only.
+
+    Returns
+    -------
+    reordered : ndarray of shape (n_samples, n_samples)
+        Consensus matrix reordered by dendrogram leaves.
+    order : ndarray of shape (n_samples,)
+        The permutation of indices applied to rows and columns.
+    """
+    matrix_for_order = np.nan_to_num(consensus_matrix, nan=fill_nan_for_order)
+    distances = squareform(1.0 - matrix_for_order, checks=False)
+    linkage_matrix = linkage(distances, method="average")
+    order = leaves_list(linkage_matrix)
+
+    return consensus_matrix[np.ix_(order, order)], order
+
+
+def compute_consensus_metrics(
+    consensus_matrices: list[np.ndarray],
+) -> tuple[list[np.ndarray], list[np.ndarray], list[float]]:
+    """Compute stability metrics for multiple consensus matrices.
+
+    Parameters
+    ----------
+    consensus_matrices : list of ndarray
+        Consensus matrices to evaluate.
+
+    Returns
+    -------
+    gini_list : list of ndarray
+        Per-sample stability scores based on the Gini-style statistic.
+    ce_list : list of ndarray
+        Per-sample stability scores based on cross-entropy.
+    pac_list : list of float
+        Global PAC-based stability scores (1 - PAC).
+    """
+    gini_list = []
+    ce_list = []
+    pac_list = []
+
+    for consensus_matrix in consensus_matrices:
+        s_gini, s_ce = stability_from_consensus(consensus_matrix)
+        pac = compute_consensus_pac(consensus_matrix)
+
+        gini_list.append(s_gini)
+        ce_list.append(s_ce)
+        pac_list.append(pac)
+
+    return gini_list, ce_list, pac_list
+
+
+def stability_from_consensus(
+    consensus_matrix: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute per-sample stability scores from a consensus matrix.
+
+    Parameters
+    ----------
+    consensus_matrix : ndarray of shape (n_samples, n_samples)
+        Consensus matrix with values in [0, 1] and NaNs for never-sampled pairs.
+
+    Returns
+    -------
+    stability_gini : ndarray of shape (n_samples,)
+        Gini-based stability score per sample in [0, 1].
+    stability_ce : ndarray of shape (n_samples,)
+        Cross-entropy-based stability score per sample in [0, 1].
+    """
+    consensus_probs = np.array(consensus_matrix, dtype=float, copy=True)
+    np.fill_diagonal(consensus_probs, np.nan)
+
+    term = consensus_probs * (1.0 - consensus_probs)
+
+    clipped = np.clip(consensus_probs, 1e-12, 1.0 - 1e-12)
+    entropy = -(clipped * np.log(clipped) + (1.0 - clipped) * np.log(1.0 - clipped))
+
+    # Gini uncertainty in [0, 0.5]; CE uncertainty in [0, log2]
+    uncertainty_gini = 2.0 * np.nanmean(term, axis=1)
+    uncertainty_ce = np.nanmean(entropy, axis=1)
+
+    # Rescale to [0, 1] stability scores
+    stability_gini = 1.0 - np.clip(2.0 * uncertainty_gini, 0.0, 1.0)
+    stability_ce = 1.0 - np.clip(uncertainty_ce / np.log(2.0), 0.0, 1.0)
+
+    return stability_gini, stability_ce
+
+
+def compute_consensus_pac(
+    consensus_matrix: np.ndarray,
+    *,
+    tau: float = 0.05,
+) -> float:
+    """Compute PAC-based stability score from a consensus matrix.
+
+    PAC measures the proportion of ambiguous consensus values in
+    (tau, 1-tau). This function returns 1 - PAC so that larger values
+    indicate greater stability.
+
+    Parameters
+    ----------
+    consensus_matrix : ndarray of shape (n_samples, n_samples)
+        Consensus matrix with values in [0, 1] and NaNs for never-sampled pairs.
+    tau : float, default=0.05
+        Ambiguity threshold defining the PAC interval.
+
+    Returns
+    -------
+    score : float
+        Stability score in [0, 1], or NaN if no valid pairs exist.
+    """
+    consensus_probs = np.array(consensus_matrix, dtype=float, copy=True)
+    n_samples = consensus_probs.shape[0]
+    mask = ~np.eye(n_samples, dtype=bool)
+    values = consensus_probs[mask]
+    values = values[~np.isnan(values)]
+
+    if values.size == 0:
+        return np.nan
+
+    ambiguous = ((values > tau) & (values < (1 - tau))).sum()
+    pac = ambiguous / values.size
+    return 1.0 - pac