Running LENS ============ Choosing a Running Method -------------------------- LENS can be run locally, in a hybrid local/cloud configuration, or entirely in the cloud. Local ~~~~~ **Manifest preparation** Launch LENS with your manifest: .. code-block:: console raft run --project-id my-project-lens \ --workflow lens \ --version 1.9-dev \ --species human \ --input-data fastqs ``raft run`` assumes human samples and FASTQ input, so the above is equivalent to: .. code-block:: console raft run --project-id my-project-lens \ --workflow lens \ --version 1.9-dev \ LENS supports mouse samples with an additional requirement -- MHC alleles must be provided when generating the manifest. Run with ``--species mouse`` and ``--setup-only``, then modify the config: .. code-block:: console raft run --project-id my-project-lens \ --workflow lens \ --version 1.9-dev \ --species mouse \ --setup-only Then launch the workflow: .. code-block:: console raft run-workflow --project-id my-project-lens Hybrid ~~~~~~ The hybrid method runs LENS locally with data stored on Google Cloud. Add ``--cloud`` and ``--profile`` to the local command: .. code-block:: console raft run --project-id my-project-lens \ --workflow lens \ --version 1.9-dev \ --cloud gs:// \ --profile Upload references to ``gs:///references/cloud/``, FASTQs to ``gs:///fastqs//``, and your manifest to ``gs:///metadata//``. An appropriate Nextflow profile must be set up beforehand. Cloud ~~~~~ To run LENS entirely in the cloud, use the `RAFT Cloud Launcher `_. Preparing Your Samples ----------------------- LENS requires a `manifest `_ 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. Using the Config Generator ---------------------------- The recommended way to run LENS is through RAFT's interactive Config Generator. When you start a new project without a workflow profile, RAFT opens a browser-based configuration tool that lets you select tools, set parameters, and modify references — all without editing configuration files directly. Use ``--workflow-profile standard`` to accept defaults and skip manual configuration: .. code-block:: console raft run --project-id my-project-lens --workflow-profile standard Without a workflow profile, RAFT opens the Config Generator: .. code-block:: console raft run --project-id my-project-lens After saving your manifest (see :doc:`preparing_your_samples`), RAFT opens the Config Generator. .. image:: screenshots/config_generator_overview.png :width: 800 The Config Generator walks you through: 1. **Workflow selection** — choose LENS, species (human or mouse), starting data (FASTQs or BAMs), and version. 2. **Runtime limits** — set max CPUs and memory. 3. **Tool selection** — expand accordion sections to pick tools for each step (e.g., ``fastp`` or ``trimmomatic`` for trimming, ``mutect2`` or ``strelka2`` for variant calling). 4. **Parameters** — edit tool-specific parameters directly in the form. 5. **References** — modify reference file paths if needed. 6. **Methods description** — an auto-generated methods section based on your selections, ready to copy into manuscripts. .. image:: screenshots/config_generator_tool_selection.png :width: 800 After configuration, click **Save to RAFT** to save and launch the workflow, or **Copy to CLI** to get the command for terminal use. .. note:: Intermediate files are deleted automatically after a successful run. Use ``--keep-intermediates`` if you need to retain them.