cytocommunity2 1.0.1__tar.gz → 1.0.2__tar.gz

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

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

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

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

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

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

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

@@ -13,7 +13,7 @@ DEFAULT_CONFIG_FILE = "hyperparameters.json"
 # belong in hyperparameters.json.
 FIXED_DOWNSTREAM = {
     "dominant_cell_type": {"frequency_threshold": 0.5},
-    "differential_composed": {"p_value_threshold": 0.05},
+    "differential_composed": {"p_value_threshold": 0.05, "minimum_samples": 3},
     "moran": {
         "minimum_positive_count": 2,
         "minimum_cn_cells": 10,

{cytocommunity2-1.0.1 → cytocommunity2-1.0.2}/src/cytocommunity2/downstream/differential_composition.py

@@ -66,11 +66,13 @@ def build_label_comparisons(labels, mode):
     raise ValueError(f"Unknown comparison mode: {mode}")
 
 
-def composition_wilcoxon_tests(cell_type, target_values, reference_values):
+def composition_wilcoxon_tests(
+    cell_type, target_values, reference_values, *, minimum_samples=3
+):
     """Run one-sided asymptotic Wilcoxon rank-sum tests."""
     target = np.asarray(target_values, dtype=float)
     reference = np.asarray(reference_values, dtype=float)
-    if len(target) < 2 or len(reference) < 2:
+    if len(target) < minimum_samples or len(reference) < minimum_samples:
         return None
     if not np.isfinite(target).all() or not np.isfinite(reference).all():
         return None
@@ -100,10 +102,12 @@ def composition_wilcoxon_tests(cell_type, target_values, reference_values):
     return rows
 
 
-def analyze_differential_composition(matrix_records, celltypes, *, mode):
+def analyze_differential_composition(matrix_records, celltypes, *, mode, minimum_samples=3):
     """Calculate all directional composition comparisons in memory.
 
     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.
     """
     normalized_records = [
         {**record, "matrix": np.asarray(record["matrix"], dtype=float)}
@@ -114,8 +118,20 @@ def analyze_differential_composition(matrix_records, celltypes, *, mode):
     labels = sorted({record["condition"] for record in normalized_records})
     comparisons = build_label_comparisons(labels, mode)
     outputs = {comparison["name"]: {} for comparison in comparisons}
+    eligible = [
+        comparison
+        for comparison in comparisons
+        if sum(
+            record["condition"] in comparison["target_labels"]
+            for record in normalized_records
+        ) >= minimum_samples
+        and sum(
+            record["condition"] in comparison["reference_labels"]
+            for record in normalized_records
+        ) >= minimum_samples
+    ]
     for cn_index in range(expected_shape[1]):
-        for comparison in comparisons:
+        for comparison in eligible:
             rows = []
             for cell_index, cell_type in enumerate(celltypes):
                 target = [
@@ -129,7 +145,7 @@ def analyze_differential_composition(matrix_records, celltypes, *, mode):
                     if record["condition"] in comparison["reference_labels"]
                 ]
                 result = composition_wilcoxon_tests(
-                    cell_type, target, reference
+                    cell_type, target, reference, minimum_samples=minimum_samples
                 )
                 if result is not None:
                     rows.extend(result)
@@ -147,16 +163,19 @@ def run_differential_composition_analysis(
         paths.enrichment, paths.input_dir
     )
     outputs = analyze_differential_composition(
-        records, celltypes, mode=config.downstream["ttest_mode"]
+        records, celltypes, mode=config.downstream["ttest_mode"],
+        minimum_samples=config.downstream["differential_composed"]["minimum_samples"],
     )
     output_dir = Path(output_dir or paths.downstream_data / "DifferentialComposed")
     for comparison, cn_tables in outputs.items():
         comparison_dir = output_dir / comparison
-        comparison_dir.mkdir(parents=True, exist_ok=True)
-        for old_file in comparison_dir.glob("CN*.csv"):
-            old_file.unlink()
-        for cn, table in cn_tables.items():
-            table.to_csv(comparison_dir / f"{cn}_{comparison}.csv", index=False)
+        if comparison_dir.exists():
+            for old_file in comparison_dir.glob("CN*.csv"):
+                old_file.unlink()
+        if cn_tables:
+            comparison_dir.mkdir(parents=True, exist_ok=True)
+            for cn, table in cn_tables.items():
+                table.to_csv(comparison_dir / f"{cn}_{comparison}.csv", index=False)
     return outputs
 
 

{cytocommunity2-1.0.1 → cytocommunity2-1.0.2}/src/cytocommunity2/downstream/dominant_celltype.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 import numpy as np
 import pandas as pd
+from scipy.cluster.hierarchy import leaves_list, linkage
 
 from ..config import CytoCommunityConfig
 from ..paths import build_paths
@@ -16,6 +17,8 @@ class DominantCellTypeResult:
 
     frequency: pd.DataFrame
     dominant_cell_types: pd.DataFrame
+    cn_order: tuple[str, ...] = ()
+    cn_linkage: np.ndarray | None = None
 
 
 def load_enrichment_matrices(enrichment_dir, input_dir):
@@ -46,12 +49,26 @@ def analyze_dominant_celltypes(
     score_threshold,
     frequency_threshold,
 ):
-    """Compute dominant cell types from aligned enrichment matrices."""
+    """Compute dominant cell types and cluster CNs by enrichment frequency."""
     matrices = np.asarray(enrichment_matrices, dtype=float)
 
     frequencies = (matrices > score_threshold).mean(axis=0)
     cn_names = [f"CN{index}" for index in range(1, matrices.shape[2] + 1)]
     frequency = pd.DataFrame(frequencies, index=celltypes, columns=cn_names)
+    # Each CN is represented by its across-sample enrichment frequency for
+    # every cell type, the same values displayed in the heatmap.
+    cn_linkage = None
+    if len(cn_names) > 1:
+        cn_linkage = linkage(
+            frequency.to_numpy().T,
+            method="ward",
+            metric="euclidean",
+            optimal_ordering=True,
+        )
+    cn_order = (
+        tuple(cn_names[index] for index in leaves_list(cn_linkage))
+        if cn_linkage is not None else tuple(cn_names)
+    )
     dominant = pd.DataFrame(
         {
             "CN": cn_names,
@@ -63,7 +80,7 @@ def analyze_dominant_celltypes(
             ],
         }
     )
-    return DominantCellTypeResult(frequency, dominant)
+    return DominantCellTypeResult(frequency, dominant, cn_order, cn_linkage)
 
 
 def run_dominant_celltype_analysis(config: CytoCommunityConfig, *, output_dir=None):

{cytocommunity2-1.0.1 → cytocommunity2-1.0.2}/src/cytocommunity2/downstream/plotting/dominant.py

@@ -9,13 +9,25 @@ def _prepare(result):
     frequency = result.frequency.copy()
     frequency.columns = frequency.columns.astype(str).str.strip()
     frequency.index = frequency.index.astype(str).str.strip()
-    cn_order = sorted(
+    cn_order = result.cn_order or sorted(
         frequency.columns,
         key=lambda column: int(column.removeprefix("CN")),
     )
     return frequency.loc[:, cn_order]
 
 
+def _equal_level_linkage(linkage):
+    """Give each dendrogram merge level equal display height."""
+    display_linkage = linkage.copy()
+    n_leaves = len(linkage) + 1
+    levels = np.zeros(2 * n_leaves - 1, dtype=int)
+    for index, (left, right, _, _) in enumerate(linkage):
+        level = max(levels[int(left)], levels[int(right)]) + 1
+        levels[n_leaves + index] = level
+        display_linkage[index, 2] = level
+    return display_linkage
+
+
 def plot_dominant_celltype_results(result, config):
     """Save the frequency heatmap and its colorbar."""
     import matplotlib as mpl
@@ -35,12 +47,26 @@ def plot_dominant_celltype_results(result, config):
     frequency = _prepare(result)
 
     rows, columns = frequency.shape
-    heat_height = 0.68 * 10 * rows / (8 * columns)
-    figure = plt.figure(figsize=(10, 8))
-    heat_axis = figure.add_axes([0.10, 0.10, 0.68, heat_height])
+    cell_fraction = min(0.68 / columns, 0.68 / rows)
+    heat_width = columns * cell_fraction
+    heat_height = rows * cell_fraction
+    figure = plt.figure(figsize=(8, 8))
+    heat_axis = figure.add_axes([0.10, 0.10, heat_width, heat_height])
+    if result.cn_linkage is not None:
+        from scipy.cluster.hierarchy import dendrogram
+
+        tree_axis = figure.add_axes([0.10, 0.108 + heat_height, heat_width, 0.075])
+        tree = dendrogram(_equal_level_linkage(result.cn_linkage), no_plot=True)
+        for x, y in zip(tree["icoord"], tree["dcoord"]):
+            tree_axis.plot(
+                [(value - 5) / 10 for value in x], y,
+                color="#4c5966", linewidth=0.8,
+            )
+        tree_axis.set_xlim(-0.5, columns - 0.5)
+        tree_axis.axis("off")
     heat_axis.imshow(
         frequency.to_numpy(), cmap="RdYlBu_r", vmin=0, vmax=1,
-        aspect="auto", interpolation="nearest", origin="upper",
+        aspect="equal", interpolation="nearest", origin="upper",
     )
     heat_axis.set_xticks(np.arange(columns))
     heat_axis.set_xticklabels(frequency.columns, rotation=90, fontsize=10)

{cytocommunity2-1.0.1 → cytocommunity2-1.0.2}/src/cytocommunity2/downstream/plotting/dotplots.py

@@ -8,6 +8,9 @@ import pandas as pd
 from .common import dot_size, legend_size
 
 
+DCF_STAR_THRESHOLDS = (0.1, 0.05)
+
+
 def _configure_style():
     import matplotlib as mpl
 
@@ -22,7 +25,10 @@ def _configure_style():
     })
 
 
-def _draw_panel(axis, record, celltypes, cn_order, norm, threshold, rotation, title):
+def _draw_panel(
+    axis, record, celltypes, cn_order, norm, threshold, rotation, title,
+    star_thresholds=None,
+):
     effect, pvalues = record["effect"].T, record["pvalues"].T
     x_grid, y_grid = np.meshgrid(np.arange(len(celltypes)), np.arange(len(cn_order)))
     tested = np.isfinite(effect) & np.isfinite(pvalues)
@@ -37,14 +43,31 @@ def _draw_panel(axis, record, celltypes, cn_order, norm, threshold, rotation, ti
                 c=effect[mask], cmap="coolwarm", norm=norm, alpha=alpha,
                 edgecolors=edgecolor, linewidths=linewidth, zorder=zorder,
             )
-    if np.any(significant):
-        axis.scatter(
-            x_grid[significant], y_grid[significant], s=60.0, marker="*",
-            c="#1d2630", edgecolors="none", zorder=4,
-        )
+    if star_thresholds is None:
+        if np.any(significant):
+            axis.scatter(
+                x_grid[significant], y_grid[significant], s=60.0, marker="*",
+                c="#1d2630", edgecolors="none", zorder=4,
+            )
+    else:
+        weak_threshold, strong_threshold = star_thresholds
+        one_star = tested & (pvalues < weak_threshold) & (pvalues >= strong_threshold)
+        two_stars = tested & (pvalues < strong_threshold)
+        if np.any(one_star):
+            axis.scatter(
+                x_grid[one_star], y_grid[one_star], s=60.0, marker="*",
+                c="#1d2630", edgecolors="none", zorder=4,
+            )
+        if np.any(two_stars):
+            for x_offset in (-0.075, 0.075):
+                axis.scatter(
+                    x_grid[two_stars] + x_offset, y_grid[two_stars],
+                    s=45.0, marker="*", c="#1d2630", edgecolors="none",
+                    zorder=4,
+                )
     axis.set_title(title, fontsize=13, fontweight="bold", pad=10)
     if not np.any(tested):
-        axis.text(0.5, 0.5, "Not tested\n(n < 2)", transform=axis.transAxes, ha="center", va="center", color="#6d7781")
+        axis.text(0.5, 0.5, "Not tested", transform=axis.transAxes, ha="center", va="center", color="#6d7781")
     axis.set_xticks(np.arange(len(celltypes)))
     axis.set_xticklabels(celltypes, rotation=rotation, ha="right" if rotation != 90 else "center", fontsize=8.5)
     axis.set_yticks(np.arange(len(cn_order)))
@@ -58,9 +81,13 @@ def _draw_panel(axis, record, celltypes, cn_order, norm, threshold, rotation, ti
         spine.set_visible(False)
 
 
-def _add_legends(figure, axis, norm, threshold, colorbar_title):
+def _add_legends(
+    figure, axis, norm, threshold, colorbar_title, star_thresholds=None,
+    significance_title="-log10(p-value)",
+):
     import matplotlib as mpl
     import matplotlib.pyplot as plt
+    from matplotlib.legend_handler import HandlerTuple
 
     axis.axis("off")
     scalar_map = mpl.cm.ScalarMappable(norm=norm, cmap=plt.get_cmap("coolwarm"))
@@ -70,12 +97,31 @@ def _add_legends(figure, axis, norm, threshold, colorbar_title):
     colorbar.ax.tick_params(labelsize=9)
     values = (1.3, 2.0, 3.0)
     handles = [axis.scatter([], [], s=legend_size(value), color="#b9414b") for value in values]
-    handles.append(axis.scatter([], [], s=60.0, marker="*", color="#1d2630"))
+    labels = [f"{value:g}" for value in values]
+    handler_map = None
+    if star_thresholds is None:
+        handles.append(axis.scatter([], [], s=60.0, marker="*", color="#1d2630"))
+        labels.append(f"p-value < {threshold:g}")
+    else:
+        weak_threshold, strong_threshold = star_thresholds
+        handles.extend([
+            axis.scatter([], [], s=60.0, marker="*", color="#1d2630"),
+            (
+                axis.scatter([], [], s=45.0, marker="*", color="#1d2630"),
+                axis.scatter([], [], s=45.0, marker="*", color="#1d2630"),
+            ),
+        ])
+        labels.extend([
+            f"{strong_threshold:g} <= p-value < {weak_threshold:g}",
+            f"p-value < {strong_threshold:g}",
+        ])
+        handler_map = {tuple: HandlerTuple(ndivide=None, pad=0.0)}
     axis.legend(
         handles,
-        [f"{value:g}" for value in values] + [f"p-value < {threshold:g}"],
-        title="-log10(p-value)", frameon=False, loc="center left",
+        labels,
+        title=significance_title, frameon=False, loc="center left",
         bbox_to_anchor=(0.36, 0.50), labelspacing=1.0, handletextpad=0.75,
+        handler_map=handler_map,
     )
 
 
@@ -97,7 +143,8 @@ def _normalization(records, *, cap=None):
 
 def _save_dotplots(
     records, celltypes, cn_order, norm, threshold, output_dir, prefix,
-    colorbar_title, *, grid_name=None, grid_title=None,
+    colorbar_title, *, grid_name=None, grid_title=None, star_thresholds=None,
+    significance_title="-log10(p-value)",
 ):
     import matplotlib.pyplot as plt
 
@@ -109,6 +156,7 @@ def _save_dotplots(
         _draw_panel(
             axis, record, celltypes, cn_order, norm, threshold, 90,
             f"{record['target']} vs {record['reference']}",
+            star_thresholds,
         )
         output = output_dir / f"{prefix}{record['name']}.pdf"
         figure.savefig(output, bbox_inches="tight", dpi=1200)
@@ -116,7 +164,10 @@ def _save_dotplots(
         plt.close(figure)
         outputs.append(output)
     figure, axis = plt.subplots(figsize=(4.6, 3.6))
-    _add_legends(figure, axis, norm, threshold, colorbar_title)
+    _add_legends(
+        figure, axis, norm, threshold, colorbar_title, star_thresholds,
+        significance_title,
+    )
     legend = output_dir / "LEGEND.pdf"
     figure.savefig(legend, bbox_inches="tight", dpi=1200)
     plt.close(figure)
@@ -130,8 +181,12 @@ def _save_dotplots(
             _draw_panel(
                 axis, record, celltypes, cn_order, norm, threshold, 55,
                 grid_title(record) if grid_title else record["target"],
+                star_thresholds,
             )
-        _add_legends(figure, axes[len(records)], norm, threshold, colorbar_title)
+        _add_legends(
+            figure, axes[len(records)], norm, threshold, colorbar_title,
+            star_thresholds, significance_title,
+        )
         for axis in axes[len(records) + 1:]:
             axis.set_visible(False)
         figure.subplots_adjust(left=0.07, right=0.98, bottom=0.10, top=0.96, hspace=0.60, wspace=0.25)
@@ -170,6 +225,8 @@ def _differential_records(config, results):
     celltype_index = {celltype: index for index, celltype in enumerate(celltypes)}
     records = []
     for name in names:
+        if not results.get(name):
+            continue
         target, reference = name.split("_gt_", 1)
         reference_mean = means[reference] if reference != "rest" else np.nanmean(np.stack([
             matrix for condition, matrices in condition_matrices.items()
@@ -208,14 +265,25 @@ def plot_differential_composition_results(config, results, output_dir=None):
     """Save the original differential-composition dot plots."""
     _configure_style()
     celltypes, records = _differential_records(config, results)
+    output_dir = Path(output_dir or config.project_root / "plot" / "DifferentialComposed")
+    plotted_names = {record["name"] for record in records}
+    for name in results:
+        if name not in plotted_names:
+            for old_plot in (output_dir / f"{name}.pdf", output_dir / f"{name}.png"):
+                old_plot.unlink(missing_ok=True)
+    if not records:
+        for old_plot in (output_dir / "LEGEND.pdf", output_dir / "DotPlot_all.pdf"):
+            old_plot.unlink(missing_ok=True)
+        return {"plots": [], "legend": None, "grid": None}
     threshold = config.downstream["differential_composed"]["p_value_threshold"]
     return _save_dotplots(
         records, celltypes, range(1, records[0]["effect"].shape[1] + 1),
         _normalization(records, cap=4.0), threshold,
-        output_dir or config.project_root / "plot" / "DifferentialComposed",
+        output_dir,
         "", "log2FC",
         grid_name="DotPlot_all.pdf" if config.downstream["ttest_mode"] == "one_vs_rest" else None,
         grid_title=lambda record: f"{record['target']}  (n={record['sample_count']})",
+        star_thresholds=DCF_STAR_THRESHOLDS,
     )
 
 

{cytocommunity2-1.0.1 → cytocommunity2-1.0.2}/src/cytocommunity2/learning/selection.py

@@ -28,16 +28,42 @@ def calculate_enrichment_matrix(
     num_cn,
     minimum_adjusted_p,
 ):
-    """Calculate BH-adjusted cell-type enrichment scores for one sample."""
+    """Calculate enrichment while retaining cells with an unassigned CN."""
     cell_labels = np.asarray(cell_labels, dtype=str)
-    cn_labels = np.asarray(cn_labels, dtype=np.int64)
+    cn_labels = pd.to_numeric(
+        pd.Series(np.asarray(cn_labels)).replace("NA", np.nan),
+        errors="raise",
+    ).to_numpy(dtype=float)
+    if cell_labels.size != cn_labels.size:
+        raise ValueError("Cell-type and CN-label vectors must have equal lengths")
 
     categories = pd.Categorical(cell_labels, categories=cell_types)
     cell_type_codes = categories.codes
+    if np.any(cell_type_codes < 0):
+        unknown = sorted(np.unique(cell_labels[cell_type_codes < 0]).tolist())
+        raise ValueError(f"Unknown cell types: {unknown}")
+
+    assigned = np.isfinite(cn_labels)
+    assigned_labels = cn_labels[assigned]
+    if np.any(assigned_labels != np.floor(assigned_labels)) or np.any(
+        (assigned_labels < 1) | (assigned_labels > num_cn)
+    ):
+        raise ValueError(f"CN labels must be integers from 1 to {num_cn}, or NA")
 
     counts = np.zeros((len(cell_types), num_cn), dtype=np.int64)
-    np.add.at(counts, (cell_type_codes, cn_labels - 1), 1)
-    cell_type_totals = counts.sum(axis=1)
+    np.add.at(
+        counts,
+        (
+            cell_type_codes[assigned],
+            assigned_labels.astype(np.int64) - 1,
+        ),
+        1,
+    )
+    # Cells without a CN assignment remain part of the sample and their cell
+    # type totals, but they do not contribute to any CN-specific overlap.
+    cell_type_totals = np.bincount(
+        cell_type_codes, minlength=len(cell_types)
+    )
     cn_totals = counts.sum(axis=0)
     raw_pvalues = np.ones(counts.shape, dtype=np.float64)
 
@@ -88,7 +114,7 @@ def calculate_enrichment(
             .iloc[:, 0]
             .to_numpy()
         )
-        cn_labels = np.asarray(cn_labels_by_sample[sample], dtype=np.int64)
+        cn_labels = np.asarray(cn_labels_by_sample[sample])
         matrix = calculate_enrichment_matrix(
             cell_labels,
             cn_labels,
@@ -109,13 +135,14 @@ def calculate_enrichment(
 def _load_cn_labels(samples, result_table_dir):
     result_table_dir = Path(result_table_dir)
     return {
-        sample: pd.read_csv(
-            result_table_dir / f"ResultTable_{sample}.csv",
-            usecols=["CN_Label"],
-            dtype={"CN_Label": np.int64},
-        )
-        ["CN_Label"]
-        .to_numpy()
+        sample: pd.to_numeric(
+            pd.read_csv(
+                result_table_dir / f"ResultTable_{sample}.csv",
+                usecols=["CN_Label"],
+                na_values=["NA"],
+            )["CN_Label"],
+            errors="raise",
+        ).to_numpy(dtype=float)
         for sample in samples
     }
 

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

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