scCS-py 0.3.2__py3-none-any.whl

scCS/__init__.py

@@ -0,0 +1,154 @@
+"""
+scCS — Single-cell Commitment Scores with radial star embedding.
+
+Generalizes the 2-state commitment score framework from:
+
+    Kriukov et al. (2025) "Single-cell transcriptome of myeloid cells in
+    response to transplantation of human retinal neurons reveals reversibility
+    of microglial activation"
+
+to any number of cell fates (k-furcations), with:
+- User-supplied bifurcation cluster (e.g., leiden cluster '17')
+- Radial star embedding: progenitor at origin, each fate on its own arm
+- Cells ordered along arms by differentiation metric (pseudotime,
+  CytoTRACE2, pathway score, or any custom per-cell score)
+- Population-level scores: unCS, nCS, commitment vector, entropy
+- Per-cell fate affinity scores
+
+Quick start
+-----------
+>>> import scCS
+>>> scorer = scCS.CommitmentScorer(
+...     adata,
+...     bifurcation_cluster='17',          # leiden cluster at the bifurcation
+...     terminal_cell_types=['FateA', 'FateB', 'FateC'],
+...     cluster_key='leiden',
+... )
+>>> scorer.build_embedding(differentiation_metric='pseudotime')
+>>> scorer.fit()
+>>> result = scorer.score()
+>>> print(result.summary())
+>>> scorer.plot_star(result)
+
+For k=2 (reproducing manuscript):
+>>> scorer = scCS.CommitmentScorer(
+...     adata,
+...     bifurcation_cluster='17',
+...     terminal_cell_types=['homeostatic', 'activated'],
+...     cluster_key='leiden',
+... )
+>>> scorer.build_embedding(differentiation_metric='pseudotime')
+>>> scorer.fit()
+>>> result = scorer.score()
+>>> # result.pairwise_nCS[0, 1] should be ~8.066 (manuscript value)
+"""
+
+__version__ = "0.3.2"
+__author__ = "Emil Kriukov"
+
+# Main API
+from .trajectory import CommitmentScorer
+
+# Fate map
+from .bifurcation import FateMap, build_fate_map
+
+# Embedding
+from .embedding import (
+    build_star_embedding,
+    project_velocity_star,
+    run_velocity_pipeline,
+)
+
+# Core math (for advanced users)
+from .scores import (
+    CommitmentScoreResult,
+    compute_magnitudes,
+    compute_angles,
+    bin_angles,
+    equal_sectors,
+    centroid_sectors,
+    compute_sector_magnitudes,
+    compute_unCS,
+    compute_nCS,
+    compute_commitment_vector,
+    # Entropy
+    compute_population_entropy,      # aggregate velocity-mass entropy
+    compute_mean_cell_entropy,       # mean per-cell k-way entropy
+    compute_per_fate_cell_entropy,   # per-fate binary cell entropy, shape (k,)
+    compute_nn_cell_entropy,         # NN-smoothed per-cell entropy, shape (n_cells,)
+    compute_commitment_entropy,      # backward-compat alias for compute_population_entropy
+    compute_pairwise_cs_matrix,
+    compute_cell_scores,
+)
+
+# Driver genes
+from .drivers import (
+    get_velocity_drivers,
+    get_deg_drivers,
+)
+
+# Pathway enrichment
+from .enrichment import (
+    run_enrichment_per_fate,
+    export_enrichment_tables,
+)
+
+# Plotting
+from .plot import (
+    plot_star_embedding,
+    plot_star_panels,
+    plot_rose,
+    plot_pairwise_cs,
+    plot_commitment_bar,
+    plot_commitment_heatmap,
+    plot_subset_comparison,
+    plot_expression_trends,
+    plot_nn_entropy_elbow,
+)
+
+__all__ = [
+    # Main class
+    "CommitmentScorer",
+    # Fate map
+    "FateMap",
+    "build_fate_map",
+    # Embedding
+    "build_star_embedding",
+    "project_velocity_star",
+    "run_velocity_pipeline",
+    # Results
+    "CommitmentScoreResult",
+    # Core math
+    "compute_magnitudes",
+    "compute_angles",
+    "bin_angles",
+    "equal_sectors",
+    "centroid_sectors",
+    "compute_sector_magnitudes",
+    "compute_unCS",
+    "compute_nCS",
+    "compute_commitment_vector",
+    "compute_population_entropy",
+    "compute_mean_cell_entropy",
+    "compute_per_fate_cell_entropy",
+    "compute_nn_cell_entropy",
+    "compute_commitment_entropy",   # backward-compat alias
+    "compute_pairwise_cs_matrix",
+    "compute_cell_scores",
+    # Driver genes
+    "get_velocity_drivers",
+    "get_deg_drivers",
+    # Pathway enrichment
+    "run_enrichment_per_fate",
+    "export_enrichment_tables",
+    # Plots
+    "plot_star_embedding",
+    "plot_star_panels",
+    "plot_rose",
+    "plot_pairwise_cs",
+    "plot_commitment_bar",
+    "plot_commitment_heatmap",
+    "plot_subset_comparison",
+    "plot_expression_trends",
+    "plot_nn_entropy_elbow",
+]

scCS/bifurcation.py

@@ -0,0 +1,226 @@
+"""
+bifurcation.py — Cluster-level fate map construction for scCS.
+
+In scCS, the bifurcation point is explicitly defined by the user as a
+single cluster (e.g., leiden cluster '17').  There is no automatic
+fate detection — the user supplies:
+
+    bifurcation_cluster  : the progenitor/root cluster label
+    terminal_cell_types  : list of terminal fate cluster labels
+
+This module builds a standardized FateMap from those labels, computing
+centroids in the scCS star embedding space (X_sccs) and collecting
+per-fate cell indices.
+
+The FateMap is the single source of truth consumed by CommitmentScorer.score().
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import List, Optional
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# FateMap dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FateMap:
+    """Standardized description of k cell fates for commitment scoring.
+
+    Attributes
+    ----------
+    bifurcation_cluster : str
+        Label of the progenitor/root cluster supplied by the user.
+    fate_names : list of str
+        Human-readable labels for each terminal fate (length k).
+    fate_centroids : np.ndarray, shape (k, 2)
+        Mean 2D position of each fate's cells in the scCS embedding.
+    root_centroid : np.ndarray, shape (2,)
+        Mean 2D position of the bifurcation cluster cells.
+        In the scCS star embedding this is always near (0, 0).
+    root_cells : np.ndarray of int
+        Indices of bifurcation cluster cells in adata.
+    fate_cell_indices : list of np.ndarray
+        Per-fate arrays of cell indices.
+    arm_angles_deg : np.ndarray, shape (k,)
+        Angle (degrees) of each fate's radial arm in the star embedding.
+    cluster_key : str
+        The obs column used for cluster labels.
+    k : int
+        Number of fates (read-only property).
+    """
+    bifurcation_cluster: str
+    fate_names: List[str]
+    fate_centroids: np.ndarray
+    root_centroid: np.ndarray
+    root_cells: np.ndarray
+    fate_cell_indices: List[np.ndarray]
+    arm_angles_deg: np.ndarray
+    cluster_key: str
+
+    @property
+    def k(self) -> int:
+        return len(self.fate_names)
+
+    def summary(self) -> str:
+        lines = [
+            f"FateMap  (bifurcation_cluster='{self.bifurcation_cluster}', k={self.k})",
+            f"  Cluster key : '{self.cluster_key}'",
+            f"  Root cells  : {len(self.root_cells)}",
+            f"  Root centroid: ({self.root_centroid[0]:.3f}, {self.root_centroid[1]:.3f})",
+        ]
+        for j, name in enumerate(self.fate_names):
+            n = len(self.fate_cell_indices[j])
+            c = self.fate_centroids[j]
+            a = self.arm_angles_deg[j]
+            lines.append(
+                f"  Fate {j}: '{name}'  n_cells={n}  "
+                f"centroid=({c[0]:.2f}, {c[1]:.2f})  arm_angle={a:.1f}°"
+            )
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# FateMap construction
+# ---------------------------------------------------------------------------
+
+def build_fate_map(
+    adata,
+    bifurcation_cluster: str,
+    terminal_cell_types: List[str],
+    cluster_key: str = "leiden",
+    verbose: bool = True,
+) -> FateMap:
+    """Build a FateMap from user-supplied cluster labels.
+
+    This is the only fate-detection strategy in scCS.  The user explicitly
+    names the bifurcation cluster and all terminal fate clusters.
+
+    Parameters
+    ----------
+    adata : AnnData
+        Must have X_sccs in obsm (built by build_star_embedding).
+    bifurcation_cluster : str
+        Label of the progenitor cluster in adata.obs[cluster_key].
+        Example: '17'  (leiden cluster 17)
+    terminal_cell_types : list of str
+        Labels of the k terminal fate clusters.
+        Example: ['Monocyte', 'DC', 'Neutrophil']
+    cluster_key : str
+        Column in adata.obs with cluster labels.
+    verbose : bool
+
+    Returns
+    -------
+    FateMap
+    """
+    if "X_sccs" not in adata.obsm:
+        raise ValueError(
+            "X_sccs embedding not found in adata.obsm. "
+            "Run CommitmentScorer.build_embedding() before build_fate_map()."
+        )
+
+    obs_labels = adata.obs[cluster_key].astype(str).values
+    embedding = np.array(adata.obsm["X_sccs"])
+
+    # --- Validate bifurcation cluster ---
+    bif_mask = obs_labels == str(bifurcation_cluster)
+    if bif_mask.sum() == 0:
+        available = sorted(set(obs_labels))
+        raise ValueError(
+            f"Bifurcation cluster '{bifurcation_cluster}' not found in "
+            f"adata.obs['{cluster_key}']. "
+            f"Available labels: {available}"
+        )
+    root_cells = np.where(bif_mask)[0]
+    root_centroid = embedding[root_cells].mean(axis=0)
+
+    if verbose:
+        print(
+            f"[scCS] Bifurcation cluster '{bifurcation_cluster}': "
+            f"{len(root_cells)} cells, "
+            f"centroid=({root_centroid[0]:.2f}, {root_centroid[1]:.2f})"
+        )
+
+    # --- Validate and collect terminal fates ---
+    fate_names = []
+    fate_centroids = []
+    fate_cell_indices = []
+    skipped = []
+
+    for name in terminal_cell_types:
+        mask = obs_labels == str(name)
+        n = mask.sum()
+        if n == 0:
+            warnings.warn(
+                f"Terminal fate '{name}' not found in adata.obs['{cluster_key}']. "
+                "Skipping.",
+                stacklevel=2,
+            )
+            skipped.append(name)
+            continue
+        idx = np.where(mask)[0]
+        fate_names.append(str(name))
+        fate_cell_indices.append(idx)
+        fate_centroids.append(embedding[idx].mean(axis=0))
+
+        if verbose:
+            c = embedding[idx].mean(axis=0)
+            print(f"[scCS]   Fate '{name}': {n} cells, centroid=({c[0]:.2f}, {c[1]:.2f})")
+
+    if len(fate_names) == 0:
+        raise ValueError(
+            "No valid terminal fate clusters found. "
+            f"Skipped: {skipped}"
+        )
+
+    if skipped:
+        warnings.warn(
+            f"Skipped {len(skipped)} fate(s) not found in data: {skipped}",
+            stacklevel=2,
+        )
+
+    fate_centroids = np.array(fate_centroids)
+
+    # --- Retrieve arm angles from embedding metadata ---
+    # build_star_embedding stores these in adata.uns['sccs']
+    sccs_meta = adata.uns.get("sccs", {})
+    stored_fates = sccs_meta.get("fate_names", [])
+    stored_angles = sccs_meta.get("arm_angles_deg", None)
+
+    arm_angles_deg = np.zeros(len(fate_names))
+    if stored_angles is not None and len(stored_fates) == len(stored_angles):
+        fate_to_angle = dict(zip(stored_fates, stored_angles))
+        for j, name in enumerate(fate_names):
+            if name in fate_to_angle:
+                arm_angles_deg[j] = fate_to_angle[name]
+            else:
+                # Compute from centroid direction
+                delta = fate_centroids[j] - root_centroid
+                arm_angles_deg[j] = np.degrees(np.arctan2(delta[1], delta[0])) % 360.0
+    else:
+        # Compute from centroid directions
+        for j in range(len(fate_names)):
+            delta = fate_centroids[j] - root_centroid
+            arm_angles_deg[j] = np.degrees(np.arctan2(delta[1], delta[0])) % 360.0
+
+    fate_map = FateMap(
+        bifurcation_cluster=str(bifurcation_cluster),
+        fate_names=fate_names,
+        fate_centroids=fate_centroids,
+        root_centroid=root_centroid,
+        root_cells=root_cells,
+        fate_cell_indices=fate_cell_indices,
+        arm_angles_deg=arm_angles_deg,
+        cluster_key=cluster_key,
+    )
+
+    if verbose:
+        print(f"[scCS] FateMap built: k={fate_map.k} fates")
+
+    return fate_map

scCS/drivers.py

@@ -0,0 +1,237 @@
+"""
+drivers.py — Driver gene identification for scCS fate arms.
+
+Two complementary strategies:
+
+1. Velocity-based drivers
+   For each fate arm, rank genes by their mean scVelo velocity in arm cells.
+   High positive velocity = gene is being actively upregulated along that fate.
+   Requires the 'velocity' layer (from scVelo pipeline).
+
+2. DEG-based drivers
+   For each fate arm, run a Wilcoxon rank-sum test comparing arm cells vs
+   the bifurcation (progenitor) cluster.  Returns logFC and adjusted p-value
+   per gene, with a significance flag.
+
+Both functions operate on adata_sub (the subset returned by build_star_embedding),
+which contains only bifurcation + terminal fate cells.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+
+# ---------------------------------------------------------------------------
+# 1. Velocity-based driver genes
+# ---------------------------------------------------------------------------
+
+def get_velocity_drivers(
+    adata_sub,
+    fate_names: List[str],
+    cluster_key: str,
+    bifurcation_cluster: str,
+    n_top: int = 50,
+) -> Dict[str, pd.DataFrame]:
+    """Rank genes by mean scVelo velocity in each fate arm's cells.
+
+    Parameters
+    ----------
+    adata_sub : AnnData
+        Subset containing only bifurcation + terminal fate cells.
+        Must have the 'velocity' layer (from scVelo).
+    fate_names : list of str
+        Terminal fate cluster labels.
+    cluster_key : str
+        Column in adata_sub.obs with cluster labels.
+    bifurcation_cluster : str
+        Label of the progenitor cluster (used for context only).
+    n_top : int
+        Number of top driver genes to print per fate.
+
+    Returns
+    -------
+    dict : fate_name -> DataFrame with columns [gene, mean_velocity, rank]
+        Sorted by mean_velocity descending (most upregulated first).
+    """
+    if "velocity" not in adata_sub.layers:
+        raise ValueError(
+            "'velocity' layer not found in adata_sub. "
+            "Run the scVelo pipeline first (scorer.compute_velocity() or "
+            "scvelo.tl.velocity())."
+        )
+
+    import scipy.sparse as sp
+
+    V_genes = adata_sub.layers["velocity"]
+    if sp.issparse(V_genes):
+        V_genes = V_genes.toarray()
+    V_genes = np.asarray(V_genes, dtype=float)  # (n_cells, n_genes)
+
+    genes = adata_sub.var_names
+    obs_labels = adata_sub.obs[cluster_key].astype(str).values
+    results: Dict[str, pd.DataFrame] = {}
+
+    for name in fate_names:
+        mask = obs_labels == str(name)
+        if mask.sum() == 0:
+            warnings.warn(
+                f"No cells found for fate '{name}' in adata_sub. Skipping.",
+                stacklevel=2,
+            )
+            continue
+
+        V_fate = V_genes[mask, :]  # (n_fate_cells, n_genes)
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            mean_vel = np.nanmean(V_fate, axis=0)
+
+        df = pd.DataFrame({
+            "gene": genes,
+            "mean_velocity": mean_vel,
+        }).dropna(subset=["mean_velocity"])
+
+        df = df.sort_values("mean_velocity", ascending=False).reset_index(drop=True)
+        df["rank"] = df.index + 1
+        results[name] = df
+
+        print(f"\n── Velocity drivers: {name} (top {n_top}) ──")
+        print(
+            df.head(n_top)[["rank", "gene", "mean_velocity"]]
+            .to_string(index=False)
+        )
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# 2. DEG-based driver genes
+# ---------------------------------------------------------------------------
+
+def get_deg_drivers(
+    adata_sub,
+    fate_names: List[str],
+    cluster_key: str,
+    bifurcation_cluster: str,
+    n_top: int = 50,
+    pval_cutoff: float = 0.05,
+    logfc_cutoff: float = 0.25,
+) -> Dict[str, pd.DataFrame]:
+    """Find DEGs for each fate arm vs the bifurcation cluster (Wilcoxon).
+
+    For each fate arm, compares arm cells against progenitor (bifurcation)
+    cells using a Wilcoxon rank-sum test via scanpy.
+
+    Parameters
+    ----------
+    adata_sub : AnnData
+        Subset containing only bifurcation + terminal fate cells.
+    fate_names : list of str
+        Terminal fate cluster labels.
+    cluster_key : str
+        Column in adata_sub.obs with cluster labels.
+    bifurcation_cluster : str
+        Label of the progenitor cluster (reference group).
+    n_top : int
+        Number of top significant DEGs to print per fate.
+    pval_cutoff : float
+        Adjusted p-value threshold for significance.
+    logfc_cutoff : float
+        Minimum absolute log fold-change for significance.
+
+    Returns
+    -------
+    dict : fate_name -> DataFrame with columns:
+        [gene, logfoldchange, pval, pval_adj, significant]
+        Sorted by logfoldchange descending.
+    """
+    try:
+        import scanpy as sc
+    except ImportError:
+        raise ImportError("scanpy is required for DEG analysis. pip install scanpy")
+
+    obs_labels = adata_sub.obs[cluster_key].astype(str).values
+    results: Dict[str, pd.DataFrame] = {}
+
+    for name in fate_names:
+        fate_mask = obs_labels == str(name)
+        bif_mask = obs_labels == str(bifurcation_cluster)
+        sub_mask = fate_mask | bif_mask
+
+        n_fate = fate_mask.sum()
+        n_bif = bif_mask.sum()
+
+        if n_fate < 5:
+            warnings.warn(
+                f"Fate '{name}' has only {n_fate} cells. "
+                "Skipping DEG analysis (need ≥5).",
+                stacklevel=2,
+            )
+            continue
+        if n_bif < 5:
+            warnings.warn(
+                f"Bifurcation cluster '{bifurcation_cluster}' has only {n_bif} cells. "
+                "Skipping DEG analysis (need ≥5).",
+                stacklevel=2,
+            )
+            continue
+
+        # Subset to fate + progenitor only for this pairwise comparison
+        adata_pair = adata_sub[sub_mask].copy()
+        adata_pair.obs["_deg_group"] = [
+            name if l == str(name) else "progenitor"
+            for l in adata_pair.obs[cluster_key].astype(str)
+        ]
+
+        try:
+            sc.tl.rank_genes_groups(
+                adata_pair,
+                groupby="_deg_group",
+                groups=[name],
+                reference="progenitor",
+                method="wilcoxon",
+                key_added="rank_genes",
+                pts=True,
+            )
+        except Exception as e:
+            warnings.warn(
+                f"rank_genes_groups failed for fate '{name}': {e}",
+                stacklevel=2,
+            )
+            continue
+
+        rg = adata_pair.uns["rank_genes"]
+        df = pd.DataFrame({
+            "gene": rg["names"][name],
+            "logfoldchange": rg["logfoldchanges"][name],
+            "pval": rg["pvals"][name],
+            "pval_adj": rg["pvals_adj"][name],
+        })
+        df["significant"] = (
+            (df["pval_adj"] < pval_cutoff)
+            & (df["logfoldchange"].abs() > logfc_cutoff)
+        )
+        df = df.sort_values("logfoldchange", ascending=False).reset_index(drop=True)
+        results[name] = df
+
+        n_sig = df["significant"].sum()
+        n_up = ((df["logfoldchange"] > logfc_cutoff) & df["significant"]).sum()
+        n_dn = ((df["logfoldchange"] < -logfc_cutoff) & df["significant"]).sum()
+
+        print(f"\n── DEG drivers: {name} vs progenitor ──")
+        print(f"   Significant: {n_sig}  (up: {n_up}, down: {n_dn})")
+        sig_df = df[df["significant"]].head(n_top)
+        if len(sig_df) > 0:
+            print(
+                sig_df[["gene", "logfoldchange", "pval_adj"]]
+                .to_string(index=False)
+            )
+        else:
+            print("   (no significant DEGs at current thresholds)")
+
+    return results