An overview of the generics for defining the panel outputs, along with recommendations on their implementation.
Defining the output element
.defineOutput(x)
defines the output element of the panel (e.g., a plot or table widget),
given an instance of a Panel subclass in x
.
Methods for this generic are expected to return a HTML element containing the visual output of the panel, such as the return value of plotOutput
or dataTableOutput
.
This element will be shown in the iSEE interface above the parameter boxes for x
.
Multiple elements can be returned 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.
Defining the rendered output
.renderOutput(x, se, ..., output, pObjects, rObjects)
will create an expression to render the panel's output.
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 theiSEE
app.rObjects
, a reactive list of values generated in theiSEE
app.
It is expected to attach one or more reactive expressions to output
to render the output element(s) defined by .defineOutput
.
This is typically done by calling shiny rendering functions like renderPlot
or the most appropriate equivalent for the panel's output.
The return value of this generic is not used; only the side-effect of the reactive output set-up is relevant.
The rendering expression inside the chosen rendering function is expected to:
Call
force(rObjects[[PANEL]])
, wherePANEL
is the output of.getEncodedName(x)
. This ensures that the output is rerendered upon requesting changes in.requestUpdate
.Call
.generateOutput
to generate the output content to be rendered.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 generatepObjects$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 inpObjects$commands[[PANEL]]
that holds the contents stored inpObjects$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 all of the tasks above, rather than calling .generateOutput
manually.
By doing so, the only extra work required of the rendering expression is to actually render the output (e.g., by print
ing a ggplot object).
Of course, the rendering expression must itself be encapsulated by an appropriate rendering function assigned to output
.
Developers should not attempt to modify x
in any rendering expression.
This does not have pass-by-reference semantics and any changes will not propagate to other parts of the application.
Similarly, the rendering expression should treat pObjects$memory
as read-only.
Any adjustment of parameters should be handled elsewhere, e.g., by the observer expressions in .createObservers
.
Generating content
.generateOutput(x, se, all_memory, all_contents)
actually generates the panel's output to be used in the rendering expression.
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). The values therein are used by.multiSelectionCommands
to determine the multiple row/column selection inx
to be transmitted to other (child) panels. The app will ensure that thepObjects$contents
of each panel is populated before attempting to render their children.contents
may be set toNULL
ifx
does not transmit, i.e.,.multiSelectionDimension
returns"none"
.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 SummarizedExperimentse
and ExperimentColorMapcolormap
. It may also containcol_selected
, if a multiple column selection is being transmitted tox
; and possiblyrow_selected
, if a multiple row selection is being transmitted tox
.varname
, a string specifying the name of the variable incommands
used to generatecontents
. This is used to fulfill code tracking obligations. If the current panel is not a transmitter, this may be set toNULL
instead.
The output list may contain any number of other fields that can be used by .renderOutput
but are otherwise 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.
A convenient wrapper for this call is provided by the .textEval
utility.
The all_memory
and all_contents
arguments are provided for the sole purpose of determining what multiple selections are being received by x
.
We strongly recommend passing them onto .processMultiSelections
to do the heavy lifting.
It would be unusual and inadvisable to use these arguments for any other information sharing across panels.
Exporting content
.exportOutput(x, se, all_memory, all_contents)
converts the panel output into a downloadable form.
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 converting the output into an appropriate file.