cytocommunity2 0.1.1__tar.gz → 0.1.2__tar.gz

cytocommunity2-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huBioinfo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cytocommunity2-0.1.2/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: cytocommunity2
+Version: 0.1.2
+Summary: Weakly supervised cellular-neighborhood learning for spatial omics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy<2,>=1.23
+Requires-Dist: pandas<3,>=1.5
+Requires-Dist: sci-palettes
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: scipy>=1.9
+Requires-Dist: seaborn>=0.12
+Requires-Dist: torch-geometric>=2.0
+Provides-Extra: downstream
+Requires-Dist: esda<2.6,>=2.5; extra == "downstream"
+Requires-Dist: jupyter; extra == "downstream"
+Requires-Dist: libpysal<4.10,>=4.9; extra == "downstream"
+Dynamic: license-file
+
+# CytoCommunity2
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Maintainers](#maintainers)
+- [Citation](#citation)
+
+## Overview
+
+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
+**large-scale spatial omics samples with single or multiple biological
+conditions**.
+
+Inspired by histopathology workflows, CytoCommunity2 first hierarchically
+partitions the large single-cell spatial map into small patches, performs graph
+construction and weakly supervised TCN learning for each patch, and finally
+merges results through KNN-based TCN reassignment at segmentation boundaries to
+ensure TCN spatial continuity. This strategy divides the original sample into
+patches for TCN learning, achieving **memory efficiency (typical 24G graphics
+memory is enough)** and also increased sample throughput. These optimizations
+significantly **enhance the robustness of TCNs and cross-sample alignment
+performance**.
+
+Furthermore, to make CytoCommunity2 a unified framework that is also
+**applicable for single-condition spatial omics datasets**, pseudo-samples with
+artificial labels are generated, enabling automatic TCN alignment across real
+samples via **contrastive learning**.
+
+**_In summary, the advantages of CytoCommunity2 include:_**
+
+**_(1) Using significantly less memory for large-scale spatial omics samples
+with millions of cells._**
+
+**_(2) A unified weakly-supervised model applicable for both multi-condition
+and single-condition datasets._**
+
+**_(3) High TCN alignment performance makes it well-suited for comparative
+analysis in large cohort studies._**
+
+## Installation
+
+### Hardware requirement
+
+Graphics memory: 24G
+
+Storage: 10GB or more
+
+### Install CytoCommunity2
+
+CytoCommunity2 requires Python 3.10 or newer. We recommend creating and
+activating a Conda environment first:
+
+```bash
+conda create -n cytocommunity2 python=3.10
+conda activate cytocommunity2
+```
+
+Install PyTorch for your compute platform before installing CytoCommunity2.
+For an NVIDIA GPU on Windows or Linux, first install the appropriate
+CUDA-enabled PyTorch build from the
+[official PyTorch installation page](https://pytorch.org/get-started/locally/).
+
+Install the package:
+
+```bash
+pip install cytocommunity2
+```
+
+To run the downstream analyses, install the
+optional downstream dependencies with:
+
+```bash
+pip install "cytocommunity2[downstream]"
+```
+
+This extra includes `esda`, `libpysal`, and Jupyter; they are not installed
+by the basic command above.
+
+## Usage
+
+### 1. Prepare input data
+
+The input data to CytoCommunity2 includes four types of files :
+
+(1) An image (sample) name list file, named as "ImageNameList.txt".
+
+(2) A cell type label file for each image (sample), named as "[image
+name]_CellTypeLabel.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+type names of all cells in an image (sample).
+
+(3) A cell spatial coordinate file for each image (sample), named as "[image
+name]_Coordinates.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+coordinates (tab-delimited x/y) of all cells in an image (sample). The cell
+orders should be exactly the same with "[image name]_CellTypeLabel.txt".
+
+(4) A graph label file for each image (sample), named as "[image
+name]_GraphLabel.txt". For multi-condition datasets, this file must be provided
+for every image (sample) and contain one integer indicating its biological
+condition. For single-condition datasets, graph label
+files can be omitted for all images (samples), and CytoCommunity2 will generate
+pseudo-samples for weakly-supervised learning.
+
+### 2. Configure CytoCommunity2
+
+Before running CytoCommunity2, set `input_dir` and review all
+model and downstream parameters in
+[`hyperparameters.json`](https://github.com/LiukangWu/CytoCommunity2/blob/main/hyperparameters.json). The Python workflow will use this configuration file.
+
+### 3. Run CytoCommunity2
+
+The tutorial uses a TNBC dataset as a worked example and demonstrates the
+entire CytoCommunity2 workflow, from model training and CN identification to
+downstream analysis:
+
+```bash
+jupyter notebook tutorial/TNBC_workflow.ipynb
+```
+
+### 4. Output files
+
+The main output directories are:
+
+- `CNLearning_Output/`: CN-number screening, trained models and CN labels.
+- `CNVisualization_Output/`: spatial plots and result tables.
+- `data/`: downstream analysis results and intermediate data tables.
+- `plot/`: figures generated by downstream analyses.
+
+## Maintainers
+
+- Liukang Wu (yetong@stu.xidian.edu.cn)
+- Yafei Xu (22031212416@stu.xidian.edu.cn)
+- Yuxuan Hu (huyuxuan@xidian.edu.cn)
+
+## Citation
+
+Yuxuan Hu, Jiazhen Rong, Yafei Xu, Runzhi Xie, Jacqueline Peng, Lin Gao, and
+Kai Tan. “Unsupervised and supervised discovery of tissue cellular
+neighborhoods from cell phenotypes.” *Nature Methods* 21 (2024): 267–278.
+https://doi.org/10.1038/s41592-023-02124-2

cytocommunity2-0.1.2/README.md

@@ -0,0 +1,146 @@
+# CytoCommunity2
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Maintainers](#maintainers)
+- [Citation](#citation)
+
+## Overview
+
+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
+**large-scale spatial omics samples with single or multiple biological
+conditions**.
+
+Inspired by histopathology workflows, CytoCommunity2 first hierarchically
+partitions the large single-cell spatial map into small patches, performs graph
+construction and weakly supervised TCN learning for each patch, and finally
+merges results through KNN-based TCN reassignment at segmentation boundaries to
+ensure TCN spatial continuity. This strategy divides the original sample into
+patches for TCN learning, achieving **memory efficiency (typical 24G graphics
+memory is enough)** and also increased sample throughput. These optimizations
+significantly **enhance the robustness of TCNs and cross-sample alignment
+performance**.
+
+Furthermore, to make CytoCommunity2 a unified framework that is also
+**applicable for single-condition spatial omics datasets**, pseudo-samples with
+artificial labels are generated, enabling automatic TCN alignment across real
+samples via **contrastive learning**.
+
+**_In summary, the advantages of CytoCommunity2 include:_**
+
+**_(1) Using significantly less memory for large-scale spatial omics samples
+with millions of cells._**
+
+**_(2) A unified weakly-supervised model applicable for both multi-condition
+and single-condition datasets._**
+
+**_(3) High TCN alignment performance makes it well-suited for comparative
+analysis in large cohort studies._**
+
+## Installation
+
+### Hardware requirement
+
+Graphics memory: 24G
+
+Storage: 10GB or more
+
+### Install CytoCommunity2
+
+CytoCommunity2 requires Python 3.10 or newer. We recommend creating and
+activating a Conda environment first:
+
+```bash
+conda create -n cytocommunity2 python=3.10
+conda activate cytocommunity2
+```
+
+Install PyTorch for your compute platform before installing CytoCommunity2.
+For an NVIDIA GPU on Windows or Linux, first install the appropriate
+CUDA-enabled PyTorch build from the
+[official PyTorch installation page](https://pytorch.org/get-started/locally/).
+
+Install the package:
+
+```bash
+pip install cytocommunity2
+```
+
+To run the downstream analyses, install the
+optional downstream dependencies with:
+
+```bash
+pip install "cytocommunity2[downstream]"
+```
+
+This extra includes `esda`, `libpysal`, and Jupyter; they are not installed
+by the basic command above.
+
+## Usage
+
+### 1. Prepare input data
+
+The input data to CytoCommunity2 includes four types of files :
+
+(1) An image (sample) name list file, named as "ImageNameList.txt".
+
+(2) A cell type label file for each image (sample), named as "[image
+name]_CellTypeLabel.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+type names of all cells in an image (sample).
+
+(3) A cell spatial coordinate file for each image (sample), named as "[image
+name]_Coordinates.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+coordinates (tab-delimited x/y) of all cells in an image (sample). The cell
+orders should be exactly the same with "[image name]_CellTypeLabel.txt".
+
+(4) A graph label file for each image (sample), named as "[image
+name]_GraphLabel.txt". For multi-condition datasets, this file must be provided
+for every image (sample) and contain one integer indicating its biological
+condition. For single-condition datasets, graph label
+files can be omitted for all images (samples), and CytoCommunity2 will generate
+pseudo-samples for weakly-supervised learning.
+
+### 2. Configure CytoCommunity2
+
+Before running CytoCommunity2, set `input_dir` and review all
+model and downstream parameters in
+[`hyperparameters.json`](https://github.com/LiukangWu/CytoCommunity2/blob/main/hyperparameters.json). The Python workflow will use this configuration file.
+
+### 3. Run CytoCommunity2
+
+The tutorial uses a TNBC dataset as a worked example and demonstrates the
+entire CytoCommunity2 workflow, from model training and CN identification to
+downstream analysis:
+
+```bash
+jupyter notebook tutorial/TNBC_workflow.ipynb
+```
+
+### 4. Output files
+
+The main output directories are:
+
+- `CNLearning_Output/`: CN-number screening, trained models and CN labels.
+- `CNVisualization_Output/`: spatial plots and result tables.
+- `data/`: downstream analysis results and intermediate data tables.
+- `plot/`: figures generated by downstream analyses.
+
+## Maintainers
+
+- Liukang Wu (yetong@stu.xidian.edu.cn)
+- Yafei Xu (22031212416@stu.xidian.edu.cn)
+- Yuxuan Hu (huyuxuan@xidian.edu.cn)
+
+## Citation
+
+Yuxuan Hu, Jiazhen Rong, Yafei Xu, Runzhi Xie, Jacqueline Peng, Lin Gao, and
+Kai Tan. “Unsupervised and supervised discovery of tissue cellular
+neighborhoods from cell phenotypes.” *Nature Methods* 21 (2024): 267–278.
+https://doi.org/10.1038/s41592-023-02124-2

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cytocommunity2"
-version = "0.1.1"
+version = "0.1.2"
 description = "Weakly supervised cellular-neighborhood learning for spatial omics"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = [
+dependencies = [
     "matplotlib>=3.6",
     "numpy>=1.23,<2",
     "pandas>=1.5,<3",
@@ -16,7 +16,6 @@ dependencies = [
     "scikit-learn>=1.1",
     "scipy>=1.9",
     "seaborn>=0.12",
-    "torch>=1.11",
     "torch-geometric>=2.0",
 ]
 
@@ -27,6 +26,6 @@ downstream = [
     "libpysal>=4.9,<4.10",
 ]
 
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["cytocommunity2*"]
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cytocommunity2*"]

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2/downstream/communication/cca.py

@@ -169,14 +169,7 @@ def run_cca_for_scores(
             "Y_mat": y_matrix,
         }
 
-    columns = ["CN_A", "CN_B", "n_samples"]
-    if condition is not None:
-        columns.append("Condition")
-    for component in range(communication_params["cca_canonical_components"]):
-        columns.extend(
-            [f"rho{component + 1}", f"pval{component + 1}", f"invalid_perm{component + 1}"]
-        )
-    results = pd.DataFrame(result_rows, columns=columns)
+    results = pd.DataFrame(result_rows)
     if not results.empty:
         results = results.sort_values(
             "rho1", key=lambda values: values.abs(), ascending=False, na_position="last"
@@ -303,11 +296,11 @@ def run_cca_analysis(config, *, input_file=None, output_dir=None):
             condition,
         )
         condition_results.append(result["results"])
-    by_condition = (
-        pd.concat(condition_results, ignore_index=True)
-        if condition_results
-        else pd.DataFrame(columns=["Condition", *pooled["results"].columns])
-    )
+    by_condition = (
+        pd.concat(condition_results, ignore_index=True)
+        if condition_results
+        else pd.DataFrame()
+    )
     if not by_condition.empty:
         by_condition["Condition"] = pd.Categorical(
             by_condition["Condition"], categories=conditions, ordered=True

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2/learning/api.py

@@ -8,12 +8,11 @@ import shutil
 import pandas as pd
 
 from ..config import CytoCommunityConfig
-from ..ensemble import ensemble_cn
-from ..paths import build_paths
+from ..ensemble import ensemble_cn
 from .dataset import SpatialGraphDataset
 from .model import TrainingConfig
 from .selection import evaluate_cn_num, select_cn_num
-from .training import train_one_run
+from .training import train_one_run
 
 
 @dataclass(frozen=True)
@@ -34,9 +33,11 @@ class LearningResult:
 def load_learning_result(
     dataset: SpatialGraphDataset,
     config: CytoCommunityConfig,
+    *,
+    output_dir,
 ) -> LearningResult:
     """Restore a :class:`LearningResult` from a completed learning run."""
-    output_dir = build_paths(config).learning_output
+    output_dir = Path(output_dir).expanduser().resolve()
     paths = {
         "selected CN number": output_dir / "SelectedCNNum.txt",
         "cell-type list": output_dir / "UniqueCellTypeList.txt",
@@ -85,11 +86,13 @@ def _training_config(config, num_cn, num_class):
 
 
 def run_learning(
-    dataset: SpatialGraphDataset,
-    config: CytoCommunityConfig,
+    dataset: SpatialGraphDataset,
+    config: CytoCommunityConfig,
+    *,
+    output_dir,
 ) -> LearningResult:
-    """Select the CN number, train final runs, and export consensus labels."""
-    output_dir = build_paths(config).learning_output
+    """Select the CN number, train final runs, and export consensus labels."""
+    output_dir = Path(output_dir).expanduser().resolve()
     input_dir = config.input_dir
     unique_celltypes_file = output_dir / "UniqueCellTypeList.txt"
     selected_model_dir = output_dir / "SelectedModel"
@@ -147,44 +150,38 @@ def run_learning(
         )
         del hard_assignments
         selection_results.append(result)
-        cn_pvalues = cn_pvalues[
-            [
-                "CN",
-                "n_real",
-                "n_background",
-                "real_mean",
-                "background_mean",
-                "delta_mean",
-                "KSStatistic",
-                "KSLocation",
-                "p_value_one_sided",
-                "p_adjusted_bh",
-                "RecurrenceScore",
+        cn_pvalues = cn_pvalues[
+            [
+                "CN",
+                "p_value_one_sided",
+                "p_adjusted_bh",
+                "RecurrenceScore",
                 "SignificantRecurrence",
             ]
         ].copy()
         cn_pvalues.insert(0, "NumCN", num_cn)
-        cn_pvalue_tables.append(cn_pvalues)
-        print(
-            f"K={num_cn}: Ksig={result['Ksig']}, "
-            f"significantFraction={result['SignificantFraction']:.6f}, "
-            f"MeanRS={result['MeanRS']:.6f}, CRI={result['CRI']:.6f}"
-        )
-
-    pd.concat(cn_pvalue_tables, ignore_index=True).to_csv(
-        cn_pvalues_file, index=False
-    )
-    selected = select_cn_num(selection_results)
-    selected_cn = int(selected["NumCN"])
-    selection_summary = pd.DataFrame(selection_results).sort_values("NumCN")
-    selection_summary.to_csv(selection_summary_file, index=False)
-    (output_dir / "SelectedCNNum.txt").write_text(
-        f"{selected_cn}\n", encoding="utf-8"
-    )
-    print(
-        f"\nBest CRI: K={selected_cn} ({selected['CRI']:.6f}). "
-        f"Training a fresh set of Runs 1-{config.main.final_num_runs}."
-    )
+        cn_pvalue_tables.append(cn_pvalues)
+        print(
+            f"K={num_cn}: significantCN={result['SignificantCN']}, "
+            f"significantFraction={result['SignificantFraction']:.6f}, "
+            f"meanRS={result['MeanRS']:.6f}, score={result['Score']:.6f}"
+        )
+
+    pd.DataFrame(selection_results).sort_values("NumCN").to_csv(
+        selection_summary_file, index=False
+    )
+    pd.concat(cn_pvalue_tables, ignore_index=True).to_csv(
+        cn_pvalues_file, index=False
+    )
+    selected = select_cn_num(selection_results)
+    selected_cn = int(selected["NumCN"])
+    (output_dir / "SelectedCNNum.txt").write_text(
+        f"{selected_cn}\n", encoding="utf-8"
+    )
+    print(
+        f"\nSelected K={selected_cn} with score={selected['Score']:.6f}. "
+        f"Training a fresh set of Runs 1-{config.main.final_num_runs}."
+    )
 
     selected_config = _training_config(
         config, num_cn=selected_cn, num_class=dataset.num_classes

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2/learning/dataset.py

@@ -64,10 +64,9 @@ def _build_knn_edge_index(coordinates, knn_k):
     ).contiguous()
 
 
-def build_spatial_graphs(config):
-    """Read the configured samples and construct their KNN graphs once."""
-    input_folder = config.input_dir
-    knn_k = config.main.knn_k
+def build_spatial_graphs(input_dir, *, knn_k):
+    """Read real samples and construct their coordinate-based KNN graphs once."""
+    input_folder = Path(input_dir)
     sample_names = _read_lines(input_folder / "ImageNameList.txt")
     labels_by_sample = {
         sample: _read_lines(input_folder / f"{sample}_CellTypeLabel.txt")

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2/learning/selection.py

@@ -3,9 +3,12 @@
 from itertools import combinations
 from pathlib import Path
 
-import numpy as np
-import pandas as pd
-from scipy.stats import hypergeom, ks_2samp
+import numpy as np
+import pandas as pd
+from scipy.stats import hypergeom, ttest_ind
+
+
+MIN_FLOAT_P = np.finfo(np.float64).tiny
 
 
 def read_nonempty_lines(path):
@@ -218,7 +221,7 @@ def overlap_coefficient(first, second):
     return len(first & second) / smaller_size if smaller_size else 0.0
 
 
-def _load_dominant_sets(samples, score_dir, score_threshold):
+def _load_dominant_sets(samples, score_dir, score_threshold):
     celltypes = (
         pd.read_csv(Path(score_dir) / "CellTypeVec_List.csv")
         .iloc[:, 0]
@@ -241,39 +244,42 @@ def _load_dominant_sets(samples, score_dir, score_threshold):
             set(celltypes[matrix[:, cn] > score_threshold])
             for cn in range(matrix.shape[1])
         ]
-    return dominant_sets, num_cn
-
-
-def _summarize_ks(cn, real_values, background_values):
-    real_values = np.asarray(real_values, dtype=float)
-    background_values = np.asarray(background_values, dtype=float)
-    if len(real_values) >= 1 and len(background_values) >= 1:
-        result = ks_2samp(
-            real_values,
-            background_values,
-            alternative="less",
-            method="asymp",
-        )
-        ks_statistic = float(result.statistic)
-        p_value = float(result.pvalue)
-        ks_location = float(result.statistic_location)
-    else:
-        ks_statistic, p_value, ks_location = np.nan, np.nan, np.nan
-    real_mean = np.mean(real_values) if len(real_values) else np.nan
-    background_mean = (
-        np.mean(background_values) if len(background_values) else np.nan
+    return dominant_sets, num_cn
+
+
+def _summarize_ttest(cn, real_values, background_values):
+    real_values = np.asarray(real_values, dtype=float)
+    background_values = np.asarray(background_values, dtype=float)
+    if len(real_values) >= 2 and len(background_values) >= 2:
+        result = ttest_ind(
+            real_values,
+            background_values,
+            equal_var=False,
+            alternative="greater",
+        )
+        t_statistic, p_value = float(result.statistic), float(result.pvalue)
+    else:
+        t_statistic, p_value = np.nan, np.nan
+    real_mean = np.mean(real_values) if len(real_values) else np.nan
+    background_mean = (
+        np.mean(background_values) if len(background_values) else np.nan
     )
     return {
-        "CN": cn,
-        "n_real": len(real_values),
-        "n_background": len(background_values),
-        "real_mean": real_mean,
-        "background_mean": background_mean,
-        "delta_mean": real_mean - background_mean,
-        "KSStatistic": ks_statistic,
-        "KSLocation": ks_location,
-        "p_value_one_sided": p_value,
-    }
+        "CN": cn,
+        "n_real": len(real_values),
+        "n_background": len(background_values),
+        "real_mean": real_mean,
+        "real_std": np.std(real_values, ddof=1) if len(real_values) > 1 else np.nan,
+        "background_mean": background_mean,
+        "background_std": (
+            np.std(background_values, ddof=1)
+            if len(background_values) > 1
+            else np.nan
+        ),
+        "delta_mean": real_mean - background_mean,
+        "t_statistic": t_statistic,
+        "p_value_one_sided": p_value,
+    }
 
 
 def calculate_recurrence(
@@ -316,21 +322,36 @@ def calculate_recurrence(
         )
     background_df = pd.DataFrame({"OverlapCoefficient": background_values})
 
-    ks_rows = []
-    for cn in [f"CN{index + 1}" for index in range(num_cn)]:
-        values = real_df.loc[
-            real_df["CN"] == cn, "OverlapCoefficient"
-        ].to_numpy()
-        ks_rows.append(_summarize_ks(cn, values, background_values))
-    ks_df = pd.DataFrame(ks_rows)
-    ks_df["p_adjusted_bh"] = bh_adjust(
-        ks_df["p_value_one_sided"].to_numpy()
-    )
-    ks_df["RecurrenceScore"] = ks_df["KSStatistic"] * 100.0
-    ks_df["SignificantRecurrence"] = (
-        (ks_df["p_adjusted_bh"] < recurrence_p_threshold)
-        & (ks_df["delta_mean"] > 0)
-    )
+    ttest_rows = []
+    for cn in [f"CN{index + 1}" for index in range(num_cn)]:
+        values = real_df.loc[
+            real_df["CN"] == cn, "OverlapCoefficient"
+        ].to_numpy()
+        ttest_rows.append(_summarize_ttest(cn, values, background_values))
+    ttest_rows.append(
+        _summarize_ttest(
+            "Overall", real_df["OverlapCoefficient"].to_numpy(), background_values
+        )
+    )
+    ttest_df = pd.DataFrame(ttest_rows)
+    cn_mask = ttest_df["CN"] != "Overall"
+    adjusted_pvalues = bh_adjust(
+        ttest_df.loc[cn_mask, "p_value_one_sided"].to_numpy()
+    )
+    ttest_df["p_adjusted_bh"] = np.nan
+    ttest_df["RecurrenceScore"] = np.nan
+    ttest_df["SignificantRecurrence"] = False
+    ttest_df.loc[cn_mask, "p_adjusted_bh"] = adjusted_pvalues
+    ttest_df.loc[cn_mask, "RecurrenceScore"] = -np.log10(
+        np.maximum(adjusted_pvalues, MIN_FLOAT_P)
+    )
+    ttest_df.loc[cn_mask, "SignificantRecurrence"] = (
+        (
+            ttest_df.loc[cn_mask, "p_adjusted_bh"]
+            < recurrence_p_threshold
+        )
+        & (ttest_df.loc[cn_mask, "delta_mean"] > 0)
+    )
 
     output_dir = Path(output_dir)
     output_dir.mkdir(parents=True, exist_ok=True)
@@ -338,11 +359,11 @@ def calculate_recurrence(
     background_df.to_csv(
         output_dir / "BackgroundDistribution_randomCN.csv", index=False
     )
-    ks_df.to_csv(output_dir / "KSTest_Results.csv", index=False)
-    return real_df, background_df, ks_df
+    ttest_df.to_csv(output_dir / "TTest_Results.csv", index=False)
+    return real_df, background_df, ttest_df
 
 
-def evaluate_cn_num(
+def evaluate_cn_num(
     num_cn,
     dataset,
     celltype_file,
@@ -368,60 +389,38 @@ def evaluate_cn_num(
         cn_label_dir=cn_label_dir,
         hard_assignments=hard_assignments,
     )
-    real_df, _, per_cn = calculate_recurrence(
-        enrichment_dir,
-        Path(dataset) / "ImageNameList.txt",
-        overlap_dir,
+    real_df, _, ttest_df = calculate_recurrence(
+        enrichment_dir,
+        Path(dataset) / "ImageNameList.txt",
+        overlap_dir,
         score_threshold=-np.log10(enrichment_p_threshold),
         recurrence_p_threshold=recurrence_p_threshold,
-        n_random=n_random,
-        seed=seed,
-    )
-    significant_mask = per_cn["SignificantRecurrence"].astype(bool)
-    significant_cn = int(significant_mask.sum())
-    significant_fraction = significant_cn / num_cn
-    mean_oc = float(real_df["OverlapCoefficient"].mean())
-    mean_rs = float(per_cn["RecurrenceScore"].mean())
-    cri = significant_fraction**2 * mean_rs
-    result = {
-        "NumCN": int(num_cn),
-        "Ksig": significant_cn,
-        "SignificantFraction": significant_fraction,
-        "MeanOC": mean_oc,
-        "MeanRS": mean_rs,
-        "CRI": cri,
-    }
+        n_random=n_random,
+        seed=seed,
+    )
+    per_cn = ttest_df[ttest_df["CN"] != "Overall"]
+    significant_mask = per_cn["SignificantRecurrence"].astype(bool)
+    significant_cn = int(significant_mask.sum())
+    significant_fraction = significant_cn / num_cn
+    mean_rs = float(per_cn["RecurrenceScore"].mean())
+    mean_oc = float(real_df["OverlapCoefficient"].mean())
+    score = float(
+        significant_fraction**2 * significant_cn * mean_rs
+    )
+    result = {
+        "NumCN": int(num_cn),
+        "SignificantCN": significant_cn,
+        "SignificantFraction": significant_fraction,
+        "MeanRS": mean_rs,
+        "MeanOC": mean_oc,
+        "Score": score,
+    }
     pd.DataFrame([result]).to_csv(output_dir / "CNNumScore.csv", index=False)
-    return result, per_cn.copy()
-
-
-def evaluate_selected_cn(result, config):
-    """Evaluate the selected CN labels and export the communication input."""
-    from ..paths import build_paths
-
-    paths = build_paths(config)
-    metrics = evaluate_cn_num(
-        num_cn=result.selected_cn,
-        dataset=paths.input_dir,
-        cn_label_dir=result.hard_assignment_dir,
-        celltype_file=result.unique_celltypes_file,
-        output_dir=paths.downstream_data,
-        enrichment_p_threshold=config.enrichment.p_value_threshold,
-        minimum_adjusted_p=config.enrichment.minimum_adjusted_p,
-        recurrence_p_threshold=config.recurrence.recurrence_p_threshold,
-        n_random=config.recurrence.null_draws,
-        seed=config.random_seed,
-    )
-    export_enrichment_long(
-        dataset=paths.input_dir,
-        enrichment_dir=paths.enrichment,
-        output_file=paths.communication_config / "EnrichScoreMatrix_long.csv",
-    )
-    return metrics
-
-
-def select_cn_num(results):
-    """Select the K with the maximum CRI, preferring smaller K on ties."""
-    if not results:
-        raise ValueError("No CN-number results were supplied")
-    return min(results, key=lambda row: (-row["CRI"], row["NumCN"])).copy()
+    return result, per_cn.copy()
+
+
+def select_cn_num(results):
+    """Select maximum score, using smaller K as the deterministic tie-break."""
+    if not results:
+        raise ValueError("No CN-number results were supplied")
+    return min(results, key=lambda row: (-row["Score"], row["NumCN"]))

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2/learning/training.py

@@ -14,16 +14,19 @@ import torch
 import torch.nn.functional as F
 from torch_geometric.loader import DataLoader
 
-from .model import CNModel
-
-
-def set_reproducible_seed(seed):
+from .model import CNModel
+
+
+def set_reproducible_seed(seed):
     random.seed(seed)
     np.random.seed(seed)
     torch.manual_seed(seed)
     torch.cuda.manual_seed_all(seed)
     torch.backends.cudnn.benchmark = False
     torch.backends.cudnn.deterministic = True
+    if hasattr(torch.backends, "cuda") and hasattr(torch.backends.cuda, "matmul"):
+        torch.backends.cuda.matmul.allow_tf32 = False
+    torch.backends.cudnn.allow_tf32 = False
     torch.use_deterministic_algorithms(True, warn_only=True)
 
 
@@ -133,10 +136,16 @@ def train_one_run(
         shuffle=True,
         pin_memory=True,
         generator=loader_generator,
-    )
-    if device is None:
-        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-    model = CNModel(dataset.num_features, config).to(device)
+    )
+    if device is None:
+        device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    else:
+        device = torch.device(device)
+    if device.type == "cuda":
+        print(f"  Training device: GPU ({torch.cuda.get_device_name(device)})")
+    else:
+        print("  Training device: CPU")
+    model = CNModel(dataset.num_features, config).to(device)
     optimizer = torch.optim.Adam(model.parameters(), lr=config.learning_rate)
 
     loss_csv = output_folder / "Epoch_TrainLoss.csv"

cytocommunity2-0.1.2/src/cytocommunity2.egg-info/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: cytocommunity2
+Version: 0.1.2
+Summary: Weakly supervised cellular-neighborhood learning for spatial omics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy<2,>=1.23
+Requires-Dist: pandas<3,>=1.5
+Requires-Dist: sci-palettes
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: scipy>=1.9
+Requires-Dist: seaborn>=0.12
+Requires-Dist: torch-geometric>=2.0
+Provides-Extra: downstream
+Requires-Dist: esda<2.6,>=2.5; extra == "downstream"
+Requires-Dist: jupyter; extra == "downstream"
+Requires-Dist: libpysal<4.10,>=4.9; extra == "downstream"
+Dynamic: license-file
+
+# CytoCommunity2
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Maintainers](#maintainers)
+- [Citation](#citation)
+
+## Overview
+
+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
+**large-scale spatial omics samples with single or multiple biological
+conditions**.
+
+Inspired by histopathology workflows, CytoCommunity2 first hierarchically
+partitions the large single-cell spatial map into small patches, performs graph
+construction and weakly supervised TCN learning for each patch, and finally
+merges results through KNN-based TCN reassignment at segmentation boundaries to
+ensure TCN spatial continuity. This strategy divides the original sample into
+patches for TCN learning, achieving **memory efficiency (typical 24G graphics
+memory is enough)** and also increased sample throughput. These optimizations
+significantly **enhance the robustness of TCNs and cross-sample alignment
+performance**.
+
+Furthermore, to make CytoCommunity2 a unified framework that is also
+**applicable for single-condition spatial omics datasets**, pseudo-samples with
+artificial labels are generated, enabling automatic TCN alignment across real
+samples via **contrastive learning**.
+
+**_In summary, the advantages of CytoCommunity2 include:_**
+
+**_(1) Using significantly less memory for large-scale spatial omics samples
+with millions of cells._**
+
+**_(2) A unified weakly-supervised model applicable for both multi-condition
+and single-condition datasets._**
+
+**_(3) High TCN alignment performance makes it well-suited for comparative
+analysis in large cohort studies._**
+
+## Installation
+
+### Hardware requirement
+
+Graphics memory: 24G
+
+Storage: 10GB or more
+
+### Install CytoCommunity2
+
+CytoCommunity2 requires Python 3.10 or newer. We recommend creating and
+activating a Conda environment first:
+
+```bash
+conda create -n cytocommunity2 python=3.10
+conda activate cytocommunity2
+```
+
+Install PyTorch for your compute platform before installing CytoCommunity2.
+For an NVIDIA GPU on Windows or Linux, first install the appropriate
+CUDA-enabled PyTorch build from the
+[official PyTorch installation page](https://pytorch.org/get-started/locally/).
+
+Install the package:
+
+```bash
+pip install cytocommunity2
+```
+
+To run the downstream analyses, install the
+optional downstream dependencies with:
+
+```bash
+pip install "cytocommunity2[downstream]"
+```
+
+This extra includes `esda`, `libpysal`, and Jupyter; they are not installed
+by the basic command above.
+
+## Usage
+
+### 1. Prepare input data
+
+The input data to CytoCommunity2 includes four types of files :
+
+(1) An image (sample) name list file, named as "ImageNameList.txt".
+
+(2) A cell type label file for each image (sample), named as "[image
+name]_CellTypeLabel.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+type names of all cells in an image (sample).
+
+(3) A cell spatial coordinate file for each image (sample), named as "[image
+name]_Coordinates.txt". Note that [image_name] should be consistent with your
+customized image names listed in the "ImageNameList.txt". This file lists cell
+coordinates (tab-delimited x/y) of all cells in an image (sample). The cell
+orders should be exactly the same with "[image name]_CellTypeLabel.txt".
+
+(4) A graph label file for each image (sample), named as "[image
+name]_GraphLabel.txt". For multi-condition datasets, this file must be provided
+for every image (sample) and contain one integer indicating its biological
+condition. For single-condition datasets, graph label
+files can be omitted for all images (samples), and CytoCommunity2 will generate
+pseudo-samples for weakly-supervised learning.
+
+### 2. Configure CytoCommunity2
+
+Before running CytoCommunity2, set `input_dir` and review all
+model and downstream parameters in
+[`hyperparameters.json`](https://github.com/LiukangWu/CytoCommunity2/blob/main/hyperparameters.json). The Python workflow will use this configuration file.
+
+### 3. Run CytoCommunity2
+
+The tutorial uses a TNBC dataset as a worked example and demonstrates the
+entire CytoCommunity2 workflow, from model training and CN identification to
+downstream analysis:
+
+```bash
+jupyter notebook tutorial/TNBC_workflow.ipynb
+```
+
+### 4. Output files
+
+The main output directories are:
+
+- `CNLearning_Output/`: CN-number screening, trained models and CN labels.
+- `CNVisualization_Output/`: spatial plots and result tables.
+- `data/`: downstream analysis results and intermediate data tables.
+- `plot/`: figures generated by downstream analyses.
+
+## Maintainers
+
+- Liukang Wu (yetong@stu.xidian.edu.cn)
+- Yafei Xu (22031212416@stu.xidian.edu.cn)
+- Yuxuan Hu (huyuxuan@xidian.edu.cn)
+
+## Citation
+
+Yuxuan Hu, Jiazhen Rong, Yafei Xu, Runzhi Xie, Jacqueline Peng, Lin Gao, and
+Kai Tan. “Unsupervised and supervised discovery of tissue cellular
+neighborhoods from cell phenotypes.” *Nature Methods* 21 (2024): 267–278.
+https://doi.org/10.1038/s41592-023-02124-2

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 pyproject.toml
 src/cytocommunity2/__init__.py

{cytocommunity2-0.1.1 → cytocommunity2-0.1.2}/src/cytocommunity2.egg-info/requires.txt

@@ -5,7 +5,6 @@ sci-palettes
 scikit-learn>=1.1
 scipy>=1.9
 seaborn>=0.12
-torch>=1.11
 torch-geometric>=2.0
 
 [downstream]

cytocommunity2-0.1.1/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: cytocommunity2
-Version: 0.1.1
-Summary: Weakly supervised cellular-neighborhood learning for spatial omics
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: matplotlib>=3.6
-Requires-Dist: numpy<2,>=1.23
-Requires-Dist: pandas<3,>=1.5
-Requires-Dist: sci-palettes
-Requires-Dist: scikit-learn>=1.1
-Requires-Dist: scipy>=1.9
-Requires-Dist: seaborn>=0.12
-Requires-Dist: torch>=1.11
-Requires-Dist: torch-geometric>=2.0
-Provides-Extra: downstream
-Requires-Dist: esda<2.6,>=2.5; extra == "downstream"
-Requires-Dist: jupyter; extra == "downstream"
-Requires-Dist: libpysal<4.10,>=4.9; extra == "downstream"
-
-# CytoCommunity2
-
-CytoCommunity2 is a Python package for identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across  large-scale spatial omics samples with single or multiple biological conditions .
-
-## Installation
-
-Install the core package with `python -m pip install cytocommunity2`. For the full workflow,  use `python -m pip install "cytocommunity2[downstream]"`.

cytocommunity2-0.1.1/README.md

@@ -1,7 +0,0 @@
-# CytoCommunity2
-
-CytoCommunity2 is a Python package for identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across  large-scale spatial omics samples with single or multiple biological conditions .
-
-## Installation
-
-Install the core package with `python -m pip install cytocommunity2`. For the full workflow,  use `python -m pip install "cytocommunity2[downstream]"`.

cytocommunity2-0.1.1/src/cytocommunity2.egg-info/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: cytocommunity2
-Version: 0.1.1
-Summary: Weakly supervised cellular-neighborhood learning for spatial omics
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: matplotlib>=3.6
-Requires-Dist: numpy<2,>=1.23
-Requires-Dist: pandas<3,>=1.5
-Requires-Dist: sci-palettes
-Requires-Dist: scikit-learn>=1.1
-Requires-Dist: scipy>=1.9
-Requires-Dist: seaborn>=0.12
-Requires-Dist: torch>=1.11
-Requires-Dist: torch-geometric>=2.0
-Provides-Extra: downstream
-Requires-Dist: esda<2.6,>=2.5; extra == "downstream"
-Requires-Dist: jupyter; extra == "downstream"
-Requires-Dist: libpysal<4.10,>=4.9; extra == "downstream"
-
-# CytoCommunity2
-
-CytoCommunity2 is a Python package for identifying and comparing tissue cellular neighborhoods (TCNs or CNs) across  large-scale spatial omics samples with single or multiple biological conditions .
-
-## Installation
-
-Install the core package with `python -m pip install cytocommunity2`. For the full workflow,  use `python -m pip install "cytocommunity2[downstream]"`.