output-generics {iSEE} | R Documentation |
An overview of the generics for defining the panel outputs, along with recommendations on their implementation.
In .defineOutput(x, ...)
, the following arguments are required:
x
, an instance of a Panel subclass.
...
, further arguments that are not currently used.
Methods for this generic are expected to return an output element for inclusion into the iSEE interface, such as the output of plotOutput
.
Multiple elements can be provided via a tagList
.
The IDs of the output elements are expected to be prefixed with the panel name from .getEncodedName(x)
and an underscore, e.g., "ReducedDimensionPlot1_someOutput"
.
One of the output elements may simply have the ID set to PANEL
alone;
this is usually the case for simple panels with one primary output like a DotPlot.
In .renderOutput(x, se, ..., output, pObjects, rObjects)
, the following arguments are required:
x
, an instance of a Panel class.
se
, a SummarizedExperiment object containing the current dataset.
...
, further arguments that may be used by specific methods.
output
, the Shiny output object from the server function.
pObjects
, an environment containing global parameters generated in the iSEE
app.
rObjects
, a reactive list of values generated in the iSEE
app.
It is expected to attach a reactive expression to output
to render the output elements created by .defineOutput
.
The return value of this generic is not used; only the side-effect of the output set-up is relevant.
The rendering expression defined in .renderOutput
is also expected to:
Call force(rObjects[[PANEL]])
, where PANEL
is the output of .getEncodedName(x)
.
This ensures that the output is rerendered upon requesting changes in .requestUpdate
.
Fill pObjects$contents[[PANEL]]
with some content related to the displayed output that allows cross-referencing with single/multiple selection structures.
This will be used in other generics like .multiSelectionCommands
and .singleSelectionValue
to determine the identity of the selected point(s).
As a result, it is only strictly necessary if the panel is a potential transmitter, as determined by the return value of .multiSelectionDimension
.
Fill pObjects$commands[[PANEL]]
with a character vector of commands required to produce the displayed output.
This should minimally include the commands required to generate pObjects$contents[[PANEL]]
;
for plotting panels, the vector should also include code to create the plot.
Fill pObjects$varname[[PANEL]]
with a string containing the R expression in pObjects$commands[[PANEL]]
that holds the contents stored in pObjects$contents[[PANEL]]
.
This is used for code reporting, and again, is only strictly necessary if the panel is a potential transmitter.
We strongly recommend calling .retrieveOutput
within the rendering expression,
which will automatically perform tasks 1-3 above, rather than calling .generateOutput
manually.
This means that the only extra work required in the implementation of .renderOutput
is to perform task 4 and
to choose an appropriate rendering function.
In .generateOutput(x, se, all_memory, all_contents)
, the following arguments are required:
x
, an instance of a Panel class.
se
, a SummarizedExperiment object containing the current dataset.
all_memory
, a named list containing Panel objects parameterizing the current state of the app.
all_contents
, a named list containing the contents of each panel.
Methods for this generic should return a list containing:
contents
, some arbitrary content for the panel (usually a data.frame).
This is used during app initialization to ensure that pObjects$contents
of transmitter panels is filled before rendering their children.
It should be of a structure that allows it to be cross-referenced against the output of .multiSelectionActive
to determine the selected rows/columns.
commands
, a list of character vectors of R commands that, when executed, produces the contents of the panel and any displayed output (e.g., a ggplot object).
Developers should write these commands as if the evaluation environment only contains the SummarizedExperiment se
and ExperimentColorMap colormap
.
The output list may contain any number of other fields that will be ignored.
We suggest implementing this method using eval(parse(text=...))
calls,
which enables easy construction and evaluation of the commands and contents at the same time.
Developers should consider using the .processMultiSelections
function for easily processing the multiple selection parameters.
In .exportOutput(x, se, all_memory, all_contents)
, the following arguments are required:
x
, an instance of a Panel class.
se
, a SummarizedExperiment object containing the current dataset.
all_memory
, a named list containing Panel objects parameterizing the current state of the app.
all_contents
, a named list containing the contents of each panel.
Methods for this generic should generate appropriate files containing the content of x
.
(For example, plots may create PDFs while tables may create CSV files.)
All files should be created in the working directory at the time of the function call, possibly in further subdirectories.
Each file name should be prefixed with the .getEncodedName
.
The method itself should return a character vector containing relative paths to all newly created files.
To implement this method, we suggest simply passing all arguments onto .generateOutput
and then handling the contents appropriately.
Aaron Lun