DotPlot-class {iSEE} | R Documentation |
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 control various aesthetics of the dots and to store the brush or lasso selection.
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"
.
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 "---"
.
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:
FacetByRow
, a string specifying the metadata field to use for creating row facets.
For RowDotPlots, this should be a field in the rowData
,
while for ColumnDotPlots, this should be a field in the colData
.
Defaults to "---"
, i.e., no row faceting.
FacetByColumn
, a string specifying the metadata field to use for creating column facets.
For RowDotPlots, this should be a field in the rowData
,
while for ColumnDotPlots, this should be a field in the colData
.
Defaults to "---"
, i.e., no column faceting.
The following slots control the effect of the transmitted selection from another panel:
SelectionEffect
, a string specifying the selection effect.
This should be one of "Transparent"
(the default), where all non-selected points become transparent;
"Color"
, where all selected points change to the specified color;
"Restrict"
, where all non-selected points are not plotted.
SelectionAlpha
, a numeric scalar in [0, 1] specifying the transparency to use for non-selected points when SelectionEffect="Transparent"
.
Defaults to 0.1.
SelectionColor
, a string specifying the color to use for selected points when SelectionEffect="Color"
.
Defaults to "red"
.
The following slots control the behavior of brushes:
ZoomData
, a named numeric vector of plot coordinates with "xmin"
, "xmax"
, "ymin"
and "ymax"
elements parametrizing 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.
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 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
.
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.
The following slots refer to general plotting parameters:
FontSize
, positive numeric scalar specifying the relative font size.
Defaults to 1.
LegendPosition
, string specifying the position of the legend on the plot.
Defaults to "Right"
but can also be "Bottom"
.
In addition, this class inherits all slots from its parent Panel class.
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:
.defineOutput(x, id)
returns a UI element for a brushable plot.
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;
and commands
, a list of character vector containing the R commands required to generate contents
and plot
.
.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 testboxes.
For controlling selections:
.multiSelectionRestricted(x)
returns a logical scalar indicating whether x
is restricting the plotted points to those that were selected in a transmitting panel, i.e., is SelectionEffect="Restrict"
?
.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)
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
.
Unless explicitly specialized above, all methods from the parent class Panel are also available.
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.
Aaron Lun
RowDotPlot and ColumnDotPlot, which are more amenable to extension.