The DotPlot virtual class

The DotPlot is a virtual class for all panels where each row or column in the SummarizedExperiment is represented by no more than one point (i.e., a “dot”) in a brushable ggplot plot. It provides slots and methods to create the plot, to control various aesthetics of the dots, and to store the brush or lasso selection.

Slot overview

The following slots are relevant to coloring of the points:

• ColorBy, a string specifying how points should be colored. This should be one of "None", "Feature name", "Sample name" and either "Column data" (for ColumnDotPlots) or "Row data" (for RowDotPlots). Defaults to "None".

• ColorByDefaultColor, a string specifying the default color to use for all points if ColorBy="None". Defaults to "black" in getPanelDefault.

• ColorByFeatureName, a string specifying the feature to be used for coloring points when ColorBy="Feature name". For RowDotPlots, this is used to highlight the point corresponding to the selected feature; for ColumnDotPlots, this is used to color each point according to the expression of that feature. If NA, this defaults to the name of the first row.

• ColorByFeatureSource, a string specifying the name of the panel to use for transmitting the feature selection to ColorByFeatureName. Defaults to "---".

• ColorBySampleName, a string specifying the sample to be used for coloring points when ColorBy="Sample name". For RowDotPlots, this is used to color each point according to the expression of that sample; for ColumnDotPlots, this is used to highlight the point corresponding to the selected sample. If NA, this defaults to the name of the first column.

• ColorBySampleSource, a string specifying the name of the panel to use for transmitting the sample selection to ColorBySampleNameColor. Defaults to "---".

• ColorByFeatureDynamicSource, a logical scalar indicating whether x should dynamically change its selection source when coloring by feature. Defaults to FALSE in getPanelDefault.

• ColorBySampleDynamicSource, a logical scalar indicating whether x should dynamically change its selection source when coloring by feature. Defaults to FALSE in getPanelDefault.

• SelectionAlpha, a numeric scalar in [0, 1] specifying the transparency to use for non-selected points. Defaults to 0.1 in getPanelDefault.

The following slots control other metadata-related aesthetic aspects of the points:

• ShapeBy, a string specifying how the point shape should be determined. This should be one of "None" and either "Column data" (for ColumnDotPlots) or "Row data" (for RowDotPlots). Defaults to "None".

• SizeBy, a string specifying the metadata field for controlling point size. This should be one of "None" and either "Column data" (for ColumnDotPlots) or "Row data" (for RowDotPlots). Defaults to "None".

The following slots control the faceting:

• FacetRowBy, a string indicating what to use for creating row facets. For RowDotPlots, this should be one of "None", "Row data" or "Row selection". For ColumnDotPlots, this should be one of "None", "Column data" or "Column selection". Defaults to "None", i.e., no row faceting.

• FacetByColumn, a string indicating what to use for creating column facets. For RowDotPlots, this should be one of "None", "Row data" or "Row selection". For ColumnDotPlots, this should be one of "None", "Column data" or "Column selection". Defaults to "None", i.e., no column faceting.

The following slots control any text to be shown on the plot:

• LabelCenters, a logical scalar indicating whether the label the centers (technically medoids) of all cells in each group, where groups are defined by a discrete covariate in the relevant metadata field. Defaults to FALSE.

• LabelCentersBy, a string specifying the metadata field to define the groups when LabelCenters is TRUE. This should be a discrete variable in rowData or colData for RowDotPlots and ColumnDotPlots, respectively. Defaults to the name of the first column.

• LabelCentersColor, a string specifying the color used for the labels at the center of each group. Only used when LabelCenters is TRUE. Defaults to "black".

• CustomLabels, a logical scalar indicating whether custom labels should be inserted on specific points. Defaults to FALSE.

• CustomLabelsText, a (possibly multi-line) string with the names of the points to label when CustomLabels is set to TRUE. Each line should contain the name of a row or column for RowDotPlots and ColumnDotPlots, respectively. Leading and trailing whitespace are stripped, and all text on a line after # is ignored. Defaults to the name of the first row/column.

The following slots control interactions with the plot image:

• ZoomData, a named numeric vector of plot coordinates with "xmin", "xmax", "ymin" and "ymax" elements parameterizing the zoom boundaries. Defaults to an empty vector, i.e., no zoom.

• BrushData, a list containing either a Shiny brush (see ?brushedPoints) or an iSEE lasso (see ?lassoPoints). Defaults to an empty list, i.e., no brush or lasso.

• HoverInfo, a logical scalar indicating whether the feature/sample name should be shown upon mouse-over of the point. Defaults to TRUE.

The following slots control some aspects of the user interface:

• DataBoxOpen, a logical scalar indicating whether the data parameter box should be open. Defaults to FALSE.

• VisualBoxOpen, a logical scalar indicating whether the visual parameter box should be open. Defaults to FALSE.

• VisualChoices, a character vector specifying the visible interface elements upon initialization. This can contain zero or more of "Color", "Shape", "Size", "Point" , "Facet", "Text", and "Other". Defaults to "Color".

The following slots control the addition of a contour:

• ContourAdd, logical scalar indicating whether a contour should be added to a (scatter) plot. Defaults to FALSE.

• ContourColor, string specifying the color to use for the contour lines. Defaults to "blue".

The following slot controls whether the aspect ratio is fixed to 1 or not:

• FixAspectRatio, logical scalar indicating whether the aspect ratio of a scatter plot should be fixed to 1. Defaults to FALSE.

The following slot controls whether the violin boundaries are plotted or not:

• ViolinAdd, logical scalar indicating whether the violin boundaries should be plotted. Defaults to TRUE.

The following slots control the general appearance of the points.

• PointSize, positive numeric scalar specifying the relative size of the points. Defaults to 1.

• PointAlpha, non-negative numeric scalar specifying the transparency of the points. Defaults to 1, i.e., not transparent.

• Downsample, logical scalar indicating whether to downsample points for faster plotting. Defaults to FALSE in getPanelDefault.

• DownsampleResolution, numeric scalar specifying the resolution of the downsampling grid (see ?subsetPointsByGrid) if Downsample=TRUE. Larger values correspond to reduced downsampling at the cost of plotting speed. Defaults to 200 in getPanelDefault.

The following slots refer to general plotting parameters:

• FontSize, positive numeric scalar specifying the relative font size. Defaults to 1 in getPanelDefault.

• PointSize, positive numeric scalar specifying the relative point size. Defaults to 1 in getPanelDefault.

• LegendPosition, string specifying the position of the legend on the plot. Defaults to "Bottom" in getPanelDefault. The other valid choice is "Right".

In addition, this class inherits all slots from its parent Panel class.

Supported methods

In the following code snippets, x is an instance of a DotPlot class. Refer to the documentation for each method for more details on the remaining arguments.

For setting up the objects:

• .cacheCommonInfo(x) adds a "DotPlot" entry containing valid.assay.names, a character vector of valid assay names. Valid names are defined as those that are non-empty, i.e., not "". This method will also call the equivalent Panel method.

• .refineParameters(x, se) replaces NA values in ColorByFeatureName and ColorBySampleNameColor with the first row and column name, respectively, of se. This will also call the equivalent Panel method.

For defining the interface:

• .defineInterface(x, se, select_info) defines the user interface for manipulating all slots described above and in the parent classes. It will also create a data parameter box that can respond to specialized .defineDataInterface. This will override the Panel method.

• .defineVisualColorInterface(x, se, select_info) defines the user interface subpanel for manipulating the color of the points.

• .defineVisualShapeInterface(x, se) defines the user interface subpanel for manipulating the shape of the points.

• .defineVisualSizeInterface(x, se) defines the user interface subpanel for manipulating the size of the points.

• .defineVisualPointInterface(x, se) defines the user interface subpanel for manipulating other point-related parameters.

• .defineVisualFacetInterface(x, se) defines the user interface subpanel for manipulating facet-related parameters.

• .defineVisualTextInterface(x, se) defines the user interface subpanel for manipulating text-related parameters.

• .defineVisualOtherInterface(x, se) defines the user interface subpanel for manipulating other parameters. Currently this returns NULL.

• .defineOutput(x) returns a UI element for a brushable plot.

• .allowableColorByDataChoices(x, se) returns a character vector containing all atomic variables in the relevant *Data dimension.

For generating the output:

• .generateOutput(x, se, all_memory, all_contents) returns a list containing contents, a data.frame with one row per point currently present in the plot; plot, a ggplot object; commands, a list of character vector containing the R commands required to generate contents and plot; and varname, a string containing the name of the variable in commands that was used to obtain contents.

• .generateDotPlot(x, labels, envir) returns a list containing plot and commands, as described above. This is called within .generateOutput for all DotPlot instances by default. Methods are also guaranteed to generate a dot.plot variable in envir containing the ggplot object corresponding to plot.

• .prioritizeDotPlotData(x, envir) returns NULL.

• .colorByNoneDotPlotField(x) returns NULL.

• .colorByNoneDotPlotScale(x) returns NULL.

• .exportOutput(x, se, all_memory, all_contents) will create a PDF file containing the current plot, and return a string containing the path to that PDF. This assumes that the plot field returned by .generateOutput is a ggplot object.

For defining reactive expressions:

• .createObservers(x, se, input, session, pObjects, rObjects) sets up observers for some (but not all!) of the slots. This will also call the equivalent Panel method.

• .renderOutput(x, se, output, pObjects, rObjects) will add a rendered plot element to output. The reactive expression will add the contents of the plot to pObjects$contents and the relevant commands to pObjects$commands. This will also call the equivalent Panel method to render the panel information text boxes.

For controlling selections:

• .multiSelectionCommands(x, index) returns a character vector of R expressions that - when evaluated - returns a character vector of the names of selected points in the active and/or saved selections of x. The active selection is returned if index=NA, otherwise one of the saved selection is returned.

• .multiSelectionActive(x) returns x[["BrushData"]] or NULL if there is no brush or closed lasso.

• .multiSelectionClear(x) returns x after setting the BrushData slot to an empty list.

• .singleSelectionValue(x, contents) returns the name of the first selected element in the active brush. If no brush is active, NULL is returned instead.

• .singleSelectionSlots(x) will return a list specifying the slots that can be updated by single selections in transmitter panels, mostly related to the choice of coloring parameters. This includes the output of callNextMethod.

For documentation:

• .definePanelTour(x) returns an data.frame containing the steps of a tour relevant to subclasses, mostly describing the specification of visual effects and the creation of a brush or lasso.

Unless explicitly specialized above, all methods from the parent class Panel are also available.

Subclass expectations

The DotPlot is a rather vaguely defined class for which the only purpose is to avoid duplicating code for ColumnDotPlots and RowDotPlots. We recommend extending those subclasses instead.

See also

RowDotPlot and ColumnDotPlot, which are more amenable to extension.

Author

Aaron Lun