In mattlee821/EpiCircos: An implementation of Circos plots for epidemiologists

# Required packages
if (!require("devtools")) install.packages("devtools")
library(devtools)
devtools::install_github("mattlee821/EpiCircos")
library(EpiCircos)

EpiCircos

An implementation of Circos plots for epidemiologists

Full documentation is available on the EpiCircos website.

Citation

If you use the package please use this citation. Please also cite circlize and if using the legend functions cite ComplexHeatmap, both citations can be found here.

Install

Install directly from GitHub using the following code:

# Install devtools
install.packages("devtools")
library(devtools)

# Install EpiCircos directly from GitHub
devtools::install_github("mattlee821/EpiCircos")
library(EpiCircos)

You may be unable to install the pakcage because of an issue installing ComplexHeatmap. An example error:

Skipping 1 packages not available: ComplexHeatmap
Installing 12 packages: circlize, ComplexHeatmap, digest, dplyr, ellipsis, GlobalOptions, pillar, Rcpp, rlang, shape, tibble, vctrs
Error: (converted from warning) package ‘ComplexHeatmap’ is not available (for R version 3.5.3)

To fix this you should install ComplexHeatmap first and then EpiCircos. Install ComplexHeatmap as follows:

# Install devtools
install.packages("devtools")
library(devtools)

# Install ComplexHeatmap directly from Bioconductor
if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("ComplexHeatmap")

# Install EpiCircos directly from GitHub
devtools::install_github("mattlee821/EpiCircos")
library(EpiCircos)

Description

Epidemiologists using large complex data are limited in choice of visualisation tools. Circos plots proivde an informative visualisation tool for examining large complex data, but are traditionally used in genomics and are not easily adaptable for epidemiology. In genomics work Circos plots provide an efficeint way of visually inspecting and comparing data and results.

EpiCircos is a function that simplifies the Circlize package for use with epidemiological data. Data can be displayed in a number of ways:

scatter
line
bar
histogram - the function doesn't work perfectly yet 06/10/2019
chord diagram - not yet supported 06/10/2019
legend - the legend function has currently been removed 06/10/2019

How to

Circos plots can be created by callingcircos_plot(). You can plot up to three tracks using track_number =. The plot is limited to three tracks for readability.

Example data is stored in the function, you can access it in your environment with data <- EpiCircos_data. The data can be used directly in the circos_plot() function by assigning it to track1_data = EpiCircos_data. This is simulated data based on a Mendelian randomization analysis of body mass index to 123 metabolites. It has 123 rows (outcomes) and 8 columns (variables). The variables include betas, standard errors and p-values. For more info ?EpiCircos::EpiCircos_data. NOTE: The example data is the ideal situation for how your own dataframe should be formatted for use with EpiCircos.

head(EpiCircos::EpiCircos_data)

Example

The simplest Circos plot to make is with 1 track.

circos_plot(track_number = 1, # how many track do you want to plot
            track1_data = EpiCircos::EpiCircos_data, # what is the dataframe for your first track
            track1_type = "points", # how do you want to plot your first track
            label_column = 1, # whats is the column of your labels
            section_column = 2, # what is the column of your sections
            estimate_column = 4, # what is the column of your estimate (beta, OR etc.)
            pvalue_column = 5, # what is the column of your p-value
            pvalue_adjustment = 0.05, # what do you want your p-value adjustment to be (multiple testing threshold)
            lower_ci = 7, # what is the column of your lower confidence interval
            upper_ci = 8) # what is the column of your upper confidence interval

You can have multiple tracks each with differnt styles. Track styles can be: "points", "lines", "bar", "histogram".

circos_plot(track_number = 3,
            track1_data = EpiCircos::EpiCircos_data,
            track2_data = EpiCircos::EpiCircos_data,
            track3_data = EpiCircos::EpiCircos_data,
            track1_type = "points",
            track2_type = "lines",
            track3_type = "bar",
            label_column = 1,
            section_column = 2,
            estimate_column = 4,
            pvalue_column = 5,
            pvalue_adjustment = 0.05,
            lower_ci = 7,
            upper_ci = 8,
            lines_column = 4,
            lines_type = "o",
            bar_column = 4,
            histogram_column = 4,
            histogram_binsize = 0.01,
            histogram_densityplot = F)

Saving plots

For best results save your plot as a PDF. If just using the RStudio plots panel you will not be able to see the finished plot as it will appear. Similarly, saving as anything other than .PDF will not give a good visualisation.

Plot as displayed in the RStudio plots panel:

circos_plot(track_number = 3,
            track1_data = EpiCircos::EpiCircos_data,
            track2_data = EpiCircos::EpiCircos_data,
            track3_data = EpiCircos::EpiCircos_data,
            track1_type = "points",
            track2_type = "lines",
            track3_type = "bar",
            label_column = 1,
            section_column = 2,
            estimate_column = 4,
            pvalue_column = 5,
            pvalue_adjustment = 0.05,
            lower_ci = 7,
            upper_ci = 8,
            lines_column = 4,
            lines_type = "o",
            bar_column = 4,
            histogram_column = 4,
            histogram_binsize = 0.01,
            histogram_densityplot = F)