plot_genome_track: Plot genome tracks in linear or circular layout

Description

Visualise genomic tracks as either a linear karyoploteR plot or a circular plot (base R graphics). Set circular = TRUE to switch to the circular layout; the same track_list works for both views without modification.

Supported track types in each list element:

type = "rect" : data as GRanges/data.frame, drawn as rectangles
type = "line" : data as GRanges/data.frame with value_col, drawn as lines
type = "area" : same as line but filled (linear only)
type = "region": piled-up regions (linear only)
type = "coverage": coverage area plot (linear only)

A track with ideogram = TRUE is drawn inside the chromosome bar (linear) or as the outermost ring with a grey background (circular). Only "rect" type is supported for ideogram tracks.

A per-track height field (numeric, default 1) controls relative sizing. In linear mode heights are proportional fractions of the data panel; in circular mode they scale the radial thickness of each ring.

A per-track highlight field (list or list-of-lists with data/col/alpha/border) draws highlight bands within that track only.

Entries with type = "highlight" draw translucent bands spanning all real tracks. These accept: data, col (default "#F1C40F"), alpha (default 0.18), border (default NA), and min.degree (circular only, default 0.4).

Each list element may also contain: name, col, bg.col, border, ylim, lwd, alpha (0--1 transparency), legend_font_col, ideogram, height, highlight.

Usage

plot_genome_track(
  genome_name,
  genome_size = NULL,
  genome = NULL,
  track_list,
  circular = FALSE,
  label = NULL,
  chromosomes = NULL,
  zoom = NULL,
  plot.type = 1,
  track.gap = 0.01,
  legend.show = TRUE,
  legend.position = NULL,
  legend.cex = 0.6,
  legend.bty = "n",
  legend.border = NA,
  legend.font.col = "black",
  legend.lwd = 1,
  legend.seg.len = -0.5,
  legend.box.lwd = 0.25,
  legend.x.intersp = 1,
  legend.lty = 1,
  axis.cex = NULL,
  title.cex = NULL,
  base.tick.dist = NULL,
  start.degree = 34.47,
  track.height = 0.05,
  gap.after = 0,
  cell.padding = c(0, 0, 0, 0),
  track.margin = c(0.005, 0.005),
  circle.margin = c(0.001, 0.001),
  canvas.xlim = c(-1, 1),
  canvas.ylim = c(-1, 1),
  axis.unit = "Mb",
  axis.step = NULL,
  axis.show.unit = FALSE,
  label.column = 4,
  label.niceFacing = TRUE,
  label.cex = 0.6,
  label.side = "inside",
  label.labels_height = 0.01,
  label.connection_height = 0.03,
  label.line_lwd = 0.25
)

Value

Invisibly returns the KaryoPlot object (linear) or NULL

(circular).

Arguments

genome_name: Character. Used for the title.
genome_size: Numeric. Total genome length (single-chromosome genomes).
genome: Optional GRanges, or a karyoploteR genome string (e.g. "hg38"). Ignored in circular mode.
track_list: List of track specs (see above).
circular: Logical. If TRUE, render as a circular plot using base R graphics instead of a karyoploteR linear plot.
label: Optional data.frame/GRanges with labels.
chromosomes: Character vector to restrict/reorder chromosomes (linear only).
zoom: A GRanges object, a character string, or a character vector specifying one or more regions to zoom into (e.g. "chr1:1e6-2e6" or c("chr1:1e6-1.2e6", "chr1:3e6-3.2e6")). In linear mode each region is drawn as a separate stacked panel. In circular mode the regions are concatenated around the circle with small gaps between them. NULL (default) shows the full genome.
plot.type: karyoploteR plot.type (linear only).
track.gap: Relative gap between tracks (linear only, 0 to ~0.05).
legend.show: Logical.
legend.position: Legend position. Character for linear (e.g. "topright"), numeric vector of length 2 for circular (e.g. c(0.75, 1)).
legend.cex, legend.bty, legend.border: See legend.
legend.font.col: Character. Default legend text colour.
legend.lwd, legend.seg.len, legend.box.lwd, legend.x.intersp, legend.lty: Additional legend parameters.
axis.cex: Axis label size.
title.cex: Title size.
base.tick.dist: Numeric or NULL (linear only).
start.degree: Numeric. Starting angle in degrees for the circular layout (default 34.47, matching the circlize convention).
track.height, gap.after, cell.padding, track.margin: Kept for backward compatibility; ignored in the base R circular layout.
circle.margin: Numeric vector (length 2 or 4) controlling plot margins as fractions of the device size. Length 2 is recycled as c(bottom, left, bottom, left). Default c(0.001, 0.001).
canvas.xlim, canvas.ylim: Numeric length-2 vectors controlling the plotting window (circular only). Adjust to pan or zoom into a portion of the circle.
axis.unit, axis.step, axis.show.unit: Circular axis parameters.
label.column, label.niceFacing, label.cex, label.side, label.labels_height, label.connection_height, label.line_lwd: Circular label parameters.

Examples

Run this code

if (FALSE) {
data(ecoli_rep_hotspots)

library("BSgenome.Ecoli.NCBI.ASM584v2")
genome_name <- "BSgenome.Ecoli.NCBI.ASM584v2"
chr_name    <- "U00096.3"
genome <- get(genome_name, envir = asNamespace(genome_name))
chr_length  <- length(genome[[chr_name]])
genome_name="BSgenome.Ecoli.NCBI.ASM584v2"
bins_gc <- make_genomiccoord(
  bsgenome    = genome_name,
  chromosomes = chr_name,
  window      = 200L,
  slide       = 200L,
  start       = 1,
  end         = chr_length,
  strand      = "+"
)
input_new <- list(pkg_name = genome_name, seq = bins_gc)
gr_batch <- to_genomic_ranges_fast(input_new)
tm_ASM584v2 <- tm_calculate(
  gr_batch,
  method   = "tm_nn"
)
Tm <- as.data.frame(tm_ASM584v2$gr[, c("Tm", "GC")])

tracks <- list(
  list(type = "rect", data = ecoli_rep_hotspots$all_peaks_IP_mutH,
       col = "#2C3E50", bg.col = "grey", name = "MutL-AR",
       legend_font_col = "#2C3E50", ideogram = TRUE, height = 0.5),
  list(type = "line", data = Tm, value_col = "GC",
       name = "GC content", col = "#4A90E2",
       legend_font_col = "#4A90E2"),
  list(type = "line", data = Tm, value_col = "Tm",
       name = "Melting temp", col = "#E06666",
       legend_font_col = "#E06666", height = 2),
  list(type = "line", data = ecoli_rep_hotspots$bins_rep,
       value_col = "count", name = "Microsatellites", col = "#2ECC71",
       legend_font_col = "#2ECC71"),
  list(type = "line", data = ecoli_rep_hotspots$bins_cru,
       value_col = "count", name = "Cruciform", col = "#3B3E6B",
       legend_font_col = "#3B3E6B"),
  list(data = ecoli_rep_hotspots$ssdna, name = "ssDNA",
       col = "#8E44AD", legend_font_col = "#8E44AD"),
  list(type = "line", data = ecoli_rep_hotspots$bins_gatc,
       value_col = "count", name = "GATC sites", col = "#D35400",
       legend_font_col = "#D35400"),
  list(type = "highlight", data = ecoli_rep_hotspots$all_peaks_IP_mutH,
       col = "#F1C40F", alpha = 0.18)
)

# Circular
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks, circular = TRUE)

# Linear
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks)

# Linear zoom (single region)
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks,
                  zoom = "U00096.3:1000000-2000000")

# Linear zoom (multiple regions — stacked panels)
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks,
                  zoom = c("U00096.3:1000000-1200000",
                           "U00096.3:3000000-3200000"))

# Circular zoom (multiple regions — concatenated arcs)
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks, circular = TRUE,
                  zoom = c("U00096.3:1000000-1200000",
                           "U00096.3:3000000-3200000"))

# Circular with canvas panning
plot_genome_track("E. coli", genome_size = 4641652,
                  track_list = tracks, circular = TRUE,
                  canvas.xlim = c(0.5, 1), canvas.ylim = c(0, 1),
                  circle.margin = c(0.05, 0.05))
}

Run the code above in your browser using DataLab