scCS-py 0.3.2__tar.gz

sccs_py-0.3.2/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: scCS-py
+Version: 0.3.2
+Summary: Single-cell Commitment Scores with radial star embedding
+Author: Emil Kriukov
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Requires-Dist: anndata>=0.9
+Requires-Dist: scanpy>=1.9
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.12
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: velocity
+Requires-Dist: scvelo>=0.2.5; extra == "velocity"
+Provides-Extra: enrichment
+Requires-Dist: gseapy>=1.0; extra == "enrichment"
+Provides-Extra: all
+Requires-Dist: scvelo>=0.2.5; extra == "all"
+Requires-Dist: gseapy>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-autoapi>=3.0; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"

sccs_py-0.3.2/README.md

@@ -0,0 +1,36 @@
+# scCS — Single-Cell Commitment Scores
+
+[![Documentation Status](https://readthedocs.org/projects/sccs-py/badge/?version=latest)](https://sccs-py.readthedocs.io/en/latest/)
+
+**scCS** computes RNA velocity-based commitment scores for single-cell data,
+generalizing the 2-state (homeostatic/activated) framework from
+Kriukov et al. (2025) to arbitrary k-furcations.
+
+## Installation
+
+    pip install git+https://github.com/mcrewcow/scCS.git
+
+## Quickstart
+
+    import scCS
+    import scanpy as sc
+
+    adata = sc.read_h5ad("your_data.h5ad")
+    scorer = scCS.CommitmentScorer(adata, cluster_key="cell_type")
+    result = scorer.score(compute_cell_level=True)
+    scorer.plot_star(result, color_by="fate")
+    scorer.plot_commitment_bar(result)
+
+## Key features
+
+- k-furcation support — works for any number of fate branches
+- Star embedding — radial layout with one arm per fate
+- unCS / nCS — unnormalized and cell-count-corrected commitment scores
+- Expression trends — gene expression vs commitment axis
+- Color map support — preserves your original scanpy cluster colors
+
+## Citation
+
+Kriukov et al. (2025) Single-cell transcriptome of myeloid cells in response
+to transplantation of human retinal neurons reveals reversibility of microglial
+activation. DOI: 10.XXXX

sccs_py-0.3.2/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scCS-py"
+version = "0.3.2"
+description = "Single-cell Commitment Scores with radial star embedding"
+authors = [{ name = "Emil Kriukov" }]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=1.5",
+    "scipy>=1.10",
+    "anndata>=0.9",
+    "scanpy>=1.9",
+    "matplotlib>=3.7",
+    "seaborn>=0.12",
+    "scikit-learn>=1.2",
+]
+
+[project.optional-dependencies]
+velocity = ["scvelo>=0.2.5"]
+enrichment = ["gseapy>=1.0"]
+all = ["scvelo>=0.2.5", "gseapy>=1.0"]
+dev = ["pytest>=7.0", "pytest-cov"]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-autoapi>=3.0",
+    "furo",
+    "numpydoc",
+    "nbsphinx",
+    "ipykernel",
+]
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sccs_py-0.3.2/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_py-0.3.2/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