Concepts
========

REVISE reconstructs Spatially-inferred Virtual Cells (SVCs) from spatial
transcriptomics data, tissue morphology, and matched single-cell RNA-seq
references. The central idea is to choose the reconstruction route from the
data's resolution and dominant technical limitation, then let the unified
pipeline resolve the correct strategy from ``revise/revise.yaml``.

What Is an SVC?
---------------

An SVC is a reconstructed cell-level unit represented as an ``AnnData`` object.
It carries inferred expression and/or spatial information that can be consumed
by the case notebooks and downstream analysis services.

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

   * - SVC kind
     - What it improves
     - When to use it
   * - ``sp-SVC``
     - Spatial localization and local tissue architecture.
     - Use this when high-definition ST already has rich spatial signal but
       suffers from segmentation or bin-to-cell assignment uncertainty.
   * - ``sc-SVC``
     - Molecular completeness and cell-state resolution.
     - Use this when an imaging or sequencing ST platform benefits from
       matched scRNA-seq references to restore missing genes or refine selected
       cell types.

Route Selection
---------------

REVISE routes by ``platform`` and ``confounding``. In normal use, choose a
profile first; override the platform/confounding pair only when validating a
new route.

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

   * - Profile
     - SVC
     - Platform and confounding
     - Typical question
   * - ``application_sp``
     - ``sp-SVC``
     - ``hST`` + ``bin2cell``
     - Can we refine Visium HD-style bins into biologically coherent cell-level
       spatial units?
   * - ``application_sc``
     - ``sc-SVC``
     - ``iST`` + ``segmentation``
     - Can we refine Xenium-style cell measurements with matched scRNA-seq and
       recover whole-transcriptome signals for a selected cell type?
   * - ``application_sc_sst``
     - ``sc-SVC``
     - ``sST`` + ``spot_size``
     - Can spot-level data be reconstructed at higher effective cellular
       resolution?
   * - ``benchmark_*``
     - ``sp-SVC`` or ``sc-SVC``
     - ``sim2real`` + one of six confounding factors
     - Does reconstruction recover ground-truth SVCs under controlled
       segmentation, bin2cell, batch, spot-size, gene-panel, or dropout
       perturbations?

Confounding Factors
-------------------

.. figure:: ../../png/ST_limitations.png
   :alt: Current ST limitations addressed by REVISE
   :align: center

   REVISE separates spatially heterogeneous limitations from spatially
   homogeneous limitations, then maps each family to a concrete benchmark or
   application route.

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

   * - Family
     - Factors
     - REVISE route
   * - Spatially heterogeneous
     - Segmentation artifacts and bin-to-cell assignment errors.
     - ``sp-SVC`` routes for hST and Sim2Real-ST segmentation/bin2cell
       benchmarks.
   * - Spatially homogeneous
     - Spot size, batch effect, gene panel limitation, and gene dropout.
     - ``sc-SVC`` super-resolution and imputation routes.

Inputs and Outputs
------------------

Most runs need an ST file, a matched single-cell reference, and a writable output
root. Benchmark runs also need the Sim2Real-ST ground-truth SVC file.

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

   * - Input or output
     - Config key
     - Notes
   * - Spatial transcriptomics data
     - ``io.st_file``
     - ``AnnData`` file containing spatial measurements for the selected
       sample.
   * - Single-cell reference
     - ``io.sc_ref_file``
     - Matched scRNA-seq reference used by anchoring and local refinement.
   * - Ground truth SVC
     - ``io.gt_svc_file``
     - Required for benchmark evaluation.
   * - Published application outputs
     - ``sp_SVC.h5ad``, ``sc_SVC_expr.h5ad``, ``sc_SVC_spatial.h5ad``
     - Notebook-compatible copies produced by application wrappers.
   * - Canonical run metadata
     - ``merged_config.json``, ``provenance.json``
     - Written for every unified run to make configuration and data
       fingerprints inspectable.

Where to Go Next
----------------

- Run the shortest working path in :doc:`quickstart`.
- Learn the wrapper scripts and notebook outputs in :doc:`case`.
- Inspect routing and override rules in :doc:`configuration`.
- Extend strategies or plugins using :doc:`architecture` and :doc:`api/index`.