The PCGR software comes with a range of options to configure the analyses performed and to customize the output report.
Key settings
Below, we will outline key settings that are important with respect to the sequencing assay that has been conducted.
Whole-genome, whole-exome or targeted sequencing assay
By default, PCGR expects that the input VCF comes from whole-exome
sequencing. This can be adjusted with the assay option,
which takes three alternative values:
--assay <WGS|WES|TARGETED>
If the input VCF comes from a targeted sequencing assay/panel
(i.e. --assay TARGETED), the target size of the assay/panel
should be adjusted accordingly, which is critical for tumor mutational
burden estimation. Assay target size, reflecting the protein-coding
portion of the assayed genomic region in megabases, can be
configured through the following option:
--target_size_mb <value>
Tumor-control vs. tumor-only
By default, PCGR expects that the input VCF contains somatic variants identified from a tumor-control sequencing setup. This implies that the VCF contains information with respect to variant allelic depth/support both for the tumor sample and the corresponding control sample.
If the input VCF comes from a tumor-only assay, turn
on the --tumor_only option. In this mode, PCGR conducts a
set of successive filtering steps on the raw input set of variants,
aiming to exclude the majority of germline variants from the tumor-only
input set. In addition to default filtering applied against variants
found in the gnomAD/1000 Genomes Project databases (population-specific
allele frequency thresholds can be configured, see below), additional
filtering procedures can be explicitly set, i.e.:
-
--exclude_dbsnp_nonsomatic(recommended) --exclude_likely_het_germline--exclude_likely_hom_germline--exclude_nonexonic
If the user has provided a panel-of-normals VCF file as
input(--pon_vcf), one may also opt to remove variants found
in that variant collection using a dedicated option:
--exclude_pon
IMPORTANT NOTE 1: A number of the analyses available in PCGR are not particularly well-suited for tumor-only input, e.g. mutational signature analysis and MSI status prediction. IMPORTANT NOTE 2: If you run PCGR on tumor-only WGS assays, we strongly recommend that you pre-filter your VCF against the exome, since we have frequently encountered that the large unfiltered variant set from such assays will cause a crash in PCGR. See also this issue.
Sample properties
A few properties of the tumor sample can be fed to the report, currently only used for display/reporting:
-
--tumor_ploidy <value>- ploidy estimate -
--tumor_purity <value>- purity estimate -
--cell_line- cell line sample
Allelic support
Proper designation of INFO tags in the input VCF that denote variant depth/allelic fraction is critical to make the report as comprehensive as possible. See the input section on how to accomplish this.
Several options are used to inform PCGR about tags in the VCF INFO field that encodes this information:
--tumor_dp_tag <value>--tumor_af_tag <value>--control_dp_tag <value>--control_af_tag <value>--call_conf_tag <value>
If these tags are set correctly, one may set thresholds (sequencing depth and/or allelic fraction) on the variants to be included in the report, i.e. through:
--tumor_dp_min <value>--tumor_af_min <value>--control_dp_min <value>--control_af_max <value>
Tumor site
The primary tissue/site of the tumor sample that is analyzed can and should be be provided, through the following option:
--tumor_site <value>
This option takes a value between 0 and 30, reflecting the main primary sites/tissues for human cancers. Note that the default value is 0 (implies Any tissue/site), which essentially prohibits the presence of tier 1 variants occurring in the report. If you want to check the nature of cancer subtypes attributed to each of the primary tissue/sites, take a look at the table with phenotype terms and associated primary sites.
Large input sets (VCF)
For input VCF files with > 500,000 variants, note that these will be subject to filtering prior to the final step in PCGR (step 4: reporting). For such scenarios, raw input sets will be filtered according to consequence type, in the sense that intergenic/intronic/upstream/downstream gene variants will be excluded prior to reporting. This is a necessary step to avoid memory issues etc. during processing with the PCGR R package.
If you have a large input VCF, and have sufficient memory capacity on
your compute platform, we also recommend to increase the VEP
buffer size (option --vep_buffer_size), as this will
speed up the VEP processing significantly.
All options
A tumor sample report is generated by running the pcgr command, which takes the following arguments and options:
usage:
pcgr -h [options]
--input_vcf <INPUT_VCF>
--pcgr_dir <PCGR_DIR>
--output_dir <OUTPUT_DIR>
--genome_assembly <GENOME_ASSEMBLY>
--sample_id <SAMPLE_ID>
Personal Cancer Genome Reporter (PCGR) workflow for clinical interpretation of somatic nucleotide variants and copy number aberration segments
Required arguments:
--input_vcf INPUT_VCF
VCF input file with somatic variants in tumor sample, SNVs/InDels
--pcgr_dir PCGR_DIR PCGR base directory with accompanying data directory, e.g. ~/pcgr-1.2.0
--output_dir OUTPUT_DIR
Output directory
--genome_assembly {grch37,grch38}
Human genome assembly build: grch37 or grch38
--sample_id SAMPLE_ID
Tumor sample/cancer genome identifier - prefix for output files
vcfanno options:
--vcfanno_n_proc VCFANNO_N_PROC
Number of vcfanno processes (option '-p' in vcfanno), default: 4
VEP options:
--vep_n_forks VEP_N_FORKS
Number of forks (option '--fork' in VEP), default: 4
--vep_buffer_size VEP_BUFFER_SIZE
Variant buffer size (variants read into memory simultaneously, option '--buffer_size' in VEP)
- set lower to reduce memory usage, default: 100
--vep_pick_order VEP_PICK_ORDER
Comma-separated string of ordered transcript/variant properties for selection of primary variant consequence
(option '--pick_order' in VEP), default: canonical,appris,biotype,ccds,rank,tsl,length,mane
--vep_no_intergenic Skip intergenic variants during processing (option '--no_intergenic' in VEP), default: False
--vep_regulatory Add VEP regulatory annotations (option '--regulatory') or non-coding interpretation, default: False
--vep_gencode_all Consider all GENCODE transcripts with Variant Effect Predictor (VEP) (option '--gencode_basic' in VEP is used by default in PCGR).
Tumor mutational burden (TMB) and MSI options:
--target_size_mb TARGET_SIZE_MB
For mutational burden analysis - approximate protein-coding target size in Mb of sequencing assay (default: 34 (WES/WGS))
--estimate_tmb Estimate tumor mutational burden from the total number of somatic mutations and target region size, default: False
--estimate_msi_status
Predict microsatellite instability status from patterns of somatic mutations/indels, default: False
--tmb_algorithm {all_coding,nonsyn}
Method for calculation of TMB, all coding variants (Chalmers et al., Genome Medicine, 2017), or non-synonymous variants only, default: all_coding
Mutational signature options:
--estimate_signatures
Estimate relative contributions of reference mutational signatures in query sample and detect potential kataegis events, default: False
--min_mutations_signatures MIN_MUTATIONS_SIGNATURES
Minimum number of SNVs required for reconstruction of mutational signatures (SBS) by MutationalPatterns (default: 200, minimum n = 100)
--all_reference_signatures
Use all reference mutational signatures (SBS, n = 67) in signature reconstruction rather than only those already attributed to the tumor type (default: False)
--include_artefact_signatures
Include sequencing artefacts in the collection of reference signatures (default: False
--prevalence_reference_signatures {1,2,5,10,15,20}
Minimum tumor-type prevalence (in percent) of reference signatures to be included in refitting procedure (default: 5)
Tumor-only options:
--tumor_only Input VCF comes from tumor-only sequencing, calls will be filtered for variants of germline origin, (default: False)
--cell_line Input VCF comes from tumor cell line sequencing (requires --tumor_only), calls will be filtered for variants of germline origin, (default: False)
--pon_vcf PON_VCF VCF file with germline calls from Panel of Normals (PON) - i.e. blacklisted variants, (default: None)
--maf_onekg_eur MAF_ONEKG_EUR
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - European pop, default: 0.002)
--maf_onekg_amr MAF_ONEKG_AMR
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - Ad Mixed American pop, default: 0.002)
--maf_onekg_afr MAF_ONEKG_AFR
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - African pop, default: 0.002)
--maf_onekg_eas MAF_ONEKG_EAS
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - East Asian pop, default: 0.002)
--maf_onekg_sas MAF_ONEKG_SAS
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - South Asian pop, default: 0.002)
--maf_onekg_global MAF_ONEKG_GLOBAL
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (1000 Genomes Project - global pop, default: 0.002)
--maf_gnomad_nfe MAF_GNOMAD_NFE
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - European (non-Finnish), default: 0.002)
--maf_gnomad_asj MAF_GNOMAD_ASJ
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - Ashkenazi Jewish, default: 0.002)
--maf_gnomad_fin MAF_GNOMAD_FIN
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - European (Finnish), default: 0.002)
--maf_gnomad_oth MAF_GNOMAD_OTH
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - Other, default: 0.002)
--maf_gnomad_amr MAF_GNOMAD_AMR
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - Latino/Admixed American, default: 0.002)
--maf_gnomad_afr MAF_GNOMAD_AFR
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - African/African-American, default: 0.002)
--maf_gnomad_eas MAF_GNOMAD_EAS
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - East Asian, default: 0.002)
--maf_gnomad_sas MAF_GNOMAD_SAS
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - South Asian, default: 0.002)
--maf_gnomad_global MAF_GNOMAD_GLOBAL
Exclude variants in tumor (SNVs/InDels, tumor-only mode) with MAF > pct, (gnomAD - global population, default: 0.002)
--exclude_pon Exclude variants occurring in PoN (Panel of Normals, if provided as VCF (--pon_vcf), default: False)
--exclude_likely_hom_germline
Exclude likely homozygous germline variants (100 pct allelic fraction for alternate allele in tumor, very unlikely somatic event, default: False)
--exclude_likely_het_germline
Exclude likely heterozygous germline variants (40-60 pct allelic fraction, AND presence in dbSNP + gnomAD, AND not existing as somatic event in COSMIC/TCGA, default: False)
--exclude_dbsnp_nonsomatic
Exclude variants found in dbSNP (only those that are NOT found in ClinVar(somatic origin)/DoCM/TCGA/COSMIC, defult: False)
--exclude_nonexonic Exclude non-exonic variants, default: False)
Allelic support options:
--tumor_dp_tag TUMOR_DP_TAG
Specify VCF INFO tag for sequencing depth (tumor, must be Type=Integer, default: _NA_
--tumor_af_tag TUMOR_AF_TAG
Specify VCF INFO tag for variant allelic fraction (tumor, must be Type=Float, default: _NA_
--control_dp_tag CONTROL_DP_TAG
Specify VCF INFO tag for sequencing depth (control, must be Type=Integer, default: _NA_
--control_af_tag CONTROL_AF_TAG
Specify VCF INFO tag for variant allelic fraction (control, must be Type=Float, default: _NA_
--call_conf_tag CALL_CONF_TAG
Specify VCF INFO tag for somatic variant call confidence (must be categorical, e.g. Type=String, default: _NA_
--tumor_dp_min TUMOR_DP_MIN
If VCF INFO tag for sequencing depth (tumor) is specified and found, set minimum required depth for inclusion in report (default: 0)
--tumor_af_min TUMOR_AF_MIN
If VCF INFO tag for variant allelic fraction (tumor) is specified and found, set minimum required AF for inclusion in report (default: 0)
--control_dp_min CONTROL_DP_MIN
If VCF INFO tag for sequencing depth (control) is specified and found, set minimum required depth for inclusion in report (default: 0)
--control_af_max CONTROL_AF_MAX
If VCF INFO tag for variant allelic fraction (control) is specified and found, set maximum tolerated AF for inclusion in report (default: 1)
Other options:
--input_cna INPUT_CNA
Somatic copy number alteration segments (tab-separated values)
--logr_gain LOGR_GAIN
Log ratio-threshold (minimum) for segments containing copy number gains/amplifications (default: 0.8)
--logr_homdel LOGR_HOMDEL
Log ratio-threshold (maximum) for segments containing homozygous deletions (default: -0.8)
--cna_overlap_pct CNA_OVERLAP_PCT
Mean percent overlap between copy number segment and gene transcripts for reporting of gains/losses in tumor suppressor genes/oncogenes, (default: 50)
--tumor_site TSITE Optional integer code to specify primary tumor type/site of query sample,
choose any of the following identifiers:
0 = Any
1 = Adrenal Gland
2 = Ampulla of Vater
3 = Biliary Tract
4 = Bladder/Urinary Tract
5 = Bone
6 = Breast
7 = Cervix
8 = CNS/Brain
9 = Colon/Rectum
10 = Esophagus/Stomach
11 = Eye
12 = Head and Neck
13 = Kidney
14 = Liver
15 = Lung
16 = Lymphoid
17 = Myeloid
18 = Ovary/Fallopian Tube
19 = Pancreas
20 = Peripheral Nervous System
21 = Peritoneum
22 = Pleura
23 = Prostate
24 = Skin
25 = Soft Tissue
26 = Testis
27 = Thymus
28 = Thyroid
29 = Uterus
30 = Vulva/Vagina
(default: 0 - any tumor type)
--tumor_purity TUMOR_PURITY
Estimated tumor purity (between 0 and 1) (default: None)
--tumor_ploidy TUMOR_PLOIDY
Estimated tumor ploidy (default: None)
--cpsr_report CPSR_REPORT
CPSR report file (Gzipped JSON - file ending with 'cpsr.<genome_assembly>.json.gz' - germline report of patient's blood/control sample
--vcf2maf Generate a MAF file for input VCF using https://github.com/mskcc/vcf2maf (default: False)
--show_noncoding List non-coding (i.e. non protein-altering) variants in report, default: False
--assay {WES,WGS,TARGETED}
Type of DNA sequencing assay performed for input data (VCF) default: WES
--include_trials (Beta) Include relevant ongoing or future clinical trials, focusing on studies with molecularly targeted interventions
--preserved_info_tags PRESERVED_INFO_TAGS
Comma-separated string of VCF INFO tags from query VCF that should be kept in PCGR output TSV file
--report_theme {default,cerulean,journal,flatly,readable,spacelab,united,cosmo,lumen,paper,sandstone,simplex,yeti}
Visual report theme (rmarkdown)
--report_nonfloating_toc
Do not float the table of contents (TOC) in output report (rmarkdown), default: False
--force_overwrite By default, the script will fail with an error if any output file already exists. You can force the overwrite of existing result files by using this flag, default: False
--version show program's version number and exit
--basic Run functional variant annotation on VCF through VEP/vcfanno, omit other analyses (i.e. Tier assignment/MSI/TMB/Signatures etc. and report generation (STEP 4), default: False
--no_vcf_validate Skip validation of input VCF with Ensembl's vcf-validator, default: False
--debug Print full commands to log
--pcgrr_conda PCGRR_CONDA
pcgrr conda env name (default: pcgrr)Example run
The examples folder contains input VCF files from two tumor samples sequenced within TCGA (GRCh37 only). A report for a colorectal tumor case can be generated by running the following command in your terminal window:
$ (base) conda activate pcgr
$ (pcgr)
pcgr \
--pcgr_dir /Users/you/dir2/data \
--output_dir /Users/you/dir3/pcgr_outputs \
--sample_id tumor_sample.COAD \
--tumor_dp_tag TDP \
--tumor_af_tag TVAF \
--call_conf_tag TAL \
--genome_assembly grch37 \
--input_vcf /Users/you/pcgr/examples/tumor_sample.COAD.vcf.gz \
--tumor_site 9 \
--input_cna /Users/you/pcgr/examples/tumor_sample.COAD.cna.tsv \
--tumor_purity 0.9 \
--tumor_ploidy 2.0 \
--include_trials \
--assay WES \
--estimate_signatures \
--estimate_msi_status \
--estimate_tmb \
--force_overwriteThis command will run the Conda-based PCGR workflow and produce the following files in the examples folder:
| N | File | Description |
|---|---|---|
| 1 | pcgr_acmg.grch37.html | An interactive HTML report for clinical interpretation (rmarkdown) |
| 2 | pcgr_acmg.grch37.flexdb.html | An interactive HTML report for clinical interpretation (flexdashboard) |
| 3 | pcgr_acmg.grch37.vcf.gz (.tbi) | Bgzipped VCF file with rich set of annotations for precision oncology |
| 4 | pcgr_acmg.grch37.pass.vcf.gz (.tbi) | Bgzipped VCF file with rich set of annotations for precision oncology (PASS variants only) |
| 5 | pcgr_acmg.grch37.pass.tsv.gz | Compressed vcf2tsv-converted file with rich set of annotations for precision oncology |
| 6 | pcgr_acmg.grch37.snvs_indels.tiers.tsv | Tab-separated values file with variants organized according to tiers of functional relevance |
| 7 | pcgr_acmg.grch37.mutational_signatures.tsv | Tab-separated values file with information on contribution of mutational signatures |
| 8 | pcgr_acmg.grch37.json.gz | Compressed JSON dump of HTML report content |
| 9 | pcgr_acmg.grch37.cna_segments.tsv.gz | Compressed tab-separated values file with annotations of gene transcripts that overlap with somatic copy number aberrations |
| 10 | pcgr_config.rds | PCGR configuration object (RDS format), mostly for debugging purposes |