Customizing Data Analysis in cBioPortal with custom annotations and advanced filtering options

cBioPortal’s Study View and Results View can now be filtered using driver annotations. cBioPortal already allows users to annotate mutations with annotations like ‘highly actionable’ or ‘potential drug target,’ as we explained earlier in this article. In the newest cBioPortal release (v5.3.5), you can also add custom annotations to structural variants (SV) and copy number alterations (CNA) in your cBioPortal instance. In addition, cBioPortal now shows the annotation menu in the Results View, the Study View, and the Group Comparison View, allowing you to filter alteration events by your custom annotations.

Custom annotations can be helpful in many scenarios. Sometimes cBioPortal’s Oncoprint, Groups comparison, or Study view might contain a number of irrelevant genes. These genes show up in this simply because they are neighboring the relevant genes. You could annotate the relevant gene amplification as ‘Driver’ to exclude these irrelevant genes. Now you can remove the irrelevant alteration event by filtering on ‘Driver.’

Out-of-the-box cBioPortal supports the Driver annotation, which indicates that a variant drives tumor growth, or Passenger annotation that possibly just rides along as some passenger and is present as a ‘side effect’ (also known as variants of unknown significance or VUS annotation in cBioPortal). However, the situation might be slightly more complex. Maybe your dataset contains mutations that are neither driver nor passenger? Or perhaps you only want to view mutations that are potential drug targets? This is where custom driver annotations come into play, a feature that isn’t readily available in the public cBioPortal instance but can be enabled for private deployments of cBioPortal.

How to add custom driver annotations to your data?

We created four new columns in the data files to add custom annotations. These columns already existed for the mutation data file; the format is the same for CNA and SV data. To add ‘Driver’ and ‘Passenger’ annotations, you can add the annotation to the cbp_driver column. Or, when you want to add your own unique scoring system, you can use the cbp_driver_tiers column.

To recreate the example from the introduction, you can add the ‘Driver’ annotations to the cbp_driver column in the CNA data file, so you can later filter out any irrelevant alteration event later on.

Figure 1. A simplified example of a CNA data file containing driver annotations.

Filter using your custom annotations.

Once the data files with the annotations are imported, you use them as filters in cBioPortal’s Study, Result, and Group Comparison pages. Click the ‘Annotations Filter’ button (between the Custom Selection and Charts buttons) on the top right of your cBioPortal page to see your categories. The menu has two options:

  • In the Driver Annotation section, you can filter by Passenger and Driver annotations, similar to the annotations provided by OncoKb.

  • In the Categorical Annotation section, you can filter by the custom categories you provided in the cbp_driver_tiers column. This list is automatically derived from the values used in your data file. When you deselect some categories, the page will exclude all samples marked with those annotations.

Figure 2. In the Study View, you can filter structural variants and copy number alterations by your custom driver annotations as listed in the annotation filter menu.

Try it yourself

The public portal on does not use custom driver annotations. However, you can easily set up your own local instance using docker. Make sure to set the property skin.show_settings_menu to true in your file to activate the optional annotation menu. Next, you have to annotate your studies: we have documented this for CNA, SV, and mutation data files. The final step is loading your annotated studies and starting your cBioPortal instance to analyze your data.

Closing remarks

The Hyve provides services to develop, extend and improve features in cBioPortal such as the custom driver annotations and filtering menu described in this article. Implemented features are released to the community via the cBioPortal repository on GitHub. We hope you like this new feature and that it proves helpful in your work. Please get in touch with us for inquiries on cBioPortal feature development projects or other services concerning cBioPortal.

Written by

Bas Leenknegt