In ETHZ-INS/epiwraps: epiwraps: Wrappers for plotting and dealing with epigenomics data

library(BiocStyle)

Plotting signals in a region

The plotSignalTracks function is a wrapper around the r BiocStyle::Biocpkg("Gviz") package, which plots one or more signals along genomic coordinates (in a genome-browser like fashion). The function lacks the full flexibility of the r BiocStyle::Biocpkg("Gviz") package, but presents a considerable simpler interface, with automatic default parameters, etc. It has two essential arguments: a (named) list of files whose signal to display (can be a mixture of bigwig, bam, or bed-like files), and the region in which to display the signals (can be given as a GRanges or as a string). The function then automatically determines the relevant track type and setting from the file types.

suppressPackageStartupMessages(library(epiwraps))

# get the path to an example bigwig file:
bwf1 <- system.file("extdata/example_rna.bw", package="epiwraps")
plotSignalTracks(list(RNA=bwf1), region="8:22165140-22212326", genomeAxis=TRUE)
# we could plot multiple tracks as follows:
plotSignalTracks(list(track1=bwf1, track2=bwf1), region="8:22165140-22212326")

GRanges objects can also be plotted as annotation tracks alongside other data:

myregions <- GRanges("8", IRanges(c(22166000,22202300), width=3000))
plotSignalTracks(list(RNA=bwf1, regions=myregions), region="8:22165140-22212326")

Colors, track display types, and such parameters can either be set for all tracks or for each individual track, for example:

myregions <- GRanges("8", IRanges(c(22166000,22202300), width=3000))
plotSignalTracks(list(RNA=bwf1, regions=myregions), colors=c("red", "black"),
                 region="8:22165140-22212326")

For bam files, we can also plot individual reads:

# we fetch an example bam file:
bam <- system.file("extdata", "ex1.bam", package="Rsamtools")
plotSignalTracks(c("my bam file"=bam), "seq1:1-1500", type="alignments")

Merging signal from different tracks

In addition to being displayed one below the other, data tracks can be combined in different ways. To do this, the tracks can simply be given in a nested fashion:

plotSignalTracks(list(track1=bwf1, combined=c(bwf1,bwf1)),
                 region="8:22165140-22212326")

In this example we are always using the same track, but the first element ('track1') plots the track alone, while the second ('combined') merges the two given tracks. By default, the mean is shown, but this can be controlled through the aggregation argument. In addition to usual operations, the tracks can be overlayed on top of one another (aggregation='overlay'), or shown as a heatmap (aggregation='heatmap').

Using an EnsDb object

If an EnsDb object is available (see the r BiocStyle::Biocpkg("ensembldb") package for a description of the class and its methods, and the r BiocStyle::Biocpkg("AnnotationHub") package for a convenient way of fetching such annotation objects), two additional options are available: first, instead of specifying the region as coordinates, one can specify a gene or transcript name, and the corresponding region will be fetched. In addition, the genes or transcripts can be displayed. For example:

# we fetch the GRCh38 Ensembl 103 annotation (this is not run in the vignette,
# as it takes some time to download the annotation the first time is used):
library(AnnotationHub)
ah <- AnnotationHub()
ensdb <- ah[["AH89426"]]
# we plot our previous RNA bigwig file, around the BMP1 locus:
plotSignalTracks(c(coverage=bwf1), region="BMP1", ensdb=ensdb, 
                 transcripts="full")

Now we can see that the coverage is nicely restricted to exons, and that some transcripts/exons are not expressed as highly as others. The transcripts could also have been collapsed into a gene model using transcripts="collapsed" (the default).

To display only the gene track, the first argument can simply be omitted.

Further track customization

In addition to the colors and type argument (and a number of others), which can customize the appearance of tracks, any additional parameters supported by the respective r BiocStyle::Biocpkg("Gviz") function can be passed through the genes.params (for Gviz's GeneRegionTrack), align.params (for Gviz's AlignmentsTrack, when plotting individual reads), or tracks.params (for any other Gviz DataTrack).

For example, if you wish to manually set the same y-axis range for all data tracks, this can be done with:

plotSignalTracks(list(track1=bwf1, track2=bwf1), region="8:22165140-22212326",
                 tracks.params=list(ylim=c(0,200)))

Also, in addition to passing filepaths or GRanges, any Gviz track(s) can be passed (i.e. objects inheriting the GdObject class) can be passed, enabling full track customization when needed.

Session info

sessionInfo()

ETHZ-INS/epiwraps documentation built on Oct. 27, 2024, 8:02 p.m.