# Variant Annotators

{% hint style="info" %}
Coming Soon: Germline support for OncoKB Annotator
{% endhint %}

## Introduction

Annotates variants in MAF with OncoKB™ annotation. Supports both python2 and python3.

* **MafAnnotator.py**: A Mutation Annotation Format (MAF) file is a tab-delimited text file that lists mutations. MAFAnnotator annotated genes from MAF file by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **FusionAnnotator.py**: Annotate fusions by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **CnaAnnotator.py**: Annotate copy number alterations by [OncoKB Level of Evidences](https://www.oncokb.org/levels) rules.
* **ClinicalDataAnnotator.py**: Annotate clinical data by [OncoKB™ Level of Evidences](https://www.oncokb.org/levels) rules.
* **OncoKBPlots.py**: Draw OncoKB™ Actionability genes graph.<br>

Please run the commands below to see usage details in terminal.

```bash
python MafAnnotator.py -h
python FusionAnnotator.py -h
python CnaAnnotator.py -h
python ClinicalDataAnnotator.py -h
python OncoKBPlots.py -h
```

{% hint style="info" %}
We recommend processing VCF files by [vcf2maf](https://github.com/mskcc/vcf2maf/) with [MSK override isoforms](https://github.com/mskcc/vcf2maf/blob/master/data/isoform_overrides_at_mskcc) before using the **MafAnnotator** here.
{% endhint %}

Please go to [OncoKB™ Annotator Github Repository](https://github.com/oncokb/oncokb-annotator) to see source code and more details.

## OncoKB™ API Token

When you run `MafAnnotator.py`, `FusionAnnotator.py` and `CnaAnnotator.py`, you need a token before accessing the OncoKB™ data via its web API. Please visit [OncoKB™ Data Access Page](https://www.oncokb.org/dataAccess) for more information about how to register an account and get an OncoKB™ API token.\
With the token listed under [OncoKB™ Account Settings Page](https://www.oncokb.org/account/settings), you could use it in the following format.

```bash
python ${FILE_NAME.py} -i ${INPUT_FILE} -o ${OUTPUT_FILE} -b ${ONCOKB_API_TOKEN}
```

## Python Examples

### MAF Annotator

When you type `python MafAnnotator.py -h` in terminal, you can see all Python command parameters as below. `-i <input MAF file>`, `-o <output MAF file>` and`-b oncokb_api_bear_token` are required.

```bash
MafAnnotator.py -i <input MAF file> -o <output MAF file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token] [-a]
Essential MAF columns (case insensitive):
    HUGO_SYMBOL: Hugo gene symbol
    VARIANT_CLASSIFICATION: Translational effect of variant allele
    TUMOR_SAMPLE_BARCODE: sample ID
    AMINO_ACID_CHANGE: amino acid change
    PROTEIN_START: protein start
    PROTEIN_END: protein end
    PROTEIN_POSITION: can be used instead of PROTEIN_START and PROTEIN_END (in the output of vcf2map)
Essential clinical columns:
    SAMPLE_ID: sample ID
    ONCOTREE_CODE: tumor type code from oncotree (oncotree.mskcc.org)
Cancer type will be assigned based on the following priority:
    1) ONCOTREE_CODE in clinical data file
    2) ONCOTREE_CODE exist in MAF
    3) default tumor type (-t)
Default OncoKB™ base url is http://oncokb.org.
Use -a to annotate mutational hotspots
```

### Fusion Annotator

When you type python `FusionAnnotator.py -h` in terminal, you can see all Python command parameters as below. The required parameters is the same with MAF Annotator.

```bash
FusionAnnotator.py -i <input Fusion file> -o <output Fusion file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token]
  Essential Fusion columns (case insensitive):
    HUGO_SYMBOL: Hugo gene symbol
    VARIANT_CLASSIFICATION: Translational effect of variant allele
    TUMOR_SAMPLE_BARCODE: sample ID
    FUSION: amino acid change, e.g. "TMPRSS2-ERG fusion"
  Essential clinical columns:
    SAMPLE_ID: sample ID
    ONCOTREE_CODE: tumor type code from oncotree (oncotree.mskcc.org)
  Cancer type will be assigned based on the following priority:
     1) ONCOTREE_CODE in clinical data file
     2) ONCOTREE_CODE exist in Fusion
     3) default tumor type (-t)
  Default OncoKB™ base url is http://oncokb.org
```

### CNA Annotator

When you type python `CnaAnnotator.py -h` in terminal, you can see all Python command parameters as below. The required parameters is the same with MAF Annotator.

```bash
CnaAnnotator.py -i <input CNA file> -o <output CNA file> [-p previous results] [-c <input clinical file>] [-s sample list filter] [-t <default tumor type>] [-u oncokb-base-url] [-b oncokb_api_bear_token]
  Input CNA file should follow the GISTIC output (https://cbioportal.readthedocs.io/en/latest/File-Formats.html#discrete-copy-number-data)
  Essential clinical columns:
    SAMPLE_ID: sample ID
  Cancer type will be assigned based on the following priority:
     1) ONCOTREE_CODE in clinical data file
     2) ONCOTREE_CODE exist in MAF
     3) default tumor type (-t)
  Default OncoKB™ base url is http://oncokb.org
```

### Clinical Data Annotator

When you type python `ClinicalDataAnnotator.py -h` in terminal, you can see all Python command parameters as below. `-i <input clinical file>`, `-o <output clinical file>` and`-a <annotated alteration files, separate by ,>` are required.

```bash
ClinicalDataAnnotator.py -i <input clinical file> -o <output clinical file> -a <annotated alteration files, separate by ,> [-s sample list filter]
  Essential clinical columns:
    SAMPLE_ID: sample ID
```

### OncoKB Plots

When you type `python OncoKBPlots.py -h` in terminal, you can see all Python command parameters as below. `-i <input clinical file>` and `-o <output clinical file>` are required.

```bash
OncoKBPlots.py -i <annotated clinical file> -o <output PDF file> [-c <categorization column, e.g. CANCER_TYPE>] [-s sample list filter] [-n threshold of # samples in a category] [-l comma separated levels to include]
  Essential clinical columns:
    SAMPLE_ID: sample ID
    HIGHEST_LEVEL: Highest OncoKB levels
  Supported levels (-l): 
    LEVEL_1,LEVEL_2,LEVEL_3A,LEVEL_3B,LEVEL_4,ONCOGENIC,VUS
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.oncokb.org/oncokb-annotator/gene-annotation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.