karyoploteR: uncircle your genomes

Hi all,

I’d like to present karyoploteR, an R/Bioconductor package we have developed to plot any data on any genome in non-circular layouts. The goal of this project was to develop a tool as flexible as Circos, but easier to use and representing genomes as straight lines instead of circles, and I think we are pretty close to that.

Links

Examples

Just a few examples of plots created with karyoploteR. More available in the Tutorials and Examples page.

Philosophy

The idea behind the package is to try to mimic as much as possible the R base graphics philosophy: create a basic (possibly empty) plot and add data iteratively using simple graphical primitives. The simple graphical primitives part is important. kpPoints, the karyoploteR function equivalent to points, knows nothing about your data, about any special consideration, about anything. It only plots a point where the user says. This has the benefit of making karyoploteR very flexible with regard to the original data. Oh, and the standard graphics parameters (col, border, pch, lwd, lty…) are all available and work as expected.

The inners

At the heart of karyoploteR, there’s a coordinates change function mapping the genomic coordinates to the plotting coordinates. All plotting functions are implemented around it and end up calling the base R graphics functions (lines, points, rect…) with the transformed coordinates. This function is available to the end-user, so it’s possible (and not difficult) for the end-user to implement additional plotting functions. However, most users will never need to see or care about this.

Show me some code

The main function a user needs to know is plotKaryotype, that will create a plot of the genome and return the karyoplot object needed by the other functions. Giving a set of chromosomes, it will restrict the plot to the selected chromosomes.

kp <- plotKaryotype()

Then, using plotting functions such as kpPoints, kpLines, kpRect, kpSegments, kpText, kpAbline, kpPolygon, etc…, we can keep adding data to the plot.

library(karyoploteR)

x <- 1:23*10e6
y <- rnorm(23, 0.5, 0.1)

kp <- plotKaryotype(chromosomes="chr1")

kpPoints(kp, chr = "chr1", x=x, y=y)
kpText(kp, chr="chr1", x=x, y=y, labels=c(1:23), pos=3)
kpLines(kp, chr="chr1", x=x, y=y, col="#FFAADD")
kpArrows(kp, chr="chr1", x0=x, x1=x, y0=0, y1=y, col="#DDDDDD")

There are additional plotting functions performing more involved computations prior to drawing: kpPlotDensity, that will compute the density of features on the genome and plot it and its sister kpPlotBAMDensity, to plot the density of reads in a BAM file; kpPlotMarkers, to position text labels on the genome (genes or any other feature) avoiding label overlapping; kpPlotLinks, to plot links between genomic regions to represent translocations or any other data type involving two genomic regions; or kpPlotRainfall, to create rainfall plots representing the distance between consecutive genomic features (usually somatic mutations) to show their regional clustering.

Not only human

It is possible to give a different genome name to plotKaryotype to create a karyoplot for the genome of another species. For some of them, karyoploteR will be able to even get the cytoband information and draw a karyoplot with banded ideograms. For others, it will only plot the chromosomes as gray rectangles, but for all of them the data plotting functionality will be available. In fact, it’s even possible to provide it with a completely new genome (either real or made up) and work with it without any problem.

Zooming in

Providing a single zoom parameter to plotKaryotype you can zoom in up to base level. This, combined with karyoploteR’s capabilities for plotting genes and transcripts structures and very precise positioning of genomic features and genomic and epigenomic data, will help you explore the ins and outs of your data.

Combining multiple plots in multi-panel figures

Using the ggplotify package you can combine multiple karyoplots into a single figure or even combine them with other
R plots.

library(karyoploteR)
library(ggplotify)
library(cowplot)

p1 <- as.ggplot(expression(plotKaryotype(main="Human (hg19)")))
p2 <- as.ggplot(expression(plotKaryotype(genome = "mm10", main="Mouse (mm10)")))
plot_grid(p1, p2, ncol=2, labels=LETTERS)

I hope you find it as useful as we do, and that karyoploteR may help you in your future genome drawing endeavors.

Oh, and if you have any idea or a bug report, pull requests are always welcome!

Bernat