cytocommunity2 1.0.2__tar.gz → 1.0.4__tar.gz

{cytocommunity2-1.0.2/src/cytocommunity2.egg-info → cytocommunity2-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cytocommunity2
-Version: 1.0.2
+Version: 1.0.4
 Summary: Weakly supervised cellular-neighborhood learning for spatial omics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -30,6 +30,8 @@ Dynamic: license-file
 
 ## Overview
 
+![CytoCommunity2 overview](support/Fig.1.png)
+
 To enhance CytoCommunity (https://github.com/huBioinfo/CytoCommunity), we
 present CytoCommunity2, **a unified weakly-supervised framework** for
 identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/README.md

@@ -10,6 +10,8 @@
 
 ## Overview
 
+![CytoCommunity2 overview](support/Fig.1.png)
+
 To enhance CytoCommunity (https://github.com/huBioinfo/CytoCommunity), we
 present CytoCommunity2, **a unified weakly-supervised framework** for
 identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cytocommunity2"
-version = "1.0.2"
+version = "1.0.4"
 description = "Weakly supervised cellular-neighborhood learning for spatial omics"
 readme = "README.md"
 requires-python = ">=3.10"

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/__init__.py

@@ -10,7 +10,7 @@ from .learning import (
 )
 from .visualization import visualize_results
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 __all__ = [
     "CytoCommunityConfig",

cytocommunity2-1.0.4/src/cytocommunity2/_io.py

@@ -0,0 +1,11 @@
+"""Shared reader for the workflow's one-value-per-line text files."""
+
+from pathlib import Path
+
+
+def read_nonempty_lines(path):
+    return [
+        line.strip()
+        for line in Path(path).read_text(encoding="utf-8-sig").splitlines()
+        if line.strip()
+    ]

cytocommunity2-1.0.4/src/cytocommunity2/colors.py

@@ -0,0 +1,34 @@
+"""Shared categorical colors used across CytoCommunity2 figures."""
+
+
+CN_PALETTE = "d3_category20"
+
+
+def cn_color_map(cns):
+    """Map CN numbers or CN-prefixed labels to fixed spatial/OC colors."""
+    import sci_palettes
+
+    palette = list(sci_palettes.PALETTES[CN_PALETTE].values())
+    colors = {}
+    for cn in cns:
+        number = int(str(cn).removeprefix("CN"))
+        if not 1 <= number <= len(palette):
+            raise ValueError(
+                f"CN {cn!r} is outside the 1..{len(palette)} range of "
+                f"palette {CN_PALETTE!r}."
+            )
+        colors[cn] = palette[number - 1]
+    return colors
+
+
+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"):
+        palette.extend(plt.get_cmap(name).colors)
+    return {
+        celltype: palette[index]
+        for index, celltype in enumerate(celltypes)
+    }

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/config.py

@@ -9,11 +9,10 @@ from typing import Any, Mapping
 
 DEFAULT_CONFIG_FILE = "hyperparameters.json"
 
-# Established analysis rules stay stable across runs; only experimental choices
-# belong in hyperparameters.json.
-FIXED_DOWNSTREAM = {
+# Statistical thresholds and numerical settings for downstream analyses.
+DOWNSTREAM_PARAMETERS = {
     "dominant_cell_type": {"frequency_threshold": 0.5},
-    "differential_composed": {"p_value_threshold": 0.05, "minimum_samples": 3},
+    "differential_composition": {"p_value_threshold": 0.05, "minimum_samples": 3},
     "moran": {
         "minimum_positive_count": 2,
         "minimum_cn_cells": 10,
@@ -27,9 +26,10 @@ FIXED_DOWNSTREAM = {
         "cca_p_threshold": 0.05,
         "cca_minimum_common_samples": 3,
         "cca_minimum_abs_rho": 0.0,
-        "cca_sd_epsilon": 1e-8,
+        "cca_min_std": 1e-8,
         "cca_max_iterations": 1000,
-        "cca_canonical_components": 2,
+        "cca_n_components": 2,
+        "cca_top_celltypes": 5,
     },
 }
 
@@ -40,7 +40,7 @@ class MainConfig:
     cn_num_min: int
     cn_num_max: int
     final_num_runs: int
-    num_epoch: int
+    num_epochs: int
     embedding_dimension: int
     learning_rate: float
     mini_batch_size: int
@@ -82,17 +82,10 @@ class CytoCommunityConfig:
         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 resolve its configured 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, ["input_dir", "random_seed", "main", "downstream"], "root")
 
     project_root = config_file.parent
     input_dir = Path(raw["input_dir"]).expanduser()
@@ -104,14 +97,14 @@ def _load_config(config_file=None, config_class=CytoCommunityConfig):
     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}
+    for section, parameters in DOWNSTREAM_PARAMETERS.items():
+        downstream[section] = {**downstream.get(section, {}), **parameters}
 
     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:
+    if main.final_num_runs < 1 or main.num_epochs < 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")

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/__init__.py

@@ -1,8 +1,4 @@
-"""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.
+"""Downstream analyses of learned cellular neighborhoods.
 """
 
 from .coherence import run_coherence_analysis

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/coherence.py

@@ -20,15 +20,10 @@ class CoherenceMetrics:
     pas: float
 
 
-def _coherence_inputs(cluster_labels, coordinates):
-    labels = np.asarray(cluster_labels)
-    locations = np.asarray(coordinates, dtype=float)
-    return labels, locations
-
-
 def compute_chaos(cluster_labels, coordinates):
     """Compute the normalized sum of within-CN nearest-neighbor distances."""
-    labels, locations = _coherence_inputs(cluster_labels, coordinates)
+    labels = np.asarray(cluster_labels)
+    locations = np.asarray(coordinates, dtype=float)
     locations = StandardScaler().fit_transform(locations)
     distances = []
     for label in np.unique(labels):
@@ -43,7 +38,8 @@ def compute_chaos(cluster_labels, coordinates):
 
 def compute_pas(cluster_labels, coordinates, *, k=10):
     """Compute the percentage of abnormal spots (PAS) metric."""
-    labels, locations = _coherence_inputs(cluster_labels, coordinates)
+    labels = np.asarray(cluster_labels)
+    locations = np.asarray(coordinates, dtype=float)
     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(
@@ -93,5 +89,5 @@ def run_coherence_analysis(config: CytoCommunityConfig, *, output_dir=None, pas_
     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)
+    result.to_csv(output_dir / "CoherenceMetrics.csv", index=False)
     return result

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/communication/between.py

@@ -2,7 +2,6 @@
 
 from pathlib import Path
 
-import numpy as np
 import pandas as pd
 from scipy.stats import spearmanr
 
@@ -27,26 +26,22 @@ def select_cca_pairs(cca_pairs, top_n):
 
 
 def analyze_between_cn(
-    scores_long, cca_pairs, coordinate_tables, *, minimum_samples, top_n_cca_pairs
+    scores_long, cca_pairs, loading_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`.
-    """
+    """Calculate between-CN correlations without filesystem access."""
     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"])
-        coordinates = coordinate_tables[(cn_a, cn_b)].copy()
-        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"])
-        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"]
+        loadings = loading_tables[(cn_a, cn_b)].copy()
+        loadings["CellType"] = loadings["CellType"].astype(str).str.strip()
+        loadings_a = loadings.dropna(subset=["CN_A_loading1"])
+        loadings_b = loadings.dropna(subset=["CN_B_loading1"])
+        top_a_index = loadings_a["CN_A_loading1"].abs().idxmax()
+        top_b_index = loadings_b["CN_B_loading1"].abs().idxmax()
+        top_a = loadings_a.loc[top_a_index, "CellType"]
+        top_b = loadings_b.loc[top_b_index, "CellType"]
         scores_a = scores.loc[
             (scores["CN"] == cn_a) & (scores["CellType"] == top_a),
             ["Sample", "Score"],
@@ -70,13 +65,8 @@ def analyze_between_cn(
                 "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),
@@ -86,19 +76,19 @@ def analyze_between_cn(
     if not result.empty:
         result = result.sort_values(
             "rho1_CCA", key=lambda values: values.abs(), ascending=False
-        )
+        ).drop(columns="rho1_CCA")
     return result
 
 
 def run_between_cn_statistics(config_dir, minimum_samples, top_n_cca_pairs):
-    """Compatibility workflow operating on the established communication folder."""
+    """Calculate and save Spearman statistics for top CCA pairs."""
     config_dir = Path(config_dir)
     scores = pd.read_csv(config_dir / "EnrichScoreMatrix_long.csv")
-    pairs = pd.read_csv(config_dir / "CCA_config.csv")
+    pairs = pd.read_csv(config_dir / "CCA_results.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"
+            config_dir / f"CCA_loadings_CN{row.CN_A}_vs_CN{row.CN_B}.csv"
         )
         for row in selected.itertuples(index=False)
     }

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/communication/cca.py

@@ -20,7 +20,7 @@ def pair_rng(base_seed, condition, cn_a, cn_b):
     return np.random.default_rng(seed)
 
 
-def clean_cca_data(x, y, minimum_common_samples, sd_epsilon):
+def clean_cca_data(x, y, minimum_common_samples, min_std):
     """Align two matrices and remove incomplete or near-constant variables."""
     if x is None or y is None or x.shape[1] == 0 or y.shape[1] == 0:
         return None
@@ -29,15 +29,13 @@ def clean_cca_data(x, y, minimum_common_samples, sd_epsilon):
         return None
     x = x.loc[common]
     y = y.loc[common]
-    x = x.loc[:, x.notna().sum(axis=0) > 0]
-    y = y.loc[:, y.notna().sum(axis=0) > 0]
-    x = x.loc[:, x.std(axis=0) > sd_epsilon]
-    y = y.loc[:, y.std(axis=0) > sd_epsilon]
+    x = x.loc[:, x.std(axis=0) > min_std]
+    y = y.loc[:, y.std(axis=0) > min_std]
     if x.shape[1] == 0 or y.shape[1] == 0:
         return None
     complete = x.notna().all(axis=1) & y.notna().all(axis=1)
     x, y = x.loc[complete], y.loc[complete]
-    if x.shape[0] < minimum_common_samples or x.shape[1] == 0 or y.shape[1] == 0:
+    if x.shape[0] < minimum_common_samples:
         return None
     return {
         "X": x.values,
@@ -62,10 +60,23 @@ def build_score_list(frame, cn_list):
     return matrices
 
 
+def select_top_features(matrix, top_n=5):
+    """Select cell types by decreasing mean enrichment before variance filtering."""
+    if matrix is None or matrix.shape[1] == 0:
+        return matrix
+    means = matrix.mean(axis=0).fillna(-np.inf)
+    selected = means.sort_values(ascending=False, kind="stable").head(top_n).index
+    return matrix.loc[:, selected]
+
+
 def run_cca_for_scores(
     score_list, cn_list, communication_params, random_seed, condition=None
 ):
     """Run CCA and permutation tests on in-memory enrichment matrices."""
+    score_list = {
+        cn: select_top_features(matrix, communication_params["cca_top_celltypes"])
+        for cn, matrix in score_list.items()
+    }
     result_rows = []
     cache = {}
     for cn_a, cn_b in combinations(map(str, cn_list), 2):
@@ -75,7 +86,7 @@ def run_cca_for_scores(
             score_list[cn_a],
             score_list[cn_b],
             communication_params["cca_minimum_common_samples"],
-            communication_params["cca_sd_epsilon"],
+            communication_params["cca_min_std"],
         )
         if cleaned is None:
             continue
@@ -93,7 +104,7 @@ def run_cca_for_scores(
         model.fit(x_matrix, y_matrix)
         x_scores, y_scores = model.transform(x_matrix, y_matrix)
         actual_components = min(
-            communication_params["cca_canonical_components"], x_scores.shape[1]
+            communication_params["cca_n_components"], x_scores.shape[1]
         )
         correlations = [
             np.corrcoef(x_scores[:, index], y_scores[:, index])[0, 1]
@@ -111,7 +122,7 @@ def run_cca_for_scores(
                 shuffled_y = rng.permutation(y_matrix)
                 permutation_model = CCA(
                     n_components=min(
-                        communication_params["cca_canonical_components"],
+                        communication_params["cca_n_components"],
                         max_components,
                     ),
                     scale=True,
@@ -143,7 +154,7 @@ def run_cca_for_scores(
         row = {"CN_A": cn_a, "CN_B": cn_b, "n_samples": n_samples}
         if condition is not None:
             row["Condition"] = str(condition)
-        for component in range(communication_params["cca_canonical_components"]):
+        for component in range(communication_params["cca_n_components"]):
             row[f"rho{component + 1}"] = (
                 correlations[component] if component < len(correlations) else None
             )
@@ -177,8 +188,8 @@ def run_cca_for_scores(
     return {"results": results, "cache": cache}
 
 
-def cca_coordinate_tables(
-    results, cache, celltype_order, canonical_components, condition=None
+def cca_loading_tables(
+    results, cache, celltype_order, n_components, condition=None
 ):
     """Convert fitted CCA scores into per-pair cell-type loading tables."""
     tables = {}
@@ -198,47 +209,41 @@ def cca_coordinate_tables(
             if cell_type in set(entry["X_ct"]) | set(entry["Y_ct"])
         ]
         data = {"CellType": all_celltypes}
-        maximum = min(canonical_components, entry["X_scores"].shape[1])
+        maximum = min(n_components, entry["X_scores"].shape[1])
         for component in range(maximum):
             x_score = entry["X_scores"][:, component]
             y_score = entry["Y_scores"][:, component]
             x_loadings = {
                 cell_type: np.corrcoef(entry["X_mat"][:, index], x_score)[0, 1]
-                if len(x_score) > 1
-                else np.nan
                 for index, cell_type in enumerate(entry["X_ct"])
             }
             y_loadings = {
                 cell_type: np.corrcoef(entry["Y_mat"][:, index], y_score)[0, 1]
-                if len(y_score) > 1
-                else np.nan
                 for index, cell_type in enumerate(entry["Y_ct"])
             }
-            data[f"CN_A_coord_can{component + 1}"] = [
+            data[f"CN_A_loading{component + 1}"] = [
                 x_loadings.get(cell_type, np.nan) for cell_type in all_celltypes
             ]
-            data[f"CN_B_coord_can{component + 1}"] = [
+            data[f"CN_B_loading{component + 1}"] = [
                 y_loadings.get(cell_type, np.nan) for cell_type in all_celltypes
             ]
-            data[f"rho{component + 1}"] = [row.get(f"rho{component + 1}", np.nan)] * len(all_celltypes)
-            data[f"pval{component + 1}"] = [row.get(f"pval{component + 1}", np.nan)] * len(all_celltypes)
         tables[(cn_a, cn_b)] = pd.DataFrame(data)
     return tables
 
 
-def write_cca_coordinates(
-    results, cache, output_dir, celltype_order, canonical_components, condition=None
+def write_cca_loadings(
+    results, cache, output_dir, celltype_order, n_components, condition=None
 ):
-    """Write coordinate tables using the original filenames."""
+    """Write per-pair cell-type CCA loading tables."""
     output_dir = Path(output_dir)
     output_dir.mkdir(parents=True, exist_ok=True)
-    tables = cca_coordinate_tables(
-        results, cache, celltype_order, canonical_components, condition
+    tables = cca_loading_tables(
+        results, cache, celltype_order, n_components, condition
     )
     prefix = f"{condition}_" if condition is not None else ""
     for (cn_a, cn_b), table in tables.items():
         table.to_csv(
-            output_dir / f"CCA_coordinates_{prefix}CN{cn_a}_vs_CN{cn_b}.csv",
+            output_dir / f"CCA_loadings_{prefix}CN{cn_a}_vs_CN{cn_b}.csv",
             index=False,
         )
     return tables
@@ -268,13 +273,13 @@ def run_cca_analysis(
     pooled = run_cca_for_scores(
         build_score_list(frame, cn_list), cn_list, params, config.random_seed
     )
-    pooled["results"].to_csv(output_dir / "CCA_config.csv", index=False)
-    write_cca_coordinates(
+    pooled["results"].to_csv(output_dir / "CCA_results.csv", index=False)
+    write_cca_loadings(
         pooled["results"],
         pooled["cache"],
         output_dir,
         celltype_order,
-        params["cca_canonical_components"],
+        params["cca_n_components"],
     )
     condition_results = []
     for condition in conditions:
@@ -286,13 +291,12 @@ def run_cca_analysis(
             config.random_seed,
             condition,
         )
-        result["results"].to_csv(output_dir / f"CCA_config_{condition}.csv", index=False)
-        write_cca_coordinates(
+        write_cca_loadings(
             result["results"],
             result["cache"],
             output_dir,
             celltype_order,
-            params["cca_canonical_components"],
+            params["cca_n_components"],
             condition,
         )
         condition_results.append(result["results"])
@@ -310,16 +314,17 @@ def run_cca_analysis(
             key=lambda values: abs(values) if values.name == "rho1" else values,
             ascending=[True, False],
         )
-    by_condition.to_csv(output_dir / "CCA_config_by_condition.csv", index=False)
+    by_condition.to_csv(output_dir / "CCA_results_by_condition.csv", index=False)
     return {"pooled": pooled["results"], "by_condition": by_condition}
 
 
 __all__ = [
     "build_score_list",
-    "cca_coordinate_tables",
+    "cca_loading_tables",
     "clean_cca_data",
     "pair_rng",
     "run_cca_analysis",
     "run_cca_for_scores",
-    "write_cca_coordinates",
+    "select_top_features",
+    "write_cca_loadings",
 ]

{cytocommunity2-1.0.2 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/communication/within.py

@@ -234,7 +234,7 @@ def run_within_cn_analysis(
     }
     outputs["pooled"].to_csv(output_dir / "SpearmanWithinCNs.csv", index=False)
     for comparison in build_condition_comparisons(
-        scores["Condition"], config.downstream["ttest_mode"]
+        scores["Condition"], config.downstream["comparison_mode"]
     ):
         result = compute_condition_comparison_stats(
             wide_dict=wide,