ANNOTATION SUITE FOR GENIE

Usage:

bash annotation_suite_wrapper.sh

    -i | --input-directory               input data directory for processing mutation data files
    -o | --output-directory              output directory to write processed and annotated mutation data files to
    -m | --merged-mutation-file          path to write the merged mutation file for the center
    -c | --center-name                   name of the center being processed
    -s | --sequence-source               name of the sequence source used by the center (i.e., WXS, WGS)
    -p | --annotation-scripts-home       path to the annotation suite scripts directory

Arguments

Input Directory ( -i | --input-directory ) : This is the input directory where the unprocessed MAFs and/or VCFs can be found.

Output Directory ( -o | --output-directory ) : This is the output directory where the processed (standardized) MAFs and annotated MAFs will be written. Sub-directories within the output directory will hold the standardized MAFs and annotated MAFs. These sub-directories will be created if they do not already exist. Any existing files within the output-directory and subdirectories will be deleted when this script is run.

The standardized MAFs generated by vcf2maf.py and maf2maf.py will be written to ${OUTPUT_DATA_DIRECTORY}/processed. The annotated MAFs from running the Genome Nexus annotation pipeline will be written to ${OUTPUT_DATA_DIRECTORY}/annotated.

Merged Mutation File ( -m | --merged-mutation-file ) : This is the filepath of the final (standardized and annotated) MAF. The annotation suite wrapper will call merge_mafs.py with the argument --input-mafs-directory that points to an input directory containing the annotated MAF(s) - within the scope of the annotation suite, this input directory will be ${OUTPUT_DATA_DIRECTORY}/annotated.

Center Name ( -c | --center-name ) : This is the center name to be used when standardizing the unprocessed MAF(s) and VCF(s). All records in all output MAFs will have the entered value set in the "Center" column.

Sequence Source ( -s | --sequence-source ) : The sequence source is a required field for a standard MAF as defined by the TCGA project. Accepted values are either WGS and WXS. For GENIE, WXS is used since GENIE samples are sequenced with targeted gene panels.

Annotation Suite Scripts Directory ( -p | --annotation-scripts-home ) : needs to point to the directory where the packaged Genome Nexus Annotation Pipeline JAR and annotation suite python scripts and data files are located:

• merge_mafs.py (located in this repository)
• vcf2maf.py (located in this repository)
• maf2maf.py (located in this repository)
• annotator.jar - The genome nexus annotation pipeline (See how to build the jar file here)
• application.properties (optional) - custom properties for the annotation pipeline. The common use case is to specify custom genome nexus url with genomenexus.base property.
• AwsSsl.truststore - custom trust store. Used to hold an ssl certificate (aka HTTPS certificate) of trusted websites. In our case the trust store holds certificates of custom genome nexus instance. See how to create trust store and upload the certificate here.

Create a trust store

Create an empty trust store with the following command:

keytool -noprompt \
    -genkey -alias secure-key \
    -dname "CN=annotation-tools" \
    -storepass annotation-tools \
    -keypass annotation-tools \
    -keyalg RSA -keystore AwsSsl.truststore

You can export .cer file for your custom genome nexus using browser. There are multiple articles in the internet for different browsers and operating systems.

After you have the .cer file, you can import it to the trust store with the command like the following (replace CERTFILENAME with the file name of your certificate):

keytool -import -noprompt \
    -trustcacerts \
    -alias CERTFILENAME \
    -file CERTFILENAME.cer \
    -keystore AwsSsl.truststore \
    -storepass annotation-tools

Install Python packages

You need to have python3 installed.

pip install -r requirements.txt

You might want to create a virtual envirounment first instead of installing packages globally.

Run scripts example

Here is an example of how to run scripts from the repositroy directory:

./annotation_suite_wrapper.sh --input-directory=/data/vcfs/ --output-directory=/data/maf/ --merged-mutation-file=/data/merged.maf --center-name=CTR --sequence-source=WGS --annotation-scripts-home=$(pwd)

Merging standardized and annotated MAFs from multiple centers

This suite of tools was designed with the AACR Project GENIE in mind, which receives mutation data from multiple centers. This annotation suite wrapper tool was designed such that it will need to be run indidvidually for each center to generate a per-center MAF that has been standardized and annotated with Genome Nexus. These per-center MAFs can be merged to generate a single GENIE project MAF with one of the existing tools provided: merge_mafs.py

The MAF merging script supports two different input arguments for merging MAFs: (1) a comma-delimited list of MAF filenames and (2) an input directory containing all MAFs to be merged. Option (2) is used by the annotation_suite_wrapper.sh to generate a per-center MAF. Option (1) was added to facilitate the merge of the individual per-center MAFs to generate the final single MAF for GENIE that will be imported into the cBioPortal.

Germline files

If "germline" is in the filename then vcf2maf.py and maf2maf.py will assume that the file contains germline data. This will set the value in the output MAF Mutation_Status column to "GERMLINE". Please follow this naming convention if the mutation data file(s) are germline data.

VCF to MAF Conversion Tool

VCF is a standard text file format for storing variation data. It contains meta-information lines, a header line, and then data lines each containing information about a position in the genome.

Mutation Annotation Format (MAF) is a tab-delimited text file with aggregated mutation information from VCF Files.

vcf2maf.py can be used as a standalone tool to convert a VCF file to a Mutation Annotation Format (MAF) file.

Usage:

python3 vcf2maf.py --help

  -i | --input-data             A list of .vcf files or input data directories, separated by commas [required]
  -o | --output-directory       output data directory [optional]
  -c | --center                 name of the center (standard MAF field = 'Center') [optional]
  -s | --sequence-source        Sequencing source (standard MAF field = 'Sequencing_Source'), e.g., WXS or WGS [optional]
  -t | --tumor-id               The ID of the tumor sample utilized in the genotype columns of the VCF file. [optional]
  -n | --normal-id              The ID of the normal sample utilized in the genotype columns of the VCF file. [optional]

Requirements

python 3

Running the tool example

python3 vcf2maf.py --input-data /data/vcfs --output-directory /data/maf/ --center-name CTR --sequence-source WGS --tumor-id Tumor --normal-id Normal

This command converts the VCF files in /vcf folder to MAF format.

• The --input-data option is used to specify either a single VCF file or a directory containing multiple VCF files (separated by commas). This option supports passing multiple input files or directories at once.
• The --output-directory option allows you to specify the directory where the MAF files will be saved. If no output path is provided, the default output directory vcf2maf_output will be used in the current working directory.
• The --tumor-id option allows you to specify the ID of the tumor sample used in the genotype columns of the VCF file. If the option is not used, the script will automatically identify the tumor ID from either the tumor_sample keyword in the meta data lines or the sample columns from VCF header.
• The --normal-id option allows you to specify the ID of the normal sample used in the genotype columns of the VCF file. If the option is not used, the script will automatically identify the normal ID from either the normal_sample keyword in the meta data lines or the sample columns from VCF header.