Accessing and Reviewing Outputs
================================

The recommended way to review LENS outputs is through the RAFT Output Viewer —
an interactive web interface for exploring pMHC reports, QC metrics, and cohort
comparisons.

Launching the viewer
--------------------

After a LENS run completes:

.. code-block:: console

   raft generate-reports --project-id my-project-lens

A demonstration report is also available:

.. code-block:: console

   raft generate-reports --demo

.. image:: screenshots/viewer_overview.png
   :width: 800

Navigating the viewer
---------------------

The viewer provides several views, accessible from the sidebar:

Report view
~~~~~~~~~~~

The primary view for exploring predicted pMHCs:

- Select a patient from the sidebar to load their report
- Each pMHC is displayed as a card showing peptide sequence, HLA allele,
  antigen source badge (color-coded by type), and key metrics
- Filter by **Top N**, **sort metric**, **allele**, or **antigen source**
- Interactive visualizations (histograms, scatter plots, box plots) appear
  alongside the cards

.. image:: screenshots/viewer_pmhc_card.png
   :width: 800

.. image:: screenshots/viewer_filtering.png
   :width: 800

QC view
~~~~~~~

Sample-level quality control metrics organized by sample type:

- **Tumor DNA** — alignment stats, coverage, variant calling metrics
- **Tumor RNA** — alignment stats, RNA quality, expression metrics
- **Normal DNA** — alignment stats, somalier relatedness checks
- **HLA typing** — allele calls with confidence scores
- **Germline phasing** — WhatsHap phasing summary

.. image:: screenshots/viewer_qc_dashboard.png
   :width: 800

Cohort QC view
~~~~~~~~~~~~~~~

Cross-patient QC metrics in a table format for comparing samples across the
entire project.

Joint Analysis view
~~~~~~~~~~~~~~~~~~~~

For patients with multiple groups (e.g., pre- and post-treatment):

- **pMHC sharedness** — Venn diagram showing shared vs. exclusive pMHCs
- **Expression changes** — gene expression comparison across groups
- **Gained/lost antigens** — antigens unique to each group
- **Allelic consistency** — HLA allele consistency checks

.. image:: screenshots/viewer_joint_analysis.png
   :width: 800

For a guide to interpreting the report columns and prioritization scores, see
:doc:`interpreting_report`. For exhaustive column-by-column documentation, see
:doc:`report_column_reference`.

Output directory structure
---------------------------

RAFT saves all outputs under the project's ``outputs/`` directory:

- **``outputs/samples/``** — sample-level outputs (BAMs, VCFs, quantifications,
  etc.)
- **``outputs/qc/``** — quality control summaries and metrics
- **``outputs/reports/``** — Nextflow execution reports, traces, and timelines
- **``outputs/lens/``** — the primary LENS report (``*.report.tsv``) and run QC
  summary (``*.run_qc_summary.tsv``)

Directory names map directly to manifest fields: ``Dataset/``,
``Patient_Name/``, and ``Run_Name/``. Combined run directories (e.g.,
``ad-123+nd-234/``) represent outputs from paired or grouped inputs.

To find specific file types:

.. code-block:: console

   # VCF files
   find outputs/ -name "*vcf*"
   # BAM files
   find outputs/ -name "*.bam"
   # LENS reports
   find outputs/ -name "*.report.tsv"