Interpreting the Report
=======================

The LENS workflow concludes by generating a report consisting of predicted
pMHCs. The report is a tab-separated file (``*.report.tsv``) located in the
project's ``outputs/lens/<DATASET>/<PAT_NAME>/<RUN_NAME>/`` directory.

.. tip::

   The interactive RAFT Output Viewer (launched with ``raft generate-reports``)
   provides the best way to explore the LENS report — with pMHC cards,
   filtering, visualizations, and QC dashboards. See :doc:`accessing_and_reviewing_outputs` for details.

This page provides a surface-level guide to reading and using the LENS report.
For an exhaustive column-by-column reference, see :doc:`report_column_reference`.

What the report contains
________________________

Each row in the report represents a predicted pMHC (peptide-MHC complex). A
single report combines candidates from all seven antigen sources:

- Somatic Nucleotide Variants (SNVs)
- Somatic Insertion and Deletion Variants (InDels)
- Splice Variants
- Fusion Events
- Endogenous Retroviruses (ERVs)
- Viruses
- Cancer-testis Antigens (CTAs)

Because the report combines candidates from several antigen sources, many
columns only apply to one source. For example, fusion breakpoint columns are
populated only for fusion-derived pMHCs, and InDel allele columns are populated
only for InDel-derived pMHCs.

Key columns
____________

The following columns are the most important for initial review:

.. list-table::
   :widths: 35 65
   :header-rows: 1

   * - Column
     - Description
   * - ``candidate_id``
     - Stable row identifier used to join report rows, review scores, and review evidence JSON.
   * - ``allele``
     - The HLA allele presenting the peptide.
   * - ``peptide``
     - The peptide sequence.
   * - ``antigen_source``
     - The source of the antigen (``SNV``, ``INDEL``, ``SPLICE``, ``FUSION``, ``ERV``, ``VIRUS``, or ``CTA/SELF``).
   * - ``mhcflurry_2.1.1.aff``
     - Binding affinity (nM) from MHCflurry. Lower values indicate stronger binding.
   * - ``priority_score_recommended``
     - Recommended priority score for cross-source ranking (higher is better).
   * - ``priority_score_basis``
     - Which scoring model was used for ``priority_score_recommended``.

Prioritizing candidates
________________________

The ``priority_score_recommended`` column provides a single score for ranking
pMHCs across all antigen sources. It is calculated from binding affinity,
allele-specific transcript abundance, and cancer cell fraction (CCF, when
available).

Use ``priority_score_recommended`` as the primary cross-source sorting score.
The companion ``priority_score_basis`` column records which source score was
selected for each row (e.g., ``MHCFLURRY_WITH_CCF``, ``MHCFLURRY_NO_CCF``,
``NETMHCPAN_WITH_CCF``, etc.).

Agretopicity and CCF-aware priority scores are most meaningful for variant
sources where a matched wildtype sequence and tumor context are available.
For non-variant sources, and for variant rows without a matched wildtype
peptide or CCF input, these fields can be missing or marked as not computed.
This is why ``priority_score_recommended`` exists — it selects the best
available score for each row regardless of source.

For the prioritization formula, see the :doc:`faq`.

Understanding missing values
____________________________

LENS uses explicit values for missing or non-applicable data:

.. list-table::
   :widths: 35 65
   :header-rows: 1

   * - Value
     - Meaning
   * - ``NOT_APPLICABLE``
     - The field does not apply to the candidate's antigen source or context.
   * - ``NOT_COMPUTED``
     - The computation did not run or the required input was unavailable.
   * - ``NO_DETECTED_MUTATION``
     - A mutation scan ran and did not detect a mutation in the requested gene.
   * - ``NO_MATCHED_WT``
     - A matched wildtype peptide or sequence could not be identified.
   * - ``NO_LOHHLA_RESULT_FOR_ALLELE``
     - LOHHLA ran but did not report a p-value for the candidate's presented allele.
   * - ``NA``
     - Legacy or tool-derived missing value. Check the column and antigen source before interpreting.

LOHHLA p-values are allele-level annotations. Use ``lohhla_allele_loss_status``
to distinguish an available p-value from an allele that did not have a LOHHLA
result. Missing p-values should not be interpreted as evidence against HLA loss.

Review columns
_______________

The final report includes review scoring columns produced by the review
evidence workflow:

.. list-table::
   :widths: 35 65
   :header-rows: 1

   * - Column
     - Description
   * - ``candidate_id``
     - Stable row identifier used to join report rows, review scores, and review evidence JSON.
   * - ``alignment_confidence_score``
     - Review score summarizing alignment and read-level confidence evidence.
   * - ``final_tier``
     - Review tier assigned to the candidate (``PASS``, ``REVIEW``, or ``FAIL``).
   * - ``reasons``
     - Semicolon-delimited review flags that contributed to the score or tier. Can be empty.

Common filtering strategies
____________________________

Filter by antigen source
~~~~~~~~~~~~~~~~~~~~~~~~~

To focus on a specific antigen source:

.. code-block:: console

  awk -F'\t' '$antigen_source_col == "SNV"' report.tsv

Replace ``$antigen_source_col`` with the column number for ``antigen_source``.
Valid values: ``SNV``, ``INDEL``, ``SPLICE``, ``FUSION``, ``ERV``, ``VIRUS``,
``CTA/SELF``.

Filter by binding affinity
~~~~~~~~~~~~~~~~~~~~~~~~~~~

LENS filters pMHCs by default at < 500 nM binding affinity. To apply a stricter
threshold (e.g., < 50 nM):

.. code-block:: console

  awk -F'\t' '$aff_col < 50' report.tsv

Sort by priority score
~~~~~~~~~~~~~~~~~~~~~~

To rank candidates across all antigen sources:

.. code-block:: console

  sort -t$'\t' -k priority_score_recommended_col -nr report.tsv

Run QC summary
______________

Next to the final report, LENS writes ``*.run_qc_summary.tsv`` — a compact,
long-format TSV with ``section``, ``metric``, ``value``, ``level``, and
``detail`` columns. It summarizes:

- Report row counts
- Candidate ID integrity
- Antigen-source counts
- Missingness for important report columns
- Final-report validation messages

Execution trace status is not included in this summary because Nextflow writes
trace/report files after the workflow DAG finishes. Use RAFT project status or
``raft generate-reports`` to inspect task status counts and failed or retried
tasks from ``outputs/reports/trace*.txt``.

Further reading
_______________

- :doc:`report_column_reference` — exhaustive column-by-column documentation
  for every antigen source
- :doc:`accessing_and_reviewing_outputs` — overview of the full output directory structure
- :doc:`technical_details` — default tools, references, and pipeline internals