Installation
============

Choose the installation path that matches how you will use REVISE. For a normal
analysis workflow, install the PyPI package. For documentation, refactoring, or
route development, use an editable checkout.

Prerequisites
-------------

- Python environment with the scientific stack required by your selected route.
- Local access to input ``.h5ad`` files under ``raw_data/``.
- A writable output location such as ``output/`` or ``results_unified/``.

Stable Release
--------------

Install the latest release from PyPI:

.. code-block:: bash

   pip install revise-svc

Optional annotation support installs ``tacco``:

.. code-block:: bash

   pip install "revise-svc[annotation]"


Development Install
-------------------

Clone the repository and install with development tooling:

.. code-block:: bash

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

The source distribution and wheel include ``revise/revise.yaml``. Installed
Python code can therefore use ``REVISEPipeline()`` without passing a config
path. Source-tree scripts still default to ``--config revise/revise.yaml`` for
backward compatibility.

Useful development checks:

.. code-block:: bash

   ruff check revise/
   black revise/
   python revise/validate_refactor.py

After installation, run one of the commands in :doc:`quickstart` to validate
that your data layout and route selection are correct.


Documentation Build
-------------------

ReadTheDocs uses the repository-level ``.readthedocs.yaml`` file. Local docs
builds use ``docs/conf.py`` as the Sphinx configuration:

.. code-block:: bash

   pip install -r docs/requirements.txt
   cd docs
   make html

The documentation build imports ``revise`` from the repository checkout and
mocks heavy scientific dependencies. ReadTheDocs therefore does not install the
full runtime package during docs builds.

``docs/source/api/generated/`` is produced by Sphinx autosummary during the
build and is intentionally not tracked by Git. Notebook pages under
``docs/benchmark`` and ``docs/case`` are tracked symbolic links to the
maintained notebooks in ``reproduce/``.


Data Layout
-----------

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

.. code-block:: text

   raw_data/
   ├── Sim2Real-ST/
   │   ├── segmentation/
   │   ├── bin2cell/
   │   ├── batch_effect/
   │   ├── spot_size/
   │   ├── gene_panel/
   │   └── gene_dropout/
   └── Real_application/

Generated outputs should go under ``output/`` or ``results_unified/``. These
directories are intentionally ignored by Git.