SCORPION (version 1.3.3)

circosEdges: Circos plot of differential network edges

Description

Draws a circular (Circos) plot of transcription factor to target links from a testEdges two-sample result. Genes are placed on their genomic coordinates, links are coloured continuously by significance, flagged as known or novel against an optional a priori network, and genes belonging to supplied gene sets can be labelled around the circle.

Usage

circosEdges(
  edgesDF,
  species = "hsapiens_gene_ensembl",
  geneCoords = NULL,
  priorNet = NULL,
  geneSets = NULL,
  pAdjThreshold = 0.05,
  log2FCThreshold = 0,
  maxEdges = 500L,
  colorBy = "log2FoldChange",
  linkColors = c("#2166AC", "#F7F7F7", "#B2182B"),
  lwdRange = c(0.5, 4),
  nmaxTF = 20L,
  nmaxTarget = 20L,
  knownColor = "grey60",
  novelColor = "#D95F02",
  geneSetColors = NULL,
  chromosomes = NULL,
  mainChromosomesOnly = TRUE,
  ensemblMirror = "www",
  transparency = 0.5,
  hRatio = 0.6,
  fontFamily = "sans",
  legend = TRUE
)

Value

Invisibly, a list with edges (the plotted links annotated with coordinates and novelty) and coords (the gene coordinate table with

outDegree, inDegree and total degree columns, each the sum of log2FoldChange over a gene's outgoing / incoming links). The function is called for the side effect of drawing the plot.

Arguments

edgesDF

A data.frame produced by testEdges (two-sample or paired). Must contain the columns tf, target, log2FoldChange and pAdj (pValue is used as a fallback when pAdj is absent).

species

Ensembl dataset name passed to biomaRt when geneCoords is NULL, e.g. "hsapiens_gene_ensembl" for human or "mmusculus_gene_ensembl" for mouse. See biomaRt::listDatasets() for the full multi-species list.

geneCoords

Optional data.frame supplying gene coordinates from any source (overrides the biomaRt download). Must have columns gene, chr, start and end.

priorNet

Optional a priori TF-target network whose first two columns are the TF and target. Links present here are labelled "known", all others "novel". Accepts a data.frame or a matrix.

geneSets

Optional gene-set annotation used to label genes around the circle: either a path to a GMT file or a named list of character vectors.

pAdjThreshold

Numeric significance cutoff applied to pAdj (or pValue when pAdj is missing). Default 0.05.

log2FCThreshold

Numeric minimum absolute log2FoldChange required to draw a link. Default 0.

maxEdges

Integer cap on the number of links drawn; when exceeded, the most significant edges are kept. Default 500.

colorBy

Name of the edgesDF column mapped to the link colour ramp. Default "log2FoldChange", giving a continuous diverging colour scale centred at zero. When the default is used but log2FoldChange is absent (e.g. single-sample testEdges output), it falls back to meanEdge.

linkColors

Length-3 vector of colours for the low, mid and high ends of colorBy. Default blue-white-red; a diverging ramp is used when colorBy has negative values, otherwise a sequential low-to-high ramp.

lwdRange

Length-2 numeric giving the minimum and maximum link line width; each link's thickness is scaled linearly within this range by its -log10 adjusted p-value. Default c(0.5, 4).

nmaxTF, nmaxTarget

Integers giving how many TFs and targets to label, selected by the largest absolute out-degree and in-degree respectively. Use NULL or Inf to label all. Defaults 20.

knownColor, novelColor

Border colours distinguishing known from novel links. Defaults grey and orange.

geneSetColors

Optional named vector mapping gene-set names to colours. When NULL, colours are generated automatically.

chromosomes

Optional character vector restricting and ordering the chromosomes shown. When NULL, all chromosomes present are used.

mainChromosomesOnly

Logical; when TRUE (the default) and chromosomes is NULL, only the main chromosomes (numbered, plus X, Y and MT) are kept and unplaced scaffolds/contigs are dropped.

ensemblMirror

biomaRt mirror to query: one of "www", "useast" or "asia". Default "www".

transparency

Numeric link transparency in [0, 1] (0 is opaque). Default 0.5.

hRatio

Numeric in [0, 1] controlling how far link ribbons bend toward the circle centre; smaller values give flatter, less tangled links. Default 0.6.

fontFamily

Font family used for all plot text, e.g. "sans" (Helvetica/Arial, the default) for a publication look.

legend

Logical; whether to draw legends for effect size, novelty and gene sets. Default TRUE.

Author

Daniel Osorio <[e-mail]>

Details

Requires the circlize package, and biomaRt when gene coordinates are downloaded automatically (geneCoords = NULL). Genes without coordinates, and links whose TF or target lacks coordinates, are dropped with a message.

See Also

testEdges, runSCORPION

Examples

if (FALSE) {
data(scorpionTest)
nets <- runSCORPION(
  gexMatrix = scorpionTest$gex,
  tfMotifs = scorpionTest$tf,
  ppiNet = scorpionTest$ppi,
  cellsMetadata = scorpionTest$metadata,
  groupBy = c("donor", "region")
)
res <- testEdges(
  networksDF = nets,
  testType = "two.sample",
  group1 = grep("--T$", colnames(nets), value = TRUE),
  group2 = grep("--N$", colnames(nets), value = TRUE)
)

# Human coordinates auto-downloaded from Ensembl, known/novel vs a prior net
circosEdges(
  edgesDF = res,
  species = "hsapiens_gene_ensembl",
  priorNet = scorpionTest$tf,
  geneSets = "hallmark.gmt"
)
}