covPlotObject-class: Versatile coverage plots for SpliceWiz

In alexchwong/SpliceWiz: interactive analysis and visualization of alternative splicing in R

Versatile coverage plots for SpliceWiz

Description

Here, we implement fast and versatile ggplot and plotly based coverage and sashimi plots. Users can plot with unlimited number of individual, individual-normalized, or group-normalized tracks. Also implemented is user-defined group-comparison differential plots (including t-test plots). Additionally, users can generate ggplots subsetted by exon groups. See details below.

Usage

getPlotObject(object, Event, strand = c("*", "+", "-"), tracks, condition, ...)

## S4 method for signature 'covPlotObject'
tracks(object)

## S4 method for signature 'covPlotObject'
condition(object)

plotView(
  object,
  view_start,
  view_end,
  oldP = covPlotly(),
  centerByEvent = FALSE,
  EventZoomFactor = 0.2,
  EventBasesFlanking = 100,
  resolution = 5000,
  trackList = list(),
  diff_stat = c("t-test", "none"),
  diffList = list(),
  reverseGenomeCoords = FALSE,
  ribbon_mode = c("sd", "sem", "ci", "none"),
  normalizeCoverage = FALSE,
  plotAnnotations = TRUE,
  plotAnnoSubTrack = TRUE,
  showExonRanges = FALSE,
  verticalLayout = c(4, 1, 1, 2),
  horizontalLayout = c(),
  filterByTranscripts = "",
  filterByEventTranscripts = FALSE,
  filterByExpressedTranscripts = TRUE,
  condenseTranscripts = FALSE,
  plotJunctions = TRUE,
  plotJuncPSI = FALSE,
  junctionThreshold = 0.01,
  plotRanges = GRanges(),
  rangesBasesFlanking = 100,
  usePlotly = FALSE,
  ...
)

Arguments

object	For getPlotObject(), a covDataObject created using getCoverageData. For plotView(), a covPlotObject created using getPlotObject().
Event	The EventName of the alternative splicing event which will be highlighted and used for normalization
strand	The strand for coverage / junction plotting. Options are "+", "-", or "*" (unstranded - default)
tracks	Sample names or condition categories
condition	For condition-based group plots, the name of the condition.
...	Ignored / not used
view_start, view_end	The start and end coordinates for plotting
oldP	(Optional) If plotting the same tracks and track-widths, supplying the old covPlotly object (returned from a previous call to plotView()) results in faster run-time (as plotly::subplot is a time- consuming function)
centerByEvent	(default FALSE) If true, centers the view to the specified Event
EventZoomFactor	If centerByEvent = TRUE, the zoom-out factor to plot the view. Zooms out in exponents of 3 (i.e., zoom of 1 means 3x, 2 means 9x, and 0 means 1x)
EventBasesFlanking	(default 100) If centerByEvent = TRUE, includes how many bases flanking the event.
resolution	The number of horizontal "pixels" or data-points to plot. This is calculated per sub-plot. Smaller numbers lead to lower resolution but faster plots. Default is 5000
trackList	A list, with each element being a vector of 1 or more track names or indices to plot. If a vector is supplied it will be coerced to a list
diff_stat	(default "t-test") Which statistical method to perform differential comparisons.
diffList	A list, with each element being a vector of size 2, containing names or indices of which tracks to contrast.
reverseGenomeCoords	If TRUE, the genomic coordinate axis will be reversed to plot negative stranded genes
ribbon_mode	The statistic to represent variance. Options are "sd" - standard deviation, "sem" - standard error of the mean, "ci" - 95% confidence interval, or "none"
normalizeCoverage	If TRUE, coverages and junctions of individual samples will be normalized by the given Event.
plotAnnotations	Whether the main annotation track should be plotted
plotAnnoSubTrack	If plotting by exon ranges (using plotRanges), whether a separate sub-track showing zoomed-in exons should be shown above the main annotation track (and below the coverage plots)
showExonRanges	(only applies if usePlotly = FALSE) Whether the main annotation track should be replaced by labeled exon names. If TRUE the returned value of plotView() is a named GRanges object containing the exon ranges
verticalLayout	A vector (of length 4) containing relative heights of the following elements: (1) main block of coverage tracks, (2) differential track, (3) annotation sub-track, and (4) main annotation track. Default c(4,1,1,2)
horizontalLayout	A vector containing relative widths of coverage tracks. Only used alongside plotRanges with more than 1 range to plot. If omitted, plotView will attempt to scale widths to the widths of the exon ranges.
filterByTranscripts	(default "") One or more named transcripts to filter the annotation track.
filterByEventTranscripts	(default FALSE) If TRUE, only transcripts involved in the given Event will be plotted, if any
filterByExpressedTranscripts	(default TRUE) Only transcripts with supported junctions will be plotted on the annotation axis. An expressed junction is that which contains more than the minimum junctionThreshold in at least 1 track
condenseTranscripts	Whether to plot by genes TRUE or transcripts FALSE
plotJunctions	Whether to plot junction counts as numbered arcs. Plots normalized junctions if normalizeCoverage = TRUE.
plotJuncPSI	If plotting group coverage plots, whether to plot mean +/- sd of normalized junction counts FALSE, or estimated junction PSI based on SpliceOver metric applied to each junction TRUE.
junctionThreshold	(default 0.01) Junctions with expressions below this threshold will not be plotted. For raw counts, this is a fraction of maximum coverage value of the track.
plotRanges	A GRanges object containing one or more exon ranges to plot. If given, view_start and view_end will be ignored. Typical use is to use the output of the plotView(..., usePlotly = FALSE), which returns a named GRanges object, then subset this output by exon name.
rangesBasesFlanking	(default 100) How many flanking bases to add to each of plotRanges. Ignored if only 1 range given (or using view_start and view_end)
usePlotly	If TRUE, returns a covPlotly object containing the plotly-based interactive plot. If FALSE, returns a ggplot object.

Details

The typical pipeline for plotting versatile coverage plots is as follows:

• A covDataObject is generated by calling getCoverageData() using an input NxtSE object. This step retrieves coverage, junction counts and normalization data for the relevant genomic region being queried. A new covDataObject is necessary when querying a new genomic region.

• A covPlotObject is generated by calling getPlotObject() using an input covDataObject. This step retrieves alternative splicing event specific data, such as normalized coverages, or group combined coverages. A new covPlotObject is required when changing condition, Event, strand, or when querying using a different set of tracks.

• Plots can be generated by calling plotView() using a covPlotObject. Interactive plotly plots can be generated by setting usePlotly = TRUE, otherwise, static plots are generated. For interactive plots, a covPlotly object is returned, which contains raw data which is downsampled by pixel resolution prior to plotting for performance reasons. A new covPlotly is required unless one only wishes to downsample the resolution

  • see setResolution for covPlotly objects.

Tracks are now versatile (unlimited). Samples are retrieved by individual sample names at getCoverageData(). If condition is set in getPlotObject(), track names are defined by their condition categorical names; otherwise, tracks are named by individual samples when retrieved using getPlotObject().

• When calling plotView(), trackList by default displays all tracks as ordered in the covPlotObject. Users can supply a vector containing either the track names (or numbers, as ordered in the covPlotObject). Alternatively, multiple traces can be stacked in a single track by using a list, e.g. trackList = list(A = c(1,2,3), B = c(4,5,6)).

• For differential comparisons, diffList takes a list of pairs of samples. For example, if trackList = list("A", "B"), then setting diffList = list(c("A", "B")) will compare groups "A" and "B". This is only activated by setting diff_stat to anything other than none. For now, only t-test is supported.

plotView() supports plotting by exon ranges, for which only static plots are currently supported. The workflow for generating such a plot is as follows:

• A GRanges object is returned by the plotView() function and setting showExonRanges = TRUE. plotView() will simultaneously show an annotation plot of exons labelled by their "exon names", which is the transcript name appended with "-E" followed by the exon number.

• If plotView() is called and usePlotly = TRUE is set, a covPlotly object is returned. Calling showExons() on this object will display a plotly plot showing exon names, and returning a GRanges object of exon ranges.

• Exon ranges can be supplied to the plotView() function by setting the plotRanges parameter as a GRanges object. This will generate a static plot showing coverage plots segmented by exons.

Value

For getPlotObject(): A covPlotObject object containing Event-based data to create coverage plots using plotView().

For plotView():

• If usePlotly = TRUE, returns a covPlotly object containing plotly-based interactive plot

• If usePlotly = FALSE, returns a patchwork-assembled static plot, unless showExonRanges = TRUE in which it shows the plot and returns a named GRanges object containing exon ranges.

Functions

• getPlotObject(): Generates a covPlotObject object from a covDataObject. Allows users to change parameters such as viewing window, conditions, tracks, and other parameters, for customizing plot parameters

• tracks(covPlotObject): Returns the tracks contained in the covPlotObject object

• condition(covPlotObject): Returns the condition value set in the covPlotObject object

• plotView(): Creates a coverage plot using the stored data in the covPlotObject

See Also

getCoverageData covPlotly

Examples

se <- SpliceWiz_example_NxtSE(novelSplicing = TRUE)

# Assign annotation of the experimental conditions
colData(se)$treatment <- rep(c("A", "B"), each = 3)

# Retrieve coverage data for all samples for the gene "SRSF3" (and surrounds)

dataObj <- getCoverageData(
    se,
    Gene = "SRSF3",
    tracks = colnames(se)
)

# Retrieves raw / normalized coverage / junction data for the 
# specified SRSF3 skipped exon event:

plotObj_samples <- getPlotObject(
    dataObj,
    Event = "SE:SRSF3-203-exon4;SRSF3-202-int3"
)

# Retrieves data for samples grouped by the specified condition

plotObj_group <- getPlotObject(
    dataObj,
    Event = "SE:SRSF3-203-exon4;SRSF3-202-int3",
    condition = "treatment",
    tracks = c("A", "B")
)

# Display tracks and conditions of covPlotObject

tracks(plotObj_group)
condition(plotObj_group)

# Show static ggplots

plotView(plotObj_samples)

plotView(plotObj_group, centerByEvent = TRUE)

# Plot junctions using PSI estimates based on individual junction SpliceOver
# metrics

plotView(plotObj_group, centerByEvent = TRUE, plotJuncPSI = TRUE)


# Show normalized coverages, individual samples stacked in grouped tracks

plotView(
    plotObj_samples, 
    normalizeCoverage = TRUE, 
    trackList = list(A = c(1,2,3), B = c(4,5,6))
)

# Show stacked group comparisons with t-test

plotView(
    plotObj_group, 
    trackList = list(c(1,2)),
    diffList = list(c("A", "B")),
    diff_stat = "t-test"
)

# Show interactive plotly:

if(interactive()) {
    p <- plotView(plotObj_samples, usePlotly = TRUE)
    show(p)
}

# Show exons with coverage plot

# static:
gr <- plotView(plotObj_samples, showExonRanges = TRUE)

# interactive:
if(interactive()) {
    p <- plotView(plotObj_samples, usePlotly = TRUE)
    gr <- showExons(p)
}

# Plot coverage by exons

p <- plotView(plotObj_samples, 
    plotRanges = gr[c("SRSF3-203-E3", "SRSF3-203-E4", "SRSF3-203-E5")],
    horizontalLayout = c(1,1,1)
)

alexchwong/SpliceWiz documentation built on Oct. 15, 2024, 10:12 a.m.