REVISE Documentation
====================

.. raw:: html

   <section class="revise-hero">
     <p class="revise-eyebrow">REconstruction via Vision-integrated Spatial Estimation</p>
     <h1>Spatially inferred virtual cells from ST, histology, and scRNA-seq.</h1>
     <p class="revise-lead">
       REVISE reconstructs Spatially-inferred Virtual Cells (SVCs) by routing
       each dataset through a config-driven topology-aware optimal transport
       pipeline. The documentation is organized around the decisions users make
       first: which SVC mode to run, which platform/confounding route applies,
       and how outputs flow into benchmark or application notebooks.
     </p>
     <div class="revise-actions">
       <a class="revise-button revise-button-primary" href="source/quickstart.html">Start with a route</a>
       <a class="revise-button" href="source/concepts.html">Understand SVCs</a>
       <a class="revise-button" href="source/architecture.html">See the architecture</a>
     </div>
   </section>

Resources
---------

- Package: `revise-svc on PyPI <https://pypi.org/project/revise-svc/>`_
- Code: `GitHub repository <https://github.com/wuys13/REVISE>`_
- Data and reproduced results: `Zenodo <https://zenodo.org/records/17705737>`_
- Documented package version: ``0.0.32``

.. figure:: ../png/REVISE_overview.png
   :alt: Overview of the REVISE framework
   :align: center

   REVISE combines spatial transcriptomics, histology, and single-cell
   reference information to reconstruct SVCs for benchmark and real-data
   application workflows.

Choose Your Path
----------------

.. raw:: html

   <div class="revise-card-grid">
     <a class="revise-card" href="source/concepts.html">
       <span class="revise-card-kicker">Concepts</span>
       <h2>Know what REVISE reconstructs</h2>
       <p>Compare sp-SVC and sc-SVC, map platforms to confounding factors, and
       learn the expected inputs and outputs before running a case.</p>
     </a>
     <a class="revise-card" href="source/quickstart.html">
       <span class="revise-card-kicker">Quick start</span>
       <h2>Run the shortest useful example</h2>
       <p>Install the package, pick a route, run a wrapper script, or call the
       unified Python API directly.</p>
     </a>
     <a class="revise-card" href="source/case.html">
       <span class="revise-card-kicker">Applications</span>
       <h2>Reconstruct real tissue sections</h2>
       <p>Use sp-SVC for Visium HD-style spatial refinement or sc-SVC for
       Xenium/Visium molecular completion and downstream biology.</p>
     </a>
     <a class="revise-card" href="source/benchmark.html">
       <span class="revise-card-kicker">Benchmarks</span>
       <h2>Reproduce Sim2Real-ST evaluations</h2>
       <p>Run the six confounding-factor families and inspect normalized PCC,
       SSIM, MSE, and NRMSE outputs.</p>
     </a>
     <a class="revise-card" href="source/gallery.html">
       <span class="revise-card-kicker">Gallery</span>
       <h2>Browse rendered case notebooks</h2>
       <p>Open paper-facing application notebooks for sp-SVC and sc-SVC cases,
       including Xenium cell-type analyses and Visium HD reconstruction.</p>
     </a>
     <a class="revise-card" href="source/configuration.html">
       <span class="revise-card-kicker">Configuration</span>
       <h2>Control profiles and routes</h2>
       <p>Understand how defaults, profiles, runtime overrides, IO overrides,
       and dotted set-overrides merge into a single run configuration.</p>
     </a>
     <a class="revise-card" href="source/api/index.html">
       <span class="revise-card-kicker">API</span>
       <h2>Extend the unified engine</h2>
       <p>Use REVISEPipeline, SVC result carriers, strategy registries, plugin
       registries, and analysis services.</p>
     </a>
   </div>

Two SVC Modes
-------------

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

   * - Mode
     - Best for
     - Typical platforms
     - Primary outputs
   * - ``sp-SVC``
     - Spatial refinement when high-definition ST is affected by segmentation
       or bin-to-cell assignment artifacts.
     - hST such as Visium HD; Sim2Real-ST segmentation and bin2cell benchmarks.
     - ``sp_SVC.h5ad`` and canonical ``artifacts/sp_svc.h5ad``.
   * - ``sc-SVC``
     - Molecular completion and cell-state refinement when ST measures limited
       genes or spot-level mixtures.
     - iST/sST such as Xenium and Visium; super-resolution and imputation
       benchmarks.
     - ``sc_SVC_expr.h5ad``, ``sc_SVC_spatial.h5ad``, and canonical artifacts.

Core Execution Model
--------------------

All modern execution flows through one public engine:

1. ``revise.framework.REVISEPipeline.run()``
2. ``revise/revise.yaml`` profiles and runtime/io overrides
3. ``revise.recon.pipeline.UnifiedReconstructionPipeline``
4. backend strategy and plugin registries in ``revise/backend/``

The fixed lifecycle is documented in :doc:`source/architecture`; practical
profile and override examples are documented in :doc:`source/configuration`.

.. toctree::
   :caption: Start Here
   :maxdepth: 2
   :hidden:

   source/concepts
   source/quickstart
   source/installation

.. toctree::
   :caption: Run REVISE
   :maxdepth: 2
   :hidden:

   Application mode <source/case>
   Benchmark mode <source/benchmark>
   source/configuration

.. toctree::
   :caption: Gallery
   :maxdepth: 2
   :hidden:

   Application cases <source/gallery>

.. toctree::
   :caption: Reference
   :maxdepth: 2
   :hidden:

   source/architecture
   source/api/index