cytocommunity2 0.1.1__py3-none-any.whl

cytocommunity2/__init__.py

@@ -0,0 +1,23 @@
+"""Public Python API for CytoCommunity2."""
+
+from .config import CytoCommunityConfig
+from .learning import (
+    LearningResult,
+    SpatialGraphDataset,
+    build_spatial_graphs,
+    load_learning_result,
+    run_learning,
+)
+from .visualization import visualize_results
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "CytoCommunityConfig",
+    "LearningResult",
+    "SpatialGraphDataset",
+    "build_spatial_graphs",
+    "load_learning_result",
+    "run_learning",
+    "visualize_results",
+]

cytocommunity2/colors.py

@@ -0,0 +1,19 @@
+"""Shared categorical colors used across CytoCommunity2 figures."""
+
+
+def celltype_color_map(celltypes):
+    """Return the canonical cell-type colors in the supplied display order."""
+    import matplotlib.pyplot as plt
+
+    palette = []
+    for name in ("tab20", "tab20b", "tab20c", "Set1", "Dark2", "Accent", "Paired"):
+        cmap = plt.get_cmap(name)
+        palette.extend(
+            list(cmap.colors)
+            if hasattr(cmap, "colors")
+            else [cmap(index / 255) for index in range(256)]
+        )
+    return {
+        celltype: palette[index]
+        for index, celltype in enumerate(celltypes)
+    }

cytocommunity2/config.py

@@ -0,0 +1,136 @@
+"""Central configuration loading and validation for CytoCommunity2."""
+
+import json
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+
+DEFAULT_CONFIG_FILE = "hyperparameters.json"
+INPUT_DIR_NAME = "TNBC_Input_pCR"
+
+# Established analysis rules stay stable across runs; only experimental choices
+# belong in hyperparameters.json.
+FIXED_DOWNSTREAM = {
+    "dominant_cell_type": {"frequency_threshold": 0.5},
+    "differential_composed": {"p_value_threshold": 0.05},
+    "moran": {
+        "minimum_positive_count": 2,
+        "minimum_cn_cells": 10,
+        "p_value_threshold": 0.05,
+    },
+    "communication": {
+        "minimum_samples": 3,
+        "permutation_max_attempt_multiplier": 20,
+        "spearman_p_threshold": 0.05,
+        "permutation_p_threshold": 0.05,
+        "cca_p_threshold": 0.05,
+        "cca_minimum_common_samples": 3,
+        "cca_minimum_abs_rho": 0.0,
+        "cca_sd_epsilon": 1e-8,
+        "cca_max_iterations": 1000,
+    },
+}
+
+
+@dataclass(frozen=True)
+class MainConfig:
+    knn_k: int
+    cn_num_min: int
+    cn_num_max: int
+    final_num_runs: int
+    num_epoch: int
+    embedding_dimension: int
+    learning_rate: float
+    mini_batch_size: int
+    beta: float
+
+
+@dataclass(frozen=True)
+class EnrichmentConfig:
+    p_value_threshold: float = 0.05
+    minimum_adjusted_p: float = 1e-20
+
+
+@dataclass(frozen=True)
+class RecurrenceConfig:
+    recurrence_p_threshold: float = 0.05
+    null_draws: int = 10000
+
+
+@dataclass(frozen=True)
+class VisualizationConfig:
+    point_size: float = 2.0
+
+
+@dataclass(frozen=True)
+class CytoCommunityConfig:
+    config_file: Path
+    project_root: Path
+    input_dir: Path
+    random_seed: int
+    main: MainConfig
+    enrichment: EnrichmentConfig
+    recurrence: RecurrenceConfig
+    visualization: VisualizationConfig
+    downstream: Mapping[str, Any]
+
+    @property
+    def celltype_order(self):
+        groups = self.downstream["dominant_cell_type"]["cell_type_groups"]
+        return [cell_type for group in groups.values() for cell_type in group]
+
+    @classmethod
+    def from_json(cls, config_file=None):
+        """Load and validate a JSON configuration file."""
+        return _load_config(config_file, config_class=cls)
+
+
+def _require_keys(values, required, section):
+    missing = [key for key in required if key not in values]
+    if missing:
+        raise ValueError(f"Missing configuration keys in {section}: {missing}")
+
+
+def _load_config(config_file=None, config_class=CytoCommunityConfig):
+    """Load one configuration file and use the adjacent TNBC input folder."""
+    config_file = Path(config_file or DEFAULT_CONFIG_FILE).expanduser().resolve()
+    raw = json.loads(config_file.read_text(encoding="utf-8"))
+    _require_keys(raw, ["random_seed", "main", "downstream"], "root")
+
+    project_root = config_file.parent
+    input_dir = project_root / INPUT_DIR_NAME
+
+    main = MainConfig(**raw["main"])
+    enrichment = EnrichmentConfig()
+    recurrence = RecurrenceConfig()
+    visualization = VisualizationConfig(**raw.get("visualization", {}))
+    downstream = dict(raw["downstream"])
+    for section, fixed_values in FIXED_DOWNSTREAM.items():
+        downstream[section] = {**downstream.get(section, {}), **fixed_values}
+
+    if main.knn_k < 1:
+        raise ValueError("main.knn_k must be positive")
+    if main.cn_num_min < 1 or main.cn_num_min > main.cn_num_max:
+        raise ValueError("Require 1 <= main.cn_num_min <= main.cn_num_max")
+    if main.final_num_runs < 1 or main.num_epoch < 1:
+        raise ValueError("Run and epoch counts must be positive")
+    if main.embedding_dimension < 1 or main.mini_batch_size < 1:
+        raise ValueError("Embedding dimension and mini-batch size must be positive")
+    if main.learning_rate <= 0 or not 0 <= main.beta <= 1:
+        raise ValueError("Learning rate must be positive and beta must be in [0, 1]")
+    if not math.isfinite(visualization.point_size) or visualization.point_size <= 0:
+        raise ValueError("visualization.point_size must be finite and positive")
+
+    return config_class(
+        config_file=config_file,
+        project_root=project_root,
+        input_dir=input_dir.resolve(),
+        random_seed=int(raw["random_seed"]),
+        main=main,
+        enrichment=enrichment,
+        recurrence=recurrence,
+        visualization=visualization,
+        downstream=downstream,
+    )

cytocommunity2/downstream/__init__.py

@@ -0,0 +1,18 @@
+"""Reusable downstream analyses for CytoCommunity2 results.
+
+The top-level :mod:`cytocommunity2` API intentionally remains small.  These
+functions live in a dedicated namespace because downstream analyses are
+optional and evolve independently from model training.
+"""
+
+from .coherence import run_coherence_analysis
+from .composition import (
+    run_differential_composition_analysis,
+    run_dominant_celltype_analysis,
+)
+
+__all__ = [
+    "run_coherence_analysis",
+    "run_differential_composition_analysis",
+    "run_dominant_celltype_analysis",
+]

cytocommunity2/downstream/coherence.py

@@ -0,0 +1,115 @@
+"""Spatial coherence metrics and their file-based workflow."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from sklearn.neighbors import NearestNeighbors
+from sklearn.preprocessing import StandardScaler
+
+from ..config import CytoCommunityConfig
+from ..paths import build_paths
+
+
+@dataclass(frozen=True)
+class CoherenceMetrics:
+    """CHAOS and PAS values for one cellular-neighborhood assignment."""
+
+    chaos: float
+    pas: float
+
+
+def _validated_inputs(cluster_labels, coordinates):
+    labels = np.asarray(cluster_labels)
+    locations = np.asarray(coordinates, dtype=float)
+    if labels.ndim != 1:
+        raise ValueError("cluster_labels must be one-dimensional")
+    if locations.ndim != 2 or locations.shape[1] != 2:
+        raise ValueError("coordinates must have shape (n_cells, 2)")
+    if len(labels) != len(locations):
+        raise ValueError("cluster_labels and coordinates must have equal length")
+    if len(labels) == 0:
+        raise ValueError("at least one cell is required")
+    if not np.isfinite(locations).all():
+        raise ValueError("coordinates must contain only finite values")
+    return labels, locations
+
+
+def compute_chaos(cluster_labels, coordinates):
+    """Compute the normalized sum of within-CN nearest-neighbor distances."""
+    labels, locations = _validated_inputs(cluster_labels, coordinates)
+    locations = StandardScaler().fit_transform(locations)
+    distances = []
+    for label in np.unique(labels):
+        points = locations[labels == label]
+        if len(points) <= 1:
+            continue
+        neighbors = NearestNeighbors(n_neighbors=2, algorithm="kd_tree").fit(points)
+        nearest_distances, _ = neighbors.kneighbors(points)
+        distances.append(np.sum(nearest_distances[:, 1]))
+    return float(np.sum(distances) / len(labels))
+
+
+def compute_pas(cluster_labels, coordinates, *, k=10):
+    """Compute the percentage of abnormal spots (PAS) metric."""
+    labels, locations = _validated_inputs(cluster_labels, coordinates)
+    if not 1 <= k < len(labels):
+        raise ValueError("k must satisfy 1 <= k < number of cells")
+    neighbors = NearestNeighbors(n_neighbors=k + 1, algorithm="kd_tree").fit(
+        locations
+    )
+    _, indices = neighbors.kneighbors(locations)
+    neighbor_indices = indices[:, 1:]
+    different = labels[neighbor_indices] != labels[:, None]
+    return float((different.sum(axis=1) > (k / 2)).mean())
+
+
+def compute_coherence(cluster_labels, coordinates, *, pas_k=10):
+    """Return both spatial coherence metrics without reading or writing files."""
+    return CoherenceMetrics(
+        chaos=compute_chaos(cluster_labels, coordinates),
+        pas=compute_pas(cluster_labels, coordinates, k=pas_k),
+    )
+
+
+def analyze_result_tables(result_table_dir, *, pas_k=10):
+    """Calculate coherence metrics for all result-table CSV files."""
+    rows = []
+    for csv_path in sorted(Path(result_table_dir).glob("*.csv")):
+        sample = csv_path.stem.removeprefix("ResultTable_")
+        frame = pd.read_csv(csv_path)
+        required = ["x_coordinate", "y_coordinate", "CN_Label"]
+        missing = [column for column in required if column not in frame]
+        if missing:
+            raise ValueError(f"Missing columns in {csv_path}: {missing}")
+        frame = frame[required].copy()
+        for column in required:
+            frame[column] = pd.to_numeric(frame[column], errors="coerce")
+        frame = frame.dropna(subset=required)
+        metrics = compute_coherence(
+            frame["CN_Label"].to_numpy(dtype=np.int64),
+            frame[["x_coordinate", "y_coordinate"]].to_numpy(dtype=float),
+            pas_k=pas_k,
+        )
+        rows.append({"Sample": sample, "CHAOS": metrics.chaos, "PAS": metrics.pas})
+
+    result = pd.DataFrame(rows, columns=["Sample", "CHAOS", "PAS"]).round(4)
+    if result.empty:
+        raise FileNotFoundError(f"No result-table CSV files found in {result_table_dir}")
+    average = pd.DataFrame(
+        [{"Sample": "Average", "CHAOS": result["CHAOS"].mean(), "PAS": result["PAS"].mean()}]
+    ).round(4)
+    return pd.concat([result, average], ignore_index=True)
+
+
+def run_coherence_analysis(config, *, output_dir=None, pas_k=10):
+    """Run the file-oriented workflow and return the written table."""
+    if not isinstance(config, CytoCommunityConfig):
+        config = CytoCommunityConfig.from_json(config)
+    paths = build_paths(config)
+    output_dir = Path(output_dir or paths.downstream_data / "Coherence")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    result = analyze_result_tables(paths.result_tables, pas_k=pas_k)
+    result.to_csv(output_dir / "config.csv", index=False)
+    return result

cytocommunity2/downstream/communication/__init__.py

@@ -0,0 +1,11 @@
+"""Within- and between-CN communication analyses."""
+
+from .between import run_between_cn_analysis
+from .cca import run_cca_analysis
+from .within import run_within_cn_analysis
+
+__all__ = [
+    "run_between_cn_analysis",
+    "run_cca_analysis",
+    "run_within_cn_analysis",
+]

cytocommunity2/downstream/communication/between.py

@@ -0,0 +1,142 @@
+"""Spearman analysis for top CCA-derived between-CN pairs."""
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from scipy.stats import spearmanr
+
+from ...config import CytoCommunityConfig
+from ...paths import build_paths
+
+
+def normalize_scores_long(scores_long):
+    frame = scores_long.copy().dropna(subset=["Sample", "CN", "CellType", "Score"])
+    for column in ["Sample", "CN", "CellType"]:
+        frame[column] = frame[column].astype(str).str.strip()
+    frame["Score"] = pd.to_numeric(frame["Score"], errors="coerce")
+    return frame.dropna(subset=["Score"])
+
+
+def select_cca_pairs(cca_pairs, top_n):
+    pairs = cca_pairs.copy()
+    pairs["CN_A"] = pairs["CN_A"].astype(str).str.strip()
+    pairs["CN_B"] = pairs["CN_B"].astype(str).str.strip()
+    pairs["rho1"] = pd.to_numeric(pairs["rho1"], errors="coerce")
+    pairs = pairs.dropna(subset=["rho1"])
+    return pairs.reindex(
+        pairs["rho1"].abs().sort_values(ascending=False).index
+    ).head(top_n)
+
+
+def analyze_between_cn(
+    scores_long, cca_pairs, coordinate_tables, *, minimum_samples, top_n_cca_pairs
+):
+    """Calculate between-CN correlations without filesystem access.
+
+    ``coordinate_tables`` maps ``(CN_A, CN_B)`` string tuples to coordinate
+    DataFrames returned by :func:`cca_coordinate_tables`.
+    """
+    scores = normalize_scores_long(scores_long)
+    pairs = select_cca_pairs(cca_pairs, top_n_cca_pairs)
+    rows = []
+    for _, pair in pairs.iterrows():
+        cn_a, cn_b = str(pair["CN_A"]), str(pair["CN_B"])
+        try:
+            coordinates = coordinate_tables[(cn_a, cn_b)].copy()
+        except KeyError as error:
+            raise KeyError(f"Missing CCA coordinate table for CN{cn_a} vs CN{cn_b}") from error
+        coordinates["CellType"] = coordinates["CellType"].astype(str).str.strip()
+        coordinates_a = coordinates.dropna(subset=["CN_A_coord_can1"])
+        coordinates_b = coordinates.dropna(subset=["CN_B_coord_can1"])
+        if coordinates_a.empty or coordinates_b.empty:
+            raise ValueError(f"No valid CCA coordinate for CN{cn_a} vs CN{cn_b}")
+        top_a_index = coordinates_a["CN_A_coord_can1"].abs().idxmax()
+        top_b_index = coordinates_b["CN_B_coord_can1"].abs().idxmax()
+        top_a = coordinates_a.loc[top_a_index, "CellType"]
+        top_b = coordinates_b.loc[top_b_index, "CellType"]
+        scores_a = scores.loc[
+            (scores["CN"] == cn_a) & (scores["CellType"] == top_a),
+            ["Sample", "Score"],
+        ].rename(columns={"Score": "Score_A"})
+        scores_b = scores.loc[
+            (scores["CN"] == cn_b) & (scores["CellType"] == top_b),
+            ["Sample", "Score"],
+        ].rename(columns={"Score": "Score_B"})
+        merged = pd.merge(scores_a, scores_b, on="Sample", how="inner")
+        if len(merged) < minimum_samples:
+            raise ValueError(
+                f"Too few overlapping samples for CN{cn_a}({top_a}) vs CN{cn_b}({top_b})"
+            )
+        if merged["Score_A"].nunique() < 2 or merged["Score_B"].nunique() < 2:
+            raise ValueError(
+                f"Constant enrichment scores for CN{cn_a}({top_a}) vs CN{cn_b}({top_b})"
+            )
+        rho, p_value = spearmanr(merged["Score_A"], merged["Score_B"], nan_policy="omit")
+        rows.append(
+            {
+                "CN_A": cn_a,
+                "CN_B": cn_b,
+                "rho1_CCA": pair["rho1"],
+                "pval1_CCA": pair["pval1"],
+                "rho2_CCA": pair["rho2"] if "rho2" in pairs else np.nan,
+                "pval2_CCA": pair["pval2"] if "pval2" in pairs else np.nan,
+                "Top_CellType_A": top_a,
+                "Top_CellType_B": top_b,
+                "TopA_coord_can1": coordinates_a.loc[top_a_index, "CN_A_coord_can1"],
+                "TopB_coord_can1": coordinates_b.loc[top_b_index, "CN_B_coord_can1"],
+                "Spearman_rho": rho,
+                "Spearman_p": p_value,
+                "N_overlap": len(merged),
+            }
+        )
+    result = pd.DataFrame(rows)
+    if not result.empty:
+        result = result.sort_values(
+            "rho1_CCA", key=lambda values: values.abs(), ascending=False
+        )
+    return result
+
+
+def run_between_cn_statistics(config_dir, minimum_samples, top_n_cca_pairs):
+    """Compatibility workflow operating on the established communication folder."""
+    config_dir = Path(config_dir)
+    scores = pd.read_csv(config_dir / "EnrichScoreMatrix_long.csv")
+    pairs = pd.read_csv(config_dir / "CCA_config.csv")
+    selected = select_cca_pairs(pairs, top_n_cca_pairs)
+    tables = {
+        (str(row.CN_A), str(row.CN_B)): pd.read_csv(
+            config_dir / f"CCA_coordinates_CN{row.CN_A}_vs_CN{row.CN_B}.csv"
+        )
+        for row in selected.itertuples(index=False)
+    }
+    result = analyze_between_cn(
+        scores,
+        pairs,
+        tables,
+        minimum_samples=minimum_samples,
+        top_n_cca_pairs=top_n_cca_pairs,
+    )
+    result.to_csv(config_dir / "Spearman_TopCCA_Pairs.csv", index=False)
+    return result
+
+
+def run_between_cn_analysis(config, *, config_dir=None):
+    if not isinstance(config, CytoCommunityConfig):
+        config = CytoCommunityConfig.from_json(config)
+    paths = build_paths(config)
+    params = config.downstream["communication"]
+    return run_between_cn_statistics(
+        config_dir or paths.communication_config,
+        params["minimum_samples"],
+        params["top_n_cca_pairs"],
+    )
+
+
+__all__ = [
+    "analyze_between_cn",
+    "normalize_scores_long",
+    "run_between_cn_analysis",
+    "run_between_cn_statistics",
+    "select_cca_pairs",
+]