karyoploteR: an R/Bioconductor package to plot customizable genomes displaying arbitrary data

1Data visualization is an important part of data analysis. It efficiently summarizes complex data, facilitates exploration and can reveal non-obvious patterns in the data. A natural representation for genomic data is positioned along the genome next to the ideograms of the different chromosomes. This type of representation is specially useful to identify the relation between different types of experimental data and genomic annotations. Various genomic visualization tools are available. Circos produces highly customizable high quality circular plots, as does ites R counterpart RCircos. There are other R packages capable of plotting whole genome diagrams such as: ggbio, based on the grammar of graphics that can produce different plot types including ideogram and karyogram plots; IdeoViz, to plot binned data along the genome either as lines or bars; or chromPlot, to plot up to four datasets given in a predefined format. These packages are either limited in the amount or type of data they can plot (IdeoViz and chromPlot) or have limited customization options (ggbio). In addition, the Bioconductor package Gviz is a powerful tool to create track-based plots of diverse biological data but it does not produce plots of the whole genome. There is a lack of a tool in R to create non-circular whole genome plots, able to plot arbitrary data in any organism and with ample customization capabilities.

2Here we present karyoploteR, an extendable and customizable R/Bioconductor package to plot genome ideograms and genomic data positioned along them. It’s inspired on the R base graphics, building plots with multiple successive calls to simple plotting functions.

3The interface of karyoploteR and the process to create a complete plot is very similar to that of base R graphics. We first create a simple or even empty plot with an initializing function and then add additional graphic elements with successive calls to other plotting functions. The first call creates and initializes the graphical device and returns a karyoplot object with all the information needed to add data to it. The karyoplot object contains a coordinate change function mapping genomic coordinates into plotting coordinates, which is used by all plotting functions. Plotting functions are classified into three groups: the ones adding non-data elements to the plot and two data plotting groups, low-level functions and high-level functions. karyoploteR also takes some ideas from Circos, such as not defining fixed tracks but leaving complete freedom to the user with respect to data positioning using the r0 and r1 parameters. All non-data elements in the karyoplot (main title, chromosome names, …) are drawn by specific functions. These functions accept standard graphical parameters but it’s also possible to swap them for custom functions if a higher level of customization is needed.

4Ideogram plotting is the basic functionality of karyoploteR. Default ideograms can be plotted with a single function call (Fig. 1A). However, itwe possible to customize them: positioning the chromosomes in different arrangements, representing just a subset of chromosomes or change whether the cytobands are included and how they are represented. It is also possible to create different data plotting regions either above or below the ideograms as well as customizing all sizings and margins by changing the values stored in plot.params.

5karyoploteR is not restricted to human data in any way. It is possible to specify other organisms when creating a karyoplot. Genome data for a small set of organisms is included with the package and it will use functionality from regioneR to get it from UCSC or Bioconductor for other genomes. If an organism is not available anywhere, it is possible to plot it providing its genome information. Therefore, if required, it’s possible to create custom genomes for specific purposes.

6Data plotting functions are divided in two groups: low-level and high-level. Low-level data plotting functions plot graphical primitives such as points, lines and polygons. Except for the additional chr parameter, they mimic the behaviour of their base graphics counterparts including the usage of most of the standard graphical parameters. These plotting functions offer a flexible signature and are completely data agnostic: they know nothing about biological concepts, giving the user total freedom on how to use them. High-level functions, in contrast, are used to create more complex data representations. They understand some basic concepts such as ‘genomic region’ and they usually perform some kind of computation prior to data plotting (Fig. 1B).

7In addition to customizing sizings and margins and the using custom genomes, karyoploteR can be extended with custom plotting functions. All internal functions, including the main coordinate change function, are exported and documented in the package vignette. With this it is possible to create custom plotting functions adapted to specific data types and formats.

8We have developed an R/Bioconductor package, karyoploteR, to plot arbitrary genomes with data positioned on them. It offers a flexible API inspired in R base graphics, with low-level functions to plot graphical primitives and high-level functions to plot complex data. The plots are highly customizable in data positioning and appearance and it is possible to extend the package functionality with custom plotting functions. karyoploteR requires R ≥ 3.4 and Bioconductor ≥ 3.5. More information and examples can be found at the package Bioconductor page and at https://bernatgel.github.io/karyoploter_tutorial