addPlots() adds custom plotting functions and plot metadata to an
OmicNavigator study.
addPlots(study, plots, reset = FALSE)Returns the original onStudy object passed to the argument
study, but modified to include the newly added data
An OmicNavigator study created with createStudy
A nested list containing custom plotting functions and plot
metadata. The input object is a 3-level nested list. The first, or
top-level list element name(s) must match the study modelID(s). The second,
or mid-level list element name(s) must match the names of the plotting
function(s) defined in the current R session (see Details below for
function construction requirements). The third, or bottom-level list
provides metadata to categorize, display, and support each plot. The
accepted fields are displayName, description, plotType, models, and
packages. displayName sets the plot name in the app and the description
field will display as a tool tip when hovering over plotting dropdown
menus. The plotType field is a character vector that categorizes the plot
by 1) the number of features it supports (“singleFeature” or
“multiFeature”), 2) the number of test results used by the plotting
function (“singleTest”, “multiTest”), 3) if data from one or more models is
used (add “multiModel” to specify that data from two or more models are
used in the plot; otherwise the plot is assumed to reference only data
within the model specified by the top-level list element name), and 4) if
the plot is interactive (add “plotly” to specify interactive plots built
using the plotly package; otherwise the plot is assumed to be static).
e.g., plotType = c("multiFeature", "multiTest", "plotly"). If you do not
specify the plotType, the plot will be designated as plotType = c("singleFeature", "singleTest"). The models field is an optional
character vector that specifies the models that should be used by the app
when invoking your custom plotting function. This field is set to ‘all’ by
default and is only used when plotType includes “multiModel”. If this field
is not included the app will assume all models in the study should be used
with your plotting function. If the plotting function requires additional
packages beyond those attached by default to a fresh R session, these must
be defined in the element packages. To share a plotting functions across
multiple models, use the modelID "default". Alternatively, to share a plot
across a specific subset of models, you can explicitly add the same
plotting function to each model (option available as of OmicNavigator
1.16.0).
Reset the data prior to adding the new data (default:
FALSE). The default is to add to or modify any previously added data
(if it exists). Setting reset = TRUE enables you to remove existing
data you no longer want to include in the study.
Custom plotting functions must be constructed to accept as the first argument
the value returned from getPlottingData(). Custom plotting functions can
have additional arguments, but these must be provided with default values.
The end-user should call getPlottingData() when testing their custom
plotting function. The end-user should consider the nature of the plot, i.e.
the plotType and (rarely) models values (see getPlottingData()). For
example, a custom plotting function meant to produce a multiTest plot
should accept the output of a getPlottingData() call with multiple
testIDs assigned to the testID argument. See the details section of
plotStudy() for a description of how plotType dictates the way a custom
plotting function is invoked by the app.
Note that any ggplot2 plots will require extra care. This is because the
plotting code will be inserted into a study package, and thus must follow the
best
practices for using ggplot2 within packages. Specifically, when you refer to
columns of the data frame, e.g. aes(x = group), you need to prefix it
with .data$, so that it becomes aes(x = .data$group).
Fortunately this latter code will also run fine as you interactively develop
the function.
Note that the plotting functions are written to the R package when the study
is exported via exportStudy or installed via
installStudy, not when addPlots is invoked. In other
words, if you add a custom plotting function to your study object via
addPlots, but then subsequently update the function in the global
environment prior to installing the study, this latest version will be saved
in the R package and executed when run in the app.
getPlottingData, plotStudy