Skip to contents

Input files

Source: vignettes/input.Rmd
input.Rmd

Input files

The PCGR workflow accepts the following main input files:

  • An unannotated, single-sample VCF file (>= v4.2) with called somatic variants (SNVs/InDels)
  • A file with allele-specific copy number segments (tab-separated values - TSV)
  • A file with RNA fusion transcripts detected in the tumor (tab-separated values - TSV)
  • A file with transcript/gene expression levels (tab-separated values - TSV)

At least one of these input files is required. PCGR can be run with any combination of the above, and will only produce output sections relevant to the data provided. The following arguments to the pcgr command are used for input files:

  • --input_vcf
  • --input_cna
  • --input_rna_fusion
  • --input_rna_expression

In addition to these main input files, the user can also opt to provide a panel-of-normals VCF file (--pon_vcf) for tumor-only variant filtering, as well as an input file with CPSR-classified germline variants (TSV) (--input_cpsr).

VCF

  • We strongly recommend that the input VCF is compressed and indexed using bgzip and tabix
  • If the input VCF contains multi-allelic sites, these will be subject to decomposition. Either way, we encourage that users prepare the input VCF without the presence of multi-allelic sites.
  • Variants used for reporting should be designated as PASS in the VCF FILTER column. Variants denoted with e.g. Reject as a FILTER value will not be subject to analysis in PCGR. For records with undefined values in the FILTER column ('.'), these will be considered as PASS variants.

Formatting of variant sequencing depth/allelic support (DP/AF)

The representation of variant genotype data (allelic depth and support in tumor vs. control sample) is usually formatted in the genotype fields of a VCF file, on a per-sample basis. However, considering the VCF output for the numerous somatic SNV/InDel callers that are in use, we have experienced a general lack of uniformity for how this information is encoded in the genotype fields. In order for PCGR to recognize this type of information robustly, we currently require that you as a user encode this unambiguously in the INFO field of your VCF file.

Shown below is how the VCF header for these entries should look like in your input VCF, and how the corresponding variant data is encoded per record:

VCF header

##INFO=<ID=TVAF,Number=.,Type=Float,Description="Allelic fraction of alternative allele in tumor">
##INFO=<ID=TDP,Number=.,Type=Integer,Description="Read depth across variant site in tumor">

VCF records

#CHROM  POS ID  REF ALT QUAL    FILTER  INFO
1       23519660        .       G       C       .       PASS    TVAF=0.0980;TDP=51

When you run PCGR, make sure to feed the name of the INFO tags to the tool, i.e. using the tumor_dp_tagand tumor_af_tag options:

pcgr --tumor_dp_tag TDP --tumor_af_tag TVAF

As an effort to support the users with this procedure, we are hoping to establish a VCF pre-processing script, that accepts any VCF (from any caller), and that will ensure that the file adheres to the formatting requirements of PCGR. See also this issue.

Other notes regarding input VCF

  • PCGR generates a number of VCF INFO annotation tags that are appended to the query VCF. We therefore encourage the users to submit query VCF files that have not been subject to annotations by other means, but rather a VCF file that comes directly from variant calling. If not, there are likely to be INFO tags in the query VCF file that coincide with those produced by PCGR.
  • Note that you can preserve particular tags in the INFO field towards the TSV output of PCGR. Sometimes, it can be convenient to investigate particular properties of the variants (encoded in the VCF) against functional annotations (as provided by PCGR). To achieve this, use the option --retained_info_tags <TAG1>,<TAG2> etc.

Panel-of-normals VCF

The user can submit a panel-of-normals (PoN) VCF file to PCGR, indicating variants that should be excluded/filtered from the input VCF in a tumor-only setting (i.e. option --tumor_only).

  • --pon_vcf <VCF_FILE>

The PoN VCF file needs to contain the following.

  1. The following description needs to be present in the VCF header:
##INFO=<ID=PANEL_OF_NORMALS,Number=0,Type=Flag,Description="Overlap with germline call among panel of normals">
  1. Each record in the PoN VCF file needs to contain the PANEL_OF_NORMALS flag in the INFO field

Copy number segments - allele-specific

A tab-separated values file with allele-specific copy number aberrations MUST contain the following four columns:

  • Chromosome
  • Start
  • End
  • nMajor
  • nMinor

Here, Chromosome, Start, and End denote the chromosomal segment, while nMajor and nMinor denote major and minor copy number for particular segment, a standard output of somatic copy number alteration callers. Note that coordinates must be one-based (i.e. chromosomes start at 1, not 0), and that copy numbers should be formatted as whole integers, not floating values. Below shows the initial part of a copy number segment file that is formatted correctly according to PCGR’s requirements:

  Chromosome    Start   End nMajor nMinor
  1 3218329 3550598 1 0
  1 3552451 4593614 1 1
  1 4593663 6433129 2 1

Optionally, the file may contain a column nMajor_nMinor_Imputed (values TRUE/FALSE, or 1/0), flagging segments where the total copy number is observed, but the split into major and minor copy number is imputed (e.g. by a downstream rescue step for segments that the allele-specific caller left unresolved). If the column is absent, no segments are considered imputed. Imputed segments are handled as follows:

  • total copy number-based analyses (amplification/gain/deletion calls, fraction of genome altered, tumor ploidy estimation) use them as any other segment
  • loss-of-heterozygosity (LOH) is not called for imputed segments (and they are thus not considered for two-hit candidates)
  • they are excluded from the whole-genome doubling call, and from the autosomal segment coverage requirement of --estimate_hrd
  • for the HRD scores (--estimate_hrd), they are treated as segments of unknown allele-specific state (rather than being dropped, which would make their neighbouring segments adjacent): they are never merged with their neighbours, and never counted as LOH/allelic imbalance or as part of a state transition
  • they are flagged in the output (CN_MAJOR_MINOR_IMPUTED) and drawn with a lighter minor copy number track in the copy number profile plot of the report

Importantly, you can configure predefined thresholds for segments that are considered to be high-level copy-number amplifications through the following option:

  • --n_copy_gain: minimum (total) copy number for a segment to be considered an amplification, default 6

Germline variants

The user can submit a file with germline variants processed and classified with CPSR, which caters for an integration of germline and somatic findings in the output report. This file corresponds to output file <sample_id>.cpsr.<genome_assembly>.classification.tsv.gz from the CPSR pipeline. Make sure the genome assembly is the same as the one used for the somatic variant input files.

RNA fusions

The user can submit a file with RNA fusion transcripts detected in the tumor sample. PCGR will cross-reference detected fusions against curated cancer gene databases and known fusion events, and incorporate them into the output report.

The tab-separated values file with RNA fusion calls MUST contain the following four columns:

Column Type Description
FusionGene string Fusion gene pair, two gene symbols separated by -- or :: (e.g. EML4--ALK or TMPRSS2::ERG)
LeftBreakpoint string Genomic position of the left/5’ breakpoint, formatted as chrom:position (e.g. 2:42522694)
RightBreakpoint string Genomic position of the right/3’ breakpoint, formatted as chrom:position (e.g. 2:29446394)
SplitReads integer Number of split reads supporting the fusion (non-negative integer)

An optional column Score (float) may also be included, representing a caller-specific confidence score for the fusion event.

Formatting notes

  • The chromosome field in breakpoints must be one of 1–22, X, or Y — with or without a chr prefix
  • Each gene symbol in FusionGene must be a valid alphanumeric identifier (letters, digits, ., -, _ allowed); purely numeric gene names are not accepted
  • Fusions with an empty or missing partner (e.g. intragenic or read-through events) are allowed but will generate a warning during validation

Below shows the first few records of a correctly formatted RNA fusion file:

FusionGene       LeftBreakpoint    RightBreakpoint   SplitReads
EML4--ALK        2:42522694        2:29446394        100
BCR--ABL1        22:23582899       9:13358994        50
EWSR1--FLI1      22:29683136       11:128675244      75
TMPRSS2--ERG     21:42836478       21:39737961       60
Quality control of RNA fusion events: We strongly advice users to to perform quality control of fusion events upstream of PCGR analysis - the focus in PCGR is strictly on functional annotation and potential clinical impact.
  • We recommend to carefully check e.g. the number of supporting reads for each fusion event, and to visually inspect fusion events in a genome browser (e.g. IGV) or other third-party tools (e.g. FusViz) to conduct frame inference, investigate domain retention, and rule out potential false positives.
  • Importantly, while most RNA fusion detection tools will attempt to filter out known normal/artefactual events, PCGR makes no attempt to further filter fusion events based on e.g. presence in normal tissue databases, and thus relies on the user to perform this step upstream of PCGR analysis.
  • If multiple input entries share the same gene pair (e.g. GENE_A–GENE_B) but differ only in their exact breakpoint coordinates, each will appear as a separate entry in the PCGR report. This can make the fusion section appear repetitive. PCGR does not attempt to collapse these, as there is no principled way to select a canonical breakpoint without the full caller context. We therefore recommend that users deduplicate fusion calls to one entry per gene pair — retaining the call with the highest read support or confidence score — before submitting to PCGR.

MSI result from an external caller

If microsatellite instability (MSI) has been assessed with a dedicated MSI caller, the result can be provided as an alternative (or addition) to the MSI classifier in PCGR (--estimate_msi):

  • --input_msi <FILE>: the summary result file of the MSI caller for the tumor sample
  • --input_msi_caller <CALLER>: the caller that produced the file (msisensor-pro or generic; default: generic)
  • --input_msi_threshold <PERCENT>: threshold on the MSI score for MSI-H, only for callers that report a score but no MSI status (currently msisensor-pro; default: 20)

The file name and extension are not used - the content of the file is checked. In contrast to --estimate_msi, an external MSI result can be used with any type of sequencing assay (including tumor-only and targeted panel data), and does not require a VCF file. Two formats are supported: the generic format (any MSI caller) and the summary file of MSIsensor-pro.

Generic format

The generic format is a tab-separated file with a header line and exactly one data row (one sample). Only two columns are required, so the smallest valid file is:

MSI_STATUS MSI_CALLER
MSI-H MyCaller

Optional columns provide further information that is shown in the report and in the output files:

Column Required Description
MSI_STATUS yes MSI status of the tumor sample, see accepted values below
MSI_CALLER yes Name of the MSI caller
CALLER_VERSION no Version of the MSI caller
MSI_SCORE no Numeric score, as reported by the caller
MSI_SCORE_TYPE no Description of the score, e.g. percent unstable sites
MSI_SCORE_THRESHOLD_USED no Threshold on the score applied by the caller for MSI-H
N_LOCI_EVALUATED no Number of microsatellite loci evaluated
N_LOCI_UNSTABLE no Number of unstable microsatellite loci

A file with all columns could look like this (columns shown as a table; the file itself is tab-separated):

MSI_STATUS MSI_CALLER CALLER_VERSION MSI_SCORE MSI_SCORE_TYPE MSI_SCORE_THRESHOLD_USED N_LOCI_EVALUATED N_LOCI_UNSTABLE
MSI-H MANTIS 1.0.5 0.52 step-wise difference 0.4

Further rules:

  • Accepted values for MSI_STATUS (not case-sensitive) are listed below. Other values give an error.
  • The score, threshold and loci columns are for information only: they are reported as given, and never change the MSI_STATUS.
  • Missing values of optional columns can be left empty or set to . or NA.
  • Additional columns are ignored.
Value in file Interpreted as
MSI-H, MSIH, MSI-High, MSI, Unstable MSI-H
MSS, Stable, MSI-L, MSIL, MSI-Low MSS (note that MSI-L is regarded as microsatellite stable)
Indeterminate, Undetermined, Equivocal, Inconclusive, Unknown Indeterminate

MSIsensor-pro

Use --input_msi_caller msisensor-pro for the main summary file (not the _all, _unstable or _dis files) written by the msisensor-pro pro (tumor-only) or msisensor-pro msi (tumor-normal) command. It has a header line (Total_Number_of_Sites, Number_of_Unstable_Sites, %) and a single data row. MSIsensor-pro does not report an MSI status. The status is therefore derived by PCGR from the percentage of unstable sites: MSI-H if the percentage is at or above the threshold (default 20, see below), otherwise MSS (and Indeterminate if no sites were evaluated). The report indicates that the status was derived, and which threshold was used.

Threshold for MSI-H

For the generic format, the MSI status given by the caller is used as is. The threshold on the score is only applied for a caller that reports a score but no status (MSIsensor-pro), where PCGR derives the status from the score. Practice for the threshold varies (e.g. with the sequencing assay, tumor-only versus tumor-normal analysis, and how conservative the call should be). PCGR therefore uses a default (20% unstable sites for MSIsensor-pro), which can be changed with --input_msi_threshold. The threshold is shown in the report and in the output files, and it determines whether MSI-High biomarker evidence is shown. The option cannot be used with callers that report their own status; for a different decision rule, convert the result to the generic format with the status of your choice.

Combining with the MSI classifier

If both --input_msi and --estimate_msi are used, the report shows the two results side by side (tabs External caller and PCGR classifier) and indicates if they are discordant. The external result takes precedence for the assessment of MSI-High biomarker evidence.

HRD result from an external assay/tool

If homologous recombination deficiency (HRD) has been assessed with a dedicated HRD assay or tool (e.g. a genomic instability score from an SNP panel, or a mutational signature-based classifier), the result can be provided to PCGR, as an alternative (or addition) to the genomic scar score estimated by PCGR from the copy number segments (--estimate_hrd):

  • --input_hrd <FILE>: the HRD result for the tumor sample (format below)
  • --input_hrd_threshold <SCORE>: threshold on the score (HRD_SCORE) at or above which the tumor is classified as HR-deficient (see below)

The file name and extension are not used - the content of the file is checked. An external HRD result can be used with any type of sequencing assay (including tumor-only and targeted panel data), and does not require copy number data.

Format

A tab-separated file with a header line and a single data row (one sample). Minimal examples, with an HRD status reported by the assay/tool, or with a score only (status derived by PCGR with --input_hrd_threshold):

HRD_CALLER HRD_SCORE_TYPE HRD_STATUS
MyAssay genomic_scar HR-deficient
HRD_CALLER HRD_SCORE_TYPE HRD_SCORE
HiSNP Ultra genomic_scar 47
Column Required Description
HRD_CALLER yes Name of the HRD assay/tool
HRD_SCORE_TYPE yes Kind of HRD score, see the categories below
HRD_STATUS yes, unless HRD_SCORE is given HRD status of the tumor sample, see accepted values below
HRD_SCORE yes, unless HRD_STATUS is given Numeric score, as reported by the assay/tool (higher values indicating HR deficiency)
CALLER_VERSION no Version of the HRD assay/tool
HRD_SCORE_DESCRIPTION no Description of the score, e.g. GIS (HRD-LOH + LST + TAI) or probability of HRD
HRD_SCORE_THRESHOLD_USED no Threshold on the score applied by the assay/tool for HRD_STATUS
HRD_LOH, HRD_LST, HRD_TAI no Genomic scar components (counts), if reported

A full example:

HRD_CALLER HRD_SCORE_TYPE HRD_STATUS HRD_SCORE CALLER_VERSION HRD_SCORE_DESCRIPTION HRD_SCORE_THRESHOLD_USED HRD_LOH HRD_LST HRD_TAI
MyAssay genomic_scar HR-deficient 47 1.2 GIS (HRD-LOH + LST + TAI) 42 15 20 12

Additional columns are ignored, and missing optional values may be left empty or set to ./NA.

Score types

‘HRD’ covers measurements of different kinds, on different scales. PCGR does not infer the kind of score - it is stated with HRD_SCORE_TYPE, and shown in the report (values are not case-sensitive):

HRD_SCORE_TYPE Kind of score Examples
genomic_scar Genomic scar score from copy number/allelic imbalance profiles Genomic instability score (HRD-LOH + LST + TAI, e.g. Myriad myChoice CDx, scarHRD), genome-wide LOH
mutational_signature Classifier based on mutational patterns CHORD, SigMA
composite Model combining genomic scars and mutational signatures HRDetect
other Other or proprietary scores

HRD status

Accepted values for HRD_STATUS (not case-sensitive) are listed below. Other values give an error.

Value(s) Interpreted as
HR-deficient, Deficient, HRD, HRD-positive, HRD+, Positive HR-deficient
HR-proficient, Proficient, HRP, HRD-negative, HRD-, Negative HR-proficient
Indeterminate, Undetermined, Equivocal, Inconclusive, Unknown, Borderline Indeterminate

Threshold for HR deficiency

Thresholds for HR deficiency are specific to the assay/tool (and often to the tumor type, e.g. a genomic instability score of 42 or above for the Myriad myChoice CDx assay in ovarian cancer), so PCGR has no default threshold, and the user is responsible for the threshold used:

  • without --input_hrd_threshold, the HRD_STATUS given in the file is used as is (the file must then have an HRD_STATUS)
  • with --input_hrd_threshold, the status is derived from HRD_SCORE (required): HR-deficient if the score is at or above the threshold, otherwise HR-proficient. An HRD_STATUS in the file is then not used (a warning is given if it differs from the derived status)

The report indicates how the status was obtained, and which threshold was used.

Combining with the PCGR genomic scar score

If both --input_hrd and --estimate_hrd are used, the report shows the two results side by side (tabs External assay/tool and PCGR genomic scar score). The two are not compared: even two genomic scar scores may differ in definition, scale and calibration, so the threshold of the external assay/tool does not apply to the PCGR score. The external HRD result is not (yet) used for the assessment of biomarker evidence.

Gene expression

The user can submit a file with bulk gene/transcript expression data to PCGR, indicating the relative expression levels of genes in the query sample. PCGR may conduct an expression outlier analysis (compared against other cohorts of samples), and also perform an RNA expression similarity analysis, i.e. correlation of expression profile with other tumor samples.

The tab-separated values file with gene expression estimates MUST contain the following two columns:

  • TargetID
  • TPM

The TPM column indicates the expression level of a given target, and must be provided as Transcripts per million (not log-transformed), a relatively common output measure from bulk RNA-seq pipelines. The TargetID should list transcript or gene identifiers, preferably at the transcript level. Permitted identifier types including Ensembl/RefSeq identifiers for transcript-level expression estimates, and gene symbols and Ensembl gene identifiers for gene-level expression estimates.