plot-generics {iSEE}R Documentation

Plotting generics

Description

A series of generics for controlling how plotting is performed in DotPlot panels. DotPlot subclasses can specialize one or more of them to modify the behavior of .generateOutput.

Generating plotting data

In .generateDotPlotData(x, envir), the following arguments are required:

The method should add a plot.data variable in envir containing a data.frame with columns named "X" and "Y", denoting the variables to show on the x- and y-axes respectively. It should return a list with commands, a character vector of commands that produces plot.data when evaluated in envir; and labels, a list of strings containing labels for the x-axis (named "X"), y-axis ("Y") and plot ("title").

Each row of the plot.data data.frame should correspond to one row or column in the SummarizedExperiment envir$se for RowDotPlots and ColumnDotPlots respectively. Note that, even if only a subset of rows/columns in the SummarizedExperiment are to be shown, there must always be one row in the data.frame per row/column of the SummarizedExperiment, and in the same order. All other rows of the data.frame should be filled in with NAs rather than omitted entirely. This is necessary for correct interactions with later methods that add other variables to plot.data.

Any internal variables that are generated by the commands should be prefixed with . to avoid potential clashes with reserved variable names in the rest of the application.

Generating the ggplot object

In .generateDotPlot(x, labels, envir), the following arguments are required:

Methods for this generic should return a list with plot, a ggplot object; and commands, a character vector of commands to produce that object when evaluated inside envir. This plot will subsequently be the rendered output in .renderOutput. Note that envir should contain a copy of the plot object in a variable named dot.plot - see below for details.

Methods are expected to respond to the presence of various fields in the plot.data. The data.frame will contain, at the very least, the fields "X" and "Y" from .generateDotPlotData. Depending on the parameters of x, it may also have the following columns:

envir may also contain the following variables:

Developers may wish to use the .addMultiSelectionPlotCommands utility to draw brushes and lassos of x. Note that this refers to the brushes and lassos made on x itself, not those transmitted from another panel to x.

It would be very unwise for methods to alter the x-axis, y-axis or faceting values in plot.data. This will lead to uninuitive discrepancies between apparent visual selections for a brush/lasso and the actual multiple selection that is evaluated by downstream functions like .processMultiSelections.

In certain situations, a DotPlot subclass may be able to build off a ggplot generated by its parent class. This is easily done by exploiting the fact that methods for this generic are expected to store a copy of their plot ggplot object as a dot.plot variable in envir. A specialized method for the subclass can callNextMethod() to populate envir with the initial dot.plot, and then just construct and execute commands to add more ggplot2 layers as desired.

Prioritizing points

In .prioritizeDotPlotData(x, envir), the following arguments are required:

Methods for this generic are expected to generate a .priority variable in envir, an ordered factor of length equal to nrow(plot.data) indicating the priority of each point. They may also generate a .rescaled variable, a named numeric vector containing the scaling factor to apply to the downsampling resolution for each level of .priority.

The method itself should return a list containing commands, a character vector of R commands required to generate these variables; and rescaled, a logical scalar indicating whether a .rescaled variable was produced.

Points assigned the highest level in .priority are regarded as having the highest visual importance. Such points will be shown on top of other points if there are overlaps on the plot, allowing developers to specify that, e.g., DE genes should be shown on top of non-DE genes. Scaling of the resolution enables developers to peform more aggressive downsampling for unimportant points.

Methods for this generic may also return NULL, in which case no special action is taken.

Controlling the “None” color scale

In some cases, it is desirable to insert a default scale when ColorBy="None". This is useful for highlighting points in a manner that is integral to the nature of the plot, e.g., up- or down-regulated genes in a MA plot. We provide a few generics to help control which points are highlighted and how they are colored.

.colorByNoneDotPlotField(x) expects x, an instance of a DotPlot subclass, and returns a string containing a name of a column in plot.data to use for coloring in the ggplot mapping. This assumes that the relevant field was added to plot.data by a method for .generateDotPlotData.

.colorByNoneDotPlotScale(x) expects x, an instance of a DotPlot subclass, and returns a string containing a ggplot2 scale_color_* call, e.g., scale_color_manual. This string should end with a "+" operator as additional ggplot2 layers will be added by iSEE.

Author(s)

Kevin “K-pop” Rue-Albrecht, Aaron “A-bomb” Lun


[Package iSEE version 2.0.0 Index]