REVISE

With uv:

uv venv --python 3.11
source .venv/bin/activate

Or with conda:

conda create -n revise python=3.11 -y
conda activate revise

sc-SVC-sr does not by itself infer true sub-spot cell positions. When the ST H5AD contains segmentation-derived cell centers, REVISE uses them. Virtual cells without a supplied center remain at their source spot center.

Set inputs.st.path and inputs.reference.path explicitly. paths.root_dir: . means the launch current working directory, not the application YAML directory; otherwise it must be an existing absolute directory. Input and output values are relative children of that root and cannot escape it with ... Package code in revise.config.authority owns engine defaults and routing.

• Both inputs must have non-empty X, unique obs_names, unique var_names, and at least one shared gene.
• The ST input must contain finite two-dimensional coordinates in obsm["spatial"].
• Every route requires global_anchoring.broad_column in reference obs. Only standard sc-SVC accepts and requires local_refinement.subtype_column. sc-SVC-sr composition and expression allocation use the broad assignment.
• A reference filter_column and filter_value must be provided together or both omitted. When present, filtering runs before the spatial and reference count/gene preprocessing steps.
• For sST inputs with segmentation-derived centers, the optional uns["revise_cell_locations"] table uses unique cell_id values as its index and contains spot_name, x, and y. Its cell IDs must agree with uns["all_cells_in_spot"]; x/y must use the same coordinate system and scale as obsm["spatial"]. Missing centers fall back to the spot center. The optional score matrix can be provided with the exact inputs.pm_on_cell.path. Its axes must exactly equal the active virtual-cell IDs and normalized cell types; values must be finite and within [0, 1]. REVISE reorders exact axes but does not clip or normalize PM. Without that field, coordinates are retained while cell types are assigned to the existing rows by a seeded random permutation of each spot's inferred quota.

ST format accepts h5ad, spatialdata, or auto; the reference remains H5AD. SpatialData table and spatial-element selections live under inputs.st.spatialdata.table and inputs.st.spatialdata.element. REVISE does not expose a coordinate-conversion promise through this entry point.

execution.seed and algorithm.ot_method are optional. The latter controls both GA and LR; omitting it keeps the selected engine profile authoritative. Standard sc-SVC defaults to TACCO and requires the tacco extra; REVISE never changes solvers automatically. Unknown or route-inapplicable application fields are errors; the engine YAML and generic key/value overrides are not public application controls.

To install the current repository source:

git clone https://github.com/wuys13/REVISE.git
cd REVISE
pip install .

The base package contains reconstruction, the POT implementation, clustering, and the core scientific stack. Install additional capabilities only when needed:

For optional groups from a source checkout, replace revise-svc with .. For development:

pip install -e ".[dev]"

Installation does not download research data or external analysis databases.

From a source checkout, run one confounding family:

python reproduce/benchmark_main.py \
  --config configs/benchmark/segmentation.yaml \
  --data-root raw_data/Sim2Real-ST \
  --sample-name P2CRC/cut_part1 \
  --dataset-task segmentation \
  --evaluate true \
  --output-root output/benchmark

Supported values are segmentation, bin2cell, batch_effect, spot_size, gene_panel, and gene_dropout. Run the bounded multi-family launcher with:

bash reproduce/benchmark_main.sh

The analysis notebooks are under reproduce/benchmark/.

Biological insights enabled by SVC reconstruction

Application reconstruction and downstream-analysis notebooks are under reproduce/case/. Some require the optional pathway, cci, or trajectory installation groups and their corresponding external reference resources.

The notebooks preserve the paper workflows, but their presence does not mean that the current source checkout has rerun every real-data analysis. Real-data end-to-end validation remains a separate release step. Installation does not download the paper datasets, reproduced results, or external analysis databases.

from reconstruct import run_application

spatial_svc = run_application("configs/application/VisiumHD.yaml")
spatial, expression = run_application("configs/application/Xenium_T.yaml")

# sp-SVC and sc-SVC-sr return one AnnData; sc-SVC returns this fixed pair.

Application callers provide one YAML. REVISEPipeline.run() remains the engine-level interface used by Benchmark and advanced integrations; it is not the Application configuration API. Benchmark execution continues to use the separate cf selector for its confounding family.

• revise/: installable reconstruction and analysis package.
• reproduce/: benchmark launchers and benchmark/application notebooks.
• docs/: detailed user and method documentation.
• logo/, png/: public project and scientific figures.
• tests/: behavioral, scientific-contract, packaging, and CLI tests.
• .github/: continuous integration.
• constraints/: tested Python 3.10/3.11 dependency constraints.