EnhancedVolcano R Package

repository·devel·Indexed 19 days ago

https://github.com/kevinblighe/enhancedvolcano

An R package for generating highly-configurable, publication-ready volcano plots to visualize differential expression analysis results. It provides advanced customization options including custom coloring (colCustom) and shape (shapeCustom) schemes, continuous color gradients (colGradient), variable highlighting via encircling or shading, and label connectors to prevent overlap. The package integrates with ggplot2, allowing for further axis and coordinate customization.

Tokens: 5.2K
Snippets: 18
Records: 18
Agent score: 17%

What's inside EnhancedVolcano

Use a continuous colour scheme with colGradient

devel

To switch from a discrete colour scheme to a continuous one, use the colGradient parameter. Provide a vector of two colours (e.g., c('red3', 'royalblue')) to create a gradient based on the values in the y axis (nominal or adjusted p-value).

  p1 <- EnhancedVolcano(res,
    lab = rownames(res),
    x = "log2FoldChange",
    y = "pvalue",
    pCutoff = 10e-4,
    FCcutoff = 2,
    ylim = c(0, -log10(10e-12)),
    pointSize = c(ifelse(res$log2FoldChange>2, 8, 1)),
    labSize = 6.0,
    shape = c(6, 6, 19, 16),
    title = "DESeq2 results",
    subtitle = "Differential expression",
    caption = bquote(~Log[2]~ "fold change cutoff, 2; p-value cutoff, 10e-4"),
    legendPosition = "right",
    legendLabSize = 14,
    colAlpha = 0.9,
    colGradient = c('red3', 'royalblue'),
    drawConnectors = TRUE,
    hline = c(10e-8),
    widthConnectors = 0.5)

Highlight variables using custom point sizes

devel

The pointSize parameter accepts a vector of values. You can pass a vector of the same length as your results to assign a unique size to every point, allowing you to highlight specific variables (e.g., those with high fold change) by making them larger.

  p1 <- EnhancedVolcano(res,
    lab = rownames(res),
    x = "log2FoldChange",
    y = "pvalue",
    pCutoff = 10e-4,
    FCcutoff = 2,
    ylim = c(0, -log10(10e-12)),
    pointSize = c(ifelse(res$log2FoldChange>2, 8, 1)),
    labSize = 6.0,
    shape = c(6, 6, 19, 16),
    title = "DESeq2 results",
    subtitle = "Differential expression",
    caption = bquote(~Log[2]~ "fold change cutoff, 2; p-value cutoff, 10e-4"),
    legendPosition = "right",
    legendLabSize = 14,
    col = c("grey30", "forestgreen", "royalblue", "red2"),
    colAlpha = 0.9,
    drawConnectors = TRUE,
    hline = c(10e-8),
    widthConnectors = 0.5)

Install EnhancedVolcano via Bioconductor

devel

To install the stable version of EnhancedVolcano, use BiocManager. If you wish to install the development version, use devtools::install_github.

# Install stable version
if (!requireNamespace('BiocManager', quietly = TRUE))
  install.packages('BiocManager')

BiocManager::install('EnhancedVolcano')

# Install development version
devtools::install_github('kevinblighe/EnhancedVolcano')

Encircle and shade specific variables

devel

You can highlight specific variables using encircle and shade parameters.

encircle: A vector of variable names to be encircled. Use encircleCol, encircleSize, encircleFill, and encircleAlpha to customize the appearance.
shade: A vector of variable names to be shaded. Use shadeFill, shadeAlpha, shadeSize, and shadeBins to customize the shading effect.

Note: This feature works best for a small number of key variables. For more complex identification, use shapeCustom.

  # define different cell-types that will be shaded
  celltype1 <- c('VCAM1','CXCL12')
  celltype2 <- c('SORT1', 'KLF15')

  EnhancedVolcano(res,
    lab = rownames(res),
    x = 'log2FoldChange',
    y = 'pvalue',
    selectLab = c(celltype1, celltype2),
    xlab = bquote(~Log[2]~ 'fold change'),
    title = 'Shading cell-type 1|2',
    pCutoff = 10e-14,
    FCcutoff = 1.0,
    pointSize = 8.0,
    labSize = 6.0,
    labCol = 'black',
    labFace = 'bold',
    boxedLabels = TRUE,
    shape = 42,
    colCustom = keyvals,
    colAlpha = 1,
    legendPosition = 'right',
    legendLabSize = 20,
    legendIconSize = 20.0,
    # encircle
      encircle = celltype1,
      encircleCol = 'black',
      encircleSize = 2.5,
      encircleFill = 'pink',
      encircleAlpha = 1/2,
    # shade
      shade = celltype2,
      shadeAlpha = 1/2,
      shadeFill = 'skyblue',
      shadeSize = 1,
      shadeBins = 5,
    drawConnectors = TRUE,
    widthConnectors = 2.0,
    gridlines.major = TRUE,
    gridlines.minor = FALSE,
    border = 'full',
    borderWidth = 5,
    borderColour = 'black')

Override shape scheme with shapeCustom

devel

To override the default shape scheme, provide a named vector to the shapeCustom parameter. This allows you to assign specific shapes to different groups of variables (e.g., different cell types).

  # define different cell-types that will be shaded
  celltype1 <- c('VCAM1','KCTD12','ADAM12','CXCL12')
  celltype2 <- c('CACNB2','SPARCL1','DUSP1','SAMHD1','MAOA')

  # create custom key-value pairs for different cell-types
  keyvals.shape <- ifelse(
    rownames(res) %in% celltype1, 17,
      ifelse(rownames(res) %in% celltype2, 64,
        3))
  keyvals.shape[is.na(keyvals.shape)] <- 3
  names(keyvals.shape)[keyvals.shape == 3] <- 'PBMC'
  names(keyvals.shape)[keyvals.shape == 17] <- 'Cell-type 1'
  names(keyvals.shape)[keyvals.shape == 64] <- 'Cell-type 2'

  p1 <- EnhancedVolcano(res,
    lab = rownames(res),
    x = 'log2FoldChange',
    y = 'pvalue',
    selectLab = rownames(res)[which(names(keyvals) %in% c('high', 'low'))],
    xlab = bquote(~Log[2]~ 'fold change'),
    title = 'Custom shape over-ride',
    pCutoff = 10e-14,
    FCcutoff = 1.0,
    pointSize = 4.5,
    labSize = 4.5,
    shapeCustom = keyvals.shape,
    colCustom = NULL,
    colAlpha = 1,
    legendLabSize = 15,
    legendPosition = 'left',
    legendIconSize = 5.0,
    drawConnectors = TRUE,
    widthConnectors = 0.5,
    colConnectors = 'grey50',
    gridlines.major = TRUE,
    gridlines.minor = FALSE,
    border = 'partial',
    borderWidth = 1.5,
    borderColour = 'black')

Override colouring scheme with colCustom

devel

You can override the default discrete colour scheme by providing a named vector to the colCustom parameter. This is useful for colouring variables by specific metadata like pathway, cell-type, or group. The names of the vector should correspond to the row names (or identifiers) in your results object.

  # create custom key-value pairs for 'high', 'low', 'mid' expression by fold-change
  keyvals <- ifelse(
    res$log2FoldChange < -2.5, 'royalblue',
      ifelse(res$log2FoldChange > 2.5, 'gold',
        'black'))
  keyvals[is.na(keyvals)] <- 'black'
  names(keyvals)[keyvals == 'gold'] <- 'high'
  names(keyvals)[keyvals == 'black'] <- 'mid'
  names(keyvals)[keyvals == 'royalblue'] <- 'low'

  EnhancedVolcano(res,
    lab = rownames(res),
    x = 'log2FoldChange',
    y = 'pvalue',
    selectLab = rownames(res)[which(names(keyvals) %in% c('high', 'low'))],
    xlab = bquote(~Log[2]~ 'fold change'),
    title = 'Custom colour over-ride',
    pCutoff = 10e-14,
    FCcutoff = 1.0,
    pointSize = 3.5,
    labSize = 4.5,
    shape = c(6, 4, 2, 11),
    colCustom = keyvals,
    colAlpha = 1,
    legendPosition = 'left',
    legendLabSize = 15,
    legendIconSize = 5.0,
    drawConnectors = TRUE,
    widthConnectors = 1.0,
    colConnectors = 'black',
    arrowheads = FALSE,
    gridlines.major = TRUE,
    gridlines.minor = FALSE,
    border = 'partial',
    borderWidth = 1.5,
    borderColour = 'black')

Customize axis tick marks
devel
Since EnhancedVolcano returns a ggplot2 object, you can use standard ggplot2 functions to customize axis ticks and limits. For example, use ggplot2::coord_cartesian(xlim=...) to set limits and ggplot2::scale_x_continuous(breaks=...) to define specific tick marks.
```
  p1 +
    ggplot2::coord_cartesian(xlim=c(-6, 6)) +
    ggplot2::scale_x_continuous(
      breaks=seq(-6,6, 1))
```
https://github.com/kevinblighe/enhancedvolcano/blob/devel/README.md
Load EnhancedVolcano into R
devel
After installation, load the package into your R session using library().
```
library(EnhancedVolcano)
```
https://github.com/kevinblighe/enhancedvolcano

Italicise labels and flip the volcano plot

devel

To italicise labels, encode the label strings using the italic('...') syntax and set parseLabels = TRUE. This allows the internal ggplot2 or ggrepel engine to parse the expressions. To flip the volcano plot on its side, append + coord_flip() to the EnhancedVolcano() call.

  lab_italics <- paste0("italic('", rownames(res), "')")
  selectLab_italics = paste0(
    "italic('",
    c('VCAM1','KCTD12','ADAM12', 'CXCL12','CACNB2','SPARCL1','DUSP1','SAMHD1','MAOA'),
    "')")

  EnhancedVolcano(res,
    lab = lab_italics,
    x = 'log2FoldChange',
    y = 'pvalue',
    selectLab = selectLab_italics,
    xlab = bquote(~Log[2]~ 'fold change'),
    pCutoff = 10e-14,
    FCcutoff = 1.0,
    pointSize = 3.0,
    labSize = 6.0,
    labCol = 'black',
    labFace = 'bold',
    boxedLabels = TRUE,
    parseLabels = TRUE,
    col = c('black', 'pink', 'purple', 'red3'),
    colAlpha = 4/5,
    legendPosition = 'bottom',
    legendLabSize = 14,
    legendIconSize = 4.0,
    drawConnectors = TRUE,
    widthConnectors = 1.0,
    colConnectors = 'black') + coord_flip()

Configure cut-off lines and extra threshold lines
devel
Modify the visual style of the significance threshold lines using:
- cutoffLineType: "blank", "solid", "dashed", "dotted", "dotdash", "longdash", or "twodash".
- cutoffLineCol: Color of the line.
- cutoffLineWidth: Thickness of the line (set to 0 to disable).
Add additional horizontal or vertical lines using:
- hline: Vector of y-axis values.
- hlineCol: Vector of colors for horizontal lines.
- hlineType: Vector of line types for horizontal lines.
- hlineWidth: Vector of line widths for horizontal lines.
- vline: Vector of x-axis values.
- vlineCol: Vector of colors for vertical lines.
- vlineType: Vector of line types for vertical lines.
- vlineWidth: Vector of line widths for vertical lines.
```
EnhancedVolcano(res,
  lab = rownames(res),
  x = 'log2FoldChange',
  y = 'pvalue',
  xlim = c(-6, 6),
  pCutoff = 10e-12,
  FCcutoff = 1.5,
  cutoffLineType = 'blank',
  cutoffLineCol = 'black',
  cutoffLineWidth = 0.8,
  hline = c(10e-20, 10e-50, 10e-90),
  hlineCol = c('pink', 'hotpink', 'purple'),
  hlineType = c('solid', 'longdash', 'dotdash'),
  hlineWidth = c(1.0, 1.5, 2.0),
  gridlines.major = FALSE,
  gridlines.minor = FALSE)
```
https://github.com/kevinblighe/enhancedvolcano
Add label connectors to maximize space
devel
To prevent label overlapping and maximize free space, enable drawConnectors = TRUE.
Additional connector settings:
- widthConnectors: Width of the connector lines.
- colConnectors: Color of the connector lines.
- typeConnectors: "open" or "closed".
- endsConnectors: "last", "first", or "both".
- lengthConnectors: Length of the connectors (default is unit(0.01, 'npc')).
```
EnhancedVolcano(res,
  lab = rownames(res),
  x = 'log2FoldChange',
  y = 'pvalue',
  drawConnectors = TRUE,
  widthConnectors = 0.75)
```
https://github.com/kevinblighe/enhancedvolcano
Configure thresholds, title, and point/label sizes
devel
You can override default statistical thresholds and adjust the visual scale of points and labels using pCutoff, FCcutoff, pointSize, and labSize.
```
EnhancedVolcano(res,
  lab = rownames(res),
  x = 'log2FoldChange',
  y = 'pvalue',
  title = 'N061011 versus N61311',
  pCutoff = 10e-32,
  FCcutoff = 0.5,
  pointSize = 3.0,
  labSize = 6.0)
```
https://github.com/kevinblighe/enhancedvolcano