SMART
Somatic Mutation Annotation and Reporting Tool
A Dockerised pipeline for somatic variant annotation, filtration, and clinical reporting — from raw VCF to audience-targeted output in a single command.
Somatic Mutation Annotation and Reporting Tool
A Dockerised pipeline for somatic variant annotation, filtration, and clinical reporting — from raw VCF to audience-targeted output in a single command.
SMART automates the end-to-end processing of somatic VCF files generated by cancer sequencing panels (e.g. TSO500). Starting from raw VCFs in hg19/GRCh37 or GRCh38 coordinates, it performs PASS filtering, optional coordinate liftover, comprehensive functional annotation via Ensembl VEP 114, and clinical annotation via the OncoKB REST API. Results are delivered in three audience-targeted output files.
Everything runs inside a single Docker container — no local installation
of VEP, GATK, or OncoKB is required. A single docker run
command takes you from raw VCF to clinical report.
VEP, GATK, bcftools, Python, and the OncoKB annotator all run inside a single container. No local installs, reproducible across machines.
Clinical TSV (77 fields), bioinformatics TSV (670 fields), and full MAF (1,000+ fields). Each audience gets exactly what they need.
A curated NM whitelist ensures VEP annotation and OncoKB queries use the same clinically relevant transcript. MANE Select used as fallback.
Variants overlapping multiple preferred isoforms (e.g. CDKN2A p16/INK4a & p14ARF) produce one row per transcript with independent OncoKB evidence.
Therapeutic (LEVEL_1–4, R1–R2), diagnostic (Dx1–3), prognostic (Px1–2), and FDA levels. Drug names and tumour types structured as indexed columns.
Four integration suites (field-level API check, caller compatibility, transcript prioritisation impact, parallel processing) plus 161 unit tests.
Every pipeline run produces three files from a single post-analysis step. Column counts scale with OncoKB evidence — runs with more variants across more tumour types produce more expanded JSON columns.
77 curated fields for clinical scientists. Variant identity, consequence, top-line OncoKB actionability, ClinVar, CancerHotspots, and pathogenicity scores. Two-row header (field names + source metadata).
670 fields for bioinformaticians. Extends Tier 3 with full gnomAD stratification, all SpliceAI delta scores, complete CIViC annotation, and every OncoKB JSON expansion (ONCOKB_TX_*, ONCOKB_DIAG_*).
1,000+ fields in standard MAF format. All non-dropped fields for downstream tools: cBioPortal, oncoPrint generators, R/Python analysis pipelines.
bash utils/get_ref_files.sh to download the VEP cache, SpliceAI scores,
REVEL, ClinVar, CIViC, gnomAD constraints, CancerHotSpots, and the GRCh38 reference genome
(~200 GB total).
git clone https://github.com/Manuel-DominguezCBG/SMART.git && cd SMARTdocker build -t smart:latest .
data/OriginalVcf/ and copy your transcript whitelist
(e.g. TSO500_transcript_MANE.txt) into data/.
export ONCOKB_TOKEN=your_token_heredocker run --rm -v $(pwd):/data -v /path/to/refs:/refs monkiky/smart:latest "$ONCOKB_TOKEN" --transcripts-file /data/transcripts.txt --config /data/Config.yaml --ref-dir /refs
/data directory under
Output_Results/. See the full documentation
for all command-line options.
When a variant overlaps more than one preferred transcript (e.g. CDKN2A p16/INK4a and p14ARF), the pipeline now produces one output row per matching transcript, each with independent VEP annotation and OncoKB evidence level.
Omitting the OncoKB token now automatically activates VEP-only mode. The pipeline runs through VEP annotation and stops, producing annotated VCFs without requiring an OncoKB account.
The --jobs N flag runs up to N samples concurrently on a single machine, reducing wall-clock time for multi-sample runs.
MafAnnotator incorrectly overwrote CNA oncogenicity with Unknown. Post-analysis now overrides MafAnnotator output for CNA rows using values from the OncoKB API directly.
End-to-end Dockerised pipeline: PASS filter → LiftOver → VEP → OncoKB → vcf2table → MafAnnotator → post-analysis with three output tiers.
18 variants · 22 output rows · 3 tiers · colour-coded OncoKB levels · searchable & sortable
If you use SMART in your research, please cite:
SMART integrates annotations from Ensembl VEP, OncoKB, CIViC, ClinVar, gnomAD, SpliceAI, REVEL, and CancerHotspots. Please also cite those resources as appropriate.