Architecture

REVISE is organized around a single public orchestration API and a fixed reconstruction lifecycle. Profiles in revise/revise.yaml select the route; registries map that route to concrete platform adapters, confounding-factor strategies, OT solver markers, and local reconstruction strategies.

System Map

REVISEPipeline.run()
|-- load revise/revise.yaml
|-- merge defaults, profile, runtime/io overrides, and set_overrides
|-- resolve platform adapter, confounding strategy, and OT solver
|-- create PipelineContext and run directory
`-- delegate to UnifiedReconstructionPipeline
    |-- validate_inputs
    |-- global_anchoring
    |-- prepare_local_units
    |-- build_graph
    |-- build_ot_problem
    |-- solve_ot
    |-- update_expression
    |-- finalize_svc
    `-- evaluate_if_needed

Public Entry Point

revise.framework.REVISEPipeline is the stable user-facing API. It performs configuration resolution, route inference, metadata writing, deterministic seed setup, lazy strategy initialization, and dry-run validation.

When installed from PyPI, REVISEPipeline() loads the packaged revise.yaml automatically. Source-tree scripts may still pass config_path="revise/revise.yaml" for compatibility.

Configuration Surface

revise/revise.yaml is the source of truth for runtime routes and paper-facing defaults. New routing behavior should normally be added there rather than scattered through scripts.

YAML section	Responsibility
`defaults`	Baseline runtime, IO, preprocessing, graph, OT, plotting, reconstruction, benchmark, sc-SVC, and imputation settings.
`router`	Maps `platform` plus `confounding` to mode, task, SVC kind, strategy, platform adapter, confounding strategy, and OT solver.
`profiles`	Named presets used by wrapper scripts, notebooks, and direct API calls.
`locked_params`	Guardrail for low-level OT settings that should not drift accidentally during paper and rebuttal-style runs.

Unified Lifecycle

revise.recon.pipeline.UnifiedReconstructionPipeline owns the fixed stage order. Strategy implementations customize stage internals but do not change the topology of the lifecycle. This makes application and benchmark routes easier to compare because each run records the same stage trace in provenance.

Stage	Purpose
`validate_inputs`	Check required files, route compatibility, and strategy context.
`global_anchoring`	Align spatial data and the single-cell reference at the global level.
`prepare_local_units`	Build local reconstruction units for the selected SVC route.
`build_graph`	Construct spatial/expression neighborhood graphs.
`build_ot_problem` and `solve_ot`	Form and solve the optimal transport problem.
`update_expression`	Transfer or refine molecular signals.
`finalize_svc`	Produce the `SVC` result carrier and write canonical artifacts.
`evaluate_if_needed`	Compute normalized benchmark metrics when evaluation is enabled.

Registries and Plugins

The backend separates route selection from implementation details:

StrategyRegistry selects local refinement strategies such as SpSvcApplicationStrategy, ScSvcApplicationStrategy, ScSvcSrBenchmarkStrategy, and ScSvcImputeBenchmarkStrategy.
PluginRegistry selects platform adapters, confounding-factor strategies, and OT solver route markers.
Analysis services consume the unified SVC result carrier and keep notebook-facing downstream workflows compatible.

Run Artifacts

Every unified run writes metadata that should be inspected before comparing results:

<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 additionally write metrics_normalized.csv when evaluation is enabled. Application wrappers publish notebook-compatible copies under output/ while keeping canonical artifacts in the resolved run directory.

Extension Checklist

When adding a route or strategy, keep the change local to the existing extension points:

Add or update a profile in revise/revise.yaml.
Add a router entry if the platform/confounding pair is new.
Register any new strategy or plugin in revise/backend/registry.py.
Add a dry-run or focused validator command that proves the route resolves.
Document the new route in Configuration and the relevant application or benchmark page.