# README Welcome to the documentation for Genome Nexus! Genome Nexus is a comprehensive one-stop resource for fast, automated and high-throughput annotation and interpretation of genetic variants in cancer. Genome Nexus integrates information from a variety of existing resources, including databases that convert DNA changes to protein changes, predict the functional effects of protein mutations, and contain information about mutation frequencies, gene function, variant effects, and clinical actionability. ![Genome Nexus Annotation Service](https://user-images.githubusercontent.com/1334004/63193491-a0822d00-c03b-11e9-8546-3293091264eb.png) # Architecture 📐 ![Architecture Overview](https://user-images.githubusercontent.com/1334004/63124264-ddd1b680-bf78-11e9-9122-514330e8fcd8.png) ## Backend Genome Nexus aggregates variant annotation from various sources. There are two types: 1. Small sized annotations are stored as static data in the mongo database directly, see the [genome-nexus-importer repo](https://github.com/genome-nexus/genome-nexus-importer) if you want to update/change this data. 2. Larger annotation sources are pulled on the fly from other APIs and cached in the mongo database. For a list of all supported variant annotation sources see this Google Sheet: The code for the backend can be found here: . ## REST API Genome Nexus provides a [REST API](https://www.genomenexus.org/swagger-ui.html) for variant annotation. See [API](/api) ## API Clients Clients in various languages can be generated to access it. See [API](/api) ## Genome Nexus Website The frontend of the website is here: . ## Other Websites The main consumer of the Genome Nexus REST API is [cBioPortal](https://cbioportal.org). cBioPortal provides visualization, analysis, and download of large-scale cancer genomics data sets. Variants in cBioPortal are annotated using Genome Nexus. The other examples in the figure are potential other consumers. See also: [Tools](/tools) ## Command Line Interface There is a command line tool to annotate MAF and VCF files, see [API](/api) # API ⚙️ A full listing of all API endpoints can be found here: . ## API Clients For access through Python/R see the notebooks here: ## Command Line Clients There are two Command Line Clients available. One written in NodeJS which provides a simple user-friendly interface: There is also a Java Command Line Client which has been developed with a focus on internal processes at Memorial Sloan Kettering Cancer Center but might work for your use case as well: They are similar in terms of feature completeness ## Other Languages The API follows the Swagger/Open API specification, so clients can be generated in most languages: ## Applications build on top of the API See the [tools section](/tools) # Annotation Sources 🗄️ Genome Nexus aggregates variant annotation from various sources. There are two types: 1. Small sized annotations are stored as static data in the mongo database directly. See the [genome-nexus-importer repo](https://github.com/genome-nexus/genome-nexus-importer) if you want to update/change this data. 2. For larger annotation services/databases we either run the full annotation service ourselves or the program pulls on the fly from other APIs and caches the result in the mongo database. For a list of all supported variant annotation sources see this Google Sheet: ## Versions The mirrored annotation sources are either stored directly in the mongo database or we run the annotation service ourselves. In both cases the version is guaranteed. For the external annotion sources an API is called and responses are cached on a per request basis. Given that the external API is outside of our control, no particular version is guaranteed, but we provide links to documentation of those APIs to find the currently live version. See all versions from `version` [API](https://www.genomenexus.org/version). # Annotate a variant 📄 You can annotate a variant on Genome Nexus website or through API. The Genome Nexus website's variant page uses the HGVS format to describe variants. The Genome Nexus API supports multiple input formats. Please see [doc](https://github.com/genome-nexus/genome-nexus?tab=readme-ov-file#examples) for more examples. # Annotate a MAF File 📄 MAF files can be annotated using either the web interface or the command line client. The [Mutation Mapper](https://www.cbioportal.org/mutation_mapper) is a web-based tool and provides an easy-to-use graphical user interface for annotating MAF files. On the other hand, the command line client offers a more flexible approach for users who prefer command-line interfaces. Both options allow you to add additional information to the MAF file, which can be useful for downstream analysis and interpretation. ## Annotate a MAF file using the command line client To annotate a specific MAF file using the command line client, we will be using the [genome-nexus-annotation-pipeline](https://github.com/genome-nexus/genome-nexus-annotation-pipeline). This tool provides the options to customize the annotations according to your specific needs. To use the genome-nexus-annotation-pipeline for annotations, the mutation data files must have at least five columns: * Chromosome * Start\_Position * End\_Position * Reference\_Allele * Tumor\_Seq\_Allele1 or Tumor\_Seq\_Alele2 These essential columns provide the necessary information for accurate annotation of the variants. ### Minimal Example Create a MAF file: ``` (echo -e "Chromosome\tStart_Position\tEnd_Position\tReference_Allele\tTumor_Seq_Allele2"; echo -e "7\t55220240\t55220240\tG\tT") > input.txt; ``` Run the annotator using docker: ``` docker run -v ${PWD}:/wd genomenexus/gn-annotation-pipeline:master --filename /wd/input.txt --output-filename /wd/output.txt --isoform-override mskcc ``` Output can be found in `output.txt` ### Reference Genome The Genome Nexus Annotation Pipeline supports two versions of the human genome reference assembly: **GRCh37** and **GRCh38**.\ By default, the pipeline uses **GRCh37**. #### Using GRCh38 If you want to annotate with **GRCh38**, please set the `GENOMENEXUS_BASE` environment variable to `https://grch38.genomenexus.org`. Here's an example of how to do this: ``` docker run -e GENOMENEXUS_BASE=https://grch38.genomenexus.org -v ${PWD}:/wd genomenexus/gn-annotation-pipeline:latest --filename /wd/input.txt --output-filename /wd/output.txt --isoform-override mskcc ``` # Annotate a VCF File 📄 Before annotating a VCF file using Genome Nexus, it must be first converted to a MAF file. This is because the pipeline is specifically designed to annotate MAF files, which provide a standardized format for storing mutation data. ## VCF to MAF conversion To convert a Variant Call Format (VCF) file to Mutation Annotation Format (MAF), we recommend using the [vcf2maf-lite Python tool](https://github.com/genome-nexus/vcf2maf-lite). It is a lightweight Python adaptation of the [vcf2maf Perl tool](https://github.com/mskcc/vcf2maf), that converts the VCF to MAF format without adding variant annotations. ### Minimal Example ``` python3 vcf2maf.py --input-data /data/vcf --output-directory /data/maf/ --center CTR --sequence-source WGS --tumor-id Tumor --normal-id Normal --retain-info Custom_filters,AC,AF,AC_nfe_seu,AC_afr,AF_afr --retain-fmt alt_count_raw,ref_count_raw,depth_raw ``` 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. * The `--retain-info` option allows you to specify the INFO fields to be retained as additional columns in the MAF. If the option is not used, standard MAF columns are included by default. * The `--retain-fmt` option allows you to specify the FORMAT fields to be retained as additional columns in the MAF. If the option is not used, standard MAF columns are included by default. ### Convert with Docker vcf2maf-lite is available in DockerHub at ``` docker pull genomenexus/vcf2maf-lite:main docker run -v ${PWD}:/wd genomenexus/vcf2maf-lite:main python3 vcf2maf_lite.py --input-data /wd/test.vcf --output-directory /wd/maf/ --center CTR --sequence-source WGS --tumor-id Tumor --normal-id Normal --retain-info Custom_filters,AC,AF,AC_nfe_seu,AC_afr,AF_afr --retain-fmt alt_count_raw,ref_count_raw,depth_raw ``` Output can be found in the /maf directory. ## Annotate a MAF file: Once the VCF file has been converted to Mutation Annotation Format (MAF), the MAF file can be annotated using Genome Nexus. Refer to the [Annotate a MAF File](https://docs.genomenexus.org/annotate-maf-file) section for detailed instructions. # Tools 📊 The Genome Nexus API powers several visualizations in [cBioPortal](https://www.cbioportal.org), for instance: * the online [Mutation Mapper Tool](https://www.cbioportal.org/mutation_mapper), which uses Genome Nexus to annotate mutations supplied in MAF format and draw a lollipop plot * Several annotations displayed in the mutation tables column of cBioPortal, e.g. on the [Patient View Page](https://www.cbioportal.org/patient?studyId=lgg_ucsf_2014\&caseId=P04) For more information about the Genome Nexus and cBioPortal integration see the [cBioPortal docs](https://docs.cbioportal.org/2.1-deployment/architecture-overview#genome-nexus) Note that Command Line Clients for annotating MAF and VCF are describe in the [API](/api) section # About 👥 Genome Nexus is a comprehensive resource integrating variant annotations from [more than a dozen sources](https://docs.genomenexus.org/annotation-sources) relevant to cancer. The annotations can be accessed through a performant [application programming interface](https://docs.genomenexus.org/api) and an [intuitive user interface](https://www.genomenexus.org/), supporting various use cases of variant interpretation. It is freely available under an open source license and can be installed in a private cloud or local environment and integrated with local institutional resources. Genome Nexus is developed at [Memorial Sloan Kettering Cancer Center](http://www.mskcc.org/) (MSK) and has received several contributions from [The Hyve](http://thehyve.nl/). The [Genome Nexus website](https://www.genomenexus.org/) is hosted by the [Center for Molecular Oncology](http://www.mskcc.org/research/molecular-oncology) at MSK. The software is available under an open source license via [GitHub](https://github.com/genome-nexus). ### How do I cite Genome Nexus? When using Genome Nexus, please cite [de Bruijn et al., JCO CCI 2022](https://ascopubs.org/doi/abs/10.1200/CCI.21.00144). Genome Nexus aggregates variant annotation from various sources. See this [documentation](https://docs.genomenexus.org/pages/-LmQuewDTBW0ft2NQkFz#annotation-sources🗄️) for all supported annotation sources. Remember to also cite the underlying annotation sources you are using. ### Current Funding * [Marie-José and Henry R. Kravis Center for Molecular Oncology at MSK](http://www.mskcc.org/research/molecular-oncology) ### Past Funding * [The Fund for Innovation in Cancer Informatics](https://www.the-ici-fund.org/) ### Contributors **Memorial Sloan Kettering Cancer Center, New York, USA** * Ino de Bruijn * Onur Sumer * Xiang Li * Angelica Ochoa * Manda Wilson * Robert Sheridan * Avery Wang * Hongxin Zhang * Aaron Lisman * Benjamin Gross * Nikolaus Schultz * Jianjiong Gao **The Hyve, the Netherlands** * Sander Rodenburg * Pieter Lukasse * Sjoerd van Hagen **Alumni** * Cyriac Kandoth * Zachary Heins * Sander Tan * Ananthan Sadagopan * Alice Thum * Emily Zhang # Used By 🔧 Genome Nexus is used by a number of organizations and projects: * [**cBioPortal**](https://cbioportal.org/) * [**AACR GENIE**](https://genie.synapse.org/) * [**OncoKB**](https://www.oncokb.org/) * [**Memorial Sloan Kettering Cancer Center**](https://mskcc.org/) * **Tempo** Time-Efficient Mutational Profiling in Oncology (Tempo) is a computational pipeline for processing data of paired-end whole-exome (WES) and whole-genome sequencing (WGS) of human cancer samples with matched normals. Its components are containerized and the pipeline runs on the [Juno high-performance computing cluster](http://mskcchpc.org/display/CLUS/Juno+Cluster+Guide) at Memorial Sloan Kettering Cancer Center and on [Amazon Web Services](https://cmotempo.netlify.app/#:~:text=Amazon%20Web%20Services,opens%20new%20window) (AWS). The pipeline was written by members of the [Center for Molecular Oncology](https://www.mskcc.org/research-programs/molecular-oncology). * **Argos** The [ARGOS](https://github.com/mskcc/argos-cwl/) pipeline, developed by the CMO/BIC group at Memorial Sloan Kettering Cancer Center, is an informatics pipeline designed for analysis of cancer genomics data, specifically from the MSK-IMPACT targeted suite of assays. The pipeline operates on tumor/normal pairs and is designed to be reproducible and portable. The inputs are FASTQ files and BWA is used for sequence alignment to the GRCh37 reference genome, followed by ABRA for realignment. * **MSK-ACCESS** Developed by scientists in the CMO Technology Innovation Lab and Department of Pathology, this high-sensitivity assay is offered by the CMO to MSK researchers for profiling circulating tumor DNA derived from blood plasma. The inclusion of matched buffy coat DNA enables the identification and elimination of germline variants and mutations associated with clonal hematopoiesis, a significant confounder of most commercial assays. The assay is available for clinical use in the Molecular Diagnostics Service and for research projects in the Integrated Genomics Operations (IGO). CCI supports the data processing and analysis of research projects utilizing MSK-ACCESS in IGO and leads the ongoing development of the MSK-ACCESS pipeline for all applications. The current version of the pipeline is available here: [mskcc/ACCESS-Pipeline: cfDNA Sequencing Pipeline with UMI (github.com)](https://github.com/mskcc/ACCESS-Pipeline), and more details about the assay and analysis are described in this paper below as well as here: [Brannon, A. R. et al. Enhanced specificity of clinical high-sensitivity tumor mutation profiling in cell- free DNA via paired normal sequencing using MSK-ACCESS. Nat Commun 12, 3770 (2021)](https://www.nature.com/articles/s41467-021-24109-5) * **MSK-IMPACT** [MSK-IMPACT](https://www.nature.com/articles/nm.4333) is a custom hybridization capture–based assay encompassing all genes that are druggable by approved therapies or are targets of experimental therapies being investigated in clinical trials at Memorial Sloan Kettering Cancer Center (MSKCC), as well as frequently mutated genes in human cancer (somatic and germline mutations). MSK-IMPACT is capable of detecting sequence mutations, small insertions and deletions, copy number alterations and select structural rearrangements, and it has been validated and approved for clinical use by the New York State Department of Health Clinical Laboratory Evaluation Program. Samples are processed, followed by sequencing and analysis. Sequencers are monitored by an automated data management system, which initiates the analysis pipeline upon the end of the sequencing run. Each alteration identified by the pipeline is manually reviewed to ensure accuracy. Sequencing results are stored in a clinical-grade database and reported back to patients and physicians through the electronic medical record. Between January 2014 and May 2016, 12,670 tumor samples from 11,369 unique patients were submitted for MSK-IMPACT sequencing. Of these, 10,945 cases were successfully sequenced for a final assay success rate of 86%. * **CMO-CH assay** The CMO-CH assay, developed by scientists at the Center for Molecular Oncology (CMO) Technology Innovation Lab in collaboration with CMO cfDNA Informatics (CCI), the Clonal Hematopoiesis (CH) program, and Diagnostic Molecular Pathology, utilizes the same barcoding and ultra-deep sequencing technology as MSK-ACCESS. It is designed to detect Clonal Hematopoiesis (CH) mutations in white blood cells with high sensitivity. The CMO-CH assay is specifically offered by the CMO to MSK researchers for profiling white blood cell DNA and identifying mutations in the most commonly altered CH-associated genes. It is available for research projects through the Integrated Genomics Operations (IGO). CCI provides support for the data processing and analysis of these projects. To analyze the data generated from the CMO-CH assay, a workflow is utilized. You can find the workflow at the following link: .