Frequently asked questions
==========================

This page collects common RAFT questions about setup, manifests, projects, and
workflow execution. If you are diagnosing a failure or unexpected behavior,
start with :doc:`troubleshooting`.

What is RAFT?
-------------

RAFT (Reproducible Analyses Framework and Tools) is a workflow manager for
building, running, packaging, and reviewing bioinformatics projects in a
consistent way. It helps organize inputs, references, workflow code, logs, and
outputs under a reproducible project structure.

What directory should I run RAFT from?
--------------------------------------

Run workspace-level RAFT commands from the workspace root, the directory that
contains ``.raft.cfg``.

If you are unsure where that is, check the path you used for:

.. code-block:: console

  $ raft setup --default

If a command says RAFT cannot find ``.raft.cfg``, change back to the workspace
root and rerun it there.

Do I need a manifest before I create a project?
-----------------------------------------------

Not always. For many workflow runs, ``--manifest`` is optional during initial
setup. If you omit it, RAFT can open the manifest generator so you can create
one interactively.

For example:

.. code-block:: console

  $ raft run \
      --project-id my-project \
      --workflow lens \
      --version v1.9-dev \
      --setup-only

If you prefer command-line creation, generate a starter TSV with:

.. code-block:: console

  $ raft manifest-template --output my_manifest.tsv

What does ``--setup-only`` do?
------------------------------

``--setup-only`` prepares the project but does not launch Nextflow. Depending
on the workflow, it may:

- create the project directory structure
- fetch workflow configuration and modules
- load metadata and references
- generate or save manifest/config files

Use it when you want to inspect or edit the generated project before running:

.. code-block:: console

  $ raft project-status --project-id my-project
  $ raft run --project-id my-project

How do I rerun an existing project?
-----------------------------------

Use the project ID:

.. code-block:: console

  $ raft run --project-id my-project

If the project has already run before, RAFT and Nextflow will attempt to resume
work unless you disable resume behavior explicitly.

How do I see what happened in a project?
----------------------------------------

Start with the project summary:

.. code-block:: console

  $ raft project-status --project-id my-project

That is the safest first command for inspection because it is read-only and
surfaces workflow context, manifest details, trace/report locations, and next
steps.

Where are my workflow outputs?
------------------------------

RAFT projects usually store outputs under:

- ``projects/<PROJECT_ID>/outputs/``
- ``projects/<PROJECT_ID>/outputs/reports/`` for Nextflow reports and traces
- ``projects/<PROJECT_ID>/logs/`` for execution logs

The exact workflow-specific files depend on the workflow you ran. See
:doc:`accessing-and-reviewing-outputs` for the general layout.

Can I run RAFT without a default Nextflow profile?
--------------------------------------------------

Yes, but only with caveats. RAFT can continue with conservative local resource
caps when it does not detect a standard/default profile in
``~/.nextflow/config``.

For a real cluster or production run, pass a profile explicitly:

.. code-block:: console

  $ raft run --project-id my-project --profile slurm

How do I update references for an off-the-shelf workflow?
---------------------------------------------------------

For OTS workflows, use:

.. code-block:: console

  $ raft download-refs --workflow lens --version v1.9-dev --species human

This populates the shared references area for that workflow. If you are using a
bucket-backed run with ``--references-bucket``, make sure the required staged
reference outputs are also present in that bucket before launching the run.

How do I open the report viewer?
--------------------------------

For an existing project:

.. code-block:: console

  $ raft generate-reports --project-id my-project

You can also launch the viewer without preloading project files:

.. code-block:: console

  $ raft generate-reports --project-id my-project --no-load