update plotting manuals

DESCRIPTION

@@ -59,3 +59,4 @@ Suggests:
   ttdo (>= 0.0.6),
   UpSetR
 RoxygenNote: 7.3.1
+Roxygen: list(markdown = TRUE)

NEWS.md

@@ -1,3 +1,5 @@
+* Update getPlottingData, plotStudy, and addPlots manuals
+
 # 1.13.22
 
 * The release tarball includes version 1.9.4 of the web app

R/add.R

@@ -363,18 +363,20 @@ addMetaFeatures <- function(study, metaFeatures, reset = FALSE) {
 
 #' Add custom plotting functions
 #'
-#' Include custom plots that the app will display when a feature is selected by
-#' the user.
-#'
-#' Custom plotting functions are passed a list of data frames: \code{assays}
-#' with the measurements, \code{features} with the feature data,
-#' \code{samples} with the sample data, and \code{results} with test results
-#' data. Note that \code{assays}, \code{features} and \code{results}
-#' only include data for the specified featureID(s) (and
-#' re-ordered so their rows match). Thus your custom plotting function must have
-#' at least one argument. It can have additional arguments if you wish, but
-#' these must be provided with default values, because \code{plotStudy} only
-#' passes the plotting data to the first argument.
+#' `addPlots()` adds custom plotting functions and plot metadata to an
+#' OmicNavigator 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
+#' `testID`s 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
@@ -385,21 +387,36 @@ addMetaFeatures <- function(study, metaFeatures, reset = FALSE) {
 #' Fortunately this latter code will also run fine as you interactively develop
 #' the function.
 #'
-#' @param plots Custom plotting functions for the study. The input object is a
-#'   nested list. The first list corresponds to the modelID(s). The second list
-#'   corresponds to the name(s) of the function(s) defined in the current R
-#'   session. The third list provides metadata to describe each plot. The only
-#'   required metadata element is \code{displayName}, which controls how the
-#'   plot will be named in the app. You are encouraged to also specify the
-#'   \code{plotType}, e.g. \code{"singleFeature"}, \code{"multiFeature"},
-#'   \code{"multiTest"}, \code{"multiModel"}. PlotType accepts vector of
-#'   entries, whenever applicable, e.g., plotType = c(\code{"multiFeature"},
-#'   \code{"multiTest"}). If you do not specify the \code{plotType}, the plot
-#'   will be assumed to be \code{"singleFeature"} and \code{"singleTest"}.
-#'   Optionally, if the plotting function requires external packages, these can
-#'   be defined in the element \code{packages}. To share plots across multiple
-#'   models, use the modelID "default". To add a plotting function that returns
-#'   an interactive plotly plot, add "plotly" to the \code{plotType} vector.
+#' @param 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`.
+#'
 #' @inherit shared-add
 #'
 #' @seealso \code{\link{getPlottingData}}, \code{\link{plotStudy}}

R/plots.R

@@ -1,22 +1,52 @@
-#' Plot a feature using a custom plotting function
+#'Invoke a custom plotting function
 #'
-#' @inheritParams shared-get
-#' @inheritParams listStudies
+#'`plotStudy()` invokes a custom plotting function saved within an OmicNavigator
+#'study. This function is called by the app using the study-model-test
+#'selection, feature selections, and plotting function metadata (see
+#'[addPlots()]) to define arguments.
 #'
-#' @details The arguments \code{study}, \code{modelID}, \code{featureID}, and
-#' \code{testID} are passed to the function \code{\link{getPlottingData}}, and
-#' the nested list returned by this function is passed as the first argument to
-#' your custom plotting function.
+#'@inheritParams shared-get
+#'@inheritParams listStudies
 #'
-#' @return This function is called for the side effect of creating a plot. It
-#'   invisibly returns the result from the custom plotting function specified by
-#'   \code{plotID}. Previously it invisibly returned the study object. It's
-#'   unlikely you relied on this behavior. For a ggplot2 plot, the return value
-#'   will be the plotting object with class \code{"ggplot"}.
+#'@details The arguments \code{study}, \code{modelID}, \code{featureID}, and
+#'  `testID` are passed to the function [getPlottingData()]. The list returned
+#'  by `getPlottingData()` is passed as the first argument to a custom plotting
+#'  function. Some custom `plotTypes` (see [addPlots()]) require care when being
+#'  invoked and attention should be paid to how a custom plot will be rendered
+#'  by the app. Custom plots with `plotType = c(‘multiModel’, ‘singleTest’)`
+#'  accept a `modelID` vector of length n and a vector of `testID`s length n,
+#'  where n is the number of models. Custom plots with `plotType =
+#'  c(‘multiModel’, ‘multiTest’)` accept `modelID` and `testID` vectors of
+#'  length m, where m is the total number of tests considered across all models
+#'  (note `testID`s are often repeated across models). Note that the index
+#'  positions of these two vectors should correspond. That is, `testID` position
+#'  1 should be found in the model specified by `modelID` position 1, etc.
 #'
-#' @seealso \code{\link{addPlots}}, \code{\link{getPlottingData}}
+#'  The app will invoke custom plotting functions via `plotStudy()` using the
+#'  current menu selections and plot metadata (see [addPlots()]). Plots with
+#'  `plotType = ‘multiTest’` will be invoked with all `testID`s found within the
+#'  currently selected model. Plots with `plotType =
+#'  c(‘multiModel’,‘singleTest’)` will be invoked with all `modelID`s within the
+#'  study (unless the plot has specified a list of models via `models`) and the
+#'  currently selected `testID` (an error will result if the currently selected
+#'  `testID` is not present in all relevant models for the plot). Plots with
+#'  `plotType = c(‘multiModel’, ‘multiTest’)` will be invoked with all
+#'  `modelID`s within the study (unless the plot has specified a list of models
+#'  via `models`) and all identical `testID`s across models (if there are no
+#'  matching testIDs across models an error will result).
 #'
-#' @export
+#'@return
+#'
+#'  This function is called for the side effect of creating a plot. It invisibly
+#'  returns the result from the custom plotting function specified by `plotID`.
+#'  Previously it invisibly returned the study object. It's unlikely you relied
+#'  on this behavior. For a ggplot2 plot, the return value will be the plotting
+#'  object with class `"ggplot"`. For a plotly plot, the return value will be
+#'  the json schema used for plotting with class `“json”`.
+#'
+#'@seealso \code{\link{addPlots}}, \code{\link{getPlottingData}}
+#'
+#'@export
 plotStudy <- function(study, modelID, featureID, plotID, testID = NULL, libraries = NULL) {
   stopifnot(
     is.character(modelID),
@@ -253,18 +283,38 @@ getMappingPlottingData <- function(study = study, modelID = modelID, featureID =
   )
 }
 
-#' Get plotting data
+#'Get plotting data from an OmicNavigator study
+#'
+#'Returns `assay`, `sample`, `feature`, and `result` data that may be used for
+#'plotting. This function is called by `plotStudy()` and the output is passed to
+#'custom plotting functions. It should be used directly when interactively
+#'creating custom plotting functions.
 #'
-#' This function creates the input data that \code{\link{plotStudy}} passes to
-#' custom plotting functions added with \code{\link{addPlots}}. You can use it
-#' directly when you are interactively creating your custom plotting functions.
-#' Note that for multiModel plots testID is required to be a named vector, with
-#' each testID named after the related modelID.
+#'The end-user should call this function and populate the first argument of
+#'their custom plotting function with the output. When building functions, the
+#'end-user should understand the category of plotting function they are creating
+#'(e.g. `singleFeature` or `multiFeature`, see [addPlots()]) and call
+#'`getPlottingData()` accordingly.
 #'
-#' @inheritParams shared-get
-#' @inheritParams listStudies
+#'Custom plots that accept data from multiple models and a single test
+#'(`plotType = c(‘multiModel’, ‘singleTest’)`; see [addPlots()]) should be built
+#'to accept output from `getPlottingData()` where `modelID` is vector of length
+#'n and `testID` is a vector of length n, where n is the number of models.
+#'Custom plots that accept data from multiple models and multiple tests
+#'(`plotType = c(‘multiModel’, ‘multiTest’)`) should be built to accept output
+#'from `getPlottingData()` where `modelID` and `testID` vectors are length m,
+#'where m is the total number of tests considered across all models (note that
+#'`testID`s must be repeated across models for the plotting function to work in
+#'the app). The index positions of these two vectors should correspond. That is,
+#'`testID` position 1 should be found in the model specified by `modelID`
+#'position 1, etc. See [addPlots()] for information about the assignment of
+#'`plotTypes` for your custom plots.
 #'
-#' @return Returns a list of 4 data frames:
+#'
+#'@inheritParams shared-get
+#'@inheritParams listStudies
+#'
+#'@return Returns a list of at least 4 objects:
 #'
 #' \item{\code{assays}}{A data frame that contains the assay measurements,
 #' filtered to only include the row(s) corresponding to the input featureID(s)
@@ -288,17 +338,15 @@ getMappingPlottingData <- function(study = study, modelID = modelID, featureID =
 #' order of this input. The column order is unchanged. If multiple testIDs are
 #' provided, they are stored in a list object.}
 #'
-#' The data frame \code{results} is only returned if you pass a testID. By
-#' default the app will always pass the currently selected testID. To make
-#' \code{results} a list of data frames (one for each testID for the currently
-#' selected modelID), set the plotType to be "multiTest" when adding the plot
-#' with \code{\link{addPlots}}. For "multiModel" plots, testID and modelID
-#' should be vectors of same length, where the index position indicate which
-#' test in testID relate to which model in modelID.
+#' \item{\code{mapping}}{A data frame that contains the featureID(s) from each
+#' model. This is the filtered mapping object. This data frame is returned when multiple models are passed as arguments}
+#'
+#'  The data frame \code{results} is only returned if you pass a testID. By
+#'  default the app will always pass the currently selected testID.
 #'
-#' @seealso \code{\link{addPlots}}, \code{\link{plotStudy}}
+#'@seealso \code{\link{addPlots}}, \code{\link{plotStudy}}
 #'
-#' @export
+#'@export
 getPlottingData <- function(study, modelID, featureID, testID = NULL, libraries = NULL) {
   stopifnot(
     is.character(modelID),