Quick Start
===========

This page is the shortest path from installation to a real REVISE run. Use it
when you already know which route you want; use :doc:`concepts` first if you
need to choose between sp-SVC and sc-SVC.

Install
-------

.. code-block:: bash

   pip install revise-svc

Optional annotation support installs ``tacco``:

.. code-block:: bash

   pip install "revise-svc[annotation]"

For source-tree development:

.. code-block:: bash

   git clone https://github.com/wuys13/REVISE.git
   cd REVISE
   pip install -e ".[dev]"

Download Data
-------------

Download Sim2Real-ST benchmark data, generated results, and real application
data from `Zenodo <https://zenodo.org/records/17705737>`_. Place inputs under
``raw_data/``:

.. code-block:: text

   raw_data/
   |-- Sim2Real-ST/
   `-- Real_application/

Run sp-SVC for hST
------------------

Use this route for high-definition spatial refinement, such as Visium HD-style
data with bin-to-cell uncertainty.

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

Expected published output:

.. code-block:: text

   output/sp_SVC_case/P1CRC/sp_SVC.h5ad

Run sc-SVC for iST
------------------

Use this route for Xenium-style data when the goal is selected-cell-type
molecular completion and downstream biological analysis.

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

Expected published outputs:

.. code-block:: text

   output/sc_SVC_case/P2CRC_Xenium/T/sc_SVC_expr.h5ad
   output/sc_SVC_case/P2CRC_Xenium/T/sc_SVC_spatial.h5ad

Run a Benchmark Case
--------------------

Use this route to reproduce one Sim2Real-ST confounding-factor family and write
per-gene normalized metrics.

.. code-block:: bash

   python benchmark_main.py \
     --cf segmentation \
     --raw_data_path raw_data/Sim2Real-ST \
     --sample_name P2CRC/cut_part1 \
     --task segmentation \
     --save_path output/benchmark

Expected metric file:

.. code-block:: text

   output/benchmark/segmentation/P2CRC/cut_part1/sim2real-segmentation/<case>/metrics_normalized.csv

To launch the full Sim2Real-ST benchmark set across all supported confounding
factors and all three published P2CRC parts:

.. code-block:: bash

   SAMPLE_PARTS="part1 part2 part3" \
   SAVE_PATH=results_unified/benchmark_runs/sim2real_all \
   bash benchmark_main.sh

The task-specific scripts in ``reproduce/benchmark/`` accept the same
``RAW_DATA_PATH``, ``SAMPLE_PATIENT``, ``SAMPLE_PARTS``, ``CONFIG_PATH``, and
``SAVE_PATH`` environment variables, so they can be used to reproduce one
benchmark family at a time while keeping the output layout identical.

Use the Python API
------------------

Root wrapper scripts and notebooks ultimately route through
``REVISEPipeline.run``. Calling the API directly is useful for custom IO roots,
dry runs, and programmatic workflows.

.. code-block:: python

   from revise.framework import REVISEPipeline

   pipeline = REVISEPipeline()
   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"],
   )

Validate a Development Checkout
-------------------------------

Run the smallest structural check first, then choose the benchmark or
regression command that matches the files you changed.

.. code-block:: bash

   python revise/validate_refactor.py
   python revise/validate_all_benchmarks.py --sample-size 800
   python revise/validate_full_regression.py --output-root results_unified/full_regression_latest
   cd docs && make html

Next Steps
----------

- For mode-specific details, see :doc:`case` and :doc:`benchmark`.
- For profile and override rules, see :doc:`configuration`.
- For strategy and plugin extension points, see :doc:`architecture`.