Outputs
=======

RAFT writes workflow results under each project's ``outputs/`` directory. This
page focuses on the technical structure of that directory and how it relates to
the project's ``work/`` and ``logs/`` directories.

Output categories
-----------------

Most projects include at least these subdirectories:

- ``outputs/samples/``: biological outputs organized by dataset, patient, and
  run
- ``outputs/qc/``: quality-control outputs organized using the same hierarchy
- ``outputs/reports/``: Nextflow execution reports such as DAGs, traces, and
  timelines

``outputs/reports/``
--------------------

The ``reports/`` directory contains workflow-level execution reports generated
by Nextflow. Common files include:

- ``dag.dot``: directed acyclic graph description of the workflow
- ``report.html``: run summary with process-level resource and execution
  details
- ``timeline.html``: graphical timeline of process execution
- ``trace.txt``: tabular process-level execution log

During execution, some report files may first appear under the project's
``logs/`` directory and then be copied or linked into ``outputs/reports/`` when
the run completes.

Hierarchical output structure
-----------------------------

Sample-level outputs under ``samples/`` and ``qc/`` follow the same basic
hierarchy:

.. code-block:: text

  outputs/
    samples/
      <DATASET>/
        <PATIENT_NAME>/
          <RUN_NAME>/
    qc/
      <DATASET>/
        <PATIENT_NAME>/
          <RUN_NAME>/

These names come from the manifest:

- ``Dataset`` defines ``<DATASET>``
- ``Patient_Name`` defines ``<PATIENT_NAME>``
- ``Run_Name`` defines ``<RUN_NAME>``

Some workflows also create combined run directories for grouped analyses. For
example, a tumor-normal pair may be represented as
``ad-Pt01+nd-Pt01``.

``samples/``
------------

The ``samples/`` directory contains analysis outputs intended for downstream
biological interpretation.

For example, the outputs for run ``ar-279`` from patient ``Pt01`` in dataset
``Foo_2024`` would typically live under:

.. code-block:: text

  outputs/samples/Foo_2024/Pt01/ar-279/

A run directory usually contains one subdirectory per tool or task, for
example:

.. code-block:: text

  fastp/
  salmon_aln_quant/
  samtools_coverage/
  seq2hla/
  seqtk_subseq/
  starfusion/

In many workflows, these files are symbolic links back into the project's
``work/`` directory rather than independent copies. That keeps outputs
organized without duplicating large intermediate files unnecessarily.

``qc/``
-------

The ``qc/`` directory contains tool-reported QC metrics and summaries. These
files follow the same dataset/patient/run hierarchy as ``samples/``.

For example:

.. code-block:: text

  outputs/qc/Foo_2024/Pt01/ad-Pt01-pre/
    fastp/
    multiqc/
    samtools_coverage/

These QC outputs are what ``raft generate-reports`` reads when building the
browser-based review interface.

Relationship to ``work/`` and ``logs/``
---------------------------------------

``outputs/`` is the organized results view of a project. It is not the same as
the Nextflow ``work/`` directory.

- ``work/`` contains task working directories and intermediate execution files
- ``outputs/`` contains organized result files and links intended for review
  and downstream use
- ``logs/`` contains Nextflow logs and related execution metadata

If you are troubleshooting a failed task, start in ``logs/`` and ``work/``. If
you are looking for final workflow results, start in ``outputs/``.