cytocommunity2 1.0.3__tar.gz → 1.0.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cytocommunity2
-Version: 1.0.3
+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.3 → 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.3 → cytocommunity2-1.0.4}/pyproject.toml

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

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

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

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.3 → cytocommunity2-1.0.4}/src/cytocommunity2/config.py

@@ -29,6 +29,7 @@ DOWNSTREAM_PARAMETERS = {
         "cca_min_std": 1e-8,
         "cca_max_iterations": 1000,
         "cca_n_components": 2,
+        "cca_top_celltypes": 5,
     },
 }
 

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

@@ -60,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):
@@ -312,5 +325,6 @@ __all__ = [
     "pair_rng",
     "run_cca_analysis",
     "run_cca_for_scores",
+    "select_top_features",
     "write_cca_loadings",
 ]

{cytocommunity2-1.0.3 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/differential_composition.py

@@ -7,31 +7,25 @@ import pandas as pd
 
 from ..config import CytoCommunityConfig
 from ..paths import build_paths
-from .dominant_celltype import load_enrichment_matrices
+from .enrichment import load_enrichment_by_sample
 from .wilcoxon import rank_sum_test
 
 
 def load_condition_enrichment(enrichment_dir, input_dir):
     """Load enrichment matrices together with each sample's graph label."""
-    celltypes, matrices = load_enrichment_matrices(
+    celltypes, matrices = load_enrichment_by_sample(
         enrichment_dir, input_dir
     )
     input_dir = Path(input_dir)
-    samples = (
-        pd.read_csv(input_dir / "ImageNameList.txt", sep="\t", header=None)
-        .iloc[:, 0]
-        .astype(str)
-        .tolist()
-    )
     records = [
         {
             "sample": sample,
             "condition": int(
                 np.loadtxt(input_dir / f"{sample}_GraphLabel.txt", dtype="int64")
             ),
-            "matrix": matrices[index],
+            "matrix": matrix,
         }
-        for index, sample in enumerate(samples)
+        for sample, matrix in matrices.items()
     ]
     return celltypes, records
 

{cytocommunity2-1.0.3 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/dominant_celltype.py

@@ -9,6 +9,7 @@ from scipy.cluster.hierarchy import leaves_list, linkage
 
 from ..config import CytoCommunityConfig
 from ..paths import build_paths
+from .enrichment import load_enrichment_by_sample
 
 
 @dataclass(frozen=True)
@@ -22,24 +23,9 @@ class DominantCellTypeResult:
 
 
 def load_enrichment_matrices(enrichment_dir, input_dir):
-    """Load per-sample enrichment matrices in their stored cell-type order."""
-    enrichment_dir = Path(enrichment_dir)
-    input_dir = Path(input_dir)
-    source_celltypes = (
-        pd.read_csv(enrichment_dir / "CellTypeVec_List.csv")
-        .iloc[:, 0]
-        .astype(str)
-        .str.strip()
-        .tolist()
-    )
-    samples = pd.read_csv(input_dir / "ImageNameList.txt", header=None).iloc[:, 0]
-    matrices = [
-        pd.read_csv(
-            enrichment_dir / f"{sample}_EnrichScoreMatrix.csv", header=None
-        ).to_numpy(dtype=float)
-        for sample in samples
-    ]
-    return source_celltypes, np.stack(matrices, axis=0)
+    """Retain the stacked-array interface for dominant-cell-type analysis."""
+    celltypes, matrices = load_enrichment_by_sample(enrichment_dir, input_dir)
+    return celltypes, np.stack(list(matrices.values()), axis=0)
 
 
 def analyze_dominant_celltypes(

{cytocommunity2-1.0.3 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/enrichment.py

@@ -9,6 +9,26 @@ from scipy.stats import false_discovery_control, hypergeom
 from .._io import read_nonempty_lines
 
 
+def load_enrichment_by_sample(enrichment_dir, input_dir):
+    """Load enrichment matrices keyed by sample, in the input-list order."""
+    enrichment_dir = Path(enrichment_dir)
+    celltypes = (
+        pd.read_csv(enrichment_dir / "CellTypeVec_List.csv")
+        .iloc[:, 0]
+        .astype(str)
+        .str.strip()
+        .tolist()
+    )
+    samples = read_nonempty_lines(Path(input_dir) / "ImageNameList.txt")
+    matrices = {
+        sample: pd.read_csv(
+            enrichment_dir / f"{sample}_EnrichScoreMatrix.csv", header=None
+        ).to_numpy(dtype=float)
+        for sample in samples
+    }
+    return celltypes, matrices
+
+
 def calculate_enrichment_matrix(
     cell_labels,
     cn_labels,
@@ -126,19 +146,9 @@ def calculate_enrichment(
 def export_enrichment_long(dataset, enrichment_dir, output_file):
     """Export the selected model's enrichment matrices for communication analysis."""
     dataset = Path(dataset)
-    enrichment_dir = Path(enrichment_dir)
-    samples = read_nonempty_lines(dataset / "ImageNameList.txt")
-    celltypes = (
-        pd.read_csv(enrichment_dir / "CellTypeVec_List.csv")
-        .iloc[:, 0]
-        .astype(str)
-        .tolist()
-    )
+    celltypes, matrices = load_enrichment_by_sample(enrichment_dir, dataset)
     tables = []
-    for sample in samples:
-        matrix = pd.read_csv(
-            enrichment_dir / f"{sample}_EnrichScoreMatrix.csv", header=None
-        ).to_numpy(dtype=float)
+    for sample, matrix in matrices.items():
         table = (
             pd.DataFrame(
                 matrix,

{cytocommunity2-1.0.3 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/moran.py

@@ -7,6 +7,7 @@ from libpysal.weights import DistanceBand
 import numpy as np
 import pandas as pd
 
+from .._io import read_nonempty_lines
 from ..config import CytoCommunityConfig
 from ..paths import build_paths
 from .wilcoxon import rank_sum_test
@@ -25,9 +26,7 @@ MORAN_COLUMNS = [
 def load_graph_labels(input_dir):
     """Read each sample's condition from its GraphLabel file."""
     input_dir = Path(input_dir)
-    samples = pd.read_csv(
-        input_dir / "ImageNameList.txt", sep="\t", header=None, names=["Sample"]
-    )["Sample"].astype(str)
+    samples = read_nonempty_lines(input_dir / "ImageNameList.txt")
     return {
         sample: int(np.loadtxt(input_dir / f"{sample}_GraphLabel.txt", dtype="int64"))
         for sample in samples

{cytocommunity2-1.0.3 → cytocommunity2-1.0.4}/src/cytocommunity2/downstream/plotting/cn_selection.py

@@ -6,47 +6,32 @@ import matplotlib.pyplot as plt
 import pandas as pd
 
 from ...paths import build_paths
+from .common import save_figure
 
 
-def _save_figure(figure, output_stem):
-    output_stem = Path(output_stem)
-    output_stem.parent.mkdir(parents=True, exist_ok=True)
-    figure.savefig(output_stem.with_suffix(".pdf"), bbox_inches="tight")
-    figure.savefig(output_stem.with_suffix(".png"), dpi=300, bbox_inches="tight")
-    plt.close(figure)
-    return output_stem
-
-
-def _plot_cri(summary, output_stem):
+def _plot_cri(summary, output_stem, *, png=False):
     values = summary["CRI"]
     k_values = summary["NumCN"].astype(int)
     best_index = values.idxmax()
     best_k = int(k_values.loc[best_index])
-    best_value = float(values.loc[best_index])
 
-    figure, axis = plt.subplots(figsize=(6.0, 4.8))
+    figure, axis = plt.subplots(figsize=(7.4, 6.0))
     axis.bar(k_values, values, width=0.62, color="#c9c9c9", edgecolor="none")
     axis.plot(k_values, values, color="black", linestyle=(0, (2, 2)), marker="o")
-    axis.annotate(
-        f"Optimal: K={best_k}",
-        xy=(best_k, best_value),
-        xytext=(0, 10),
-        textcoords="offset points",
-        ha="center",
-        va="bottom",
-        fontsize=11,
-    )
-    axis.set_xlabel(r"$K$", fontsize=13)
-    axis.set_ylabel("CN resolution index (CRI)", fontsize=12)
+    axis.set_title(rf"Optimal: $K$={best_k}", fontsize=18, pad=10, loc="center")
+    axis.set_xlabel(r"$K$", fontsize=18)
+    axis.set_ylabel("CN resolution index", fontsize=16)
     axis.set_xticks(k_values)
     axis.spines[["top", "right"]].set_visible(False)
-    axis.tick_params(labelsize=10)
+    axis.tick_params(labelsize=13)
     axis.margins(x=0.04)
     figure.tight_layout()
-    return _save_figure(figure, output_stem)
+    output = save_figure(figure, output_stem, png=png)
+    plt.close(figure)
+    return output
 
 
-def plot_cn_selection_scores(selection_summary, config):
+def plot_cn_selection_scores(selection_summary, config, *, png=False):
     """Plot the composite CRI score across candidate CN numbers."""
     if isinstance(selection_summary, (str, Path)):
         summary = pd.read_csv(selection_summary)
@@ -55,4 +40,4 @@ def plot_cn_selection_scores(selection_summary, config):
 
     summary = summary.sort_values("NumCN").reset_index(drop=True)
     output_dir = build_paths(config).downstream_plot / "CNSelection"
-    return _plot_cri(summary, output_dir / "CRI_by_K")
+    return _plot_cri(summary, output_dir / "CRI_by_K", png=png)

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

@@ -1,23 +1,15 @@
 """Spatial coherence figures."""
 
 from ...paths import build_paths
+from .common import configure_style, save_figure
 
 
 def plot_coherence_results(result, config):
     """Save CHAOS and PAS boxplots."""
-    import matplotlib as mpl
     import matplotlib.pyplot as plt
     import seaborn as sns
 
-    mpl.rcParams.update({
-        "font.family": "Arial",
-        "font.size": 12,
-        "axes.linewidth": 0.8,
-        "lines.linewidth": 1.5,
-        "xtick.labelsize": 10,
-        "ytick.labelsize": 10,
-        "pdf.fonttype": 42,
-    })
+    configure_style()
     output_dir = build_paths(config).downstream_plot / "Coherence"
     output_dir.mkdir(parents=True, exist_ok=True)
     frame = result.loc[
@@ -28,7 +20,7 @@ def plot_coherence_results(result, config):
     plt.rcParams["grid.alpha"] = 0.25
     outputs = {}
     for column, axis_max in (("CHAOS", 0.02), ("PAS", 0.5)):
-        figure, axis = plt.subplots(figsize=(8, 6), dpi=1200)
+        figure, axis = plt.subplots(figsize=(8, 6))
         sns.boxplot(
             data=frame,
             y=column,
@@ -52,8 +44,7 @@ def plot_coherence_results(result, config):
         axis.spines["top"].set_visible(False)
         axis.spines["right"].set_visible(False)
         figure.tight_layout()
-        output = output_dir / f"{column}.pdf"
-        figure.savefig(output, dpi=1200, bbox_inches="tight")
+        output = save_figure(figure, output_dir / f"{column}.pdf")
         plt.close(figure)
         outputs[column] = output
     return outputs

cytocommunity2-1.0.4/src/cytocommunity2/downstream/plotting/common.py

@@ -0,0 +1,146 @@
+"""Plotting primitives shared by multiple downstream figures."""
+
+from pathlib import Path
+
+import numpy as np
+
+
+def configure_style(*, line_width=1.5, ps_fonttype=None):
+    """Apply the shared figure style while allowing per-plot line widths."""
+    import matplotlib as mpl
+
+    style = {
+        "font.family": "Arial",
+        "font.size": 12,
+        "axes.linewidth": 0.8,
+        "lines.linewidth": line_width,
+        "xtick.labelsize": 10,
+        "ytick.labelsize": 10,
+        "pdf.fonttype": 42,
+    }
+    if ps_fonttype is not None:
+        style["ps.fonttype"] = ps_fonttype
+    mpl.rcParams.update(style)
+
+
+def save_figure(figure, output, *, png=False):
+    """Save a PDF, plus a PNG when explicitly requested for notebook display."""
+    output = Path(output).with_suffix(".pdf")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    figure.savefig(output, bbox_inches="tight", dpi=1200)
+    if png:
+        figure.savefig(output.with_suffix(".png"), bbox_inches="tight", dpi=300)
+    return output
+
+
+def add_colorbar(figure, axis, norm, title, ticks=None, *, cmap, orientation="vertical"):
+    """Draw a borderless color scale with a side label and visible ticks."""
+    import matplotlib as mpl
+    from matplotlib.ticker import MaxNLocator, StrMethodFormatter
+
+    scalar = mpl.cm.ScalarMappable(norm=norm, cmap=cmap)
+    if ticks is None:
+        step = 1.0 if norm.vmax - norm.vmin > 4 else 0.5
+        ticks = np.arange(np.ceil(norm.vmin / step), np.floor(norm.vmax / step) + 1) * step
+        if len(ticks) < 2:
+            ticks = MaxNLocator(nbins=4, steps=[1, 2, 5, 10]).tick_values(norm.vmin, norm.vmax)
+            ticks = ticks[(ticks >= norm.vmin) & (ticks <= norm.vmax)]
+    colorbar = figure.colorbar(scalar, cax=axis, ticks=ticks, orientation=orientation)
+    colorbar.formatter = StrMethodFormatter("{x:g}")
+    colorbar.update_ticks()
+    colorbar.set_label(title, fontsize=12, labelpad=10)
+    if orientation == "vertical":
+        colorbar.ax.yaxis.set_label_position("left")
+    colorbar.ax.tick_params(
+        axis="y" if orientation == "vertical" else "x",
+        labelsize=10, length=3, width=0.8, pad=5, direction="out",
+        **({"right": True, "left": False, "labelright": True, "labelleft": False}
+           if orientation == "vertical" else
+           {"bottom": True, "top": False, "labelbottom": True, "labeltop": False}),
+    )
+    colorbar.outline.set_visible(False)
+    return colorbar
+
+
+def save_legend(handles, labels, output, *, title=None, columns=1):
+    """Save a categorical legend separately from its main figure."""
+    import matplotlib.pyplot as plt
+
+    figure, axis = plt.subplots(figsize=(max(3.4, 1.7 * columns), 2.5))
+    axis.axis("off")
+    axis.legend(handles, labels, title=title, ncol=columns, loc="center", frameon=False)
+    output = save_figure(figure, output)
+    plt.close(figure)
+    return output
+
+
+def dot_size(pvalues):
+    strength = np.minimum(
+        -np.log10(np.clip(np.asarray(pvalues, dtype=float), 1e-300, 1.0)),
+        5.0,
+    )
+    return legend_size(strength)
+
+
+def legend_size(strength):
+    return 30.0 + 600.0 * np.asarray(strength, dtype=float) / 5.0
+
+
+def plot_enrichment_scatter(
+    x,
+    y,
+    xlabel,
+    ylabel,
+    rho,
+    pval,
+    out_pdf,
+    enrichment_score_max=20.0,
+):
+    """Draw the shared enrichment-score scatter style."""
+    import matplotlib.pyplot as plt
+    import matplotlib.ticker as ticker
+
+    figure, axis = plt.subplots(figsize=(6, 6))
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    valid = np.isfinite(x) & np.isfinite(y)
+    x, y = x[valid], y[valid]
+    if len(x) >= 2 and len(np.unique(x)) > 1 and len(np.unique(y)) > 1:
+        slope, intercept = np.polyfit(x, y, 1)
+        x_line = np.linspace(float(np.min(x)), float(np.max(x)), 200)
+        axis.plot(
+            x_line,
+            slope * x_line + intercept,
+            linewidth=1.2,
+            color="black",
+            zorder=1,
+        )
+    axis.scatter(x, y, s=30, edgecolor="black", alpha=0.9, zorder=2)
+    axis.set_xlabel(xlabel, fontsize=10)
+    axis.set_ylabel(ylabel, fontsize=10)
+    interval = enrichment_score_max / 8
+    margin = interval / 5
+    ticks = np.linspace(0.0, enrichment_score_max, 9)
+    axis.set_xlim(-margin, enrichment_score_max + margin)
+    axis.set_ylim(-margin, enrichment_score_max + margin)
+    axis.set_xticks(ticks)
+    axis.set_yticks(ticks)
+    axis.xaxis.set_major_formatter(ticker.FormatStrFormatter("%.1f"))
+    axis.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.1f"))
+    axis.tick_params(axis="x", labelrotation=30, labelsize=10)
+    axis.tick_params(axis="y", labelsize=10)
+    axis.spines["top"].set_visible(False)
+    axis.spines["right"].set_visible(False)
+    axis.text(
+        0.80,
+        0.98,
+        f"rho = {rho:.2f}\np = {pval:.2g}",
+        transform=axis.transAxes,
+        ha="left",
+        va="top",
+        fontsize=10,
+    )
+    figure.tight_layout()
+    output = save_figure(figure, out_pdf)
+    plt.close(figure)
+    return output