cytocommunity2 1.0.7__tar.gz → 1.0.8__tar.gz

{cytocommunity2-1.0.7/src/cytocommunity2.egg-info → cytocommunity2-1.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cytocommunity2
-Version: 1.0.7
+Version: 1.0.8
 Summary: Weakly supervised cellular-neighborhood learning for spatial omics
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/pyproject.toml

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

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/__init__.py

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

cytocommunity2-1.0.8/src/cytocommunity2/_display.py

@@ -0,0 +1,23 @@
+"""Dataset-specific display labels, separate from statistical identifiers."""
+
+
+def display_label_map(config, name, overrides=None):
+    visualization = getattr(config, "visualization", None)
+    labels = dict(getattr(visualization, name, {}) or {})
+    labels.update(overrides or {})
+    return {str(key): str(value) for key, value in labels.items()}
+
+
+def celltype_label(value, config=None, *, labels=None, mathtext=True):
+    text = str(value)
+    text = display_label_map(config, "celltype_labels", labels).get(text, text)
+    # Arial lacks the superscript-plus glyph; mathtext keeps it readable.
+    return text.replace("⁺", r"$^{+}$") if mathtext else text
+
+
+def condition_label(value, config=None, *, labels=None):
+    text = str(value)
+    key = text.removeprefix("label")
+    mapping = display_label_map(config, "condition_labels", labels)
+    fallback = text if text == "rest" or text.startswith("label") else f"label{text}"
+    return mapping.get(text, mapping.get(key, fallback))

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/colors.py

@@ -2,6 +2,15 @@
 
 
 CN_PALETTE = "d3_category20"
+TARGET_COLOR = "#CB3027"
+REST_COLOR = "#466988"
+
+
+def condition_comparison_colors(condition_a, condition_b):
+    """Color the target red and rest/reference blue, independent of rho order."""
+    if str(condition_a).lower() == "rest":
+        return REST_COLOR, TARGET_COLOR
+    return TARGET_COLOR, REST_COLOR
 
 
 def cn_color_map(cns):

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/config.py

@@ -2,7 +2,7 @@
 
 import json
 import math
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Mapping
 
@@ -21,7 +21,6 @@ DOWNSTREAM_PARAMETERS = {
     "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,
@@ -62,6 +61,8 @@ class RecurrenceConfig:
 @dataclass(frozen=True)
 class VisualizationConfig:
     point_size: float = 2.0
+    celltype_labels: Mapping[str, str] = field(default_factory=dict)
+    condition_labels: Mapping[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/communication/between.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 
 import pandas as pd
+import numpy as np
 
 from ...config import CytoCommunityConfig
 from ...paths import build_paths
@@ -24,6 +25,7 @@ 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 = pairs.loc[np.isfinite(pairs["rho1"])].copy()
     return pairs.reindex(
         pairs["rho1"].abs().sort_values(ascending=False).index
     ).head(top_n)
@@ -42,8 +44,10 @@ def analyze_between_cn(
         cn_a, cn_b = str(pair["CN_A"]), str(pair["CN_B"])
         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"])
+        loadings_a = loadings.loc[np.isfinite(loadings["CN_A_loading1"])]
+        loadings_b = loadings.loc[np.isfinite(loadings["CN_B_loading1"])]
+        if loadings_a.empty or loadings_b.empty:
+            raise ValueError(f"No finite first canonical loadings for CN{cn_a} vs CN{cn_b}")
         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"]
@@ -87,19 +91,24 @@ def analyze_between_cn(
     return result.drop(columns="rho1_CCA")
 
 
-def run_between_cn_statistics(config_dir, minimum_samples, top_n_cca_pairs):
+def run_between_cn_statistics(
+    cca_dir, minimum_samples, top_n_cca_pairs, *, input_file=None, output_dir=None
+):
     """Calculate and save Spearman statistics for top CCA pairs."""
-    config_dir = Path(config_dir)
+    cca_dir = Path(cca_dir)
+    output_dir = Path(output_dir or cca_dir.parent)
+    output_dir.mkdir(parents=True, exist_ok=True)
     scores = read_scores_long(
-        config_dir / "EnrichScoreMatrix_long.csv", require_condition=False
+        input_file or cca_dir.parent.parent / "EnrichScoreMatrix_long.csv",
+        require_condition=False,
     )
     pairs = pd.read_csv(
-        config_dir / "CCA_results.csv", dtype={"CN_A": str, "CN_B": str}
+        cca_dir / "CCA_results.csv", dtype={"CN_A": str, "CN_B": str}
     )
     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_loadings_CN{row.CN_A}_vs_CN{row.CN_B}.csv",
+            cca_dir / f"CCA_loadings_CN{row.CN_A}_vs_CN{row.CN_B}.csv",
             converters={"CellType": str.strip},
         )
         for row in selected.itertuples(index=False)
@@ -111,17 +120,21 @@ def run_between_cn_statistics(config_dir, minimum_samples, top_n_cca_pairs):
         minimum_samples=minimum_samples,
         top_n_cca_pairs=top_n_cca_pairs,
     )
-    result.to_csv(config_dir / "Spearman_TopCCA_Pairs.csv", index=False)
+    result.to_csv(output_dir / "Spearman_TopCCA_Pairs.csv", index=False)
     return result
 
 
-def run_between_cn_analysis(config: CytoCommunityConfig, *, config_dir=None):
+def run_between_cn_analysis(
+    config: CytoCommunityConfig, *, input_file=None, output_dir=None, cca_dir=None
+):
     paths = build_paths(config)
     params = config.downstream["communication"]
     return run_between_cn_statistics(
-        config_dir or paths.communication_config,
+        cca_dir or paths.communication_cca,
         params["minimum_samples"],
         params["top_n_cca_pairs"],
+        input_file=input_file or paths.communication_scores,
+        output_dir=output_dir or paths.communication_between,
     )
 
 

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/communication/cca.py

@@ -2,6 +2,7 @@
 
 from itertools import combinations
 from pathlib import Path
+import warnings
 
 import numpy as np
 import pandas as pd
@@ -12,8 +13,6 @@ from ...paths import build_paths
 from .utils import (
     build_score_tables,
     condition_sort_key,
-    normalize_scores_long,
-    prune_csv_outputs,
     read_scores_long,
 )
 
@@ -22,8 +21,8 @@ def _result_columns(n_components, *, by_condition=False):
     columns = ["CN_A", "CN_B", "n_samples"]
     if by_condition:
         columns.append("Condition")
-    for component in range(1, n_components + 1):
-        columns.extend([f"rho{component}", f"pval{component}", f"invalid_perm{component}"])
+    columns.extend(["rho1", "pval1", "invalid_perm1"])
+    columns.extend(f"rho{component}" for component in range(2, n_components + 1))
     return columns
 
 
@@ -42,8 +41,8 @@ def clean_cca_data(x, y, minimum_common_samples, min_std):
     common = x.index.intersection(y.index)
     if len(common) < minimum_common_samples:
         return None
-    x = x.loc[common]
-    y = y.loc[common]
+    x = x.loc[common].replace([np.inf, -np.inf], np.nan)
+    y = y.loc[common].replace([np.inf, -np.inf], np.nan)
     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:
@@ -52,6 +51,11 @@ def clean_cca_data(x, y, minimum_common_samples, min_std):
     x, y = x.loc[complete], y.loc[complete]
     if x.shape[0] < minimum_common_samples:
         return None
+    # Removing incomplete samples can make a previously variable column constant.
+    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
     return {
         "X": x.values,
         "Y": y.values,
@@ -66,20 +70,41 @@ def build_score_list(frame, cn_list):
 
 
 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:
+    """Select the five highest-mean cell types by default, before filtering."""
+    if top_n is None or matrix is None or matrix.shape[1] == 0:
         return matrix
+    if isinstance(top_n, bool) or not isinstance(top_n, (int, np.integer)) or top_n < 1:
+        raise ValueError("cca_top_celltypes must be a positive integer or null")
     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 _fit_cca_scores(x_matrix, y_matrix, n_components, max_iterations):
+    """Fit finite canonical scores, retrying a degenerate second component."""
+    for count in range(n_components, 0, -1):
+        try:
+            model = CCA(n_components=count, scale=True, max_iter=max_iterations)
+            with np.errstate(invalid="raise", divide="raise", over="raise"):
+                model.fit(x_matrix, y_matrix)
+                x_scores, y_scores = model.transform(x_matrix, y_matrix)
+            if not (np.isfinite(x_scores).all() and np.isfinite(y_scores).all()):
+                continue
+            if any(np.ptp(scores[:, index]) == 0 for scores in (x_scores, y_scores) for index in range(count)):
+                continue
+            return x_scores, y_scores
+        except (ValueError, np.linalg.LinAlgError, FloatingPointError):
+            continue
+    return None
+
+
 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."""
+    """Fit up to two pooled components, or just one within a condition."""
+    n_components = 1 if condition is not None else communication_params["cca_n_components"]
     score_list = {
-        cn: select_top_features(matrix, communication_params["cca_top_celltypes"])
+        cn: select_top_features(matrix, communication_params.get("cca_top_celltypes", 5))
         for cn, matrix in score_list.items()
     }
     result_rows = []
@@ -97,78 +122,69 @@ def run_cca_for_scores(
             continue
         x_matrix, y_matrix = cleaned["X"], cleaned["Y"]
         n_samples = x_matrix.shape[0]
-        max_components = min(x_matrix.shape[1], y_matrix.shape[1], n_samples - 2)
+        # Column count alone does not detect proportional cell-type profiles.
+        max_components = min(
+            n_components,
+            np.linalg.matrix_rank(x_matrix - x_matrix.mean(axis=0)),
+            np.linalg.matrix_rank(y_matrix - y_matrix.mean(axis=0)),
+            n_samples - 2,
+        )
         if max_components < 1:
             continue
 
-        model = CCA(
-            n_components=max_components,
-            scale=True,
-            max_iter=communication_params["cca_max_iterations"],
-        )
-        model.fit(x_matrix, y_matrix)
-        x_scores, y_scores = model.transform(x_matrix, y_matrix)
-        actual_components = min(
-            communication_params["cca_n_components"], x_scores.shape[1]
+        scores = _fit_cca_scores(
+            x_matrix, y_matrix, max_components,
+            communication_params["cca_max_iterations"],
         )
+        if scores is None:
+            warnings.warn(
+                f"CCA could not estimate finite scores for CN{cn_a} vs CN{cn_b} "
+                f"(condition={condition}); pair omitted.", RuntimeWarning,
+            )
+            continue
+        x_scores, y_scores = scores
+        actual_components = min(n_components, x_scores.shape[1])
         correlations = [
             np.corrcoef(x_scores[:, index], y_scores[:, index])[0, 1]
             for index in range(actual_components)
         ]
+        if not np.isfinite(correlations[0]):
+            continue
 
-        p_values = []
-        invalid_counts = []
+        # Only the first canonical correlation is used for inference. rho2 and
+        # loading2 are descriptive coordinates for the pooled loading diagram.
+        observed = correlations[0]
+        extreme = 0
+        valid_count = 0
+        invalid_count = 0
         rng = pair_rng(random_seed, condition, cn_a, cn_b)
-        for component, observed in enumerate(correlations):
-            extreme = 0
-            valid_count = 0
-            invalid_count = 0
-            for _ in range(communication_params["cca_n_permutations"]):
-                shuffled_y = rng.permutation(y_matrix)
-                permutation_model = CCA(
-                    n_components=min(
-                        communication_params["cca_n_components"],
-                        max_components,
-                    ),
-                    scale=True,
-                    max_iter=communication_params["cca_max_iterations"],
-                )
-                try:
-                    permutation_model.fit(x_matrix, shuffled_y)
-                    permuted_x, permuted_y = permutation_model.transform(
-                        x_matrix, shuffled_y
-                    )
-                except (ValueError, np.linalg.LinAlgError, FloatingPointError):
-                    invalid_count += 1
-                    continue
-                if permuted_x.shape[1] <= component:
-                    continue
-                permuted_rho = abs(
-                    np.corrcoef(
-                        permuted_x[:, component], permuted_y[:, component]
-                    )[0, 1]
-                )
-                valid_count += 1
-                if permuted_rho >= abs(observed) - 1e-12:
-                    extreme += 1
-            p_values.append(
-                (extreme + 1) / (valid_count + 1) if valid_count else np.nan
+        for _ in range(communication_params["cca_n_permutations"]):
+            shuffled_y = rng.permutation(y_matrix)
+            permuted = _fit_cca_scores(
+                x_matrix, shuffled_y, x_scores.shape[1],
+                communication_params["cca_max_iterations"],
             )
-            invalid_counts.append(invalid_count)
+            if permuted is None:
+                invalid_count += 1
+                continue
+            permuted_x, permuted_y = permuted
+            permuted_rho = abs(np.corrcoef(permuted_x[:, 0], permuted_y[:, 0])[0, 1])
+            if not np.isfinite(permuted_rho):
+                invalid_count += 1
+                continue
+            valid_count += 1
+            if permuted_rho >= abs(observed) - 1e-12:
+                extreme += 1
 
         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_n_components"]):
+        row["pval1"] = (extreme + 1) / (valid_count + 1) if valid_count else np.nan
+        row["invalid_perm1"] = invalid_count
+        for component in range(n_components):
             row[f"rho{component + 1}"] = (
                 correlations[component] if component < len(correlations) else None
             )
-            row[f"pval{component + 1}"] = (
-                p_values[component] if component < len(p_values) else None
-            )
-            row[f"invalid_perm{component + 1}"] = (
-                invalid_counts[component] if component < len(invalid_counts) else None
-            )
         result_rows.append(row)
         key = "__".join(
             filter(
@@ -187,9 +203,7 @@ def run_cca_for_scores(
 
     results = pd.DataFrame(
         result_rows,
-        columns=_result_columns(
-            communication_params["cca_n_components"], by_condition=condition is not None
-        ),
+        columns=_result_columns(n_components, by_condition=condition is not None),
     )
     if not results.empty:
         results = results.sort_values(
@@ -263,19 +277,15 @@ def write_cca_loadings(
     return tables
 
 
-def _normalize_scores(frame):
-    return normalize_scores_long(frame, require_condition=True)
-
-
 def run_cca_analysis(
     config: CytoCommunityConfig, *, input_file=None, output_dir=None
 ):
     """Run pooled and condition-specific CCA using configured paths."""
     paths = build_paths(config)
     params = config.downstream["communication"]
-    output_dir = Path(output_dir or paths.communication_config)
+    output_dir = Path(output_dir or paths.communication_cca)
     output_dir.mkdir(parents=True, exist_ok=True)
-    frame = read_scores_long(input_file or output_dir / "EnrichScoreMatrix_long.csv")
+    frame = read_scores_long(input_file or paths.communication_scores)
     celltype_order = frame["CellType"].astype(str).drop_duplicates().tolist()
     conditions = sorted(frame["Condition"].unique(), key=condition_sort_key)
     cn_list = sorted(frame["CN"].unique(), key=condition_sort_key)
@@ -283,7 +293,6 @@ def run_cca_analysis(
         build_score_list(frame, cn_list), cn_list, params, config.random_seed
     )
     condition_results = []
-    fitted_conditions = []
     for condition in conditions:
         subset = frame[frame["Condition"] == condition]
         result = run_cca_for_scores(
@@ -293,14 +302,12 @@ def run_cca_analysis(
             config.random_seed,
             condition,
         )
-        condition_results.append(result["results"])
-        fitted_conditions.append((condition, result))
+        if not result["results"].empty:
+            condition_results.append(result["results"])
     by_condition = (
         pd.concat(condition_results, ignore_index=True)
         if condition_results
-        else pd.DataFrame(
-            columns=_result_columns(params["cca_n_components"], by_condition=True)
-        )
+        else pd.DataFrame(columns=_result_columns(1, by_condition=True))
     )
     if not by_condition.empty:
         by_condition["Condition"] = pd.Categorical(
@@ -311,24 +318,14 @@ def run_cca_analysis(
             key=lambda values: abs(values) if values.name == "rho1" else values,
             ascending=[True, False],
         )
-    # Retain only loadings from the completed pooled/condition analyses. A CN pair
-    # that disappeared on this run must not survive as an apparently current file.
-    current_loadings = []
-    for condition, result in [(None, pooled), *fitted_conditions]:
-        tables = write_cca_loadings(
-            result["results"], result["cache"], output_dir, celltype_order,
-            params["cca_n_components"], condition,
-        )
-        prefix = f"{condition}_" if condition is not None else ""
-        current_loadings.extend(
-            f"CCA_loadings_{prefix}CN{cn_a}_vs_CN{cn_b}.csv"
-            for cn_a, cn_b in tables
-        )
+    # The circle plot consumes only the condition summary. Loading tables are
+    # needed for pooled CCA plots and selection of between-CN cell-type pairs.
+    write_cca_loadings(
+        pooled["results"], pooled["cache"], output_dir, celltype_order,
+        params["cca_n_components"],
+    )
     pooled["results"].to_csv(output_dir / "CCA_results.csv", index=False)
     by_condition.to_csv(output_dir / "CCA_results_by_condition.csv", index=False)
-    prune_csv_outputs(
-        output_dir, "CCA_loadings_*CN*_vs_CN*.csv", current_loadings
-    )
     return {"pooled": pooled["results"], "by_condition": by_condition}
 
 

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/communication/utils.py

@@ -1,8 +1,6 @@
 """Shared communication table and statistical utilities."""
 
 import itertools
-from pathlib import Path
-
 import numpy as np
 import pandas as pd
 from scipy.stats import spearmanr
@@ -72,14 +70,6 @@ def build_score_tables(
     return tables
 
 
-def prune_csv_outputs(output_dir, pattern, current_names):
-    """Remove only obsolete files from one analysis-owned CSV filename pattern."""
-    current_names = set(current_names)
-    for path in Path(output_dir).glob(pattern):
-        if path.is_file() and path.name not in current_names:
-            path.unlink()
-
-
 def condition_label(condition):
     condition = str(condition)
     return condition if condition == "rest" else f"label{condition}"
@@ -114,7 +104,7 @@ def stable_seed(base_seed, *parts):
 def safe_spearman(x, y, min_samples):
     x = np.asarray(x, dtype=float)
     y = np.asarray(y, dtype=float)
-    valid = (~np.isnan(x)) & (~np.isnan(y))
+    valid = np.isfinite(x) & np.isfinite(y)
     x = x[valid]
     y = y[valid]
     if len(x) < min_samples or len(np.unique(x)) < 2 or len(np.unique(y)) < 2:
@@ -133,7 +123,6 @@ __all__ = [
     "condition_pairs",
     "condition_sort_key",
     "normalize_scores_long",
-    "prune_csv_outputs",
     "read_scores_long",
     "safe_spearman",
     "stable_seed",

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/communication/within.py

@@ -12,7 +12,6 @@ from .utils import (
     available_conditions,
     build_score_tables,
     condition_pair_label,
-    prune_csv_outputs,
     read_scores_long,
     safe_spearman,
     stable_seed,
@@ -88,7 +87,7 @@ def permutation_pvalue(
     x = np.asarray(x, dtype=float)
     y = np.asarray(y, dtype=float)
     labels = np.asarray(labels)
-    valid = (~np.isnan(x)) & (~np.isnan(y)) & np.isin(
+    valid = np.isfinite(x) & np.isfinite(y) & np.isin(
         labels, [condition_a, condition_b]
     )
     x, y, labels = x[valid], y[valid], labels[valid]
@@ -222,9 +221,9 @@ def run_within_cn_analysis(
     """Run and save pooled plus condition-specific within-CN analyses."""
     paths = build_paths(config)
     params = config.downstream["communication"]
-    output_dir = Path(output_dir or paths.communication_config)
+    output_dir = Path(output_dir or paths.communication_within)
     output_dir.mkdir(parents=True, exist_ok=True)
-    input_file = Path(input_file or output_dir / "EnrichScoreMatrix_long.csv")
+    input_file = Path(input_file or paths.communication_scores)
     scores = read_scores_long(input_file)
     celltype_order = scores["CellType"].astype(str).drop_duplicates().tolist()
     num_cn = int(paths.selected_cn_num.read_text(encoding="utf-8"))
@@ -251,17 +250,12 @@ def run_within_cn_analysis(
         )
         label = condition_pair_label(comparison["cond_a"], comparison["cond_b"])
         outputs[label] = result
-    # Publish only after all comparisons compute; retired comparison modes and
-    # conditions must not leave tables that a later run can mistake for current.
     outputs["pooled"].to_csv(output_dir / "SpearmanWithinCNs.csv", index=False)
-    current_names = []
     for label, result in outputs.items():
-        if label == "pooled":
+        if label == "pooled" or result.empty:
             continue
         name = f"CommunicationPair_{label}.csv"
         result.to_csv(output_dir / name, index=False)
-        current_names.append(name)
-    prune_csv_outputs(output_dir, "CommunicationPair_label*_vs_*.csv", current_names)
     return outputs
 
 

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/differential_composition.py

@@ -92,7 +92,8 @@ def analyze_differential_composition(matrix_records, celltypes, *, mode, minimum
 
     The result maps comparison names to maps of CN names and result tables.
     Comparisons with fewer than ``minimum_samples`` samples on either side
-    have empty maps.
+    have empty maps. Pairwise tests are computed once per unordered pair;
+    the reverse comparison swaps alternatives, sample counts, and rank sums.
     """
     normalized_records = [
         {**record, "matrix": np.asarray(record["matrix"], dtype=float)}
@@ -116,8 +117,12 @@ def analyze_differential_composition(matrix_records, celltypes, *, mode, minimum
         ) >= minimum_samples
     ]
     for cn_index in range(expected_shape[1]):
+        cn_name = f"CN{cn_index + 1}"
         for comparison in eligible:
+            if mode == "pairwise" and cn_name in outputs[comparison["name"]]:
+                continue
             rows = []
+            reverse_rows = []
             for cell_index, cell_type in enumerate(celltypes):
                 target = [
                     record["matrix"][cell_index, cn_index]
@@ -134,8 +139,22 @@ def analyze_differential_composition(matrix_records, celltypes, *, mode, minimum
                 )
                 if result is not None:
                     rows.extend(result)
+                    if mode == "pairwise":
+                        total_n = len(target) + len(reference)
+                        # Reversing the two rows keeps greater before less.
+                        for row in reversed(result):
+                            reverse_rows.append({
+                                **row,
+                                "Alternative": "greater" if row["Alternative"] == "less" else "less",
+                                "W_statistic": total_n * (total_n + 1) / 2 - row["W_statistic"],
+                                "N_target": row["N_reference"],
+                                "N_reference": row["N_target"],
+                            })
             if rows:
-                outputs[comparison["name"]][f"CN{cn_index + 1}"] = pd.DataFrame(rows)
+                outputs[comparison["name"]][cn_name] = pd.DataFrame(rows)
+                if mode == "pairwise":
+                    reverse_name = f"{comparison['reference_name']}_gt_{comparison['target_name']}"
+                    outputs[reverse_name][cn_name] = pd.DataFrame(reverse_rows)
     return outputs
 
 
@@ -154,9 +173,6 @@ def run_differential_composition_analysis(
     output_dir = Path(output_dir or paths.downstream_data / "DifferentialComposed")
     for comparison, cn_tables in outputs.items():
         comparison_dir = output_dir / comparison
-        if comparison_dir.exists():
-            for csv_file in comparison_dir.glob("CN*.csv"):
-                csv_file.unlink()
         if cn_tables:
             comparison_dir.mkdir(parents=True, exist_ok=True)
             for cn, table in cn_tables.items():

{cytocommunity2-1.0.7 → cytocommunity2-1.0.8}/src/cytocommunity2/downstream/enrichment.py

@@ -19,13 +19,31 @@ def load_enrichment_by_sample(enrichment_dir, input_dir):
         .str.strip()
         .tolist()
     )
+    if not celltypes or any(not celltype for celltype in celltypes):
+        raise ValueError(f"{enrichment_dir}: cell-type names must be nonempty")
+    if len(set(celltypes)) != len(celltypes):
+        raise ValueError(f"{enrichment_dir}: cell-type names must be unique")
     samples = read_nonempty_lines(Path(input_dir) / "ImageNameList.txt")
+    if not samples or len(set(samples)) != len(samples):
+        raise ValueError(f"{input_dir}: sample names must be nonempty and unique")
     matrices = {
         sample: pd.read_csv(
             enrichment_dir / f"{sample}_EnrichScoreMatrix.csv", header=None
         ).to_numpy(dtype=float)
         for sample in samples
     }
+    expected_shape = next(iter(matrices.values())).shape
+    if expected_shape[0] != len(celltypes) or expected_shape[1] == 0:
+        raise ValueError(
+            f"{enrichment_dir}: enrichment rows must match cell types and include at least one CN"
+        )
+    for sample, matrix in matrices.items():
+        if matrix.shape != expected_shape:
+            raise ValueError(
+                f"{sample}: enrichment shape={matrix.shape}, expected {expected_shape}"
+            )
+        if not np.isfinite(matrix).all():
+            raise ValueError(f"{sample}: enrichment scores must be finite")
     return celltypes, matrices