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.

.. code-block:: text

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

For the lower-level lifecycle behind this resolution process, see
:doc:`architecture`.


Resolution Order
----------------

Each run resolves configuration in a strict order:

1. ``defaults`` in ``revise/revise.yaml``.
2. The selected ``profiles.<name>`` block.
3. Runtime and IO overrides from wrapper scripts or ``pipeline.run``.
4. 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
--------

.. list-table::
   :header-rows: 1
   :widths: 1 2 2

   * - 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.

.. list-table::
   :header-rows: 1
   :widths: 1 2 2 2

   * - 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:

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

   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``:

.. code-block:: text

   <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/``.