| single-select-generics {iSEE} | R Documentation |
A panel can create a single selection on either the rows or columns and transmit this selection to another panel for use as an aesthetic parameter. For example, users can click on a RowTable to select a gene of interest, and then the panel can transmit the identities of that row to another panel for coloring by that selected gene's expression. This suite of generics controls the behavior of these single selections.
Given an instance of the Panel class x, .singleSelectionDimension(x) should return a string
specifying whether the selection contains a single "feature",
"sample", or if the Panel in x does not perform single selections at all ("none").
The output should be constant for all instances of x.
.singleSelectionValue(x, contents) should return a string specifying the selected row or column.
If no row or column is selected, it should return NULL.
contents is any arbitrary structure set by the rendering expression in .renderOutput for x.
This should contain all of the information necessary to determine the name of the selected row/column.
For example, a data.frame of coordinates is stored by DotPlots to identify the point selected by a brush/lasso.
.singleSelectionSlots(x) should return a list with one internal list for each slot in x that might respond to a single selection from a transmitting panel.
This internal list should contain at least entries with the following names:
param, the name of the slot of x that can potentially respond to a single selection in a transmitting panel,
e.g., ColorByFeatureName in DotPlots.
source, the name of the slot of x that indicates which transmitting panel to respond to,
e.g., ColorByFeatureSource in DotPlots.
The paradigm here is that the interface will contain two selectInput elements, one for each of the param and source slots.
It is possible for users to manually alter the choice in the param's selectInput;
it is also possible for users to specify a transmitting panel via the source's selectInput,
which will then trigger automatic updates to the chosen entry in the param's selectInput when the transmitter's single selection changes.
Developers are strongly recommended to follow the above paradigm.
In fact, the observers to perform these updates are automatically set up by .createObservers,Panel-method
if the internal list also contains the following named entries:
dimension, a string set to either "feature" or "sample".
This specifies whether the slot specified by param contains the identity of a single feature or a single sample.
If this is not present, no observers will be set up.
dynamic, the name of the slot indicating whether the choice of transmitting panel should change dynamically.
One example would be "ColorByFeatureDynamicSource" for DotPlots.
This can be missing if the current panel does not support dynamic selection sources.
use_mode, the name of the slot of x containing the current usage mode,
in cases where there are multiple choices of which only one involves using information held in source.
An example would be ColorBy in DotPlots where coloring by feature name is only one of many options,
such that the panel should only respond to transmitted single selections when the user intends to color by feature name.
If this is NA, the usage mode is assumed to be such that the panel should always respond to transmissions.
use_value, a string containing the relevant value of the slot specified by use_mode in order for the panel to respond to transmitted single selections.
An example would be "Feature name" in DotPlots.
protected, a logical scalar indicating whether the slot specified by param is “protected”,
i.e., changing this value will cause all existing selections to be invalidated
and will trigger re-rendering of the children receiving multiple selections.
This is FALSE for purely aesthetic parameters (e.g., coloring) and TRUE for data-related parameters
(e.g., XAxisFeatureName in FeatureAssayPlot).
Aaron Lun