Manifest specifications

This page provides the full column reference, sample naming conventions, complex sample set configurations, and manifest validation for RAFT manifests. For a task-oriented guide to creating manifests, see Preparing your samples.

Manifest columns

A RAFT manifest must have at least the columns defined in the table below. Columns can be in any order and other columns containing non-RAFT metadata are also allowed.

RAFT Columns

Column

Description

Allowed values

Dataset

Name for collection of patients

Free text

Patient_Name

Name for collection of samples

Free text

Run_Name

Name for the specific sample

Free text (see note below)

File_Prefix

Base name (or full path) of input files

Free text

Sequencing_Method

Sequencing protocol for sample

WES, WXS, WGS, RNA-Seq, or RNA (lowercase spellings such as wes and rna-seq are also accepted)

Normal

Is the sample normal or abnormal (tumor)?

TRUE or FALSE (uppercase)

Alleles

Class I MHC alleles for the patient. Optional for human samples, where LENS types alleles from the sequencing data. Required for mouse.

See the note below

Note

A sample’s Run_Name is instrumental in guiding samples through some RAFT workflows. A sample’s Run_Name should have a two-letter prefix that describes the type of sample and a delimiter (- or _) followed by an arbitrary unique identifier. The first letter of the prefix is either a (for abnormal) or n (for normal). The second letter is either r (for RNA) or d (for DNA). For example, a sample with an ar- (or ar\_) prefix is an abnormal (tumor) RNA sample while a sample with a nd- prefix is a normal DNA sample.

Note

The Alleles column holds the patient’s class I MHC alleles. For human samples it is optional. LENS types alleles directly from the sequencing data and reports the calls in the QC view. Provide it only when you want to override typing with known alleles.

When supplied for a human patient, the value must be exactly six comma-separated alleles (two HLA-A, two HLA-B, and two HLA-C) at four-digit resolution:

HLA-A01:01,HLA-A02:01,HLA-B08:01,HLA-B27:05,HLA-C01:02,HLA-C07:01

A * separator is accepted and removed, so HLA-A*01:01 is equivalent to HLA-A01:01. Alleles are matched case-insensitively.

Alleles finer than four-digit resolution are truncated to their first two fields, which is the resolution the MHC binding predictors consume. raft check-manifest reports each truncation, for example:

WARNING: Patient Pt01, run ar-001: Allele HLA-A01:01:01 is finer than
four-digit resolution and was normalized to HLA-A01:01 for MHC
prediction tools.

For mouse samples the column is required, and holds two or three class I H-2 alleles, one each for the K, D, and (optionally) L locus:

H-2-Kb,H-2-Db

The H2- spelling is also accepted and normalized to H-2-.

Every sample belonging to a patient must carry the same alleles. The one exception is a patient whose alleles appear only on ar- rows; if that patient has more than one ar- sample, each of them must carry the alleles, and they must agree.

Complex sample sets

Some sample sets need more than one sample of a given type per patient. You might have a single set of DNA samples (normal DNA and tumor DNA) alongside several RNA-seq samples taken at different timepoints, for example. RAFT’s subjoin functionality supports these cases via a Group column in the manifest:

Patient_Name Run_Name        Dataset File_Prefix     Sequencing_Method       Normal  Group
Pt01 ad-Pt01-03A     AML     9f7f7   WES     FALSE   1;2
Pt01 nd-Pt01-11A     AML     8e74a   WES     TRUE    1;2
Pt01 ar-Pt01-03A     AML     cdb288  RNA-Seq FALSE   1
Pt01 ar-Pt01-03B     AML     cdb289  RNA-Seq FALSE   2

Important

The manifest is tab-separated. The example above uses tabs between every field; if you retype it with spaces, validation will reject it.

In the Group column, ; separates group memberships. A sample with 1;2 belongs to both group 1 and group 2, which is how the shared DNA samples above participate in two sample sets. A sample in a single group carries just that group’s name.

This scenario depicts a patient (Pt01) with a DNA normal sample, a DNA tumor sample, and two RNA-seq samples. In this example, ar-Pt01-03A is a pre-treatment sample and ar-Pt01-03B is a post-treatment sample. LENS will be run on two distinct sample sets:

The pre-treatment sample set:

  • ad-Pt01-03A

  • nd-Pt01-11A

  • ar-Pt01-03A

The post-treatment sample set:

  • ad-Pt01-03A

  • nd-Pt01-11A

  • ar-Pt01-03B

Each sample set produces its own LENS report.

Note

Group identifiers do not have to be numbers. Descriptive names such as pre-treatment and post-treatment work equally well.

Validating a manifest

The workflow validates the manifest at the start of every raft run, checking required columns, allowed Sequencing_Method values, Run_Name prefix conventions, and sample composition per patient. Problems stop the run before any compute is scheduled.

To check a manifest ahead of time:

raft check-manifest -m </PATH/TO/MANIFEST>

This runs a stricter set of checks than the workflow does, additionally validating Alleles formatting and cross-sample HLA consistency within each patient.