carve-validate 1.0.0__py3-none-any.whl

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/_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/_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

carve/_grids.py

@@ -0,0 +1,153 @@
+"""Default estimator and preprocessing grids for CARVE."""
+
+from typing import Literal
+
+import numpy as np
+from sklearn.cluster import KMeans, AgglomerativeClustering
+from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+from sklearn.neighbors import NearestNeighbors
+from sklearn.preprocessing import FunctionTransformer, StandardScaler
+from umap import UMAP
+
+from .cluster import SpectralClusteringCARVE
+from ._types import GridSpec, PreprocSpec
+
+
+def estimate_knn_gamma(
+    X: np.ndarray,
+    n_neighbors: int = 7,
+    multipliers: tuple[float, ...] = (0.5, 1.0, 2.0),
+) -> list[float]:
+    """Estimate RBF gamma values using a k-NN median heuristic.
+
+    Fits a NearestNeighbors model, takes the k-th neighbor distance for
+    each point, computes sigma = median(kth_distances), and returns
+    gamma = 1 / (2 * (m * sigma)^2) for each multiplier m.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n_samples, n_features)
+        Input data.
+    n_neighbors : int, default=7
+        Number of neighbors.
+    multipliers : tuple of float, default=(0.5, 1.0, 2.0)
+        Scale multipliers applied to sigma.
+
+    Returns
+    -------
+    gammas : list of float
+        Gamma values spanning a range around the local scale.
+    """
+    nn = NearestNeighbors(n_neighbors=n_neighbors)
+    nn.fit(X)
+    dists, _ = nn.kneighbors(X)
+    kth_dists = dists[:, -1]
+    sigma = float(np.median(kth_dists))
+    if sigma <= 0:
+        sigma = (
+            float(np.mean(kth_dists[kth_dists > 0])) if np.any(kth_dists > 0) else 1.0
+        )
+    return [float(1.0 / (2.0 * (m * sigma) ** 2)) for m in multipliers]
+
+
+def default_estimator_grids(
+    X: np.ndarray,
+    n_clusters: int | np.ndarray = 10,
+    preset: Literal["light", "full"] = "light",
+) -> list[GridSpec]:
+    """Return default clustering estimator grids.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n_samples, n_features)
+        Input data used to derive data-driven hyperparameters (e.g., gamma).
+    n_clusters : int or ndarray, default=10
+        Number(s) of clusters to evaluate.
+    preset : {"light", "full"}, default="light"
+        ``"light"`` includes KMeans, Ward-linkage agglomerative, and
+        self-tuning spectral clustering. ``"full"`` adds average- and
+        single-linkage agglomerative clustering and RBF-kernel spectral
+        clustering with data-driven gamma.
+
+    Returns
+    -------
+    grids : list of tuple
+        List of (EstimatorClass, param_grid) tuples suitable for
+        ``sklearn.model_selection.ParameterGrid``.
+    """
+    ks = list(np.asarray(n_clusters).tolist())
+
+    grids: list[GridSpec] = [
+        (KMeans, {"n_clusters": ks}),
+        (AgglomerativeClustering, {"n_clusters": ks, "linkage": ["ward"]}),
+        (SpectralClusteringCARVE, {"n_clusters": ks, "affinity": ["self_tuning"]}),
+    ]
+
+    if preset == "full":
+        grids.append(
+            (
+                AgglomerativeClustering,
+                {"n_clusters": ks, "linkage": ["average", "single", "complete"]},
+            ),
+        )
+
+        grids.append(
+            (
+                SpectralClusteringCARVE,
+                {"n_clusters": ks, "affinity": ["rbf"], "gamma": estimate_knn_gamma(X)},
+            ),
+        )
+
+    return grids
+
+
+def default_normalization_options() -> list[PreprocSpec]:
+    """Return default normalization preprocessing options.
+
+    Returns
+    -------
+    options : list of tuple
+        List of (TransformerClass, param_grid) pairs.
+    """
+    return [
+        (FunctionTransformer, {}),
+        (StandardScaler, {}),
+        (FunctionTransformer, {"func": [np.log1p]}),
+    ]
+
+
+def default_dim_reduction_options(
+    X: np.ndarray,
+    subsample_ratio: float = 0.6,
+) -> list[PreprocSpec]:
+    """Return default dimensionality reduction options.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n_samples, n_features)
+        Input data used to determine feasible component counts.
+    subsample_ratio : float, default=0.6
+        Subsample ratio used in validation; constrains DR hyperparameters.
+
+    Returns
+    -------
+    options : list of tuple
+        List of (TransformerClass, param_grid) pairs.
+    """
+    n_samples, p = X.shape
+    min_n = int(round(n_samples * (1 - subsample_ratio))) - 1
+
+    return [
+        (FunctionTransformer, {}),
+        (PCA, {"n_components": list(range(2, min(min_n, p)))}),
+        (TSNE, {"n_components": [2], "perplexity": list(range(5, min(min_n, 51)))}),
+        (
+            UMAP,
+            {
+                "n_components": list(range(2, min(min_n, p))),
+                "n_neighbors": list(range(5, 51)),
+                "min_dist": [0.1],
+            },
+        ),
+    ]

carve/_output.py

@@ -0,0 +1,132 @@
+"""Console output helpers for CARVE runs."""
+
+import numpy as np
+import pandas as pd
+from typing import Any
+from sklearn.base import ClusterMixin
+from sklearn.model_selection import ParameterGrid
+from tqdm.auto import tqdm
+
+from ._types import EstimatorRecord, GridSpec
+
+
+def _print_run_header(
+    X: np.ndarray,
+    n_clusters: int | np.ndarray,
+    n_resamples: int,
+    subsample_ratio: float,
+    estimator_grids: list[GridSpec],
+    n_jobs: int,
+    randomize_preprocessing: bool,
+    random_state: int | None,
+    verbose: int,
+) -> None:
+    """Print a standard header describing the validation configuration.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n_samples, n_features)
+        Input data.
+    n_clusters : int or ndarray
+        Number(s) of clusters evaluated.
+    n_resamples : int
+        Number of resampling iterations.
+    subsample_ratio : float
+        Proportion of samples in each subsample.
+    estimator_grids : list of tuple
+        Estimator classes and parameter grids.
+    n_jobs : int
+        Parallelism used for runs.
+    randomize_preprocessing : bool
+        Whether preprocessing is randomized.
+    random_state : int or None
+        Random seed.
+    verbose : int
+        Verbosity level; prints only if >= 2.
+    """
+    if verbose < 2:
+        return
+
+    total_configs = sum(len(ParameterGrid(g)) for _, g in estimator_grids)
+    line = "=" * 60
+
+    print(f"[CARVE] {line}")
+    print("[CARVE] Validation Settings:")
+    print(f"[CARVE] n_samples          : {X.shape[0]}")
+    print(f"[CARVE] n_features         : {X.shape[1]}")
+    print(f"[CARVE] n_clusters         : {n_clusters}")
+    print(f"[CARVE] n_resamples        : {n_resamples}")
+    print(f"[CARVE] subsample_ratio    : {subsample_ratio}")
+    print(f"[CARVE] n_jobs             : {n_jobs}")
+    print(f"[CARVE] total configs      : {total_configs}")
+    print(f"[CARVE] randomize_preproc  : {randomize_preprocessing}")
+    print(f"[CARVE] random_state       : {random_state}")
+    print(f"[CARVE] {line}")
+    print("\n[CARVE] Starting validation ...\n")
+
+
+def _print_run_footer(
+    estimator_df: pd.DataFrame,
+    verbose: int,
+) -> None:
+    """Print a standard footer after validation completes.
+
+    Parameters
+    ----------
+    estimator_df : pandas.DataFrame
+        Results table with one row per estimator configuration.
+    verbose : int
+        Verbosity level; prints only if >= 2.
+    """
+    if verbose < 2:
+        return
+    print(
+        f"\n[CARVE] finished. evaluated {len(estimator_df)} estimator configurations."
+    )
+
+
+def _log_config_progress(
+    config_idx: int,
+    total_configs: int,
+    est_class: type[ClusterMixin],
+    params: dict[str, Any],
+    record: EstimatorRecord,
+    pbar_obj: tqdm | None,
+    verbose: int = 0,
+) -> None:
+    """Log per-configuration progress during grid evaluation.
+
+    Parameters
+    ----------
+    config_idx : int
+        1-based index of the current configuration.
+    total_configs : int
+        Total number of configurations in the grid.
+    est_class : type
+        Estimator class being evaluated.
+    params : dict
+        Hyperparameters for the current configuration.
+    record : dict
+        Metrics for the current configuration.
+    pbar_obj : tqdm or None
+        Optional progress-bar object used to display messages.
+    verbose : int, default=0
+        Verbosity level; logs only if >= 1.
+    """
+    if verbose <= 0:
+        return
+
+    n_clusters = params.get("n_clusters", "?")
+    msg = (
+        f"[CARVE] [{config_idx}/{total_configs}] "
+        f"est={est_class.__name__} "
+        f"n_clusters={n_clusters} | "
+        f"ARI_stab={record['ari_stability']:.3f}±{record['ari_stability_se']:.3f}  "
+        f"ARI_gen={record['ari_generalizability']:.3f}±{record['ari_generalizability_se']:.3f}  "
+        # f"ARI_avg={record['ari_average']:.3f}±{record['ari_average_se']:.3f}"
+    )
+
+    if pbar_obj is not None:
+        pbar_obj.write(msg)
+    else:
+        print(msg)