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.
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 |
|
Normal |
Is the sample normal or abnormal (tumor)? |
|
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.