output-generics: Generics for Panel outputs
In csoneson/iSEE: Interactive SummarizedExperiment Explorer

output-generics

R Documentation

Generics for Panel outputs

Description

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 the iSEE app.
rObjects, a reactive list of values generated in the iSEE 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]]), where PANEL 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 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 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 printing 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 in x to be transmitted to other (child) panels. The app will ensure that the pObjects$contents of each panel is populated before attempting to render their children. contents may be set to NULL if x 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 SummarizedExperiment se and ExperimentColorMap colormap. It may also contain col_selected, if a multiple column selection is being transmitted to x; and possibly row_selected, if a multiple row selection is being transmitted to x.
varname, a string specifying the name of the variable in commands used to generate contents. This is used to fulfill code tracking obligations. If the current panel is not a transmitter, this may be set to NULL 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.