Skip to contents
Chapters and reference

Data and workflows · Section 4 of 12

6.3 Signals and coverage data

Download R scriptIncludes preparation and every page step. File examples need the input bundle; preview and save calls are retained.
On this page
R · Example code
library(ggchord)
library(dplyr)
Data preparation and settings (expand)
R · Example code
library(dplyr)
seqs <- seq_data_example |>
  select(accver, length)
links <- ribbon_data_example |>
  select(qaccver, saccver, qstart, qend, sstart, send)
# Recover biological strands from the source annotation field.
genes <- gene_data_example |>
  transmute(accver, start, end, strand = source_strand)

Extract the input bundle so the working directory contains examples/. Each section names its optional dependencies.

1 Continuous signals: bedGraph and BigWig

This installed-package example contains actual GC percentages computed from the unchanged bundled pUC19 sequence in 100 bp windows (last window 86 bp). It is sequence composition, not measured read coverage. data-raw/prepare-signal-inputs.R records the calculation and inst/extdata/signal-sources.json records hashes and the explicit original-header mapping. Readers preserve IDs.

R · Example code
signal_file <- system.file("extdata", "pUC19-gc-100.bedGraph", package = "ggchord")
signal <- read_bedgraph(signal_file, source_file = TRUE)
data(plasmid_example_pUC19)
gc_band <- position_track("GC", side = "inside", width = unit(7, "mm"))
p_signal <- ggchord(plasmid_example_pUC19) +
  geom_seq(show.legend = FALSE) +
  geom_track(
    aes(xmin = start - 1, xmax = end, ymin = 0, ymax = value, fill = value),
    data = signal, geom = "rect", track = gc_band
  ) +
  scale_track_value_continuous("GC", limits = c(0, 100), unit = "GC (%)") +
  scale_track_fill_gradientn(
    "GC", colours = c("#F1E51D", "#31849B"), limits = c(0, 100), name = "GC (%)"
  ) +
  coord_circular()
p_signal

if (.Platform$OS.type != "windows" && requireNamespace("rtracklayer", quietly = TRUE)) {
  indexed_file <- system.file("extdata", "pUC19-gc-100.bw", package = "ggchord")
  selected_signal <- read_bigwig(
    indexed_file,
    which = data.frame(accver = "pUC19", start = c(50, 100), end = c(150, 250)),
    source_file = TRUE
  )
  selected_signal |> select(accver, start, end, value)
}

bedGraph uses four tab-separated columns, zero-based half-open coordinates and finite signed values. Import converts coordinates once; original endpoints, values, physical lines and opaque display headers remain traceable. One file represents one signal; split multiple track definitions. Literal sequence IDs track and browser are valid. Headers never set plot styles. Overlaps remain rows, without an implicit last-wins rule.

Rectangles use start - 1 and end as cell boundaries; no line is interpolated across absent ranges. BigWig requires optional rtracklayer, whose decoder does not support Windows. Use an existing bedGraph file there. Binary GRanges coordinates are already one-based inclusive. Imported runs retain binary floating-point precision; run counts are not original measurement counts. Full lengths come from the file header. Query windows form an unstranded union, results are clipped to it, and empty selection returns zero rows. Missing intervals stay absent, distinct from a stored zero; no coverage, identity, support, units or pre-clipping observation IDs are invented. Each Track’s mapping, value range, units and Guide remain explicit.

2 Aligned reads: an optional coverage bridge

Use optional GenomicAlignments, Rsamtools and GenomicRanges for an existing BAM. Keep filtering and counting choices explicit; ggchord draws the resulting signal. This example uses the dependency’s unchanged Drosophila RNA-seq subset. Its source BAM header retains the original TopHat/reference and SRR provenance; the fixed source URL and checksum are in tools/long-term-audit/v0.27.0-read-coverage-results.json. No read alignment or variant calling occurs.

R · Example code
if (requireNamespace("GenomicAlignments", quietly = TRUE) &&
    requireNamespace("Rsamtools", quietly = TRUE)) {
  bam_file <- system.file("extdata", "sm_treated1.bam", package = "GenomicAlignments")
  read_filter <- Rsamtools::ScanBamParam(
    flag = Rsamtools::scanBamFlag(
      isUnmappedQuery = FALSE, isSecondaryAlignment = FALSE,
      isNotPassingQualityControls = FALSE, isDuplicate = FALSE
    ), mapqFilter = 0L
  )
  aligned <- GenomicAlignments::readGAlignments(bam_file, param = read_filter)
  read_coverage <- GenomicAlignments::coverage(aligned, drop.D.ranges = TRUE)
  coverage_track <- bind_rows(lapply(names(read_coverage), function(id) {
    runs <- read_coverage[[id]]
    ends <- cumsum(S4Vectors::runLength(runs))
    data.frame(
      accver = id, start = c(1, head(ends, -1L) + 1), end = ends,
      value = S4Vectors::runValue(runs)
    )
  }))
  coverage_track |> head()
}

Each retained alignment record contributes one over its aligned reference blocks. Skipped regions (N) and, with this explicit choice, deletions (D) contribute zero; supplementary alignments are retained. No base-quality threshold or overlapping-mate/molecule deduplication is applied. These values are not automatically fragment counts, unique molecules, expression, Identity or variant support. Zero runs are stored zeros for this declared computation, unlike missing experimental intervals. For large inputs use the dependency’s streaming BamFile coverage method with the same explicit filters.

Pass these one-based-inclusive ranges to geom_track(geom = "rect") using xmin = start - 1, xmax = end, ymin = 0, ymax = value, as in continuous signals. Full reference lengths come from scanBamHeader(bam_file)[[1]]$targets, not the last read end. Specify source windows explicitly before displaying a small region.

For CRAM, decode using a mature installed HTSlib/pysam or samtools environment and the actual matching reference when required, retaining the original header, filters and conversion log. Never invent a reference, auto-download unrequested resources or claim all CRAM files are independently decodable. The directed prototype uses no_ref=1 solely to re-encode the same real BAM records without external reference access, then verifies all record fields/tags, reference dictionary and coverage after decoding. It is a format round trip, not an original CRAM observation or universal reference-based CRAM certification. The upstream header’s SO:sorted and absent temporary index generate retained decoder messages; sequential reading succeeds without rewriting them.

Search documentation

↑ ↓ select · Enter open · Esc close; or browse by task. API and functions