Application Mode
================

Application mode reconstructs SVCs for real spatial transcriptomics datasets and
then uses notebooks for downstream biological analysis.

Use this mode when your goal is a usable reconstructed tissue object rather
than a ground-truth benchmark metric. The wrappers publish notebook-compatible
files while the unified pipeline also keeps canonical artifacts and provenance
under the resolved run directory.

Choose an Application Route
---------------------------

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

   * - Route
     - Best fit
     - Wrapper
     - Published outputs
   * - ``application_sp``
     - hST data where spatial refinement and bin-to-cell correction are the
       main goals.
     - ``application_sp_SVC_recon.py``
     - ``sp_SVC.h5ad``
   * - ``application_sc``
     - iST data where selected-cell-type molecular completion is the main
       goal.
     - ``application_sc_SVC_recon.py``
     - ``sc_SVC_expr.h5ad`` and ``sc_SVC_spatial.h5ad``
   * - ``application_sc_sst``
     - Spot-based sST data routed through sc-SVC super-resolution.
     - Python API
     - Canonical artifacts under the run directory.


sp-SVC Application
------------------

Use sp-SVC for hST data such as Visium HD, where spatial refinement and
bin-to-cell correction are the primary goal.

.. code-block:: bash

   python application_sp_SVC_recon.py \
     --raw_data_path raw_data/Real_application \
     --sample_name P1CRC \
     --st_file HD.h5ad \
     --sc_ref_file adata_sc_all_reanno.h5ad

The wrapper defaults to ``output/sp_SVC_case`` and publishes a notebook-friendly
copy at:

.. code-block:: text

   output/sp_SVC_case/<sample_name>/sp_SVC.h5ad

The sp-SVC wrapper enables legacy-compatible filenames so existing case
notebooks can read the published ``sp_SVC.h5ad`` file directly. Canonical
unified artifacts and provenance are also retained in the resolved run
directory.


sc-SVC Application
------------------

Use sc-SVC for iST data such as Xenium, where matched scRNA-seq references are
used to refine selected cell types and restore molecular completeness.

.. code-block:: bash

   python application_sc_SVC_recon.py \
     --sample_name P2CRC \
     --data_type Xenium \
     --raw_data_path raw_data/Real_application \
     --sc_ref_file adata_sc_all_reanno.h5ad \
     --select_ct T

The wrapper defaults to ``output/sc_SVC_case`` and publishes notebook-friendly
copies at:

.. code-block:: text

   output/sc_SVC_case/<sample_name>_<data_type>/<select_ct>/sc_SVC_expr.h5ad
   output/sc_SVC_case/<sample_name>_<data_type>/<select_ct>/sc_SVC_spatial.h5ad

Use ``--legacy_mode`` when you also need legacy filenames inside the run
directory itself. The published notebook copies are written regardless.

The reconstruction notebooks under ``reproduce/case`` build these files for the
paper cell-type cases. The analysis notebooks read the published output layout
and produce downstream figures for cell states, pathway activity, spatial
patterns, and communication analyses.


Advanced Application Profiles
-----------------------------

The root wrappers cover the paper-facing hST and iST paths. The unified Python
API also exposes additional application profiles:

.. code-block:: python

   from revise.framework import REVISEPipeline

   pipeline = REVISEPipeline()
   svc = pipeline.run(
       profile="application_sc_hyper",
       io_overrides={
           "data_root": "raw_data/Real_application",
           "output_root": "output/sc_SVC_hyper_case",
           "sample_name": "P2CRC",
           "st_file": "Xenium.h5ad",
           "sc_ref_file": "adata_sc_all_reanno.h5ad",
       },
       set_overrides=["sc.select_ct=T"],
   )

``application_sc_hyper`` enables hyperresolution sc-SVC routing through
``ScSvcHyperApplicationStrategy``. ``application_sc_sst`` routes spot-based
sST data through the sc-SVC super-resolution application strategy.


Rendered paper case notebooks and additional maintained application notebooks
are collected in :doc:`gallery`, which also documents the Zenodo data download
step for notebook reproduction. This page stays focused on application routes,
wrapper commands, and the output files those notebooks consume.