Configuration

REVISE is configured through revise/revise.yaml. The YAML file is the source of truth for runtime routes, paper-facing defaults, profile presets, and guardrails for low-level parameters. Root scripts and the Python API both route through revise.framework.REVISEPipeline.

When installed from PyPI, revise.yaml is packaged next to revise/framework.py. Source-tree examples may still pass config_path="revise/revise.yaml"; installed environments can simply call REVISEPipeline().

Mental Model

Most users should choose a profile and override only IO paths. Route developers should edit the profile/router surface and then validate the route with dry_run=True before running full reconstruction.

profile -> platform + confounding -> router -> strategy/plugins -> SVC output

For the lower-level lifecycle behind this resolution process, see Architecture.

Resolution Order

Each run resolves configuration in a strict order:

defaults in revise/revise.yaml.
The selected profiles.<name> block.
Runtime and IO overrides from wrapper scripts or pipeline.run.
Dotted set_overrides such as sc.select_ct=T.

The final merged config is written to merged_config.json in the run directory, and provenance is written to provenance.json.

Profiles

Profile	Route	Typical use
`application_sp`	`hST` + `bin2cell`	sp-SVC reconstruction for Visium HD-style data.
`application_sc`	`iST` + `segmentation`	sc-SVC reconstruction for Xenium-style data.
`application_sc_hyper`	`iST` + `segmentation`	Hyperresolution sc-SVC route using `ScSvcHyperApplicationStrategy`.
`application_sc_sst`	`sST` + `spot_size`	sc-SVC super-resolution route for spot-based platforms.
`benchmark_seg`	`sim2real` + `segmentation`	Sim2Real-ST segmentation artifact benchmark.
`benchmark_bin2cell`	`sim2real` + `bin2cell`	Sim2Real-ST bin-to-cell assignment benchmark.
`benchmark_sr_batch`	`sim2real` + `batch_effect`	sc-SVC super-resolution benchmark across reference batches.
`benchmark_sr_spot_size`	`sim2real` + `spot_size`	sc-SVC super-resolution benchmark across spot sizes.
`benchmark_impute_panel`	`sim2real` + `gene_panel`	sc-SVC imputation benchmark for limited gene panels.
`benchmark_impute_dropout`	`sim2real` + `gene_dropout`	sc-SVC imputation benchmark for dropout.

Router

The router maps platform and confounding to the concrete mode, task, SVC kind, strategy, platform adapter, confounding-factor strategy, and OT solver plugin.

Platform	Confounding	Task	SVC kind
`hST`	`bin2cell`	`sp_svc`	`sp`
`iST`	`segmentation`	`sc_svc`	`sc`
`sST`	`spot_size`	`sc_svc`	`sc`
`sim2real`	`segmentation` / `bin2cell`	`sp_svc`	`sp`
`sim2real`	`batch_effect` / `spot_size`	`sc_svc_sr`	`sc`
`sim2real`	`gene_panel` / `gene_dropout`	`sc_svc_impute`	`sc`

The active strategy registry currently includes application, hyperresolution, super-resolution, segmentation/bin2cell benchmark, and imputation benchmark strategies. The plugin registry includes sim2real, hST, iST, and sST platform adapters, confounding-factor strategies, and the pot OT solver route marker.

Override Examples

Run the default hST application profile:

from revise.framework import REVISEPipeline

pipeline = REVISEPipeline()
svc = pipeline.run(
    profile="application_sp",
    io_overrides={
        "data_root": "raw_data/Real_application",
        "output_root": "output/sp_SVC_case",
        "sample_name": "P1CRC",
        "st_file": "HD.h5ad",
        "sc_ref_file": "adata_sc_all_reanno.h5ad",
    },
)

Run sc-SVC for a selected cell type:

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"],
)

Run a dry route validation without importing heavy reconstruction strategies:

svc = pipeline.run(
    runtime_overrides={"platform": "sim2real", "confounding": "gene_dropout"},
    io_overrides={"data_root": "raw_data/Sim2Real-ST", "sample_name": "P2CRC/cut_part1"},
    dry_run=True,
)

Locked Parameters

Low-level OT parameters listed in locked_params.keys are intentionally not exposed through set_overrides by default. This prevents accidental drift in paper and rebuttal-style runs. Change them in revise/revise.yaml only when you intend to alter the reproducible configuration surface.

Output Layout

Unified runs write canonical artifacts under the resolved run_dir:

<output_root>/<sample>/<route>/<case-or-run>/
├── merged_config.json
├── provenance.json
└── artifacts/
    ├── sp_svc.h5ad
    ├── sc_svc_expr.h5ad
    └── sc_svc_spatial.h5ad

Benchmark routes write metrics_normalized.csv when evaluation is enabled. Application wrappers additionally publish notebook-compatible copies such as sp_SVC.h5ad, sc_SVC_expr.h5ad, and sc_SVC_spatial.h5ad under output/.