addPlots: Add custom plotting functions

In OmicNavigator: Open-Source Software for 'Omic' Data Analysis and Visualization

Add custom plotting functions

Description

addPlots() adds custom plotting functions and plot metadata to an OmicNavigator study.

Usage

addPlots(study, plots, reset = FALSE)

Arguments

study	An OmicNavigator study created with createStudy
plots	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	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.

Details

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.

Value

Returns the original onStudy object passed to the argument study, but modified to include the newly added data

See Also

getPlottingData, plotStudy

OmicNavigator documentation built on Aug. 8, 2025, 7:22 p.m.