ColonCancer

Apply StPedf to colorectal cancer spatial transcriptomics to infer malignant cell-state trajectories across physical tumor space.

This repository contains a reproducible starter pipeline for the GSE225857 primary CRC Visium samples. It downloads the public GEO data, transfers labels from the matched non-immune scRNA-seq reference, extracts malignant spots, runs StPedf, and writes trajectory outputs for downstream validation and figure generation.

Project Goal

The working hypothesis is that StPedf can recover a biologically coherent malignant trajectory in primary colorectal cancer, such as a core-to-edge or stem/proliferative-to-invasive transition, and that the same pattern should reproduce across multiple primary CRC slides.

This is a method-application project: the novelty is applying the new StPedf spatial trajectory method to CRC and checking reproducibility across independent samples.

Data

The main dataset is GSE225857.

• Primary CRC Visium samples:
  • GSM7058756_C1
  • GSM7058757_C2
  • GSM7058758_C3
  • GSM7058759_C4
• Liver metastatic CRC spatial samples:
  • GSM7058760_L1
  • GSM7058761_L2
• Non-immune scRNA-seq reference:
  • GSM7058755_non_immune_counts.txt.gz
  • GSM7058755_non_immune_meta.txt.gz

Downloaded data, generated AnnData files, model outputs, figures, the local virtual environment, and the cloned StPedf source are intentionally ignored by Git.

Repository Layout

config/project_config.json        Shared sample names and label defaults
scripts/00_inspect_geo_archive.py Download and inspect GSE225857
scripts/01_setup_data.py          Load, QC, normalize, and cluster a Visium sample
scripts/02_label_transfer.py      Transfer scRNA labels and extract malignant spots
scripts/03_run_stpedf.py          Run StPedf trajectory inference
scripts/04_quick_figures.py       Generate quick diagnostic spatial plots
requirements-macos-py311.txt      Practical Python 3.11 environment for macOS
PROJECT_PLAN.md                   Detailed project notes and scientific plan

Setup

Create a local virtual environment and install dependencies:

python3 -m venv .venv
.venv/bin/pip install -r requirements-macos-py311.txt

Clone StPedf into the expected local path:

mkdir -p external
git clone https://github.com/YuanZ0316/StPedf.git external/StPedf

The current StPedf clone may import a missing optional module from TI/__init__.py. If import TI fails with No module named 'TI.multiple_time', guard that optional import or use only TI.single_time functions directly.

Run Pipeline

Download and inspect the GEO archive:

.venv/bin/python scripts/00_inspect_geo_archive.py

If local TLS certificates fail during download, use:

.venv/bin/python scripts/00_inspect_geo_archive.py --insecure

Process one primary CRC sample:

MPLCONFIGDIR=/tmp/mplcfg .venv/bin/python scripts/01_setup_data.py --sample GSM7058756_C1

Transfer labels from the scRNA reference and extract malignant spots:

MPLCONFIGDIR=/tmp/mplcfg .venv/bin/python scripts/02_label_transfer.py --sample GSM7058756_C1

Run StPedf:

MPLCONFIGDIR=/tmp/mplcfg .venv/bin/python scripts/03_run_stpedf.py --sample GSM7058756_C1 --epochs 50 --no-dec

Generate a quick diagnostic figure:

MPLCONFIGDIR=/tmp/mplcfg .venv/bin/python scripts/04_quick_figures.py --sample GSM7058756_C1

Repeat the same commands for GSM7058757_C2, GSM7058758_C3, and GSM7058759_C4 to test within-cohort reproducibility.

Outputs

For each sample, outputs are written under results/<sample>/.

Important files include:

• <sample>_primary_processed.h5ad
• <sample>_malignant_for_stpedf.h5ad
• <sample>_label_transfer_report.txt
• <sample>_stpedf_trajectory.h5ad
• <sample>_stpedf_quicklook.png

The trajectory AnnData stores StPedf embeddings, adaptive transition matrices, pseudotime, and spatial velocity fields.

Current First-Pass Result

The first C1 run completed locally with:

• 2,054 processed spatial spots
• 1,724 tumor-labelled spots
• 337 root spots
• pseudotime spanning 0.0 to 1.0
• velocity field computed successfully on CPU

These generated artifacts are not committed because they are large and reproducible from the scripts.

Next Steps

Run the same pipeline on C2-C4, compare pseudotime structure and driver genes across samples, and then perform pathway/trajectory interpretation for the reproducibility analysis.