Correct public repo scope and remove legacy CCST files

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,4 +1,4 @@
-__pycache__/
-*.pyc
-.DS_Store
-outputs/
+__pycache__/
+*.pyc
+.DS_Store
+outputs/

CITATION.cff

@@ -1,31 +1,31 @@
 cff-version: 1.2.0
-message: "If you use this repository, please cite the associated manuscript and this repository."
-title: "CCST for Spatial Transcriptomics"
+message: "Please cite the associated manuscript for scientific results and cite this repository as a manuscript companion placeholder when relevant."
+title: "COSTE and DST-GNN Manuscript Companion Placeholder"
 type: software
 authors:
   - family-names: "Hu"
     given-names: "Taobo"
-  - family-names: "Long"
-    given-names: "Mengping"
+  - family-names: "Long"
+    given-names: "Mengping"
 repository-code: "https://huggingface.co/hutaobo/ccst-spatial-clustering"
 license: "CC-BY-NC-4.0"
 keywords:
-  - spatial transcriptomics
-  - PyTorch Geometric
-  - graph neural network
-  - Visium
+  - spatial omics
+  - tissue architecture
+  - manuscript companion
+abstract: "Public manuscript companion placeholder for the COSTE and DST-GNN study. The current repository release does not include the DST-GNN implementation used for manuscript analyses."
 preferred-citation:
   type: article
   title: "Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics"
-  authors:
-    - family-names: "Long"
-      given-names: "Mengping"
-    - family-names: "Hu"
-      given-names: "Taobo"
-    - family-names: "Sountoulidis"
-      given-names: "Alexandros"
+  authors:
+    - family-names: "Long"
+      given-names: "Mengping"
+    - family-names: "Hu"
+      given-names: "Taobo"
+    - family-names: "Sountoulidis"
+      given-names: "Alexandros"
     - family-names: "Samakovlis"
       given-names: "Christos"
     - family-names: "Nilsson"
       given-names: "Mats"
-  note: "Included in this repository as a user-provided reference PDF."
+  note: "Scientific results should be attributed to the manuscript. The public DST-GNN implementation is not included in the current repository release."

LICENSE.md

@@ -1,9 +1,9 @@
-CCST for Spatial Transcriptomics
+COSTE and DST-GNN Manuscript Companion Placeholder
 Non-Commercial Distribution Notice
 
-This repository is intended for non-commercial research and academic use.
+The contents currently published in this repository are released for non-commercial research and academic use.
 
-Requested Hugging Face license tag:
+Repository license tag:
 
 - `cc-by-nc-4.0`
 
@@ -17,10 +17,10 @@ Official license page:
 
 Summary:
 
-- You may share and adapt the material for non-commercial purposes.
-- Appropriate attribution should be given when redistributing or adapting this repository.
+- You may share and adapt the currently published repository contents for non-commercial purposes.
+- Appropriate attribution should be given when redistributing or adapting the repository contents.
 - Commercial use is not permitted under this repository-level release setting.
 
-Important note:
+Scope note:
 
-This repository was assembled from local CCST script snapshots and user-provided reference material. If any upstream project imposes additional terms, those upstream terms should also be respected.
+The current public release is a manuscript companion placeholder consisting of descriptive documentation and repository metadata. The DST-GNN implementation described in the associated manuscript is not included in this release.

MERGE_NOTES.md

@@ -1,50 +0,0 @@
-# Merge Notes
-
-## Source Files
-
-This repository was assembled from the following local files:
-
-- `C:\Users\taobo.hu\Downloads\SRTBenchmark-main\SRTBenchmark-main\Methods\CCST_Sample.py`
-- `C:\Users\taobo.hu\Downloads\SRTBenchmark-main\SRTBenchmark-main\Methods\CCST_Sample_Optimized.py`
-
-## Main Observed Difference
-
-The local diff between the two scripts was limited to preprocessing:
-
-```text
-CCST_Sample.py
-- features = adata_preprocess(adata, min_cells=5, pca_n_comps=200)
-
-CCST_Sample_Optimized.py
-- sc.pp.highly_variable_genes(adata, flavor='seurat_v3', n_top_genes=2000)
-- adata = adata[:, adata.var.highly_variable]
-- features = adata_preprocess(adata, min_cells=5, pca_n_comps=50)
-```
-
-## Cleanup Performed
-
-- Merged duplicated logic into one script: `run_ccst.py`
-- Added CLI arguments for data paths and preprocessing choices
-- Replaced hard-coded paths with arguments
-- Kept both preprocessing behaviors through profiles
-- Added output summary JSON
-- Made the Leiden/Louvain branch executable instead of relying on undefined names
-- Removed unused imports and tightened the dependency surface
-
-## Reference PDF
-
-During local preparation, the following user-provided manuscript PDF was consulted:
-
-- `references/719013_0_art_file_252332_t72882.pdf`
-
-Extracted first-page title:
-
-- `Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics`
-
-This PDF was used as a local reference artifact during repository preparation.
-It is not intended to be uploaded as part of the public Hugging Face repository.
-
-## Planned Hub Metadata
-
-- Recommended repo name: `hutaobo/ccst-spatial-clustering`
-- Requested Hugging Face license tag: `cc-by-nc-4.0`

README.md

@@ -1,36 +1,31 @@
 ---
 license: cc-by-nc-4.0
-library_name: pytorch
 tags:
-- spatial-transcriptomics
-- graph-neural-network
-- torch-geometric
-- visium
 - research
+- computational-biology
+- spatial-omics
+- manuscript-companion
 ---
 
-# CCST for Spatial Transcriptomics
+# COSTE and DST-GNN Manuscript Companion
 
-This repository contains a cleaned, merged version of two local CCST scripts:
+The repository path `hutaobo/ccst-spatial-clustering` is retained for continuity from an earlier private working name.
 
-- `CCST_Sample.py`
-- `CCST_Sample_Optimized.py`
+This public repository is currently a manuscript companion placeholder. The public release does **not** include the DST-GNN implementation used for the manuscript results.
 
-The merged implementation is provided as `run_ccst.py`.
+## Status
 
-Recommended Hugging Face repository name:
+- This repository currently contains descriptive documentation and citation metadata only.
+- No runnable modeling pipeline is included in the present public release.
+- The current public contents should not be interpreted as the implementation behind the manuscript analyses.
 
-- `hutaobo/ccst-spatial-clustering`
+## Manuscript Context
 
-This repository is intended as a compact, publication-oriented companion repository for CCST-based spatial clustering workflows implemented with PyTorch Geometric.
-
-## Research Context
-
-Reference manuscript used while preparing this repository:
+This repository is associated with the manuscript:
 
 - *Cophenetic Spatial Topology Embedding reveals multiscale tissue architecture in spatial omics*
 
-Authors listed on the first page of the provided PDF:
+Authors listed on the manuscript title page:
 
 - Mengping Long
 - Taobo Hu
@@ -38,107 +33,29 @@ Authors listed on the first page of the provided PDF:
 - Christos Samakovlis
 - Mats Nilsson
 
-## What Was Merged
-
-The original local scripts were nearly identical. The main preprocessing difference was:
-
-- `CCST_Sample.py`: no highly variable gene filtering, PCA with 200 components
-- `CCST_Sample_Optimized.py`: HVG filtering with `n_top_genes=2000`, PCA with 50 components
-
-The merged script keeps both behaviors through a single command-line interface:
-
-- `--profile original`
-- `--profile optimized`
-
-You can also override the defaults with:
-
-- `--use-hvg` or `--no-hvg`
-- `--n-top-genes`
-- `--pca-n-comps`
-
-## Repository Layout
-
-- `run_ccst.py`: merged and cleaned CCST runner
-- `requirements.txt`: Python dependencies
-- `MERGE_NOTES.md`: provenance and merge notes
-- `LICENSE.md`: non-commercial repository license note
-- `CITATION.cff`: citation metadata for scholarly reuse
-- `references/REFERENCE_NOTE.md`: note about the manuscript reference used during repository preparation
-
-## Usage
+The manuscript describes a workflow in which COSTE-derived spatial relationship graphs are analyzed over time with a diffusion-based spatio-temporal graph neural network (DST-GNN). That implementation is not part of the current public repository contents.
 
-Example using the optimized profile:
+## What Is Currently Published
 
-```bash
-python run_ccst.py \
-  --visium-dir ./DLPFC/151673 \
-  --output-dir ./outputs/151673 \
-  --profile optimized
-```
+- `README.md`: public repository card and status summary
+- `CITATION.cff`: citation metadata for the manuscript companion repository
+- `LICENSE.md`: non-commercial distribution notice for the currently published repository contents
+- `upload_to_hf.py`: utility script for synchronizing this repository to the Hugging Face Hub
 
-Example reproducing the original local preprocessing:
+## Planned Public Release Scope
 
-```bash
-python run_ccst.py \
-  --visium-dir ./DLPFC/151673 \
-  --output-dir ./outputs/151673_original \
-  --profile original
-```
+Future public updates may include:
 
-Example with explicit overrides:
+- cohort-level COSTE spatial separation score graphs across multiple time points
+- temporal graph modeling of tissue-state transitions
+- explainability outputs for influential nodes and edges
 
-```bash
-python run_ccst.py \
-  --visium-dir ./DLPFC/151673 \
-  --output-dir ./outputs/151673_custom \
-  --profile optimized \
-  --no-hvg \
-  --pca-n-comps 120 \
-  --distance-threshold 200 \
-  --lambda-i 0.3
-```
-
-## Expected Inputs
-
-The script expects a standard 10x Visium-style sample directory with:
-
-- a count matrix file, default: `filtered_feature_bc_matrix.h5`
-- a metadata table, default: `metadata.tsv`
-
-The metadata file should include a ground-truth annotation column. By default this script uses:
-
-- `layer_guess`
-
-You can change that with:
-
-```bash
---ground-truth-column your_column_name
-```
-
-## Outputs
-
-The output directory will contain:
-
-- `features.npy`
-- `coordinates.npy`
-- `Adjacent`
-- `cell_types.npy`
-- `types_dic.txt`
-- DGI checkpoint
-- node embedding `.npy`
-- `CCST_results.h5ad`
-- `run_summary.json`
+No release timeline is promised in this repository.
 
 ## Citation
 
-If you use this repository in academic work, please cite the associated manuscript and reference this repository as the script companion used for CCST preprocessing and clustering reproduction.
-
-The repository includes a `CITATION.cff` file to support software citation workflows.
+Please cite the associated manuscript for scientific results derived from COSTE and DST-GNN analyses. The repository also includes a `CITATION.cff` file for repository-level citation metadata.
 
-## Notes
+## License
 
-- The merged script defaults to `kmeans`, because that is the branch actually exercised by the local scripts.
-- `leiden` and `louvain` are also supported in the cleaned script to make the clustering step explicit and self-contained.
-- The Hugging Face repo card is configured with `license: cc-by-nc-4.0` to reflect the requested non-commercial distribution setting on the Hub.
-- The local downloaded snapshot used to build this repo did not expose a clear software license file, so public redistribution should be reviewed carefully before release outside your intended publication workflow.
-- The manuscript PDF used during local preparation is intentionally not uploaded to the public Hugging Face repository.
+The currently published repository contents are provided under a non-commercial license. See `LICENSE.md` for details.

references/REFERENCE_NOTE.md

@@ -1,5 +0,0 @@
-# Reference Note
-
-During local preparation of this repository, a user-provided manuscript PDF was consulted for title and authorship context.
-
-That manuscript file is not included in the public Hugging Face upload.

requirements.txt

@@ -1,10 +0,0 @@
-anndata
-h5py
-matplotlib
-numpy
-pandas
-scanpy
-scikit-learn
-scipy
-torch
-torch-geometric

run_ccst.py

@@ -1,432 +0,0 @@
-#!/usr/bin/env python
-"""Run CCST on a Visium sample with configurable preprocessing.
-
-This script merges two local variants:
-- CCST_Sample.py
-- CCST_Sample_Optimized.py
-
-The original difference was limited to preprocessing:
-- original: no HVG filtering, PCA to 200 components
-- optimized: HVG filtering (top 2000 genes), PCA to 50 components
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import pickle
-import random
-import time
-import tracemalloc
-from dataclasses import dataclass
-from pathlib import Path
-
-import anndata as ad
-import matplotlib
-
-matplotlib.use("Agg")
-
-import numpy as np
-import pandas as pd
-import scanpy as sc
-import torch
-import torch.nn as nn
-from scipy import sparse
-from sklearn import metrics
-from sklearn.cluster import KMeans
-from sklearn.decomposition import PCA
-from sklearn.metrics.pairwise import euclidean_distances
-from torch_geometric.data import Data
-from torch_geometric.loader import DataLoader
-from torch_geometric.nn import DeepGraphInfomax, GCNConv
-
-
-@dataclass
-class PreprocessingConfig:
-    use_hvg: bool
-    n_top_genes: int
-    pca_n_comps: int
-
-
-class GraphEncoder(nn.Module):
-    def __init__(self, in_channels: int, hidden_channels: int) -> None:
-        super().__init__()
-        self.conv_1 = GCNConv(in_channels, hidden_channels)
-        self.conv_2 = GCNConv(hidden_channels, hidden_channels)
-        self.conv_3 = GCNConv(hidden_channels, hidden_channels)
-        self.conv_4 = GCNConv(hidden_channels, hidden_channels)
-        self.prelu = nn.PReLU(hidden_channels)
-
-    def forward(self, data: Data) -> torch.Tensor:
-        x, edge_index, edge_weight = data.x, data.edge_index, data.edge_attr
-        x = self.conv_1(x, edge_index, edge_weight=edge_weight)
-        x = self.conv_2(x, edge_index, edge_weight=edge_weight)
-        x = self.conv_3(x, edge_index, edge_weight=edge_weight)
-        x = self.conv_4(x, edge_index, edge_weight=edge_weight)
-        return self.prelu(x)
-
-
-class CorruptedGraph:
-    def __init__(self, x: torch.Tensor, edge_index: torch.Tensor, edge_attr: torch.Tensor) -> None:
-        self.x = x
-        self.edge_index = edge_index
-        self.edge_attr = edge_attr
-
-
-def set_seed(seed: int) -> None:
-    random.seed(seed)
-    np.random.seed(seed)
-    torch.manual_seed(seed)
-    if torch.cuda.is_available():
-        torch.cuda.manual_seed_all(seed)
-
-
-def resolve_preprocessing(args: argparse.Namespace) -> PreprocessingConfig:
-    if args.profile == "original":
-        default = PreprocessingConfig(use_hvg=False, n_top_genes=2000, pca_n_comps=200)
-    else:
-        default = PreprocessingConfig(use_hvg=True, n_top_genes=2000, pca_n_comps=50)
-
-    if args.use_hvg is not None:
-        default.use_hvg = args.use_hvg
-    if args.n_top_genes is not None:
-        default.n_top_genes = args.n_top_genes
-    if args.pca_n_comps is not None:
-        default.pca_n_comps = args.pca_n_comps
-    return default
-
-
-def preprocess_adata(
-    adata: ad.AnnData,
-    min_cells: int,
-    config: PreprocessingConfig,
-) -> tuple[np.ndarray, ad.AnnData]:
-    print("===== Preprocessing data")
-    sc.pp.filter_genes(adata, min_cells=min_cells)
-
-    if config.use_hvg:
-        sc.pp.highly_variable_genes(
-            adata,
-            flavor="seurat_v3",
-            n_top_genes=config.n_top_genes,
-        )
-        adata = adata[:, adata.var.highly_variable].copy()
-
-    normalized = sc.pp.normalize_total(
-        adata,
-        target_sum=1,
-        exclude_highly_expressed=True,
-        inplace=False,
-    )["X"]
-    scaled = sc.pp.scale(normalized)
-    pca = sc.pp.pca(scaled, n_comps=config.pca_n_comps)
-    return np.asarray(pca, dtype=np.float32), adata
-
-
-def build_adjacency_matrix(coordinates: np.ndarray, threshold: float) -> sparse.csr_matrix:
-    print("===== Building adjacency matrix")
-    distance_matrix = euclidean_distances(coordinates, coordinates)
-    adjacency = ((distance_matrix <= threshold) & (distance_matrix > 0)).astype(np.float32)
-    return sparse.csr_matrix(adjacency)
-
-
-def save_cell_types(cell_types: np.ndarray, output_dir: Path) -> None:
-    seen: list[str] = []
-    for cell_type in cell_types:
-        as_text = str(cell_type)
-        if as_text not in seen:
-            seen.append(as_text)
-
-    np.save(output_dir / "cell_types.npy", np.asarray(cell_types))
-    np.savetxt(output_dir / "types_dic.txt", np.asarray(seen), fmt="%s", delimiter="\t")
-
-
-def load_graph_inputs(
-    output_dir: Path,
-    lambda_i: float,
-) -> tuple[sparse.csr_matrix, sparse.csr_matrix, np.ndarray, np.ndarray]:
-    with open(output_dir / "Adjacent", "rb") as handle:
-        adjacency_raw = pickle.load(handle)
-
-    features = np.load(output_dir / "features.npy")
-    identity = sparse.identity(features.shape[0], dtype=np.float32, format="csr")
-    adjacency = (1 - lambda_i) * adjacency_raw + lambda_i * identity
-    cell_type_indices = np.load(output_dir / "cell_types.npy", allow_pickle=True)
-    return adjacency_raw, adjacency, features, cell_type_indices
-
-
-def to_pyg_graph(adjacency: sparse.csr_matrix, features: np.ndarray) -> list[Data]:
-    rows, cols = adjacency.nonzero()
-    edge_index = torch.tensor(np.vstack([rows, cols]), dtype=torch.long)
-    edge_attr = torch.tensor(adjacency.data, dtype=torch.float32)
-    graph = Data(
-        x=torch.tensor(features, dtype=torch.float32),
-        edge_index=edge_index,
-        edge_attr=edge_attr,
-    )
-    return [graph]
-
-
-def corruption(data: Data) -> CorruptedGraph:
-    shuffled = data.x[torch.randperm(data.x.size(0))]
-    return CorruptedGraph(shuffled, data.edge_index, data.edge_attr)
-
-
-def train_dgi(
-    data_loader: DataLoader,
-    in_channels: int,
-    hidden_dim: int,
-    epochs: int,
-    learning_rate: float,
-    device: torch.device,
-    model_path: Path,
-) -> DeepGraphInfomax:
-    model = DeepGraphInfomax(
-        hidden_channels=hidden_dim,
-        encoder=GraphEncoder(in_channels=in_channels, hidden_channels=hidden_dim),
-        summary=lambda z, *args, **kwargs: torch.sigmoid(z.mean(dim=0)),
-        corruption=corruption,
-    ).to(device)
-    optimizer = torch.optim.Adam(model.parameters(), lr=learning_rate)
-    torch.backends.cudnn.enabled = False
-
-    start_time = time.time()
-    for epoch in range(epochs):
-        model.train()
-        losses: list[float] = []
-        for batch in data_loader:
-            batch = batch.to(device)
-            optimizer.zero_grad()
-            pos_z, neg_z, summary = model(data=batch)
-            loss = model.loss(pos_z, neg_z, summary)
-            loss.backward()
-            optimizer.step()
-            losses.append(float(loss.item()))
-
-        if (epoch + 1) % 100 == 0:
-            print(f"Epoch {epoch + 1:04d} | loss={np.mean(losses):.6f}")
-
-    torch.save(model.state_dict(), model_path)
-    print(f"Training time: {time.time() - start_time:.1f}s")
-    return model
-
-
-def run_kmeans(embedding: np.ndarray, n_clusters: int, random_state: int) -> tuple[np.ndarray, float]:
-    reducer = PCA(n_components=min(30, embedding.shape[1]))
-    reduced = reducer.fit_transform(embedding)
-    estimator = KMeans(
-        n_clusters=n_clusters,
-        init="k-means++",
-        n_init=100,
-        max_iter=1000,
-        tol=1e-6,
-        random_state=random_state,
-    )
-    labels = estimator.fit_predict(reduced)
-    silhouette = metrics.silhouette_score(reduced, labels, metric="euclidean")
-    return labels, float(silhouette)
-
-
-def search_fixed_resolution(
-    cluster_type: str,
-    adata: ad.AnnData,
-    target_clusters: int,
-    increment: float = 0.02,
-) -> float:
-    for resolution in sorted(np.arange(0.2, 2.5, increment), reverse=True):
-        if cluster_type == "leiden":
-            sc.tl.leiden(adata, random_state=0, resolution=resolution, key_added="tmp")
-        else:
-            sc.tl.louvain(adata, random_state=0, resolution=resolution, key_added="tmp")
-        n_found = adata.obs["tmp"].nunique()
-        if n_found == target_clusters:
-            del adata.obs["tmp"]
-            return float(resolution)
-    del adata.obs["tmp"]
-    raise RuntimeError(f"Could not find a {cluster_type} resolution for {target_clusters} clusters.")
-
-
-def run_graph_clustering(
-    embedding: np.ndarray,
-    cluster_type: str,
-    target_clusters: int,
-) -> tuple[np.ndarray, float]:
-    adata_embedding = ad.AnnData(embedding)
-    sc.tl.pca(adata_embedding, n_comps=min(50, embedding.shape[1]), svd_solver="arpack")
-    sc.pp.neighbors(adata_embedding, n_neighbors=20, n_pcs=min(50, embedding.shape[1]))
-    resolution = search_fixed_resolution(cluster_type, adata_embedding, target_clusters)
-    if cluster_type == "leiden":
-        sc.tl.leiden(adata_embedding, key_added="cluster", resolution=resolution)
-    else:
-        sc.tl.louvain(adata_embedding, key_added="cluster", resolution=resolution)
-    labels = adata_embedding.obs["cluster"].astype(int).to_numpy()
-    return labels, resolution
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Run CCST on a Visium dataset.")
-    parser.add_argument("--visium-dir", type=Path, required=True, help="Path to the Visium sample directory.")
-    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for intermediate files and outputs.")
-    parser.add_argument(
-        "--count-file",
-        default="filtered_feature_bc_matrix.h5",
-        help="Count file inside the Visium directory.",
-    )
-    parser.add_argument(
-        "--metadata-file",
-        default="metadata.tsv",
-        help="Metadata TSV inside the Visium directory.",
-    )
-    parser.add_argument(
-        "--ground-truth-column",
-        default="layer_guess",
-        help="Column in the metadata TSV used as ground truth.",
-    )
-    parser.add_argument(
-        "--profile",
-        choices=["original", "optimized"],
-        default="optimized",
-        help="Preprocessing profile matching the local original or optimized script.",
-    )
-    parser.add_argument("--use-hvg", dest="use_hvg", action="store_true", default=None)
-    parser.add_argument("--no-hvg", dest="use_hvg", action="store_false")
-    parser.add_argument("--n-top-genes", type=int, default=None)
-    parser.add_argument("--pca-n-comps", type=int, default=None)
-    parser.add_argument("--min-cells", type=int, default=5)
-    parser.add_argument("--distance-threshold", type=float, default=200.0)
-    parser.add_argument("--lambda-i", type=float, default=0.3)
-    parser.add_argument("--epochs", type=int, default=5000)
-    parser.add_argument("--learning-rate", type=float, default=1e-6)
-    parser.add_argument("--hidden-dim", type=int, default=256)
-    parser.add_argument(
-        "--cluster-type",
-        choices=["kmeans", "leiden", "louvain"],
-        default="kmeans",
-    )
-    parser.add_argument("--seed", type=int, default=0)
-    return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    config = resolve_preprocessing(args)
-    set_seed(args.seed)
-    args.output_dir.mkdir(parents=True, exist_ok=True)
-
-    tracemalloc.start()
-    start_time = time.time()
-
-    adata = sc.read_visium(
-        str(args.visium_dir),
-        count_file=args.count_file,
-        load_images=True,
-    )
-    adata.var_names_make_unique()
-
-    metadata = pd.read_csv(args.visium_dir / args.metadata_file, sep="\t")
-    if not metadata.index.isin(adata.obs_names).all():
-        first_column = metadata.columns[0]
-        if metadata[first_column].astype(str).is_unique:
-            metadata = metadata.set_index(first_column)
-    missing_obs = [name for name in adata.obs_names if name not in metadata.index]
-    if missing_obs:
-        preview = ", ".join(missing_obs[:5])
-        raise KeyError(
-            f"Metadata file does not contain {len(missing_obs)} Visium barcodes. "
-            f"First missing entries: {preview}"
-        )
-
-    adata.obs["ground_truth"] = metadata.loc[adata.obs_names, args.ground_truth_column]
-    adata = adata[~pd.isnull(adata.obs["ground_truth"])].copy()
-    n_clusters = int(adata.obs["ground_truth"].nunique())
-
-    features, adata = preprocess_adata(adata, min_cells=args.min_cells, config=config)
-    coordinates = np.asarray(adata.obsm["spatial"], dtype=np.float32)
-    adjacency_raw = build_adjacency_matrix(coordinates, threshold=args.distance_threshold)
-
-    np.save(args.output_dir / "features.npy", features)
-    np.save(args.output_dir / "coordinates.npy", coordinates)
-    with open(args.output_dir / "Adjacent", "wb") as handle:
-        pickle.dump(adjacency_raw, handle)
-    save_cell_types(adata.obs["ground_truth"].to_numpy(), args.output_dir)
-
-    _, adjacency, features, _ = load_graph_inputs(args.output_dir, lambda_i=args.lambda_i)
-    print(f"Adjacency shape: {adjacency.shape} | edges={adjacency.nnz}")
-    print(f"Feature shape: {features.shape}")
-
-    graphs = to_pyg_graph(adjacency, features)
-    data_loader = DataLoader(graphs, batch_size=1)
-    device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
-    checkpoint_path = args.output_dir / f"dgi_lambdaI_{args.lambda_i}_epoch{args.epochs}.pth.tar"
-    model = train_dgi(
-        data_loader=data_loader,
-        in_channels=features.shape[1],
-        hidden_dim=args.hidden_dim,
-        epochs=args.epochs,
-        learning_rate=args.learning_rate,
-        device=device,
-        model_path=checkpoint_path,
-    )
-
-    model.eval()
-    with torch.no_grad():
-        batch = graphs[0].to(device)
-        embedding, _, _ = model(batch)
-        embedding_np = embedding.cpu().numpy()
-
-    embedding_path = args.output_dir / f"lambdaI_{args.lambda_i}_epoch{args.epochs}_embed_x.npy"
-    np.save(embedding_path, embedding_np)
-
-    if args.cluster_type == "kmeans":
-        labels, cluster_metric = run_kmeans(embedding_np, n_clusters=n_clusters, random_state=args.seed)
-        cluster_metric_name = "silhouette"
-    else:
-        labels, cluster_metric = run_graph_clustering(
-            embedding_np,
-            cluster_type=args.cluster_type,
-            target_clusters=n_clusters,
-        )
-        cluster_metric_name = "resolution"
-
-    adata.obs["CCST"] = pd.Categorical(labels)
-    ari = float(metrics.adjusted_rand_score(adata.obs["CCST"], adata.obs["ground_truth"]))
-    results_path = args.output_dir / "CCST_results.h5ad"
-    adata.write_h5ad(results_path)
-
-    elapsed_seconds = time.time() - start_time
-    _, peak_bytes = tracemalloc.get_traced_memory()
-    tracemalloc.stop()
-
-    summary = {
-        "visium_dir": str(args.visium_dir),
-        "output_dir": str(args.output_dir),
-        "profile": args.profile,
-        "use_hvg": config.use_hvg,
-        "n_top_genes": config.n_top_genes,
-        "pca_n_comps": config.pca_n_comps,
-        "min_cells": args.min_cells,
-        "distance_threshold": args.distance_threshold,
-        "lambda_i": args.lambda_i,
-        "epochs": args.epochs,
-        "hidden_dim": args.hidden_dim,
-        "cluster_type": args.cluster_type,
-        "cluster_metric_name": cluster_metric_name,
-        "cluster_metric_value": cluster_metric,
-        "ari": ari,
-        "n_clusters": n_clusters,
-        "elapsed_seconds": elapsed_seconds,
-        "peak_memory_mb": peak_bytes / 1024 / 1024,
-        "checkpoint_path": str(checkpoint_path),
-        "embedding_path": str(embedding_path),
-        "results_path": str(results_path),
-    }
-
-    with open(args.output_dir / "run_summary.json", "w", encoding="utf-8") as handle:
-        json.dump(summary, handle, indent=2)
-
-    print(json.dumps(summary, indent=2))
-
-
-if __name__ == "__main__":
-    main()

upload_to_hf.py

@@ -1,55 +1,55 @@
-#!/usr/bin/env python
-"""Create a private Hugging Face repo and upload this folder."""
-
-from __future__ import annotations
-
-import argparse
-from pathlib import Path
-
-from huggingface_hub import HfApi
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Upload this folder to Hugging Face.")
-    parser.add_argument(
-        "--repo-id",
-        default="hutaobo/ccst-spatial-clustering",
-        help="Full repo id, e.g. hutaobo/ccst-spatial-clustering",
-    )
-    parser.add_argument("--private", action="store_true", help="Create the repo as private.")
-    parser.add_argument(
-        "--repo-type",
-        default="model",
-        choices=["model", "dataset", "space"],
-        help="Repository type on the Hugging Face Hub.",
-    )
-    parser.add_argument(
-        "--folder-path",
-        type=Path,
-        default=Path(__file__).resolve().parent,
-        help="Local folder to upload.",
-    )
-    parser.add_argument(
-        "--commit-message",
-        default="Upload CCST publication companion repository",
+#!/usr/bin/env python
+"""Upload this repository to the Hugging Face Hub."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Upload this repository to Hugging Face.")
+    parser.add_argument(
+        "--repo-id",
+        default="hutaobo/ccst-spatial-clustering",
+        help="Full repo id, e.g. hutaobo/ccst-spatial-clustering",
+    )
+    parser.add_argument("--private", action="store_true", help="Create the repo as private.")
+    parser.add_argument(
+        "--repo-type",
+        default="model",
+        choices=["model", "dataset", "space"],
+        help="Repository type on the Hugging Face Hub.",
+    )
+    parser.add_argument(
+        "--folder-path",
+        type=Path,
+        default=Path(__file__).resolve().parent,
+        help="Local folder to upload.",
+    )
+    parser.add_argument(
+        "--commit-message",
+        default="Update manuscript companion placeholder",
         help="Commit message used for the Hub upload.",
     )
     return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    api = HfApi()
-    api.create_repo(repo_id=args.repo_id, private=args.private, exist_ok=True, repo_type=args.repo_type)
-    api.upload_folder(
-        folder_path=str(args.folder_path),
-        repo_id=args.repo_id,
-        repo_type=args.repo_type,
-        commit_message=args.commit_message,
-        ignore_patterns=["__pycache__", "*.pyc", "references/*.pdf"],
-    )
-    print(f"https://huggingface.co/{args.repo_id}")
-
-
-if __name__ == "__main__":
-    main()
+
+
+def main() -> None:
+    args = parse_args()
+    api = HfApi()
+    api.create_repo(repo_id=args.repo_id, private=args.private, exist_ok=True, repo_type=args.repo_type)
+    api.upload_folder(
+        folder_path=str(args.folder_path),
+        repo_id=args.repo_id,
+        repo_type=args.repo_type,
+        commit_message=args.commit_message,
+        ignore_patterns=["__pycache__", "*.pyc", "references/*.pdf"],
+    )
+    print(f"https://huggingface.co/{args.repo_id}")
+
+
+if __name__ == "__main__":
+    main()