Preparing Your Samples
=======================

LENS requires a `manifest <https://uselens.io/en/lens-v1.9-dev/manifest_specifications.html>`_ that defines the relationships among your samples, patients, and datasets. The manifest tells RAFT which samples belong together and what sequencing data each sample contains.

The organizational hierarchy follows:

.. code-block:: console

   Sample ⊂ Group ⊂ Patient ⊂ Dataset

Samples belong to groups (for multi-timepoint analyses), groups belong to patients,
and patients belong to datasets.

.. image::
   patient_names_and_runs.png
   :width: 675

A LENS manifest requires at least one tumor DNA sample, one normal DNA sample,
and one tumor RNA sample per patient. A reduced analysis (without SNV or InDel
pMHCs) can be run with only tumor RNA.

Using the Manifest Generator
------------------------------

The easiest way to create a manifest is through the RAFT Manifest Generator —
a browser-based form with autocomplete, real-time validation, and
workflow-aware requirements.

Launch it by starting a new project without a ``--manifest`` argument:

.. code-block:: console

   raft run --project-id my-project-lens --workflow lens --version 1.9-dev

The Manifest Generator opens in your browser. From there you can:

1. **Select a workflow** — choose "LENS (Tumor Antigens)" from the dropdown.
2. **Add samples** — fill in Dataset, Patient Name, Sample Type, Run Name, and
   File Prefix for each sample.
3. **Review** — the Sample Overview section organizes samples by patient and
   group, with color-coded type badges.
4. **Save** — click "Save to RAFT" to save the manifest to your project.

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

The Sample Type dropdown auto-sets the Run Name prefix and Sequencing Method:

- **Tumor DNA** → prefix ``ad-``, method ``WES``
- **Normal DNA** → prefix ``nd-``, method ``WES``
- **Tumor RNA** → prefix ``ar-``, method ``RNA-Seq``
- **Normal RNA** → prefix ``nr-``, method ``RNA-Seq``

The File Prefix field autocompletes from available FASTQ files in your project
directory and validates that the files exist.

Validation warnings appear in real time — for example, "Missing for LENS:
Normal DNA" if a normal DNA sample has not been added for a patient.

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

A hosted version of the Manifest Generator is also available for creating
manifests outside of a project:

   https://spvensko.github.io/raft-ui/raft-manifest-generator.html

Creating a manifest from the command line
------------------------------------------

If you prefer the command line, RAFT can generate a starter manifest:

.. code-block:: console

   raft manifest-template --output my_manifest.tsv

This creates a TSV file with example rows for a typical LENS run. To generate a
header-only template:

.. code-block:: console

   raft manifest-template --no-examples --output my_manifest.tsv

For the full column reference, sample naming conventions, complex sample sets
with Groups, and manifest validation, see :doc:`manifest_specifications`.

Supplying the manifest
-----------------------

Once you have a manifest, pass it when starting a project:

.. code-block:: console

   raft run --project-id my-project-lens --workflow lens --version 1.9-dev --manifest my_manifest.tsv

Manifest files must be placed in RAFT's ``inputs/metadata`` directory to be
discovered automatically.