Quick Start

This page is the shortest path from installation to a real REVISE run. Use it when you already know which route you want; use Concepts first if you need to choose between sp-SVC and sc-SVC.

Install

pip install revise-svc

Optional annotation support installs tacco:

pip install "revise-svc[annotation]"

For source-tree development:

git clone https://github.com/wuys13/REVISE.git
cd REVISE
pip install -e ".[dev]"

Download Data

Download Sim2Real-ST benchmark data, generated results, and real application data from Zenodo. Place inputs under raw_data/:

raw_data/
|-- Sim2Real-ST/
`-- Real_application/

Run sp-SVC for hST

Use this route for high-definition spatial refinement, such as Visium HD-style data with bin-to-cell uncertainty.

python application_sp_SVC_recon.py \
  --raw_data_path raw_data/Real_application \
  --sample_name P1CRC \
  --st_file HD.h5ad \
  --sc_ref_file adata_sc_all_reanno.h5ad

Expected published output:

output/sp_SVC_case/P1CRC/sp_SVC.h5ad

Run sc-SVC for iST

Use this route for Xenium-style data when the goal is selected-cell-type molecular completion and downstream biological analysis.

python application_sc_SVC_recon.py \
  --sample_name P2CRC \
  --data_type Xenium \
  --raw_data_path raw_data/Real_application \
  --sc_ref_file adata_sc_all_reanno.h5ad \
  --select_ct T

Expected published outputs:

output/sc_SVC_case/P2CRC_Xenium/T/sc_SVC_expr.h5ad
output/sc_SVC_case/P2CRC_Xenium/T/sc_SVC_spatial.h5ad

Run a Benchmark Case

Use this route to reproduce one Sim2Real-ST confounding-factor family and write per-gene normalized metrics.

python benchmark_main.py \
  --cf segmentation \
  --raw_data_path raw_data/Sim2Real-ST \
  --sample_name P2CRC/cut_part1 \
  --task segmentation \
  --save_path output/benchmark

Expected metric file:

output/benchmark/segmentation/P2CRC/cut_part1/sim2real-segmentation/<case>/metrics_normalized.csv

To launch the full Sim2Real-ST benchmark set across all supported confounding factors and all three published P2CRC parts:

SAMPLE_PARTS="part1 part2 part3" \
SAVE_PATH=results_unified/benchmark_runs/sim2real_all \
bash benchmark_main.sh

The task-specific scripts in reproduce/benchmark/ accept the same RAW_DATA_PATH, SAMPLE_PATIENT, SAMPLE_PARTS, CONFIG_PATH, and SAVE_PATH environment variables, so they can be used to reproduce one benchmark family at a time while keeping the output layout identical.

Use the Python API

Root wrapper scripts and notebooks ultimately route through REVISEPipeline.run. Calling the API directly is useful for custom IO roots, dry runs, and programmatic workflows.

from revise.framework import REVISEPipeline

pipeline = REVISEPipeline()
svc = pipeline.run(
    profile="application_sc",
    io_overrides={
        "data_root": "raw_data/Real_application",
        "output_root": "output/sc_SVC_case",
        "sample_name": "P2CRC",
        "st_file": "Xenium.h5ad",
        "sc_ref_file": "adata_sc_all_reanno.h5ad",
        "patient_key": "Patient",
    },
    set_overrides=["sc.select_ct=T"],
)

Validate a Development Checkout

Run the smallest structural check first, then choose the benchmark or regression command that matches the files you changed.

python revise/validate_refactor.py
python revise/validate_all_benchmarks.py --sample-size 800
python revise/validate_full_regression.py --output-root results_unified/full_regression_latest
cd docs && make html

Next Steps