The epitopeprediction template follows an nf-core/epitopeprediction run from the alleles the peptides bind to the peptides that bind and the tools behind the calls:
- Overview: the run in four key figures, live findings and four figures, each linked to the tab that explains it
- Data & QC: the MultiQC report, with the binder statistics of every sample and tool
- Neoepitopes: which alleles the peptides bind, which peptides bind and where they come from, and how far the prediction tools agree
The persistent Sample filters (input type, sample and MHC class) sit in the
left panel and narrow every tab. A sample is one of three inputs: a VCF of
somatic variants, a protein FASTA or a peptide table, and the input type is the
default grouping.
The samplesheet is not published by the pipeline
The hub of the dashboard is the samplesheet the run was started with
(sample, alleles, mhc_class, filename, and for variant input
tumor_sample and germline_vcf). It is not part of the published output,
so copy it under input/ in the results directory, or pass
--var METADATA_FILE=....
Allele spelling matches nf-core/hlatyping
Alleles are normalised to two fields, HLA-A*02:01, the spelling the
hlatyping template uses. A typed sample's alleles list can
go straight into this pipeline's samplesheet. The two runs are separate
projects, so a pick in one does not filter the other.
Quick start¶
depictio ingest /path/to/epitopeprediction_results \
--template nf-core/epitopeprediction/latest \
--var METADATA_FILE=/path/to/samplesheet.csv
The results directory is the only required value when the samplesheet sits at
{DATA_ROOT}/input/samplesheet.csv.
| Variable | Default | Role |
|---|---|---|
METADATA_FILE |
{DATA_ROOT}/input/samplesheet.csv |
the samplesheet the run was started with |
GROUP_COL |
input_type |
column the dashboard groups and filters samples by; input_type (Variants, Proteins or Peptides) is derived from the input file |
GROUP_COL_DISPLAY |
Input type |
reader-facing label of GROUP_COL in filters and cards |
NO_VARIANT_INPUT |
unset | set for a sheet with no VCF: drops the variant peptides and the mutant against wild type pairs |
NO_WILD_TYPE |
unset | set for a run without --wild_type: drops the mutant against wild type pairs |
SINGLE_PREDICTOR |
unset | set for a run with one tool per MHC class: drops the tool agreement |
depictio config nextflow --install # once per machine
nextflow run nf-core/epitopeprediction -r 3.2.0 -profile docker --outdir results
No depictio ingest, and no template named: the pipeline ingests its own
output directory when it finishes and resolves this template from its own
manifest. See Nextflow trigger. The
trigger passes no --var, so put a copy of the samplesheet at
results/input/samplesheet.csv before the run.
Reference¶
The template reads the samplesheet, the merged predictions (one table per
sample, in the long shape or with --wide_format_output), the candidate
peptides cut from the variants and the MultiQC report. The affinity is the
pipeline's 0 to 1 score converted back to an IC50 in nM, and a binder is the
call of the pipeline, per tool. The per-tool directories repeat the merged
predictions and are not read.
The mutant against wild type pairs, the variant peptides and the tool agreement are optional collections: an ingest that finds nothing to pair skips them, and their tiles are pruned even when the variable is not set.
Self-adapting layout
The dashboard adapts to whatever the run actually produced: components bound to pruned or unparsed data collections are hidden, tabs left with no real visualizations are dropped entirely, and the remaining components are re-packed so there are no empty rows.
Template variables¶
Variables you provide when running the template: DATA_ROOT is the results directory given to depictio ingest, the others are set with --var NAME=value:
| Variable | Required | Description |
|---|---|---|
DATA_ROOT |
✓ | epitopeprediction output directory (predictions/, variant_peptides/, variant_fasta/, the per-tool directories, multiqc/, pipeline_info/). |
METADATA_FILE |
— | The samplesheet the run was started with (--input: sample, alleles, mhc_class, filename, optional tumor_sample and germline_vcf, plus any design columns). Defaults to input/samplesheet.csv under DATA_ROOT. |
METADATA_ID_COL |
— | Samplesheet id column. epitopeprediction fixes it to sample; recorded for the metadata auto-detection. |
GROUP_COL |
— | Samplesheet column the dashboard groups and filters samples by. Defaults to input_type (Variants, Proteins or Peptides), derived from the sheet; name any design column added to the sheet instead. |
GROUP_COL_DISPLAY |
— | Reader-facing label of GROUP_COL, used in filter and card titles. |
NO_VARIANT_INPUT |
— | Set (--var NO_VARIANT_INPUT=true) for a run whose samplesheet has no VCF: variant_peptides/ is absent and no mutant peptide has a wild type, so both collections are removed. |
NO_WILD_TYPE |
— | Set (--var NO_WILD_TYPE=true) for a run without --wild_type, or with no missense variant: no wild-type peptide was predicted, so the mutant / wild-type collection is removed. |
SINGLE_PREDICTOR |
— | Set (--var SINGLE_PREDICTOR=true) for a run with one prediction tool per MHC class: no peptide is scored by two tools, so the agreement collection and the Predictors tab are removed. |
Data collections¶
9 data collections — 6 required 3 optional · 9 direct 0 derived.
Origin tells you whether a collection is real pipeline data or a reshape of it: direct = a pipeline output (scanned, or a recipe that reads raw files); derived = a recipe that reshapes one or more direct collections into the layout a visualization needs (no new measurement). Reads shows what produces it: a recipe .py transform, or a raw file scanned off disk. (A direct collection can still have a recipe — one that merely parses/cleans the raw file; derived means the recipe reshapes another collection.)
| Tag | Origin | Type | Reads | Status |
|---|---|---|---|---|
samples |
direct | Table | recipe |
required |
multiqc_data |
direct |  MultiQC |
file |
required |
epitopeprediction_predictions |
direct | Table | recipe |
required |
epitopeprediction_peptides |
direct | Table | recipe |
required |
epitopeprediction_allele_summary |
direct | Table | recipe |
required |
epitopeprediction_predictor_summary |
direct | Table | recipe |
required |
epitopeprediction_predictor_agreement |
direct | Table | recipe |
optional |
epitopeprediction_wildtype_pairs |
direct | Table | recipe |
optional |
epitopeprediction_variant_peptides |
direct | Table | recipe |
optional |
Conditional routes¶
Rows are data collections; columns are the variables you set or params.json flags auto-detected from the run. Each filled cell is the effect of setting that variable; an empty cell means that variable leaves the collection unchanged. (6 collections are unaffected by any variable — present on every run.)
+ included− removed⇄ repointed
| Data collection | NO_VARIANT_INPUT |
NO_WILD_TYPE |
SINGLE_PREDICTOR |
|---|---|---|---|
epitopeprediction_predictor_agreement |
− | ||
epitopeprediction_wildtype_pairs |
− | − | |
epitopeprediction_variant_peptides |
− |
Cross-DC links¶
14 links — selecting a value in the source collection filters the target. The join column is shown after the source.
| Source · column | Target | Filters | |
|---|---|---|---|
samples · sample |
→ | multiqc_data |
Filter the MultiQC panels by samplesheet samples (<sample>_<tool> and <sample>.prep) |
samples · sample |
→ | epitopeprediction_predictions |
Filter the predictions by samplesheet samples |
samples · sample |
→ | epitopeprediction_peptides |
Filter the peptides by samplesheet samples |
samples · sample |
→ | epitopeprediction_allele_summary |
Filter the per-allele summary by samplesheet samples |
samples · sample |
→ | epitopeprediction_predictor_summary |
Filter the per-tool summary by samplesheet samples |
samples · sample |
→ | epitopeprediction_predictor_agreement |
Filter the tool agreement by samplesheet samples |
samples · sample |
→ | epitopeprediction_wildtype_pairs |
Filter the mutant / wild-type pairs by samplesheet samples |
samples · sample |
→ | epitopeprediction_variant_peptides |
Filter the variant peptides by samplesheet samples |
epitopeprediction_predictions · allele |
→ | epitopeprediction_allele_summary |
Carry an allele pick to the per-allele summary |
epitopeprediction_predictions · allele |
→ | epitopeprediction_predictor_agreement |
Carry an allele pick to the tool agreement |
epitopeprediction_predictions · allele |
→ | epitopeprediction_wildtype_pairs |
Carry an allele pick to the mutant / wild-type pairs |
epitopeprediction_peptides · length_class |
→ | epitopeprediction_predictions |
Carry a peptide-length pick to the predictions |
epitopeprediction_peptides · length_class |
→ | epitopeprediction_variant_peptides |
Carry a peptide-length pick to the variant peptides |
epitopeprediction_predictor_summary · predictor |
→ | epitopeprediction_predictions |
Carry a tool pick on the Predictors tab to the predictions |
Recipes¶
Each recipe reshapes raw pipeline output into a tidy table. The name links to its source; Output lists the validated OUTPUT_SCHEMA columns.
| Recipe | Transforms | Output |
|---|---|---|
epitopeprediction/allele_summary.py |
Binding per allele of nf-core/epitopeprediction, one row per sample and allele. | allele_key, sample, allele, hla_locus, mhc_class, predictors, peptides, binders, binder_rate, median_ic50_nm, best_ic50_nm, median_affinity_score |
epitopeprediction/peptides.py |
Peptides of nf-core/epitopeprediction, one row per sample and peptide. | peptide_key, sample, sequence, peptide_id, length, length_class, origin, call, binder, alleles_scored, binding_alleles, binder_calls, predictors, best_allele, best_predictor, best_ic50_nm, best_affinity_class, binding_allele_list, gene, transcript, consequence, HGVSp, genomic_anchor, uniprot, protein_ids, source_records, wildtype, wt_best_ic50_nm, agretopicity |
epitopeprediction/predictions.py |
Binding predictions of nf-core/epitopeprediction, one row per prediction. | row_id, sample, sequence, length, length_class, origin, predictor, mhc_class, allele, hla_locus, affinity_score, ic50_nm, log10_ic50, percentile_rank, binder, call, affinity_class, peptide_id, gene, consequence, HGVSp, genomic_anchor, wildtype, wt_ic50_nm, agretopicity |
epitopeprediction/predictor_agreement.py |
Agreement between prediction tools of nf-core/epitopeprediction. | pair_key, sample, sequence, length_class, allele, hla_locus, mhc_class, predictor_pair, predictor_a, predictor_b, ic50_a_nm, ic50_b_nm, log10_ratio, abs_log10_ratio, binder_a, binder_b, agreement, concordant |
epitopeprediction/predictor_summary.py |
Binder calls per tool of nf-core/epitopeprediction, one row per sample and tool. | summary_key, sample, predictor, mhc_class, peptides, scored, unsupported, binders, binder_rate, alleles, median_ic50_nm |
epitopeprediction/variant_peptides.py |
Candidate peptides made from variants, nf-core/epitopeprediction. | peptide_key, sample, sequence, length, length_class, origin, gene, transcript, consequence, HGVSp, genomic_anchor, uniprot, protein_ids, source_records, wildtype |
epitopeprediction/wildtype_pairs.py |
Mutant peptides against their wild type, nf-core/epitopeprediction. | pair_key, sample, sequence, wildtype, length_class, allele, hla_locus, predictor, gene, HGVSp, genomic_anchor, ic50_nm, wt_ic50_nm, agretopicity, log10_agretopicity, binder, wt_binder, pair_call |
nf-core/epitopeprediction/samples.py |
Sample hub for nf-core/epitopeprediction: the run's samplesheet, one row per sample. | sample, input_type, mhc_class, allele_source, alleles, input_file, tumor_sample, germline_vcf |
Dashboard tabs¶
One dashboard: the Overview, then four child tabs in two groups, read from the binder statistics to the agreement between tools. Each tab below carries the same icon and colour the dashboard gives it, so the page and the app read alike.
| Group | Tabs |
|---|---|
| Data & QC | MultiQC |
| Neoepitopes | Predictions, Peptides, Predictors |
Each child tab opens with a short intro and a strip of four cards, then at most three open sections; tables follow, collapsed. The Sample sheet is pinned, collapsed, to the bottom of every child tab.
MHC binding prediction, from variants, proteins or peptides to the binders.
The run lists the samples, the alleles scored, the tools and the peptide lengths, and Pipeline walks five steps (peptides, lengths, predict, call, compare), each linked to its parameters and its tab. Four key figures: the samples, the peptides, the alleles and the predicted binders. The findings are live rows (the allele that binds the most peptides, the share of peptides that bind, the mutant peptides that bind where their wild type does not, the tool agreement) and four figures.
Data & QC · How many peptides does each tool call a binder?
MultiQC panels only. Open: the binders, non-binders and unsupported peptides per sample and tool, the rank and affinity distributions and the binder length distribution. The general statistics and the bcftools panels of the VCF inputs are collapsed; a run without variant input has no bcftools panels.
Neoepitopes · Which alleles do the peptides bind, sample by sample?
The predictions by IC50 band, the binder calls, the alleles scored and the median IC50 against the 500 nM binder line. Then the allele by sample dot plot (thirty alleles whose median affinity differs most between samples; dot size is the binder share, colour the median affinity), the log10 IC50 histogram by tool and the predictions per sample by IC50 band. Filters: allele, HLA locus, tool and an IC50 range. The tables are collapsed.
Neoepitopes · Which peptides bind, and which variant or protein do they come from?
The peptides by binder call, the predicted binders, the alleles per binder and the median best IC50. Then the peptides by length stacked by call, and the mutant against wild type IC50 of every missense mutant whose wild type was predicted: below the diagonal the mutation strengthens binding. The candidate peptides cut from the variants and the peptide table, with its record card, are collapsed. Filters: binder call, peptide length and origin.
Neoepitopes · How far do the prediction tools agree on the binders?
The binders per tool, the binder share per sample and tool, the peptides a tool could not score and the most alleles a tool scored in one sample. Then the binder share per sample and tool, IC50 against percentile rank for every prediction with a line at 500 nM, and one tool's IC50 against another's for the peptides both scored (colour is who calls a binder). Filters: tool and agreement. The per-tool and paired-prediction tables are collapsed.
A pick on a sample reaches every collection and the MultiQC panels, and an allele pick reaches the allele summary, the agreement and the mutant against wild type pairs through the project links.
Running the pipeline¶
Depictio reads the output of nf-core/epitopeprediction, it does not run the pipeline. Run the pipeline first:
nextflow run nf-core/epitopeprediction -r 3.2.0 \
--input samplesheet.csv \
--tools mhcflurry,mhcnuggets \
--wild_type \
--outdir results \
-profile docker
The samplesheet is sample,alleles,mhc_class,filename (plus tumor_sample and
germline_vcf for variant input). --tools takes one or several predictors,
and --wild_type also scores the wild-type peptide of each missense mutant.
Copy the samplesheet under results/input/, then point Depictio at the results:
See nf-co.re/epitopeprediction/usage for full pipeline documentation.
Required data structure¶
Point depictio ingest at the directory holding the pipeline output. Depictio
scans recursively and matches on file name.
<DATA_ROOT>/
├── input/samplesheet.csv # --var METADATA_FILE (not published by the pipeline)
├── pipeline_info/
│ ├── params_*.json
│ └── *software*versions*.yml
├── multiqc/multiqc_data/multiqc.parquet
├── predictions/<sample>.tsv # merged predictions, long or wide
└── variant_peptides/<sample>_length_<k>.tsv # optional; VCF input only
Validation runs¶
The repository ships
download_test_data.sh,
which fetches the subset of nf-core's AWS megatest run that the template needs
and copies the vendored samplesheet into input/:
bash depictio/projects/nf-core/epitopeprediction/3.2.0/download_test_data.sh \
/tmp/epitopeprediction_test
depictio ingest /tmp/epitopeprediction_test \
--template nf-core/epitopeprediction/latest
The run is
s3://nf-core-awsmegatests/epitopeprediction/results-e637bc7c49e6e05a09f5207501a142ec68d8570b/,
the 3.2.0 test_full run: eleven samples on synthetic data that exercise every
input route (six VCFs, a protein FASTA and four peptide tables, two of them
predicted against every supported allele), with MHCflurry, MHCnuggets and
MHCnuggets II, the wide output format and --wild_type. It is a test of the
pipeline, not a cohort.
Additional resources¶
- nf-co.re/epitopeprediction: official pipeline documentation
- nf-co.re/epitopeprediction/results: AWS test results
- Template System Reference: YAML format, variables, conditionals
- Recipes: how to read, test, and write recipes
Authorship¶
weber8thomas
Reviewing a template on your own data, or taking over a role here, is a contribution in itself: the contributing guide says what each one involves.