Visualize any gene locus with multi-track BigWig overlay

A convenience wrapper around plot_tracks that looks up a gene by symbol and creates a multi-track view without requiring the full enhanceosome pipeline.

Usage

plot_gene_tracks(
  gene_symbol,
  database,
  track_connection,
  chromatin_states = NULL,
  padding = 1000L,
  show_bigwig = TRUE,
  show_chromatin = TRUE,
  show_annotations = TRUE,
  show_gene_model = TRUE,
  show_enhancer_highlight = TRUE,
  mirror = TRUE,
  signal_style = c("line", "polygon"),
  signal_layout = "auto",
  cex_cell_label = 1.4,
  cex_axis = 1.2,
  cex_coord = 1.3,
  cex_annotation = 1.1,
  cex_gene = 1.2,
  cex_title = 1.5,
  cex_signal_label = 1.2,
  quantile_cap = 0.98,
  scale_factor = 1.1,
  export = NULL,
  width = 10,
  height = 8
)

Arguments

gene_symbol: Character. HGNC gene symbol (e.g. "INS", "GCG", "PDX1").
database: An epiRomics S4 database object.
track_connection: A data.frame from the BigWig CSV sheet (columns: path, name, color, type).
chromatin_states: Optional. Output of classify_chromatin_states.
padding: Integer. Base pairs of padding around the gene body (default 1000).
show_bigwig: Logical. Show BigWig signal tracks (default TRUE).
show_chromatin: Logical. Show chromatin state tracks (default TRUE).
show_annotations: Logical. Show BED annotation tracks (default TRUE).
show_gene_model: Logical. Show gene model panel (default TRUE).
show_enhancer_highlight: Logical. Show enhancer highlight (default TRUE).
mirror: Logical. Enable mirrored ATAC/RNA layout (default TRUE).
signal_style: Character. Signal rendering style: "line" (default) draws vertical bars at each position (IGV/UCSC browser style), "polygon" draws filled area charts.
signal_layout: Character. Signal layout mode: "auto", "stacked", or "mirrored".
cex_cell_label: Numeric. Font size for cell type labels (default 1.4).
cex_axis: Numeric. Font size for axis labels (default 1.2).
cex_coord: Numeric. Font size for coordinate bar (default 1.3).
cex_annotation: Numeric. Font size for annotation labels (default 1.1).
cex_gene: Numeric. Font size for gene model labels (default 1.2).
cex_title: Numeric. Font size for plot title (default 1.5).
cex_signal_label: Numeric. Font size for signal indicators (default 1.2).
quantile_cap: numeric. Percentile for capping extreme signal peaks (default 0.98). Peaks above this percentile are clipped to prevent axis compression.
scale_factor: numeric. Y-axis headroom multiplier (default 1.1). Values above 1.0 add whitespace above the tallest signal peak.
export: Character or NULL. File path for export (pdf, eps, png, tiff).
width: Numeric. Export width in inches (default 10).
height: Numeric. Export height in inches (default 8).

Value

Invisible NULL. A multi-panel base-R plot is drawn on the current graphics device.

Details

The function queries the TxDb for the official gene body coordinates, builds a synthetic single-region epiRomics object, and passes it to plot_tracks for rendering. The viewing window spans the gene body plus padding on each side.

Examples

## plot_gene_tracks requires a TxDb (Suggests) and a real BigWig file.
## This example confirms input validation fires correctly.
db <- make_example_database()
tc <- data.frame(path = character(), name = character(),
  color = character(), type = character(),
  stringsAsFactors = FALSE)
if (requireNamespace("TxDb.Hsapiens.UCSC.hg38.knownGene", quietly = TRUE)) {
  tryCatch(
    plot_gene_tracks("INS", db, tc),
    error = function(e) message(e$message)
  )
}
#> 
#> 'select()' returned 1:1 mapping between keys and columns
#>   2169 genes were dropped because they have exons located on both strands of
#>   the same reference sequence or on more than one reference sequence, so cannot
#>   be represented by a single genomic range.
#>   Use 'single.strand.genes.only=FALSE' to get all the genes in a GRangesList
#>   object, or use suppressMessages() to suppress this message.
#> Warning: The 2 combined objects have no sequence levels in common. (Use
#>   suppressWarnings() to suppress this warning.)