dittoVizModules

This package utilizes the dittoViz package to create interactivity-first Shiny modules for common plot types, designed to serve as building blocks for Shiny apps and as the basis for more complex/specialized modules.

These modules will contain all possible functionality from dittoViz with some additional parameters that make use of the interactive features of plotly, e.g. interactive text annotations, arbitrary shape annotations, multiple download formats, etc.

The modules provide comprehensive plot control for app users, allowing for convenient aesthetic customizations and publication-quality images. They also provide developers a way to dramatically save time and reduce complexity of their plotting code or a flexible base to build more specialized Shiny modules upon.

Install

Note that this package is in development and may break at any time.

Currently, the package can be installed from Github:

devtools::install_github("j-andrews7/dittoVizModules")

Using dittoVizModules

Including a dittoVizModules module in your Shiny application is simple. The package provides a function returning an example Shiny application for each module that showcases their functionality and how they can be used.

As an example, we can look at the createScatterPlotApp() function:

library(dittoVizModules)

createScatterPlotApp <- function(data_list) {
    # Validate input
    stopifnot(is.list(data_list))
    lapply(data_list, function(data) {
        stopifnot(is.data.frame(data))
    })

    # UI definition
    ui <- fluidPage(
        useShinyjs(),
        titlePanel("Modular scatterPlots"),
        sidebarLayout(
            sidebarPanel(
                # Add the module inputs UI for each data frame
                lapply(names(data_list), function(name) {
                    tagList(
                        scatterPlotInputsUI(name, data_list[[name]], title = h3(paste(name, "Settings"))),
                        hr()
                    )
                })
            ),
            mainPanel(
                # Add the module output UI for each data frame
                lapply(names(data_list), function(name) {
                    tagList(scatterPlotOutputUI(name), br())
                })
            )
        )
    )

    # Server function
    server <- function(input, output, session) {

        # Add the module server for each data frame
        lapply(names(data_list), function(name) {
            scatterPlotServer(name, data = reactive(data_list[[name]]))
        })
    }

    # Return the Shiny app
    shinyApp(ui, server)
}

data_list <- list("mtcars" = mtcars, "iris" = iris)
createScatterPlotApp(data_list)

Modules Provided

Currently, dittoVizModules contains a functional Shiny module for the following dittoViz visualization functions:

scatterPlot - x/y coordinate plots with additional color and shape encodings.

Modules Planned

This package is based on dittoViz and modules will be developed for all plot types generated by that package, including:

yPlot - box/violin/jitter plots.
scatterHex - hexbin plots encoding density/frequency information along x/y coordinates.
barPlot - compositional barplots.
freqPlot - box/jitter plots for discrete observation frequencies per sample/group.

dittoViz is under active development, so additional modules will be created as more visualization functions are added.

Contributing a New Module

To contribute a new module to the package, three files detailing the components & usage of the module must be added. Using the scatterPlot module as an example:

The module UI - where all inputs and outputs will be defined. The inputs and outputs should each be defined in their own function (scatterPlot_module_UI.R).
The module server function - where all server logic will be defined (scatterPlot_module_server.R).
A function to generate a basic example application using the module (scatterPlot_module_app.R).

Each function should be fully documented, all outputs should be plotly plots, default values for the UI inputs should be able to be provided via a named list, and UI inputs should be hideable.

In addition, tooltips matching the dittoViz parameter documentation (with any necessary associated edits to account for the input type) should be used for each input. Inputs supporting new functionality should also have descriptive tooltips indicating how they modify the plot.

See the scatterPlot module for how these things can be easily accomplished.

Superceded Functionality

Certain dittoViz parameters are more easily adjusted via the interactive features of plotly, e.g. axis labels, plot title, etc.

As such, inputs for such features need not be provided so long as the reason for their exclusion is included in the documentation of the module inputs UI function.

Missing/Broken Functionality

At times, there will be functionality or geoms that just can't be done in plotly, e.g. interactive ridgeplots that are available from dittoViz::yPlot().

Such missing or broken functionality should be clearly indicated in the module inputs UI function documentation. Inputs should not be generated for non-functional/broken parameters.

j-andrews7 / dittoVizModules

readme