Package 'VizModules'

Description

Creates shape specifications for one or more diagonal lines defined by slope and intercept. Lines are drawn across the provided or computed axis range.

Usage

add_ablines(
  fig,
  slopes,
  intercepts,
  colors = "#000000",
  widths = 1,
  linetypes = "solid",
  opacities = 1
)

Arguments

Details

If style vector lengths don't match the number of lines, only the first value of each style vector is used for all lines. If slopes and intercepts have different lengths, the shorter one is recycled. When the figure contains subplots (e.g., from faceting), lines are replicated across all panels with correct axis references.

Value

A list of shape specifications for use with plotly::layout().

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
add_ablines(fig, slopes = 1, intercepts = 0, colors = "red")

Description

Creates shape specifications for one or more horizontal lines at specified y-intercepts. Supports independent styling for each line.

Usage

add_hlines(
  fig,
  intercepts,
  colors = "#000000",
  widths = 1,
  linetypes = "solid",
  opacities = 1
)

Arguments

Details

If style vector lengths don't match the number of intercepts, only the first value of each style vector is used for all lines. When the figure contains subplots (e.g., from faceting), lines are replicated across all panels with correct axis references.

Value

A list of shape specifications for use with plotly::layout().

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
add_hlines(fig, intercepts = c(20, 30), colors = c("red", "blue"))

Description

Constructs a configuration list for Plotly plots, enabling interactive editing of titles and legends, export options, and additional drawing tools in the modebar.

Usage

add_plot_config(
  download.format = "png",
  filename = as.character(Sys.Date()),
  include.modebar.buttons = TRUE,
  facet.by = NULL
)

Arguments

Details

The configuration enables interactive editing of the plot title, legend text and position, colorbar position and title, and annotation tails. It also adds drawing tools (lines, paths, circles, rectangles, and an eraser) to the modebar. Native cartesian axis-title text editing is disabled because axis titles are rendered as draggable, editable annotations (see axis_titles_as_annotations() and build_facet_annotations()).

When the figure is faceted, plot title editing is disabled too. An empty editable title still draws plotly's "Click to enter Plot title" placeholder, which sits on top of the facet panel titles and swallows clicks meant for them.

Value

A named list suitable for use as the config argument in Plotly calls, containing edit options, image download settings, extra modebar buttons, and logo display preferences.

Author(s)

Jacob Martin

Examples

add_plot_config()
add_plot_config(download.format = "svg", include.modebar.buttons = FALSE)

Description

Convenience wrapper that adds horizontal, vertical, and/or diagonal lines to a plotly figure based on parsed Shiny input values.

Usage

add_reference_lines(
  fig,
  hline.intercepts = NULL,
  hline.colors = NULL,
  hline.widths = NULL,
  hline.linetypes = NULL,
  hline.opacities = NULL,
  vline.intercepts = NULL,
  vline.colors = NULL,
  vline.widths = NULL,
  vline.linetypes = NULL,
  vline.opacities = NULL,
  abline.slopes = NULL,
  abline.intercepts = NULL,
  abline.colors = NULL,
  abline.widths = NULL,
  abline.linetypes = NULL,
  abline.opacities = NULL
)

Arguments

Value

The modified plotly figure with all specified lines added.

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
add_reference_lines(fig,
    hline.intercepts = "20, 30", hline.colors = "red, blue",
    vline.intercepts = "3", abline.slopes = "5", abline.intercepts = "0"
)

Description

Creates shape specifications for one or more vertical lines at specified x-intercepts. Supports independent styling for each line.

Usage

add_vlines(
  fig,
  intercepts,
  colors = "#000000",
  widths = 1,
  linetypes = "solid",
  opacities = 1
)

Arguments

Details

If style vector lengths don't match the number of intercepts, only the first value of each style vector is used for all lines. When the figure contains subplots (e.g., from faceting), lines are replicated across all panels with correct axis references.

Value

A list of shape specifications for use with plotly::layout().

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
add_vlines(fig, intercepts = c(3, 4), colors = c("red", "blue"))

Description

Transforms the named numeric columns of a data frame the way the plot modules do for their adjustment inputs, adding the transformed values as a new column (original column name + ".adj"). The function is applied first, then an adjustment ("z-score" or "relative.to.max") rescales the result, computed over its finite values. The function name must be one of the allowed functions listed in safe_resolve_adj_fxn() (e.g., "log2", "log10", "sqrt", "abs", "as.factor"). The original data frame is returned unchanged if no transformation is specified or if the supplied function name is invalid.

Usage

adjust_column_values(
  df,
  x.col = NULL,
  y.col = NULL,
  color.col = NULL,
  x.adj.fun = NULL,
  y.adj.fun = NULL,
  color.adj.fun = NULL,
  x.adjustment = NULL,
  y.adjustment = NULL,
  color.adjustment = NULL
)

Arguments

Details

Use this to compute anything drawn over an adjusted plot (axis limits, bracket headroom, fit lines) from the values the plot actually shows, rather than the raw column. Note that dittoViz, given both an ⁠*.adjustment⁠ and an ⁠*.adj.fxn⁠, applies them in the opposite order; the modules pass it the whole transform as its function instead.

Value

A data frame identical to input df but with transformed columns added (e.g., mpg.adj) when valid transformations are specified.

Author(s)

Jacob Martin, Jared Andrews

Examples

data(mtcars)
mtcars_mod <- adjust_column_values(mtcars, x.col = "mpg", x.adj.fun = "log2")
head(mtcars_mod$mpg.adj)

# log10 first, then z-scored: the values the scatter module draws for that pair
mtcars_z <- adjust_column_values(mtcars,
    x.col = "hp", x.adj.fun = "log10", x.adjustment = "z-score"
)
range(mtcars_z$hp.adj)

Description

Wraps a base column name with the names of any data adjustments that are applied to it before plotting, so that an axis title accurately describes the values displayed. The wrapping order mirrors how the modules apply the adjustments (the adj.fxn first, then the recognized adjustment rescales the result), producing labels such as "z-score(log2(units))".

Usage

adjusted_axis_label(base, adjustment = NULL, adj.fxn = NULL)

Arguments

Details

Empty strings, NA, and NULL adjustments are ignored, so when no adjustment is requested the base label is returned unchanged.

Value

A character scalar containing the (possibly wrapped) axis label.

Author(s)

Jared Andrews

Examples

adjusted_axis_label("units")
adjusted_axis_label("units", adjustment = "z-score")
adjusted_axis_label("units", adjustment = "z-score", adj.fxn = "log2")

Description

When ggplotly converts a faceted ggplot, shared axis titles become annotations rather than axis title properties. This function finds those shared title annotations and applies the user's axis title font settings to them.

Usage

apply_axis_title_to_annotations(fig, input, isolate_fn = isolate)

Arguments

Value

The modified plotly figure with updated annotation fonts.

Author(s)

Jacob Martin

Examples

## Not run: 
p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
    ggplot2::geom_point() +
    ggplot2::facet_wrap(~cyl)
fig <- plotly::ggplotly(p)
input <- list(
    axis.title.font.size = 14, axis.title.font.family = "Arial",
    axis.title.font.color = "black", facet.title.font.size = 12,
    facet.title.font.family = "Arial", facet.title.font.color = "black"
)
apply_axis_title_to_annotations(fig, input, isolate_fn = identity)

## End(Not run)

Description

ggplotly() assigns panel layout via plotly domain coordinates (⁠fig$x$layout$xaxis*/yaxis*$domain⁠) rather than honouring the ggplot2 panel.spacing theme option. This helper rewrites those domains so that each facet panel has a uniform size and the gap between panels is exactly spacing (expressed as a fraction of the plot area, e.g. 0.04).

Usage

apply_facet_subplot_spacing(fig, spacing = 0.04, ncol = NULL, nrow = NULL)

Arguments

Details

In addition to the axis domains, any paper-anchored layout annotations (e.g. facet strip titles) and shapes (e.g. strip backgrounds, panel borders) are remapped through a piecewise-linear transform built from the old and new domain intervals, so strip labels and panel borders move with their panels. Annotations/shapes whose xref/yref is tied to an axis (for example "x", "y2", or "x2 domain") are left alone because they follow the rewritten axis automatically.

The number of columns and rows can be supplied manually, or detected automatically from the distinct x / y domain starts already present in the ggplotly output.

Value

The modified plotly figure with rewritten axis domains and remapped paper-anchored annotations/shapes. Figures with a single panel (or no layout) are returned unchanged.

Author(s)

Jacob Martin

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
    ggplot2::geom_point() +
    ggplot2::facet_wrap(~cyl)
fig <- plotly::ggplotly(p)
apply_facet_subplot_spacing(fig, spacing = 0.05)

Description

Reads the inputs created by uniform_legend_inputs_ui() (legend.show, legend.font.family, legend.font.color, legend.title.size and legend.text.size) and applies them with apply_legend_styling(). An input that has not reported yet (NULL) leaves its property unchanged, so the legend stays visible until legend.show is FALSE.

Usage

apply_legend_inputs(fig, input, isolate_fn = isolate)

Arguments

Value

The plotly figure with the legend inputs applied.

Author(s)

Jared Andrews

See Also

uniform_legend_inputs_ui(), reset_legend_inputs(), apply_legend_styling()

Examples

fig <- plotly::plot_ly(iris,
    x = ~Sepal.Length, y = ~Sepal.Width,
    color = ~Species, type = "scatter", mode = "markers"
)
legend_input <- list(
    legend.show = TRUE, legend.font.family = "Courier New", legend.font.color = "#333333",
    legend.title.size = 16, legend.text.size = 12
)
apply_legend_inputs(fig, legend_input, isolate_fn = identity)

Description

Shows or hides the legend and sets the font family, color and sizes of its title and entry labels, so the "Legend" UI inputs behave consistently across plot types. Existing legend settings (orientation, position, and any font property not supplied) are preserved because plotly::layout() merges the supplied attributes into the current layout. NULL, NA or blank values are ignored, leaving the corresponding property untouched.

Usage

apply_legend_styling(
  fig,
  title.size = NULL,
  text.size = NULL,
  position = NULL,
  font.family = NULL,
  font.color = NULL,
  show = NULL
)

Arguments

Details

Numeric colour mappings (for example fill.by/color.by on a continuous variable) are rendered as a colorbar rather than a categorical legend. The layout-level legend font and visibility do not affect a colorbar, so the colorbar title and tick fonts are updated directly on each trace (and on any shared coloraxis) using the same values, and hiding the legend turns each colorbar's showscale off. This keeps the "Legend" controls functional for both categorical and continuous legends.

Value

The plotly figure with the requested legend styling applied. Returns the figure unchanged when fig is NULL or nothing valid is supplied.

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(iris,
    x = ~Sepal.Length, y = ~Sepal.Width,
    color = ~Species, type = "scatter", mode = "markers"
)
apply_legend_styling(fig, title.size = 16, text.size = 10, font.family = "Courier New")
apply_legend_styling(fig, show = FALSE)

Description

Applies user-drawn shape styling to a Plotly figure using inputs from uniform_plotly_inputs_ui(). Updates the newshape layout property to style shapes drawn with Plotly's drawing tools (rectangles, circles, lines, etc.) in the modebar.

Usage

apply_plotly_newshape(fig, input, isolate_fn = isolate)

Arguments

Value

The modified plotly figure with updated newshape layout settings.

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
shape_input <- list(
    shape.fill = "#ff000030", shape.line.color = "#ff0000",
    shape.line.width = 2, shape.linetype = "solid", shape.opacity = 0.5
)
apply_plotly_newshape(fig, shape_input, isolate_fn = identity)

Description

The renderPlotly block in every plot module server applies the same user-configurable margins. This helper extracts that block into one call.

Usage

apply_render_margins(fig, input)

Arguments

Value

The plotly figure with margins applied.

Author(s)

Jacob Martin

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
input <- list(margin.t = 40, margin.b = 40, margin.l = 40, margin.r = 40)
apply_render_margins(fig, input)

Description

Appends the shapes and annotations from create_stat_annotations() to an existing plotly figure's layout, raising the y-axis top when the brackets need more room than the requested range gives them.

Usage

apply_stat_annotations(fig, stat_result, y.min = NULL, y.max = NULL)

Arguments

Details

The axis is only ever raised, never lowered: a top asked for through y.max (or already on the figure) is kept when it is above the brackets, so turning statistics on cannot silently undo a y-axis maximum the user chose. Reserve the room up front with stat_bracket_y_max() and this becomes a no-op.

When stat_result came from create_stat_annotations(free.y = TRUE), each panel's y-axis is raised to fit its own brackets and keeps its own bottom, and y.min/y.max are ignored: a single limit shared by every panel would undo the free scale.

The range is written straight into the figure's layout. Anything later queued with plotly::layout() that sets the axis range will still override it when the figure is built.

Value

The modified plotly figure.

Author(s)

Jared Andrews

Examples

stats_df <- compute_pairwise_stats(
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    test = "wilcox.test"
)
fig <- plotly::plot_ly(
    data = example_iris, x = ~Species, y = ~Sepal.Length, type = "box"
)
stat_result <- create_stat_annotations(
    stats_df = stats_df,
    fig = fig,
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    display = "symbol"
)
apply_stat_annotations(fig, stat_result)

Description

When using plotly subplots (e.g., via split.by in dittoViz), axis styling must be applied to all subplot axes (xaxis, xaxis2, xaxis3, etc.) individually. This helper function detects how many subplots exist and applies the provided axis styling to all of them.

Usage

apply_subplot_axis_styling(fig, xaxis_style, yaxis_style)

Arguments

Details

The styling is queued with plotly::layout(), which merges it into each axis when the figure is built, so the axes' other properties (range, domain, title text, ...) are kept. Only the styling is queued, never a copy of the axis as it stands, so a property written to the figure's layout after this call (such as a range raised by apply_stat_annotations()) is not reverted at build time.

Value

The modified plotly figure with axis styling applied to all subplots.

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
xaxis_style <- list(showline = TRUE, linecolor = "black", linewidth = 1)
yaxis_style <- list(showline = TRUE, linecolor = "black", linewidth = 1)
apply_subplot_axis_styling(fig, xaxis_style, yaxis_style)

Description

Applies title font settings from the Shiny input object to an existing plotly figure. The title is centered horizontally and positioned using the supplied title_y value in the plotly layout.

Usage

apply_title_layout(plot, input, isolate_fn, title_y = 0.95, title_x = 0.5)

Arguments

Value

The modified plotly figure with updated title styling.

Author(s)

Jacob Martin

Examples

## Not run: 
p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point()
input <- list(
    title.font.size = 16, title.font.family = "Arial", title.font.color = "black"
)
apply_title_layout(p, input, isolate_fn = identity)

## End(Not run)

Description

Plotly's native axis titles can have their text edited interactively but cannot be dragged to a new position. Faceted figures already render their shared x/y axis titles as paper-anchored annotations (via build_facet_annotations()), which the plot configuration makes both editable and draggable. This helper brings the same behaviour to single-panel (non-faceted) figures by replacing the native x/y axis titles with equivalent paper-anchored annotations.

Usage

axis_titles_as_annotations(fig)

Arguments

Details

The figure is first built with plotly::plotly_build() so that titles assigned via layout() (which are otherwise held in layoutAttrs until build time) are consolidated into the layout. Any pre-existing annotations (for example statistical brackets or facet labels) are preserved, and the font already applied to each native axis title is carried over to the corresponding annotation.

Multi-panel figures (faceting or split.by, detected by the presence of secondary axes such as xaxis2/yaxis2) are returned unchanged, since their shared titles are already draggable annotations.

Value

The plotly figure with single-panel axis titles converted to paper-anchored, draggable annotations. Returns the figure unchanged when it is faceted/split or has no axis titles.

Author(s)

Jared Andrews

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
fig <- plotly::layout(fig, xaxis = list(title = "Weight"), yaxis = list(title = "MPG"))
axis_titles_as_annotations(fig)

Description

Creates a list of plotly annotation objects suitable for labelling faceted subplots arranged in a grid of nrows rows. When nrows = 1 (the default) the behaviour matches the previous single-row layout. Optionally appends a shared X-axis title (bottom centre) and a shared, rotated Y-axis title (left centre).

Usage

build_facet_annotations(
  facet_levels,
  x.title = NULL,
  y.title = NULL,
  title.font.size = 14,
  nrows = 1,
  fig = NULL,
  title.offset = 0.02,
  axis.title.font = NULL,
  facet.title.font = NULL
)

Arguments

Value

A list of annotation lists suitable for plotly::layout(annotations = ...).

Author(s)

Jared Andrews

Examples

build_facet_annotations(c("A", "B", "C"), x.title = "X", y.title = "Y")

Description

Native plotly subplot() figures with shared (shareX/shareY) axes do not render axis border lines on the matched/inner panels, so faceted plots end up with a box around only the first panel. This helper reconstructs each panel's rectangle from the grid of x/y axis domains in the figure layout and returns paper-anchored shapes that draw a uniform border around every panel.

Usage

build_facet_panel_borders(
  fig,
  n_facets,
  showline = TRUE,
  mirror = TRUE,
  linecolor = "black",
  linewidth = 0.5,
  ncol = NULL,
  nrow = NULL
)

Arguments

Details

Panel rectangles are derived from the geometry of the subplot grid rather than from a per-panel axis index. With shared axes plotly only keeps one axis per column (x) and one per row (y), so an ⁠xaxis{i}⁠/⁠yaxis{i}⁠ lookup keyed on the facet index breaks down for grids with more than one row or column. Instead the distinct x-axis domain starts define the columns (left to right) and the distinct y-axis domain starts define the rows (top to bottom), and each facet panel is mapped to a (row, column) cell in row-major fill order — matching how subplot() lays panels out.

The borders honour the same axis styling semantics used for single-panel figures:

• showline and mirror both TRUE: full rectangle border around each panel.

• only showline TRUE: left and bottom edges only.

• showline FALSE: no borders (empty list).

Value

A list of plotly shape definitions (each paper-anchored). Returns an empty list when borders should not be drawn or panel domains cannot be resolved.

Author(s)

Jacob Martin

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
    ggplot2::geom_point() +
    ggplot2::facet_wrap(~cyl)
fig <- plotly::ggplotly(p)
build_facet_panel_borders(fig, n_facets = 3)

Description

Constructs the merged row_spec for multiDynamicInput() by combining the standard model fields (model_type, formula, line_colour, line_width) with any extra fields declared by registered backends. Each backend field is tagged with data-backend so the client can show/hide it based on the selected model type.

Usage

build_model_row_spec()

Value

A named list suitable for the row_spec argument of multiDynamicInput().

Author(s)

Jacob Martin

Examples

build_model_row_spec()

Description

Internal helper function that validates and sanitizes a numeric value intended for use as a facet dimension (rows or columns) in a ggplot2 faceting layout. Ensures the value is a positive numeric greater than or equal to 1, returning NULL for invalid inputs to gracefully handle missing or malformed facet specifications.

Usage

clean_facet_dim(val)

Arguments

Details

This function is used within VizModules lineplot functions to process user-supplied facet dimensions before passing to facet_grid() or facet_wrap(). Invalid values trigger sensible defaults rather than breaking the plot layout. Valid inputs return unchanged. Invalid inputs (NULL, NA, non-numeric, < 1) return NULL.

Value

numeric(1) or NULL Validated facet dimension value, or NULL if invalid.

Author(s)

Jacob Martin

Examples

clean_facet_dim(3)
clean_facet_dim(NA)
clean_facet_dim(NULL)

Description

Collects the plot object, its underlying data, statistical testing details (if applied), and optional UI input values into a single list for downstream download generation.

Usage

collect_source_data(
  plot_reactive,
  stats_reactive = NULL,
  inputs_reactive = NULL
)

Arguments

Details

plot_data is scoped down from the plot's full source data.frame (as returned by plotly::plotly_data()) in two ways:

• Columns are limited to those actually mapped in the plot (x, y, color/fill, shape, size, labels/values, facets, etc.), detected by inspecting the built plotly figure's trace attributes and, for columns that don't survive conversion to plotly (namely split.by/facet.by), the UI input values.

• Rows are limited to those with complete data across the detected columns, since rows with NA in a plotted aesthetic are dropped by the underlying plotting functions.

If no plotted columns can be detected, the full source data.frame is returned unchanged.

Value

A named list with elements:

plot

The plotly plot object.

plot_data

A data.frame of the plot's underlying data, limited to the columns and rows actually rendered (see Details).

stats

A data.frame of statistical test results, or NULL.

inputs

A data.frame of UI input names and values, or NULL.

Author(s)

Jacob Martin, Jared Andrews

Examples

## Not run: 
# Example usage in a Shiny app
library(shiny)
library(plotly)
library(VizModules)

ui <- fluidPage(
    plotlyOutput("my_plot"),
    downloadButton("download_data", "Download Plot and Data")
)

server <- function(input, output) {
    plot_reactive <- reactive({
       plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers")
    })

    output$my_plot <- renderPlotly(plot_reactive())
    # collect_source_data() reads reactives, so it has to run inside one.
    inputs_reactive <- reactive(reactiveValuesToList(input))
    output$download_data <- create_source_download_handler(
        reactive(collect_source_data(plot_reactive, inputs_reactive = inputs_reactive))
    )
}

shinyApp(ui, server)

## End(Not run)

Description

This function generates a Shiny application with modular ComplexHeatmap::Heatmap() components rendered interactively via InteractiveComplexHeatmap. The app features a Data Import section for uploading data, a Data Table for filtering the active dataset, and a Plot area for configuring and displaying the interactive heatmap.

Usage

ComplexHeatmap_HeatmapApp(
  data_list = NULL,
  column_data = NULL,
  defaults = NULL,
  hide.inputs = NULL,
  hide.tabs = NULL
)

Arguments

Details

When neither data_list nor column_data is provided, the app launches on the bundled pair — example_heatmap_matrix (a simulated gene x sample expression matrix) together with example_heatmap_column_data (its per-sample metadata), with column_key seeded to "sample". The column-annotation, column-split, and column-filter features are all inert without a metadata table, so this way a bare ComplexHeatmap_HeatmapApp() demonstrates the whole module.

Either way the app has the usual Data Import section for uploading data and a Data Table for filtering the active dataset. Filtering applies to the matrix; any companion metadata table rides along untouched. Uploaded data files are added to the available datasets and can be selected for plotting. If an uploaded file shares a name with an existing dataset, the existing one is overwritten with a warning.

Unlike the other modules, this one depends on the Bioconductor packages ComplexHeatmap, InteractiveComplexHeatmap, and circlize, which must be installed (e.g. via BiocManager::install()).

This is a convenience wrapper around createModuleApp(), which accepts a dataset entry that is a list of tables and filters only the primary one, so the two-table list(matrix = , column_annotations = ) shape this module's column features need is carried through without a bespoke app (see ComplexHeatmap_HeatmapServer()'s data parameter).

Value

A Shiny app object.

Author(s)

Jacob Martin, Jared Andrews

See Also

ComplexHeatmap::Heatmap(), ComplexHeatmap_HeatmapInputsUI(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapServer()

Examples

library(VizModules)
# Launch on the bundled matrix + its per-sample metadata, so the column
# annotation/split/filter features are all usable:
app <- ComplexHeatmap_HeatmapApp()
if (interactive()) shiny::runApp(app)

# Matrix only, without the per-sample metadata:
app2 <- ComplexHeatmap_HeatmapApp(data_list = list(matrix = example_heatmap_matrix))
if (interactive()) shiny::runApp(app2)

Description

Renders only the output panel showing information about the clicked or brushed cell(s) (e.g. row/column names and value), via InteractiveComplexHeatmap::HeatmapInfoOutput(). See ComplexHeatmap_HeatmapMainOutputUI() for how the separated output pieces fit together.

Usage

ComplexHeatmap_HeatmapInfoOutputUI(id, title = NULL, width = 400, ...)

Arguments

Value

A Shiny UI object for the click/brush info panel.

Author(s)

Jacob Martin

See Also

InteractiveComplexHeatmap::HeatmapInfoOutput(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapMainOutputUI(), ComplexHeatmap_HeatmapSubOutputUI()

Examples

library(VizModules)
if (requireNamespace("InteractiveComplexHeatmap", quietly = TRUE)) {
    ComplexHeatmap_HeatmapInfoOutputUI("heatmap", title = "Details")
}

Description

This should be placed in the UI where the inputs should be shown, with an id that matches the id used in the ComplexHeatmap_HeatmapServer() and ComplexHeatmap_HeatmapOutputUI() functions.

Usage

ComplexHeatmap_HeatmapInputsUI(
  id,
  data,
  defaults = NULL,
  title = NULL,
  columns = 2
)

Arguments

Details

Unlike the other plotly-based modules, this module wraps ComplexHeatmap::Heatmap() and renders its interactive output via the InteractiveComplexHeatmap package. The incoming data frame is converted to a numeric matrix (see the Data / Matrix tab) before being passed to Heatmap().

The inputs are organized into a grid via organize_inputs(), with columns controlling the number of columns in the grid. Defaults for each input can be supplied via the defaults argument (see get_default()).

Value

A Shiny tagList containing the UI elements.

Plot parameters and defaults

The following ComplexHeatmap::Heatmap() parameters can be accessed via UI inputs and/or the defaults argument:

• matrix.cols - Numeric columns forming the matrix (UI: "Matrix Columns", default: all numeric columns)

• rowname.col - Column used as row names (UI: "Row Name Column", default: "")

• name - Heatmap / legend title (UI: "Heatmap Name", default: "value")

• na_col - Color for NA cells (UI: "NA Color", default: "grey")

• scale - Z-score the matrix by row, column, or not at all (UI: "Scale", default: "None"). Applied before plotting only — row/column annotation values and the source-data download always use the unscaled matrix. Scaling happens after the Filter tab's row/column filters, so a Z-score describes only the rows and columns on screen.

• reverse.palette - Reverse the palette (UI: "Reverse Palette", default: FALSE)

• low_color, mid_color, high_color - Colors for the low/mid/high end of the value scale, i.e. what col in ComplexHeatmap::Heatmap() is built from via circlize::colorRamp2() (UI: "Low/Mid/High Color", default: blue/white/red)

• min_value, mid_value, max_value - Values mapped to low_color/mid_color/high_color (UI: "Min/Mid/Max Value", default: NA = derived from the matrix: min, mean(range(mat)), and max respectively)

• show_heatmap_legend - Show the heatmap legend (UI: "Show Legend", default: TRUE)

• border - Draw heatmap border (UI: "Border", default: FALSE)

• cluster_rows - Cluster rows (UI: "Cluster Rows", default: TRUE)

• cluster_columns - Cluster columns (UI: "Cluster Columns", default: TRUE)

• clustering_distance_rows - Row distance metric (UI: "Row Distance", default: "euclidean")

• clustering_distance_columns - Column distance metric (UI: "Column Distance", default: "euclidean")

• clustering_method_rows - Row linkage method (UI: "Row Method", default: "complete")

• clustering_method_columns - Column linkage method (UI: "Column Method", default: "complete")

• show_row_dend - Show row dendrogram (UI: "Show Row Dendrogram", default: TRUE)

• show_column_dend - Show column dendrogram (UI: "Show Column Dendrogram", default: TRUE)

• row_split_by - Row split method: "None", "K-means", "Hierarchical", or "Annotation" (UI: "Row Split Method", default: "None"). Only one split mechanism is ever active per axis, which avoids the error ComplexHeatmap::Heatmap() raises when both a k-means and a hierarchical split are requested at once.

• row_split_n - Number of row groups, used when row_split_by is "K-means" or "Hierarchical" (UI: "Row Groups", default: NA; clamped to the number of matrix rows)

• row_split_cols - Columns whose values group the rows, used when row_split_by is "Annotation" (UI: "Row Split Columns", default: none). Several columns give nested slices, one per observed combination. Values come from the same place row annotation tracks read, so a split and a track on one column always agree.

• column_split_by - Column split method: "None", "K-means", "Hierarchical", or "Annotation" (UI: "Column Split Method", default: "None")

• column_split_n - Number of column groups, used when column_split_by is "K-means" or "Hierarchical" (UI: "Column Groups", default: NA; clamped to the number of matrix columns)

• column_split_cols - Columns of the column_annotations table whose values group the heatmap columns, used when column_split_by is "Annotation" (UI: "Column Split Columns"; only shown when data supplies a column_annotations table; default: none)

• row_gap - Gap between row slices, mm (UI: "Row Gap (mm)", default: 1)

• column_gap - Gap between column slices, mm (UI: "Column Gap (mm)", default: 1)

• row_title - Row title (UI: "Row Title", default: "")

• column_title - Column title (UI: "Column Title", default: ""). A title, when set, replaces the group names a split would otherwise title its slices with; a ⁠%s⁠ in it is filled in with each slice's group name. The same goes for row_title.

• show_row_slice_titles - Title each row slice with its group name when the rows are split and row_title is blank (UI: "Show Row Slice Titles", default: TRUE). Applies to every split method: annotation values for "Annotation", cluster numbers for "K-means" and "Hierarchical". Untick it to remove the titles and the space they take.

• show_column_slice_titles - The same for columns (UI: "Show Column Slice Titles", default: TRUE)

• show_row_names - Show row names (UI: "Show Row Names", default: TRUE)

• show_column_names - Show column names (UI: "Show Column Names", default: TRUE)

• row_names_side - Row names side (UI: "Row Names Side", default: "right")

• column_names_side - Column names side (UI: "Column Names Side", default: "bottom")

• column_names_rot - Column name rotation (UI: "Column Name Rotation", default: 90)

• row_names_fontsize - Row name font size (UI: "Row Name Size", default: 12)

• column_names_fontsize - Column name font size (UI: "Column Name Size", default: 12)

• title_fontsize - Row/column title font size (UI: "Title Size", default: 13.2)

• row_annotations - Row annotation tracks, built as ComplexHeatmap::rowAnnotation() and passed as left_annotation/right_annotation per row (UI: "Annotations" tab, "Row Annotations" multiDynamicInput() — each row picks a matrix column, a side (Left or Right), and the side and font size of that track's own name label (Bottom or Top, since ComplexHeatmap places a row annotation's name above or below it), and whether that track contributes a legend ("Show Legend", default TRUE); default: none). Each row's color control appears just below the list once a column is picked: numeric columns get Low/Mid/High color pickers, everything else gets a multiColorPicker() with one color per level. Seed those colors from defaults with a named color vector keyed by the annotation's column name — the row names in a row_annotations/column_annotations default are not stable, since the client reports rows back as row1, row2, ...

• column_key - Column in column_annotations matched against the matrix's selected column names (UI: "Annotations" tab, "Column Key"; only shown when data supplies a column_annotations table)

• column_annotations - Column annotation tracks, built as ComplexHeatmap::columnAnnotation() and passed as top_annotation/bottom_annotation per row (UI: "Annotations" tab, "Column Annotations" multiDynamicInput() — each row picks a column, a side (Top or Bottom), the side and font size of that track's own name label (Right or Left, since ComplexHeatmap places a column annotation's name beside it), and whether that track contributes a legend ("Show Legend", default TRUE), with the same per-row color controls as row annotations; only shown when data supplies a column_annotations table; default: none)

Plot parameters implementing new functionality

The "Filter" tab's two inputs have no ComplexHeatmap::Heatmap() equivalent — they narrow the matrix before it is built, so a specific set of genes or samples can be plotted without wiring up the separate dataFilter module:

• row_filter - Expression keeping only the matching rows (UI: "Row Filter", default: ""). Evaluated against the matrix data frame, so every one of its columns is in scope — annotation columns, the row-name column, and the matrix columns themselves.

• column_filter - Expression keeping only the matching matrix columns (UI: "Column Filter", default: ""). Matrix columns are sample names rather than rows of a data frame, so the expression is evaluated against a frame built with one row per selected matrix column: a synthetic column field holding the column name, plus every field of column_annotations joined via column_key. column %in% c("Healthy_1", "Healthy_2") therefore works with no metadata table at all, while condition == "Disease" works as soon as one is supplied. If column_annotations already has a field named column, the real one wins and no synthetic is added.

Both are evaluated with safe_eval_filter(), which permits comparisons, &/|/!, %in%, is.na(), arithmetic, and the string helpers grepl, startsWith, endsWith, substr, nchar, toupper, tolower, and trimws. Anything else — a function call outside that list, or a symbol that is not a column — is rejected and reported in the UI rather than evaluated. An expression yielding NA for a row drops that row.

Filtering runs before everything else: scale, the annotation tracks, the split methods, and the source download all describe the filtered matrix.

Both inputs are debounced by 700ms, so the heatmap redraws once you pause rather than on every keystroke of a half-typed expression.

Plot parameters not implemented

The following ComplexHeatmap::Heatmap() parameters are not exposed because they require R code, objects, or annotations that do not map cleanly to UI inputs: cell_fun, layer_fun, post_fun, rect_gp, border_gp, custom col mapping functions for the annotation tracks (beyond the Low/Mid/High colors and multiColorPicker), row_order / column_order, row_labels / column_labels, jitter, and all rasterization parameters (use_raster, ⁠raster_*⁠).

Author(s)

Jacob Martin, Jared Andrews

See Also

ComplexHeatmap::Heatmap(), organize_inputs(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapServer(), ComplexHeatmap_HeatmapApp()

Examples

library(VizModules)
ComplexHeatmap_HeatmapInputsUI("heatmap", example_heatmap_matrix)

Description

Renders only the original (main) interactive heatmap panel, via InteractiveComplexHeatmap::originalHeatmapOutput(). Use this together with ComplexHeatmap_HeatmapSubOutputUI() and/or ComplexHeatmap_HeatmapInfoOutputUI() to place the three interactive components independently in a custom layout, instead of ComplexHeatmap_HeatmapOutputUI()'s single combined widget. All pieces used for one heatmap must share the same module id as the ComplexHeatmap_HeatmapServer() call — no server-side changes are needed to switch between the combined and separated forms.

Usage

ComplexHeatmap_HeatmapMainOutputUI(
  id,
  title = NULL,
  width = 450,
  height = 350,
  fit.width = TRUE,
  ...
)

Arguments

Value

A Shiny UI object for the main interactive heatmap panel.

Author(s)

Jacob Martin

See Also

InteractiveComplexHeatmap::originalHeatmapOutput(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapSubOutputUI(), ComplexHeatmap_HeatmapInfoOutputUI()

Examples

library(VizModules)
if (requireNamespace("InteractiveComplexHeatmap", quietly = TRUE)) {
    ComplexHeatmap_HeatmapMainOutputUI("heatmap", title = "Heatmap")
}

Description

This should be placed in the UI where the heatmap should be shown. Unlike the plotly modules, the interactive output is provided by InteractiveComplexHeatmap::InteractiveComplexHeatmapOutput(), which supplies its own resize and export controls.

Usage

ComplexHeatmap_HeatmapOutputUI(id, resizable = TRUE, fit.width = TRUE, ...)

Arguments

Details

This renders the original heatmap, the selected sub-heatmap, and the click/brush info panel together as one widget, arranged per layout (see InteractiveComplexHeatmap::InteractiveComplexHeatmapOutput() for the available layout strings, e.g. "(1-2)|3", "1|(2-3)", "1-2-3").

Pass compact = TRUE for a smaller footprint (see the "Compact mode" article section): the sub-heatmap panel is dropped entirely and the click/brush info floats near the cursor instead of occupying its own static area — equivalent to ⁠response = c(action, "brush-output"), output_ui_float = TRUE⁠, per InteractiveComplexHeatmap::InteractiveComplexHeatmapOutput()'s own docs. layout has nothing left to arrange in compact mode, since only one static panel remains. No server-side change is needed to turn compact mode on or off.

A floating info panel is moved onto ⁠<body>⁠ by InteractiveComplexHeatmap and parked off-screen when idle. It is parked to the left here rather than to the right as the package does, since a box parked past the right edge extends the host page's scrollable width by 10,000px.

To place the three components independently anywhere in a custom UI (separate tabs, cards, columns, etc.), use ComplexHeatmap_HeatmapMainOutputUI(), ComplexHeatmap_HeatmapSubOutputUI(), and ComplexHeatmap_HeatmapInfoOutputUI() instead of this function. Use one approach or the other, not both, for the same module id. Compact mode is specific to this combined widget: the separated pieces (originalHeatmapOutput(), subHeatmapOutput(), HeatmapInfoOutput(), which back the three functions above) don't accept a compact argument at all.

Value

A Shiny UI object for the interactive heatmap.

Author(s)

Jacob Martin, Jared Andrews

See Also

InteractiveComplexHeatmap::InteractiveComplexHeatmapOutput(), ComplexHeatmap_HeatmapMainOutputUI(), ComplexHeatmap_HeatmapSubOutputUI(), ComplexHeatmap_HeatmapInfoOutputUI()

Examples

library(VizModules)
if (requireNamespace("InteractiveComplexHeatmap", quietly = TRUE)) {
    # Default combined widget:
    ComplexHeatmap_HeatmapOutputUI("heatmap")
    # Same widget, main heatmap on its own row above sub-heatmap + info:
    ComplexHeatmap_HeatmapOutputUI("heatmap", layout = "1|(2-3)")
    # Compact: no sub-heatmap panel, click/brush info floats near the cursor
    ComplexHeatmap_HeatmapOutputUI("heatmap", compact = TRUE)
    # Fixed pixel widths, ignoring the container:
    ComplexHeatmap_HeatmapOutputUI("heatmap", fit.width = FALSE)
}

Description

Server logic for the ComplexHeatmap module

Usage

ComplexHeatmap_HeatmapServer(
  id,
  data,
  hide.inputs = NULL,
  hide.tabs = NULL,
  defaults = NULL
)

Arguments

Details

The incoming data frame is converted to a numeric matrix using the selected matrix columns (and optional row-name column). Row/column annotation tracks configured on the "Annotations" tab are built as ComplexHeatmap::rowAnnotation()/ComplexHeatmap::columnAnnotation() (one per side) and passed as left_annotation/right_annotation/ top_annotation/bottom_annotation. The heatmap is built with ComplexHeatmap::Heatmap() and registered for interactivity with InteractiveComplexHeatmap::makeInteractiveComplexHeatmap(), which draws it onto its own device to capture the interactive widget.

Both ComplexHeatmap and InteractiveComplexHeatmap are Bioconductor packages and are only required at runtime for this module; they are guarded with requireNamespace().

Value

The moduleServer function for the ComplexHeatmap module. The returned reactive yields the source-download bundle (matrix data + inputs).

Author(s)

Jacob Martin, Jared Andrews

See Also

ComplexHeatmap::Heatmap(), ComplexHeatmap_HeatmapInputsUI(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapApp()

Description

Renders the heatmap as a plain shiny::plotOutput() instead of an InteractiveComplexHeatmap widget. The same ComplexHeatmap_HeatmapServer() call backs both, so switching between them needs no server-side change – use this function or the interactive output functions for a given module id, not both.

Usage

ComplexHeatmap_HeatmapStaticOutputUI(
  id,
  resizable = TRUE,
  width = "100%",
  height = "100%"
)

Arguments

Details

What is given up is the widget's interactivity: cell hover/click, the sub-heatmap zoom, and the brush info panel. What is gained is a panel with no chrome of its own. InteractiveComplexHeatmap draws a grey border around the heatmap panel, a control tab strip beneath it, and sizes itself in fixed pixels; none of that can be switched off through an argument, since the border is set by an id selector in that package's own stylesheet. A plotOutput has none of it and fills its container at whatever width and height say, which is what a figure panel wants – it is how the ComplexHeatmap module appears in the Figure Builder (see figureBuilderServer()).

Unlike the interactive output, this needs only ComplexHeatmap itself, not InteractiveComplexHeatmap.

Value

A Shiny UI object for the static heatmap.

Author(s)

Jared Andrews

See Also

ComplexHeatmap_HeatmapOutputUI() for the interactive widget, ComplexHeatmap_HeatmapServer()

Examples

library(VizModules)
if (requireNamespace("ComplexHeatmap", quietly = TRUE)) {
    ComplexHeatmap_HeatmapStaticOutputUI("heatmap")
    # Fixed size, no resize handle:
    ComplexHeatmap_HeatmapStaticOutputUI("heatmap",
        resizable = FALSE, width = "600px", height = "400px"
    )
}

Description

Renders only the selected sub-heatmap panel (the zoomed-in view of a brushed/selected region), via InteractiveComplexHeatmap::subHeatmapOutput(). See ComplexHeatmap_HeatmapMainOutputUI() for how the separated output pieces fit together.

Usage

ComplexHeatmap_HeatmapSubOutputUI(
  id,
  title = NULL,
  width = 400,
  height = 350,
  fit.width = TRUE,
  ...
)

Arguments

Value

A Shiny UI object for the sub-heatmap panel.

Author(s)

Jacob Martin

See Also

InteractiveComplexHeatmap::subHeatmapOutput(), ComplexHeatmap_HeatmapOutputUI(), ComplexHeatmap_HeatmapMainOutputUI(), ComplexHeatmap_HeatmapInfoOutputUI()

Examples

library(VizModules)
if (requireNamespace("InteractiveComplexHeatmap", quietly = TRUE)) {
    ComplexHeatmap_HeatmapSubOutputUI("heatmap", title = "Selected region")
}

Description

Performs pairwise statistical tests between groups defined by a categorical variable. Supports Wilcoxon rank-sum, t-test, Kruskal-Wallis, and ANOVA. Handles nested grouping (comparing color.by groups within each x-level) and per-facet testing.

Usage

compute_pairwise_stats(
  df,
  x,
  y,
  pairs = NULL,
  test = "wilcox.test",
  p.adjust.method = "holm",
  paired = FALSE,
  group.by = NULL,
  facet.by = NULL,
  per.facet = TRUE,
  sig.threshold = 0.05,
  sig.levels = c(`****` = 1e-04, `***` = 0.001, `**` = 0.01)
)

Arguments

Value

A data.frame with columns: group1, group2, p.value, p.adj, p.signif, test, facet_level, x_level (when group.by is set).

Author(s)

Jared Andrews, Jacob Martin

Examples

compute_pairwise_stats(
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    test = "wilcox.test"
)

# Custom significance levels: only two-star tiers, lower threshold for *
compute_pairwise_stats(
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    test = "wilcox.test",
    sig.threshold = 0.01,
    sig.levels = c("**" = 0.001, "***" = 0.0001)
)

Description

Constructs a style list for a Plotly axis using values from a Shiny input object, including title font, axis lines, tick appearance, and gridline settings.

Usage

create_axis_styles(
  input,
  axis_side = c("x", "y"),
  isolate_fn = isolate,
  ggplot.axis.styling = TRUE
)

Arguments

Details

The function collects axis- and font-related settings from the provided input object and assembles them into a list suitable for use as an axis specification in Plotly layouts. The tick angle and gridline visibility are chosen based on the value of axis_side. If gridline inputs are not present in the input object, defaults to showing gridlines.

Value

A named list containing Plotly-compatible axis styling components, including title font, line properties, tick label formatting, and gridline visibility.

Author(s)

Jacob Martin

Examples

# Build a fake input list and use identity as the isolate function
input <- list(
    axis.title.font.size = 14, axis.title.font.family = "Arial",
    axis.title.font.color = "black", axis.tickfont.size = 10,
    axis.tickfont.color = "black", axis.tickfont.family = "Arial",
    axis.tickangle.x = 0, axis.tickangle.y = 0, axis.ticks = "outside",
    axis.tickcolor = "black", axis.ticklen = 5, axis.tickwidth = 1,
    show.grid.x = TRUE, show.grid.y = TRUE, grid.color = "grey90"
)
create_axis_styles(input, axis_side = "x", isolate_fn = identity)

Description

Creates ggplot2 theme arguments for axis borders and lines based on user inputs. This function handles axis styling through ggplot2 themes rather than plotly overlays, which provides better control especially when faceting is used.

Usage

create_ggplot_axis_style(input, isolate_fn = isolate)

Arguments

Details

When faceting is enabled, panel borders are always shown for the full plot. When faceting is disabled:

• If both axis.showline and axis.mirror are TRUE: Full panel border

• If only axis.showline is TRUE: Axis lines on x and y axes only

• Otherwise: No borders

Value

A named list of ggplot2 theme arguments to be passed to theme_args parameter.

Author(s)

Jacob Martin

Examples

input <- list(
    axis.showline = TRUE, axis.mirror = TRUE,
    axis.linecolor = "black", axis.linewidth = 1
)
create_ggplot_axis_style(input, isolate_fn = identity)

Description

Generates a Shiny downloadHandler() that bundles the interactive plot, images of it, and its supporting data into a single .zip archive.

Usage

create_source_download_handler(
  data_list,
  filename_base = "source_data",
  images = TRUE,
  output_id = "download.source",
  session = getDefaultReactiveDomain()
)

Arguments

Details

The archive holds, per plot: the interactive plot as self-contained HTML (⁠<name>_plot.html⁠), an ⁠<name>_plot.svg⁠ and ⁠<name>_plot.png⁠ of it, and CSVs of the plot data, the statistics, and the UI inputs.

The images are photographed in the browser, off the graph the user is looking at, so they carry every edit made after the figure was built – reference lines, statistical brackets, restyled axes and legends, dragged annotations. The capture happens between the button's click and the download itself, which is why the button pauses briefly before the archive arrives. When it cannot be done – the capture fails, the round trip times out, the plot sits on a hidden tab – the archive still downloads, without the images.

A module whose output is not a plotly graph has nothing for the browser to photograph and draws itself instead, by putting a vector_svg and/or raster_png function of ⁠(width, height, res)⁠ on its summary list, or on the reactive passed as data_list. draw_to_svg() and draw_to_png() build one from any grid or base drawing; ComplexHeatmap_HeatmapServer() is the worked example.

A summary may also carry svg_key, naming the captured image that belongs to it. The Figure Builder uses this because the browser knows a panel only by its id, while the summary is named after the panel's display label.

One caveat worth passing on to users: a plot drawn with WebGL (the dittoViz scatter plot's WebGL toggle) can only be photographed as a raster, so its points arrive as an embedded image inside an otherwise vector SVG. Turning WebGL off gives a fully editable file.

Value

A downloadHandler object suitable for assignment to a Shiny output.

Author(s)

Jacob Martin, Jared Andrews

See Also

collect_source_data(), module_tack_ui()

Examples

## Not run: 
# Example usage in a Shiny app
library(shiny)
library(plotly)
library(VizModules)
ui <- fluidPage(
    plotlyOutput("my_plot"),
    downloadButton("download_data", "Download Plot and Data")
)

server <- function(input, output) {
    plot_reactive <- reactive({
        plot_ly(mtcars, x = ~mpg, y = ~hp, type = "scatter", mode = "markers")
    })

    output$my_plot <- renderPlotly(plot_reactive())
    # collect_source_data() reads reactives, so it has to run inside one.
    inputs_reactive <- reactive(reactiveValuesToList(input))
    output$download_data <- create_source_download_handler(
        reactive(collect_source_data(plot_reactive, inputs_reactive = inputs_reactive))
    )
}

shinyApp(ui, server)

## End(Not run)

Description

Converts results from compute_pairwise_stats() into plotly-compatible shapes (brackets) and annotations (text labels). Sorts comparisons so that small-gap brackets are closest to the data and large-gap brackets are higher.

Usage

create_stat_annotations(
  stats_df,
  fig,
  df,
  x,
  y,
  display = "p.adj",
  hide.ns = FALSE,
  sig.threshold = 0.05,
  line.color = "#000000",
  line.width = 1,
  bracket.style = "capped",
  group.by = NULL,
  facet.by = NULL,
  x.order = NULL,
  font.size = 12,
  step.increase = 0.06,
  text.bump = 0.04,
  bracket.inset = 0.025,
  dodge.width = 1,
  free.y = FALSE
)

Arguments

Details

The values in y are expected to be the values drawn on the y-axis, so the plot must show them running up the y-axis. A plot whose values run along the x-axis (a rotated box plot or a ridge plot, say) has no room for vertical brackets; test it with compute_pairwise_stats() but do not draw brackets.

Value

A list with components:

annotations

List of plotly annotation objects.

shapes

List of plotly shape objects.

y.max

Numeric; maximum y value needed to accommodate all annotations.

y.min

Numeric; the smallest finite value of y.

y.range.by.axis

Under free.y, a named list of c(min, max) ranges keyed by y-axis reference ("y", "y2", ...): the panel's data minimum and the top its brackets need. NULL otherwise.

Author(s)

Jared Andrews, Jacob Martin

Examples

stats_df <- compute_pairwise_stats(
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    test = "wilcox.test"
)

fig <- plotly::plot_ly(
    data = example_iris, x = ~Species, y = ~Sepal.Length, type = "box"
)

stat_result <- create_stat_annotations(
    stats_df = stats_df,
    fig = fig,
    df = example_iris,
    x = "Species",
    y = "Sepal.Length",
    display = "symbol"
)

names(stat_result)

Description

Factory function that generates a standard Shiny application for any VizModules module. The resulting app features a Data Import section for uploading data files, a Data Table for viewing and editing the active dataset, and a Plot area for configuring and displaying an interactive plot.

Usage

createModuleApp(
  inputs_ui_fn,
  output_ui_fn,
  server_fn,
  data_list,
  defaults = NULL,
  hide.inputs = NULL,
  hide.tabs = NULL,
  show.table = TRUE,
  title = "VizModules App",
  primary.table = NULL,
  sidebar.width = 4
)

Arguments

Details

Uploaded files (Excel, CSV, TSV, or tab-delimited text) are added to the available datasets and can be selected for plotting. If an uploaded file shares a name with an existing dataset, the existing one is overwritten with a warning.

Every module-specific ⁠*App()⁠ convenience function (e.g. plotthis_BarPlotApp(), linePlotApp()) is a thin wrapper around createModuleApp(). You can also call it directly for quick prototyping or to create apps for custom wrapper modules.

Value

A shiny::shinyApp() object.

Author(s)

Jared Andrews

Examples

library(VizModules)

# Quick-launch a bar plot app with custom data:
app <- createModuleApp(
    inputs_ui_fn = plotthis_BarPlotInputsUI,
    output_ui_fn = plotthis_BarPlotOutputUI,
    server_fn    = plotthis_BarPlotServer,
    data_list    = list("iris" = iris),
    title        = "My Bar Plot",
    defaults     = NULL
)
if (interactive()) runApp(app)

# Works with any module trio, including custom wrapper modules:
app2 <- createModuleApp(
    inputs_ui_fn = dittoViz_scatterPlotInputsUI,
    output_ui_fn = dittoViz_scatterPlotOutputUI,
    server_fn    = dittoViz_scatterPlotServer,
    data_list    = list("iris" = iris),
    title        = "Scatter",
    defaults    = NULL
)
if (interactive()) runApp(app2)

Description

Renders an interactive DT table with column-level filters and returns a reactive containing only the currently visible (filtered) rows. This reactive can be passed directly to any plotting module as its data argument.

Usage

dataFilterServer(
  id,
  data,
  factor.char.cols = TRUE,
  page.length = 10,
  col.visibility = FALSE,
  hide.columns = NULL,
  filter.max.options = 50
)

Arguments

Value

A reactive expression that evaluates to the filtered subset of data based on the current DT selection/filter state. All columns are retained, including any hidden via hide.columns. Pass this reactive to a plotting module's data argument to keep the plot in sync with the table filters.

Author(s)

Jacob Martin

See Also

dataFilterUI(), resolve_column_targets()

Examples

library(shiny)
library(VizModules)

ui <- fluidPage(
    dataFilterUI("filter"),
    verbatimTextOutput("rows")
)

server <- function(input, output, session) {
    data <- reactive(iris)
    # Petal columns are hidden on load, but the "Columns" button lets users
    # bring them back, and they remain in the returned data either way.
    filtered <- dataFilterServer("filter", data,
        factor.char.cols = TRUE,
        hide.columns = c("Petal.Length", "Petal.Width"),
        col.visibility = TRUE
    )
    output$rows <- renderPrint(nrow(filtered()))
}

if (interactive()) shinyApp(ui, server)

Description

Renders an interactive DT table that allows users to filter rows of a data frame. Place this in the UI where you want the filterable table to appear, using an id that matches the one passed to dataFilterServer().

Usage

dataFilterUI(id)

Arguments

Value

A Shiny tagList containing the DT table output.

Author(s)

Jacob Martin

See Also

dataFilterServer()

Examples

library(VizModules)
dataFilterUI("myFilter")

Description

Returns a list of predefined color palettes grouped by category (Defaults, Viridis, Diverging, Qualitative, Sequential) for use with color picker UI components.

Usage

default_palettes()

Value

A named list with two elements: choices (a nested list of palette name to color vector mappings, grouped by category) and textColor (a character vector of text colors for each palette).

Author(s)

Jared Andrews

Examples

pals <- default_palettes()
names(pals$choices)

Description

This function generates a Shiny application with modular dittoViz::freqPlot() components. The app features a Data Import section for uploading data, a Data Table for filtering the active dataset, and a Plot area for configuring and displaying an interactive frequency plot.

Usage

dittoViz_freqPlotApp(
  data_list = NULL,
  defaults = NULL,
  hide.inputs = NULL,
  hide.tabs = NULL
)

Arguments

Details

When data_list is not provided (or NULL), the app launches on example_composition (twelve donors nested inside two conditions, the shape dittoViz::freqPlot() needs to compare per-sample frequencies across groups) with the settings the module gallery (moduleGalleryApp()) opens this module on, so its main features are on show from the start; any defaults you pass are applied over those. Uploaded data files are added to the available datasets and can be selected for plotting. If an uploaded file shares a name with an existing dataset, the existing one is overwritten with a warning.

This is a convenience wrapper around createModuleApp().

Value

A Shiny app object.

Author(s)

Jared Andrews

See Also

dittoViz::freqPlot(), dittoViz_freqPlotInputsUI(), dittoViz_freqPlotOutputUI(), dittoViz_freqPlotServer()

Examples

library(VizModules)
# Launch with default example data:
app <- dittoViz_freqPlotApp()
if (interactive()) runApp(app)

# The same example data, as raw cell counts and without the statistics:
app2 <- dittoViz_freqPlotApp(defaults = list(scale = "count", stats.enabled = FALSE))
if (interactive()) runApp(app2)

Description

This should be placed in the UI where the inputs should be shown, with an id that matches the id used in the dittoViz_freqPlotServer() and dittoViz_freqPlotOutputUI() functions.

Usage

dittoViz_freqPlotInputsUI(id, data, defaults = NULL, title = NULL, columns = 2)

Arguments

Details

The user inputs for this module are separated from the outputs to allow for more flexible UI design.

The inputs will automatically be organized into a grid layout via the organize_inputs() function, with columns controlling the number of columns in the grid.

Defaults can be set for each input by providing a named list of values to the defaults argument. Nearly all parameters for dittoViz::freqPlot() can be set via these inputs, so see the help for that function for an exhaustive list.

Unlike most modules here, this one does not plot columns of the incoming data. It tabulates how often each level of "Frequency Of" occurs within each sample and plots those per-sample frequencies, one facet per level. Axis limits, statistics, the point annotations and the source download therefore all describe the summarised frequency table, not the input rows.

Under a free y facet scale ("free", "free_y") the Y Axis Min/Max are not applied and each panel's significance brackets sit above that panel's own data. With a ridge plot among the plot types the values run along the x-axis, so no brackets are drawn; the test results are still included in the source download.

Because the frequencies are per-sample, "Sample" must nest inside "Group By": each sample has to carry exactly one group value (and one color value, when "Color By" is set), or dittoViz::freqPlot() errors. "Group By" and "Color By" are therefore chosen freely and "Sample" is narrowed to the columns that nest inside them, which makes an erroring combination unselectable. With no sample column each group collapses to a single point per facet, which is rarely what is wanted.

Value

A Shiny tagList containing the UI elements

Plot parameters not implemented or with altered functionality

The following dittoViz::freqPlot() parameters are not available via UI inputs:

• xlab - X-axis label (plotly allows interactive editing)

• ylab - Y-axis label (plotly allows interactive editing)

• main - Plot title (plotly allows interactive editing)

• sub - Plot subtitle (not supported in plotly)

• theme - ggplot2 theme (not applicable to plotly)

• legend.title - Legend title (managed by plotly interactively)

• split.by - Not a parameter of freqPlot(); it always facets on the frequency variable's levels. Use vars.use ("Levels To Show") to choose which of those facets are drawn

• rows.use - Row subset to plot (use the app's data table filter instead)

• data.out, data.only - Return the summary rather than the plot (the module summarises internally; use the Source Download button for the table)

• do.hover - Always TRUE, so the frequency, count and sample are readable on hover

• colors - Integer index/order into color.panel (managed via the palette UI)

• color.panel - Managed internally via the palette selection UI

• y.breaks - Custom continuous-axis breaks (not implemented)

• x.labels - Override group labels (not implemented)

• x.reorder - Reorder x-axis groups (not implemented)

• x.labels.rotate - Rotate group labels (handled by the Axes tab tick-angle controls)

• var.labels.rename - Rename facet labels (not implemented)

• var.labels.reorder - Reorder facet labels (not implemented)

• add.line - Use hline.intercepts instead for horizontal lines with full styling options

• line.linetype - Use hline.linetypes instead

• line.color - Use hline.colors instead

• line.linewidth - Use hline.widths instead

• line.opacity - Use hline.opacities instead

• boxplot.width - Boxplot width (controlled via boxgap and boxgroupgap)

• boxplot.outlier.size - Outlier point size (not implemented)

• boxplot.position.dodge - Boxplot dodge (controlled via boxgap)

• vlnplot.quantiles - Violin quantiles (doesn't translate to plotly)

• jitter.position.dodge - Jitter position dodge (calculated from boxgap)

Plot parameters and defaults

The following dittoViz::freqPlot() parameters can be accessed via UI inputs and/or the defaults argument:

• var - Variable whose per-sample frequency is tabulated, one facet per level (UI: "Frequency Of", default: 1st low-cardinality categorical variable)

• sample.by - Sample identifier the frequencies are computed within (UI: "Sample", default: "", i.e. one point per group)

• group.by - Grouping variable forming the x-axis (UI: "Group By", default: 1st categorical variable that is constant within each sample)

• color.by - Coloring variable (UI: "Color By", default: "", which follows group.by)

• vars.use - Which levels of var get a facet (UI: "Levels To Show", default: "", i.e. all)

• scale - Plot frequencies as proportions or raw counts (UI: "Scale", default: "percent")

• max.normalize - Scale each facet to its own maximum (UI: "Max Normalize", default: FALSE)

• plots - Plot types to show (UI: "Plots", default: c("boxplot", "jitter"))

• min - Y-axis minimum (UI: "Y Axis Min", auto-calculated from the frequency table)

• max - Y-axis maximum (UI: "Y Axis Max", auto-calculated from the frequency table)

• split.nrow - Number of facet rows (UI: "Rows", default: NA)

• split.ncol - Number of facet columns (UI: "Columns", default: NA)

• split.adjust - Facet scale behavior (UI: "Facet Scaling", default: "fixed")

• do.raster - Rasterize jitter points (UI: "Rasterize Jitter", default: FALSE)

• raster.dpi - DPI for rasterization (UI: "Raster DPI", default: 600)

• hover.round.digits - Hover value rounding (UI: "Hover Round Digits", default: 5)

• jitter.size - Jitter point size (UI: "Jitter Point Size", default: 1)

• jitter.width - Jitter width (UI: "Jitter Width", default: 0.2)

• jitter.color - Jitter border color (UI: "Jitter Border Color", default: "#000000")

• boxplot.show.outliers - Show boxplot outliers (UI: "Show Outliers", default: FALSE)

• boxplot.color - Boxplot outline color (UI: "Boxplot Color", default: "#000000")

• boxplot.fill - Fill boxplot (UI: "Fill Boxplot", default: TRUE)

• boxplot.lineweight - Boxplot line weight (UI: "Boxplot Line Weight", default: 0.5)

• vlnplot.lineweight - Violin line weight (UI: "Violin Line Weight", default: 0.5)

• vlnplot.scaling - Violin scaling method (UI: "Violin Scaling", default: "area")

• vlnplot.width - Violin width (derived from boxgap; not directly settable)

• ridgeplot.lineweight - Ridge line weight (UI: "Ridge Line Weight", default: 0.5)

• ridgeplot.scale - Ridge overlap scale (UI: "Ridge Scale (overlap)", default: 1.25)

• ridgeplot.ymax.expansion - Ridge Y-max expansion (UI: "Ridge Y-max Expansion", default: NA)

• ridgeplot.shape - Ridge shape (UI: "Ridge Shape", default: "smooth")

• ridgeplot.bins - Ridge bins (UI: "Ridge Bins", default: 30)

• ridgeplot.binwidth - Ridge binwidth (UI: "Ridge Binwidth", default: NA)

• legend.show - Show the legend (UI: "Show Legend", default: TRUE)

Parameters controlling additional functionality

The following parameters implementing new functionality or controlling plotly-specific features are also available:

• boxmode - Always "overlay": the boxes carry explicit x positions matching ggplot's dodge, so plotly.js is not asked to dodge them

• boxgap - Boxplot position dodge (UI: "Boxplot Position Dodge", default: 0.3)

• boxgroupgap - Boxplot group dodge (UI: "Boxplot Group Dodge", default: 0.2)

• title.font.size - Plot title font size (UI: "Title Size", default: 26)

• title.font.family - Font family for title text (UI: "Title Font", default: "Arial")

• title.font.color - Color for plot title (UI: "Title Color", default: "#000000")

• axis.title.font.size - Axis title font size (UI: "Axis Title Size", default: 18)

• axis.title.font.color - Axis title font color (UI: "Axis Title Color", default: "#000000")

• axis.title.font.family - Axis title font family (UI: "Axis Title Font", default: "Arial")

• axis.showline - Show axis border lines (UI: "Show Axis Lines", default: TRUE)

• axis.mirror - Mirror axis lines on opposite side (UI: "Mirror Axis Lines", default: TRUE)

• show.grid.x - Show X-axis major gridlines (UI: "Show X Major Gridlines", default: TRUE)

• show.grid.y - Show Y-axis major gridlines (UI: "Show Y Major Gridlines", default: TRUE)

• axis.linecolor - Color of axis lines (UI: "Axis Line Color", default: "black")

• axis.linewidth - Width of axis lines (UI: "Axis Line Width", default: 0.5)

• axis.tickfont.size - Size of tick labels (UI: "Tick Label Size", default: 12)

• axis.tickfont.color - Color of tick labels (UI: "Tick Label Color", default: "black")

• axis.tickfont.family - Font family for tick labels (UI: "Tick Label Font", default: "Arial")

• axis.tickangle.x - Rotation angle for X-axis tick labels (UI: "X-axis Tick Label Angle", default: 0)

• axis.tickangle.y - Rotation angle for Y-axis tick labels (UI: "Y-axis Tick Label Angle", default: 0)

• axis.ticks - Position of tick marks (UI: "Tick Position", default: "outside")

• axis.tickcolor - Color of tick marks (UI: "Tick Mark Color", default: "black")

• axis.ticklen - Length of tick marks (UI: "Tick Mark Length", default: 5)

• axis.tickwidth - Width of tick marks (UI: "Tick Mark Width", default: 1)

• legend.font.family - Font family of the legend title and labels (UI: "Legend Font", default: "Arial")

• legend.font.color - Font color of the legend title and labels (UI: "Legend Font Color", default: "#000000")

• legend.title.size - Legend title font size (UI: "Legend Title Size", default: 14)

• legend.text.size - Legend entry label font size (UI: "Legend Text Size", default: 12)

• hline.intercepts - Y-coordinates for horizontal reference lines (UI: "Y-intercepts", default: "")

• hline.colors - Colors for horizontal lines (UI: "Colors", default: "#000000")

• hline.widths - Widths for horizontal lines (UI: "Widths", default: "1")

• hline.linetypes - Line types for horizontal lines (UI: "Line Types", default: "dashed")

• hline.opacities - Opacities for horizontal lines (UI: "Opacities (0-1)", default: "1")

• vline.intercepts - X-coordinates for vertical reference lines (UI: "X-intercepts", default: "")

• vline.colors - Colors for vertical lines (UI: "Colors", default: "#000000")

• vline.widths - Widths for vertical lines (UI: "Widths", default: "1")

• vline.linetypes - Line types for vertical lines (UI: "Line Types", default: "dashed")

• vline.opacities - Opacities for vertical lines (UI: "Opacities (0-1)", default: "1")

• abline.slopes - Slopes for diagonal reference lines (UI: "Slopes", default: "")

• abline.intercepts - Y-intercepts for diagonal lines (UI: "Y-intercepts", default: "")

• abline.colors - Colors for diagonal lines (UI: "Colors", default: "#000000")

• abline.widths - Widths for diagonal lines (UI: "Widths", default: "1")

• abline.linetypes - Line types for diagonal lines (UI: "Line Types", default: "dashed")

• abline.opacities - Opacities for diagonal lines (UI: "Opacities (0-1)", default: "1")

• palette.colours - Named character vector mapping group levels to colors, e.g. c(A = "#FF0000", B = "blue") (UI: "Plot colors"). Seeds the picker; unnamed groups fall back to the default palette and user edits take precedence.

• annotate.by - Column whose values identify and label jitter points (UI: "Annotate By", default: ""). Restricted to the columns carried in the plot's hover text, which for this plot are the sample and color columns

• highlight.points - Values from the annotate.by column to highlight (UI: "Points to Highlight", default: ""). Values containing spaces (e.g. "CD4 T") must be separated by commas or new lines

• highlight.color - Fill color for highlighted points (UI: "Highlight Fill", default: "#00FFF7")

• highlight.size - Size of highlighted points (UI: "Highlight Size", default: 7)

• highlight.border.color - Border color for highlighted points (UI: "Highlight Border Color", default: "#000000")

• highlight.border.width - Border width for highlighted points (UI: "Highlight Border Width", default: 1)

• highlight.auto.annotate - Label highlighted points automatically (UI: "Auto-annotate Highlights", default: TRUE)

• annotation.color - Annotation text color (UI: "Annotation Color", default: "black")

• annotation.ax - Horizontal label offset in pixels (UI: "Annotation X Offset", default: 20)

• annotation.ay - Vertical label offset in pixels (UI: "Annotation Y Offset", default: -20)

• annotation.size - Annotation font size (UI: "Annotation Size", default: 10)

• annotation.showarrow - Draw an arrow from label to point (UI: "Show Arrow", default: TRUE)

• annotation.arrowcolor - Annotation arrow color (UI: "Arrow Color", default: "black")

• annotation.arrowhead - Annotation arrowhead style (UI: "Arrowhead Style", default: 2)

• annotation.arrowwidth - Annotation arrow line width (UI: "Arrow Linewidth", default: 1.5)

• stats.enabled and the other ⁠stat.*⁠ parameters - Pairwise testing of the per-sample frequencies between x-axis groups. Tests always run within each facet, since frequencies of different levels are not comparable quantities; the "Per Facet Panel" control is therefore hidden and forced on. stat.pairs takes a character vector of "A vs B" strings naming levels of group.by (or of color.by, when it differs), e.g. "Healthy vs Disease"; left unset, every pair is tested

Author(s)

Jared Andrews

See Also

dittoViz::freqPlot(), organize_inputs(), dittoViz_freqPlotOutputUI(), dittoViz_freqPlotServer(), dittoViz_freqPlotApp()

Examples

library(VizModules)
dittoViz_freqPlotInputsUI("freqPlot", example_composition)

Description

This should be placed in the UI where the plot should be shown.

Usage

dittoViz_freqPlotOutputUI(id, resizable = TRUE)

Arguments

Value

A Shiny plotlyOutput for the freqPlot

Author(s)

Jared Andrews

See Also

dittoViz::freqPlot(), dittoViz_freqPlotInputsUI(), dittoViz_freqPlotServer(), dittoViz_freqPlotApp()

Description

Server logic for freqPlot module

Usage

dittoViz_freqPlotServer(
  id,
  data,
  hide.inputs = NULL,
  hide.tabs = NULL,
  defaults = NULL
)

Arguments

Value

The moduleServer function for the freqPlot module.

Author(s)

Jared Andrews

See Also

dittoViz::freqPlot(), dittoViz_freqPlotInputsUI(), dittoViz_freqPlotOutputUI(), dittoViz_freqPlotApp()

Description

This function generates a Shiny application with modular dittoViz::scatterPlot() components. The app features a Data Import section for uploading data, a Data Table for filtering the active dataset, and a Plot area for configuring and displaying an interactive scatter plot.

Usage

dittoViz_scatterPlotApp(
  data_list = NULL,
  defaults = NULL,
  hide.inputs = NULL,
  hide.tabs = NULL
)

Arguments

Details

When data_list is not provided (or NULL), the app launches on example_sales with the settings the module gallery (moduleGalleryApp()) opens this module on, so its main features are on show from the start; any defaults you pass are applied over those. Uploaded data files are added to the available datasets and can be selected for plotting. If an uploaded file shares a name with an existing dataset, the existing one is overwritten with a warning.

This is a convenience wrapper around createModuleApp().

Value

A Shiny app object.

Author(s)

Jared Andrews

See Also

dittoViz::scatterPlot(), dittoViz_scatterPlotInputsUI(), dittoViz_scatterPlotOutputUI(), dittoViz_scatterPlotServer()

Examples

library(VizModules)
# Launch with default example data:
app <- dittoViz_scatterPlotApp()
if (interactive()) runApp(app)

# Launch with custom data:
app2 <- dittoViz_scatterPlotApp(list("sales" = example_sales))
if (interactive()) runApp(app2)

Description

This should be placed in the UI where the inputs should be shown, with an id that matches the id used in the dittoViz_scatterPlotServer() and dittoViz_scatterPlotOutputUI() functions.

Usage

dittoViz_scatterPlotInputsUI(
  id,
  data,
  defaults = NULL,
  title = NULL,
  columns = 2
)

Arguments

Details

The user inputs for this module are separated from the outputs to allow for more flexible UI design.

The inputs will automatically be organized into a grid layout via the organize_inputs() function, with columns controlling the number of columns in the grid.

Defaults can be set for each input by providing a named list of values to the defaults argument. Nearly all parameters for dittoViz::scatterPlot() can be set via these inputs, so see the help for that function for an exhaustive list.

Note that some of the parameters may have input types that differ from the actual function, e.g. shape.panel is a text input for comma-separated integers, while the function expects a vector of integers. The module will parse such inputs into the appropriate format for dittoViz::scatterPlot() automatically.

Source data note: When source data is downloaded with faceting applied and split.show.all.others = TRUE, values will be duplicated due to them being shown in every panel.

Value

A Shiny tagList containing the UI elements

Plot parameters not implemented or with altered functionality

The following dittoViz::scatterPlot() parameters are not available via UI inputs or have been superseded:

• xlab - X-axis label (auto-generated to reflect any applied X adjustment, e.g. "z-score(log2(units))"; plotly allows interactive editing)

• ylab - Y-axis label (auto-generated to reflect any applied Y adjustment, e.g. "z-score(log2(units))"; plotly allows interactive editing)

• main - Plot title (plotly allows interactive editing)

• sub - Plot subtitle (not supported in plotly)

• theme - ggplot2 theme (not applicable to plotly)

• legend.title - Legend title (managed by plotly interactively)

• legend.color.size - Legend color size (not supported in plotly)

• legend.shape.size - Legend shape size (not supported in plotly)

• add.xline - Use vline.intercepts instead for vertical lines with full styling options

• add.yline - Use hline.intercepts instead for horizontal lines with full styling options

• xline.linetype - Use vline.linetypes instead

• xline.color - Use vline.colors instead

• yline.linetype - Use hline.linetypes instead

• yline.color - Use hline.colors instead

• do.letter - Lettering subplots (not implemented for plotly)

• do.label - Labeling points interactively (not compatible with plotly hover)

• labels.size, labels.highlight, labels.use.numbers, labels.numbers.spacer, labels.repel, labels.repel.adjust, labels.split.by - Point-label styling (tied to do.label, not implemented)

• rename.color.groups - Rename color groups (not implemented)

• rename.shape.groups - Rename shape groups (not implemented)

• add.trajectory.curves - Add trajectory curves from coordinate matrices (not implemented; use add.trajectory.by.groups instead)

• do.raster - Rasterize the point layer (not implemented; use webgl for performance instead)

• raster.dpi - Rasterization DPI (not applicable without do.raster)

• show.grid.lines - Toggle grid lines (managed via the Axes tab gridline controls)

• legend.color.breaks.labels - Labels for color-scale breaks (not implemented)

The new Lines tab provides enhanced functionality including multiple lines per type, individual line widths, opacities, and diagonal/ablines with slope control.

Plot parameters and defaults

The following dittoViz::scatterPlot() parameters can be accessed via UI inputs and/or the defaults argument:

• x.by - X-axis variable (UI: "X Data", default: 2nd column)

• y.by - Y-axis variable (UI: "Y Data", default: 3rd column)

• color.by - Coloring variable (UI: "Color By", default: "")

• shape.by - Shape variable (UI: "Shape By", default: "")

• split.by - Faceting variable (UI: "Split By", default: "")

• rows.use - Row filter expression (UI: "Rows Filter", default: "")

• x.adjustment - X-axis adjustment (UI: "X Adjustment", default: "")

• y.adjustment - Y-axis adjustment (UI: "Y Adjustment", default: "")

• color.adjustment - Color adjustment (UI: "Color Adjustment", default: "")

• x.adj.fxn - X adjustment function (UI: "X Adjustment Function", default: "")

• y.adj.fxn - Y adjustment function (UI: "Y Adjustment Function", default: "")

• color.adj.fxn - Color adjustment function (UI: "Color Adjustment Function", default: "")

• size - Point size (UI: "Point Size", default: 1)

• size.by - Numeric column mapped to point size (UI: "Size By", default: ""); when set, a custom circle size legend is drawn since plotly cannot render a native size legend

• opacity - Point opacity (UI: "Point Opacity", default: 1)

• show.others - Show others (UI: "Show Others", default: TRUE)

• split.show.all.others - Show split others (UI: "Show Split Others", default: TRUE)

• plot.order - Plot order (UI: "Plot Order", default: "unordered")

• shape.panel - Shape panel values (UI: "Shape Panel", default: "16, 15, 17, 23, 25, 8")

• min.color - Minimum color (UI: "Min Color", default: "#F0E442")

• max.color - Maximum color (UI: "Max Color", default: "#0072B2")

• contour.color - Contour color (UI: "Contour Color", default: "black")

• contour.linetype - Contour linetype (UI: "Contour Linetype", default: "solid")

• color.panel - Named character vector mapping color.by levels to colors, e.g. c(setosa = "#FF0000", virginica = "blue") (UI: color.panel.ui). Seeds the picker; unnamed groups fall back to the default palette and user edits take precedence.

• single.point.color - Point color used when color.by is unset (UI: "Point color", default: "#000000")

• split.nrow - Number of split rows (UI: "Rows", default: NA)

• split.ncol - Number of split columns (UI: "Columns", default: NA)

• multivar.split.dir - Multivar split direction (UI: "Multivar Split Dir", default: "col")

• split.adjust.scales - Facet scales (UI: "Facet Scales", default: "fixed")

• annotate.by - Annotate by column (UI: "Annotate By", default: "")

• highlight.points - Values from the annotate.by column to highlight (UI: "Points to Highlight", default: ""). Values containing spaces (e.g. "CD4 T") must be separated by commas or new lines

• highlight.color - Highlight fill (UI: "Highlight Fill", default: "#00FFF7")

• highlight.size - Highlight size (UI: "Highlight Size", default: 7)

• highlight.border.color - Highlight border color (UI: "Highlight Border Color", default: "#000000")

• highlight.border.width - Highlight border width (UI: "Highlight Border Width", default: 1)

• highlight.auto.annotate - Auto-annotate highlights (UI: "Auto-annotate Highlights", default: TRUE)

• annotation.color - Annotation color (UI: "Annotation Color", default: "black")

• annotation.ax - Annotation X offset (UI: "Annotation X Offset", default: 20)

• annotation.ay - Annotation Y offset (UI: "Annotation Y Offset", default: -20)

• annotation.size - Annotation size (UI: "Annotation Size", default: 10)

• annotation.showarrow - Show arrow (UI: "Show Arrow", default: TRUE)

• annotation.arrowcolor - Arrow color (UI: "Arrow Color", default: "black")

• annotation.arrowhead - Arrowhead style (UI: "Arrowhead Style", default: 2)

• annotation.arrowwidth - Arrow linewidth (UI: "Arrow Linewidth", default: 1.5)

• legend.show - Show the legend, colorbar and size legend (UI: "Show Legend", default: TRUE)

• legend.color.title - Color legend title (UI: "Legend Title", default: "make")

• legend.color.breaks - Legend tick breaks (UI: "Legend Tick Breaks", default: "")

• size.legend.x - Custom size-legend x position (UI: "Size Legend X Position", default: 1.02); nudges the manual size legend (drawn when size.by is set) along the x-axis.

• size.legend.y - Custom size-legend y position (UI: "Size Legend Y Position", default: 0.95); nudges the manual size legend (drawn when size.by is set) along the y-axis.

• min.value - Minimum value (UI: "Min Value", default: NA)

• max.value - Maximum value (UI: "Max Value", default: NA)

• trajectory.group.by - Trajectory group by (UI: "Trajectory Group By", default: "")

• add.trajectory.by.groups - Add trajectory by groups (UI: "Add Trajectory By Groups", default: "")

• trajectory.arrow.size - Trajectory arrow size (UI: "Trajectory Arrow Size", default: 0.15)

• do.ellipse - Enable ellipses (UI: "Enable Ellipses", default: FALSE)

• do.contour - Enable contour (UI: "Enable Contour", default: FALSE)

• hover.data - Hover data columns (UI: "Hover Data", default: "")

• hover.round.digits - Hover round digits (UI: "Hover Round Digits", default: 5)

Parameters controlling additional functionality

The following parameters implementing new functionality or controlling plotly-specific features are also available:

• webgl - Plot with webGL (UI: "Plot with webGL", default: TRUE)

• shape.fill - Shape fill color (UI: "Shape Fill", default: "rgba(0, 0, 0, 0)")

• shape.line.color - Shape line color (UI: "Shape Line Color", default: "black")

• shape.line.width - Shape line width (UI: "Shape Line Width", default: 4)

• shape.linetype - Shape linetype (UI: "Shape Linetype", default: "solid")

• shape.opacity - Shape opacity (UI: "Shape Opacity", default: 1)

• title.font.size - Plot title font size (UI: "Title Size", default: 26)

• title.font.family - Font family for title text (UI: "Title Font", default: "Arial")

• title.font.color - Color for plot title (UI: "Title Color", default: "#000000")

• axis.title.font.size - Axis title font size (UI: "Axis Title Size", default: 18)

• axis.title.font.color - Axis title font color (UI: "Axis Title Color", default: "#000000")

• axis.title.font.family - Axis title font family (UI: "Axis Title Font", default: "Arial")

• axis.showline - Show axis border lines (UI: "Show Axis Borders", default: TRUE)

• axis.mirror - Mirror axis lines on opposite side (UI: "Mirror Axis Borders", default: TRUE)

• show.grid.x - Show X-axis major gridlines (UI: "Show X Gridlines", default: TRUE)

• show.grid.y - Show Y-axis major gridlines (UI: "Show Y Gridlines", default: TRUE)

• grid.color - Gridline color (UI: "Gridline Color", default: "#CCCCCC")

• axis.linecolor - Color of axis lines (UI: "Axis Line Color", default: "black")

• axis.linewidth - Width of axis lines (UI: "Axis Line Width", default: 0.5)

• axis.tickfont.size - Size of tick labels (UI: "Tick Label Size", default: 12)

• axis.tickfont.color - Color of tick labels (UI: "Tick Label Color", default: "black")

• axis.tickfont.family - Font family for tick labels (UI: "Tick Label Font", default: "Arial")

• axis.tickangle.x - Rotation angle for X-axis tick labels (UI: "X Tick Label Angle", default: 0)

• axis.tickangle.y - Rotation angle for Y-axis tick labels (UI: "Y Tick Label Angle", default: 0)

• axis.ticks - Position of tick marks (UI: "Tick Position", default: "outside")

• axis.tickcolor - Color of tick marks (UI: "Tick Mark Color", default: "black")

• axis.ticklen - Length of tick marks (UI: "Tick Mark Length", default: 5)

• axis.tickwidth - Width of tick marks (UI: "Tick Mark Width", default: 1)

• facet.title.font.size - Facet subplot title font size (UI: "Facet Subplot Title Size", default: 18)

• facet.title.font.color - Facet subplot title font color (UI: "Facet Title Color", default: "#000000")

• facet.title.font.family - Facet subplot title font family (UI: "Facet Title Font", default: "Arial")

• legend.font.family - Font family of the legend title and labels (UI: "Legend Font", default: "Arial")

• legend.font.color - Font color of the legend title and labels (UI: "Legend Font Color", default: "#000000")

• legend.title.size - Legend title font size (UI: "Legend Title Size", default: 14)

• legend.text.size - Legend entry label font size (UI: "Legend Text Size", default: 12)

• hline.intercepts - Y-coordinates for horizontal reference lines (UI: "Y-intercepts", default: "")

• hline.colors - Colors for horizontal lines (UI: "Colors", default: "#000000")

• hline.widths - Widths for horizontal lines (UI: "Widths", default: "1")

• hline.linetypes - Line types for horizontal lines (UI: "Line Types", default: "dashed")

• hline.opacities - Opacities for horizontal lines (UI: "Opacities (0-1)", default: "1")

• vline.intercepts - X-coordinates for vertical reference lines (UI: "X-intercepts", default: "")

• vline.colors - Colors for vertical lines (UI: "Colors", default: "#000000")

• vline.widths - Widths for vertical lines (UI: "Widths", default: "1")

• vline.linetypes - Line types for vertical lines (UI: "Line Types", default: "dashed")

• vline.opacities - Opacities for vertical lines (UI: "Opacities (0-1)", default: "1")

• abline.slopes - Slopes for diagonal reference lines (UI: "Slopes", default: "")

• best.fit - Enable line of best fit (UI: "Line of best fit:", default: FALSE)

• line.best.smoothness - Smoothness of line of best fit (UI: "Smoothness of line of best fit:", default: 1)

• line.best.colour - Color of line of best fit (UI: "Line of best fit colour:", default: "#000000")

• linear.model - Enable linear model line (UI: "Linear model line", default: FALSE)

Each "Adjustment Function" is applied first and the matching "Adjustment" then rescales the result (e.g. log10, then z-score), the reverse of the order dittoViz::scatterPlot() applies its ⁠*.adj.fxn⁠ and ⁠*.adjustment⁠ in.

Fit lines (linear, best fit, and custom models) are fit to the values as plotted, after any X/Y adjustment, so they are drawn over the points they describe. A custom formula such as mpg ~ hp therefore models the adjusted values; do not repeat the adjustment inside it. No fit lines are drawn while an adjustment (as.factor) makes an axis categorical.

Author(s)

Jared Andrews

See Also

dittoViz::scatterPlot(), organize_inputs(), dittoViz_scatterPlotOutputUI(), dittoViz_scatterPlotServer(), dittoViz_scatterPlotApp()

Examples

library(VizModules)
dittoViz_scatterPlotInputsUI("scatterPlot", example_mtcars)

Description

This should be placed in the UI where the plot should be shown.

Usage

dittoViz_scatterPlotOutputUI(id, resizable = TRUE)

Arguments

Value

A Shiny plotlyOutput for the scatterplot

Author(s)

Jared Andrews

Description

Server logic for scatterPlot module

Usage

dittoViz_scatterPlotServer(
  id,
  data,
  hide.inputs = NULL,
  hide.tabs = NULL,
  defaults = NULL
)

Arguments

Value

The moduleServer function for the scatterPlot module.

Author(s)

Jared Andrews

See Also

dittoViz::scatterPlot(), dittoViz_scatterPlotInputsUI(), dittoViz_scatterPlotOutputUI(), dittoViz_scatterPlotApp()

Description

This function generates a Shiny application with modular dittoViz::yPlot() components. The app features a Data Import section for uploading data, a Data Table for filtering the active dataset, and a Plot area for configuring and displaying an interactive y plot.

Usage

dittoViz_yPlotApp(
  data_list = NULL,
  defaults = NULL,
  hide.inputs = NULL,
  hide.tabs = NULL
)

Arguments

Details

When data_list is not provided (or NULL), the app launches on example_demographics with the settings the module gallery (moduleGalleryApp()) opens this module on, so its main features are on show from the start; any defaults you pass are applied over those. Uploaded data files are added to the available datasets and can be selected for plotting. If an uploaded file shares a name with an existing dataset, the existing one is overwritten with a warning.

This is a convenience wrapper around createModuleApp().

Value

A Shiny app object.

Author(s)

Jared Andrews

See Also

dittoViz::yPlot(), dittoViz_yPlotInputsUI(), dittoViz_yPlotOutputUI(), dittoViz_yPlotServer()

Examples

library(VizModules)
# Launch with default example data:
app <- dittoViz_yPlotApp()
if (interactive()) runApp(app)

# Launch with custom data:
app2 <- dittoViz_yPlotApp(list("demographics" = example_demographics))
if (interactive()) runApp(app2)

Description

This should be placed in the UI where the inputs should be shown, with an id that matches the id used in the dittoViz_yPlotServer() and dittoViz_yPlotOutputUI() functions.

Usage

dittoViz_yPlotInputsUI(id, data, defaults = NULL, title = NULL, columns = 2)

Arguments

Details

The user inputs for this module are separated from the outputs to allow for more flexible UI design.

The inputs will automatically be organized into a grid layout via the organize_inputs() function, with columns controlling the number of columns in the grid.

Defaults can be set for each input by providing a named list of values to the defaults argument. Nearly all parameters for dittoViz::yPlot() can be set via these inputs, so see the help for that function for an exhaustive list.

The "Y Data" input accepts several columns at once. "Multivar Aesthetic" (on the Facet tab) then decides how they are shown: "split" gives each variable its own facet (alongside any split.by facets), while "group" and "color" put the variables on the x-axis or the fill legend respectively. With several variables the Stats tab is only available for the "split" aesthetic with no split.by set, and comparisons are then run separately within each variable's facet. The other layouts either replace the x-axis groups being compared or facet on two dimensions at once, neither of which the significance brackets can be placed against.

The "Y Adjustment Function" is applied first and the "Y Adjustment" then rescales the result (e.g. log10, then z-score), the reverse of the order dittoViz::yPlot() applies its var.adj.fxn and var.adjustment in.

Statistics are computed on the values as plotted, after any Y adjustment, and the Y Axis Min/Max and significance brackets are in those units too. With a ridge plot among the plot types the values run along the x-axis, so no brackets are drawn; the test results are still included in the source data download.

Value

A Shiny tagList containing the UI elements

Plot parameters not implemented or with altered functionality

The following dittoViz::yPlot() parameters are not available via UI inputs:

• xlab - X-axis label (plotly allows interactive editing)

• ylab - Y-axis label (auto-generated to reflect any applied Y adjustment, e.g. "z-score(log2(units))"; plotly allows interactive editing). With several Y variables only the adjustment is shown, as the variables are named by the facet strips or the legend instead

• main - Plot title (plotly allows interactive editing)

• sub - Plot subtitle (not supported in plotly)

• theme - ggplot2 theme (not applicable to plotly)

• legend.title - Legend title (managed by plotly interactively)

• add.line - Use hline.intercepts instead for horizontal lines with full styling options

• line.linetype - Use hline.linetypes instead

• line.color - Use hline.colors instead

• line.linewidth - Use hline.widths instead

• line.opacity - Use hline.opacities instead

• rows.use - Row subset to plot (not implemented)

• colors - Integer index/order into color.panel (managed via the palette UI)

• shape.panel - Shapes used with shape.by (not implemented)

• y.breaks - Custom continuous-axis breaks (not implemented)

• x.labels - Override group labels (not implemented)

• x.labels.rotate - Rotate group labels (handled by the Axes tab tick-angle controls)

• x.reorder - Reorder x-axis groups (not implemented)

• boxplot.width - Boxplot width (controlled via boxgap and boxgroupgap)

• boxplot.outlier.size - Outlier point size (not implemented)

• boxplot.position.dodge - Boxplot dodge (controlled via boxgap)

• vlnplot.quantiles - Violin quantiles (doesn't translate to plotly)

Plot parameters and defaults

The following dittoViz::yPlot() parameters can be accessed via UI inputs and/or the defaults argument:

• var - Y-axis variable(s) (UI: "Y Data", default: 2nd numeric variable). Several may be selected; multivar.aes then controls how they are displayed

• multivar.aes - Aesthetic used for multiple var columns (UI: "Multivar Aesthetic", default: "split")

• multivar.split.dir - Facet direction for multiple var columns (UI: "Multivar Split Dir", default: "col")

• group.by - Grouping variable for x-axis (UI: "Group by", default: 2nd categorical variable)

• color.by - Coloring variable (UI: "Color by", default: "")

• shape.by - Shape variable (UI: "Shape by", default: "")

• split.by - Faceting variable (UI: "Split by (facet)", default: "")

• plots - Plot types to show (UI: "Plots to show", default: c("boxplot", "jitter"))

• color.panel - Custom color values (UI: palette picker, derived from palette)

• min - Y-axis minimum, in the units plotted (after any var.adjustment/var.adj.fxn); set with the y.min key (UI: "Y Axis Min", auto-calculated). Not applied under a free y facet scale, where each panel spans its own data.

• max - Y-axis maximum, in the units plotted; set with the y.max key (UI: "Y Axis Max", auto-calculated). Not applied under a free y facet scale.

• var.adjustment - Y-axis data adjustment (UI: "Y Adjustment", default: "")

• var.adj.fxn - Y-axis adjustment function (UI: "Y Adjustment Function", default: "")

• split.nrow - Number of facet rows (UI: "Rows", default: 4)

• split.ncol - Number of facet columns (UI: "Columns", default: 4)

• split.adjust - Facet scale behavior (UI: "Facet Scaling", default: "fixed"). A free y scale ("free", "free_y") ignores Y Axis Min/Max and stacks each panel's significance brackets above that panel's own data.

• do.raster - Rasterize jitter points (UI: "Rasterize Jitter", default: FALSE)

• raster.dpi - DPI for rasterization (UI: "Raster DPI", default: 600)

• jitter.size - Jitter point size (UI: "Jitter Point Size", default: 1)

• jitter.width - Jitter width (UI: "Jitter Width", default: 0.2)

• jitter.color - Jitter border color (UI: "Jitter Border Color", default: "#000000")

• jitter.shape.legend.size - Shape legend size (UI: "Shape Legend Size", default: 5)

• jitter.shape.legend.show - Show shape legend (UI: "Show Shape Legend", default: TRUE)

• jitter.position.dodge - Jitter position dodge (calculated from boxgap)

• boxplot.show.outliers - Show boxplot outliers

• boxplot.color - Boxplot outline color (UI: "Boxplot Color", default: "#000000")

• boxplot.fill - Fill boxplot (UI: "Fill Boxplot", default: TRUE)

• boxplot.lineweight - Boxplot line weight (UI: "Boxplot Line Weight", default: 0.5)

• vlnplot.lineweight - Violin line weight (UI: "Violin Line Weight", default: 0.5)

• vlnplot.scaling - Violin scaling method (UI: "Violin Scaling", default: "area")

• vlnplot.width - Violin width (derived from boxgap; not directly settable)

• ridgeplot.lineweight - Ridge line weight (UI: "Ridge Line Weight", default: 0.5)

• ridgeplot.scale - Ridge overlap scale (UI: "Ridge Scale (overlap)", default: 1.25)

• ridgeplot.ymax.expansion - Ridge Y-max expansion (UI: "Ridge Y-max Expansion", default: NA)

• ridgeplot.shape - Ridge shape (UI: "Ridge Shape", default: "smooth")

• ridgeplot.bins - Ridge bins (UI: "Ridge Bins", default: 30)

• ridgeplot.binwidth - Ridge binwidth (UI: "Ridge Binwidth", default: NULL)

• hover.data - Columns shown on hover (UI: "Hover Data", default: ""; empty uses a sensible default set of columns)

• hover.round.digits - Hover value rounding (UI: "Hover Round Digits", default: 5)

• legend.show - Show the legend (UI: "Show Legend", default: TRUE)

• stats.enabled and the other ⁠stat.*⁠ parameters - Pairwise testing between the group.by groups, or between the color.by levels within each group when color.by is set (Stats tab). stat.pairs takes a character vector of "A vs B" strings naming those levels, e.g. "Office vs Remote"; left unset, every pair is tested

Parameters controlling additional functionality

The following parameters implementing new functionality or controlling plotly-specific features are also available:

• boxmode - Always "overlay": the boxes carry explicit x positions matching ggplot's dodge, so plotly.js is not asked to dodge them

• boxgap - Boxplot position dodge (UI: "Boxplot Position Dodge", default: 0.3)

• boxgroupgap - Boxplot group dodge (UI: "Boxplot Group Dodge", default: 0.2)

• title.font.size - Plot title font size (UI: "Title Size", default: 26)

• title.font.family - Font family for title text (UI: "Title Font", default: "Arial")

• title.font.color - Color for plot title (UI: "Title Color", default: "#000000")

• axis.title.font.size - Axis title font size (UI: "Axis Title Size", default: 18)

• axis.title.font.color - Axis title font color (UI: "Axis Title Color", default: "#000000")

• axis.title.font.family - Axis title font family (UI: "Axis Title Font", default: "Arial")

• axis.showline - Show axis border lines (UI: "Show Axis Lines", default: TRUE)

• axis.mirror - Mirror axis lines on opposite side (UI: "Mirror Axis Lines", default: TRUE)

• show.grid.x - Show X-axis major gridlines (UI: "Show X Major Gridlines", default: TRUE)

• show.grid.y - Show Y-axis major gridlines (UI: "Show Y Major Gridlines", default: TRUE)

• axis.linecolor - Color of axis lines (UI: "Axis Line Color", default: "black")

• axis.linewidth - Width of axis lines (UI: "Axis Line Width", default: 0.5)

• axis.tickfont.size - Size of tick labels (UI: "Tick Label Size", default: 12)

• axis.tickfont.color - Color of tick labels (UI: "Tick Label Color", default: "black")

• axis.tickfont.family - Font family for tick labels (UI: "Tick Label Font", default: "Arial")

• axis.tickangle.x - Rotation angle for X-axis tick labels (UI: "X-axis Tick Label Angle", default: 0)

• axis.tickangle.y - Rotation angle for Y-axis tick labels (UI: "Y-axis Tick Label Angle", default: 0)

• axis.ticks - Position of tick marks (UI: "Tick Position", default: "outside")

• axis.tickcolor - Color of tick marks (UI: "Tick Mark Color", default: "black")

• axis.ticklen - Length of tick marks (UI: "Tick Mark Length", default: 5)

• axis.tickwidth - Width of tick marks (UI: "Tick Mark Width", default: 1)

• legend.font.family - Font family of the legend title and labels (UI: "Legend Font", default: "Arial")

• legend.font.color - Font color of the legend title and labels (UI: "Legend Font Color", default: "#000000")

• legend.title.size - Legend title font size (UI: "Legend Title Size", default: 14)

• legend.text.size - Legend entry label font size (UI: "Legend Text Size", default: 12)

• hline.intercepts - Y-coordinates for horizontal reference lines (UI: "Y-intercepts", default: "")

• hline.colors - Colors for horizontal lines (UI: "Colors", default: "#000000")

• hline.widths - Widths for horizontal lines (UI: "Widths", default: "1")

• hline.linetypes - Line types for horizontal lines (UI: "Line Types", default: "dashed")

• hline.opacities - Opacities for horizontal lines (UI: "Opacities (0-1)", default: "1")

• vline.intercepts - X-coordinates for vertical reference lines (UI: "X-intercepts", default: "")

• vline.colors - Colors for vertical lines (UI: "Colors", default: "#000000")

• vline.widths - Widths for vertical lines (UI: "Widths", default: "1")

• vline.linetypes - Line types for vertical lines (UI: "Line Types", default: "dashed")

• vline.opacities - Opacities for vertical lines (UI: "Opacities (0-1)", default: "1")

• abline.slopes - Slopes for diagonal reference lines (UI: "Slopes", default: "")

• abline.intercepts - Y-intercepts for diagonal lines (UI: "Y-intercepts", default: "")

• abline.colors - Colors for diagonal lines (UI: "Colors", default: "#000000")

• abline.widths - Widths for diagonal lines (UI: "Widths", default: "1")

• abline.linetypes - Line types for diagonal lines (UI: "Line Types", default: "dashed")

• abline.opacities - Opacities for diagonal lines (UI: "Opacities (0-1)", default: "1")

• palette.colours - Named character vector mapping group levels to colors, e.g. c(A = "#FF0000", B = "blue") (UI: "Plot colors"). Seeds the picker; unnamed groups fall back to the default palette and user edits take precedence.

• annotate.by - Column whose values identify and label jitter points (UI: "Annotate By", default: "")

• highlight.points - Values from the annotate.by column to highlight (UI: "Points to Highlight", default: ""). Values containing spaces (e.g. "CD4 T") must be separated by commas or new lines

• highlight.color - Fill color for highlighted points (UI: "Highlight Fill", default: "#00FFF7")

• highlight.size - Size of highlighted points (UI: "Highlight Size", default: 7)

• highlight.border.color - Border color for highlighted points (UI: "Highlight Border Color", default: "#000000")

• highlight.border.width - Border width for highlighted points (UI: "Highlight Border Width", default: 1)

• highlight.auto.annotate - Label highlighted points automatically (UI: "Auto-annotate Highlights", default: TRUE)

• annotation.color - Annotation text color (UI: "Annotation Color", default: "black")

• annotation.ax - Horizontal label offset in pixels (UI: "Annotation X Offset", default: 20)

• annotation.ay - Vertical label offset in pixels (UI: "Annotation Y Offset", default: -20)

• annotation.size - Annotation font size (UI: "Annotation Size", default: 10)

• annotation.showarrow - Draw an arrow from label to point (UI: "Show Arrow", default: TRUE)

• annotation.arrowcolor - Annotation arrow color (UI: "Arrow Color", default: "black")

• annotation.arrowhead - Annotation arrowhead style (UI: "Arrowhead Style", default: 2)

• annotation.arrowwidth - Annotation arrow line width (UI: "Arrow Linewidth", default: 1.5)

Author(s)

Jared Andrews, Jacob Martin

See Also

dittoViz::yPlot(), organize_inputs(), dittoViz_yPlotOutputUI(), dittoViz_yPlotServer(), dittoViz_yPlotApp()

Examples

library(VizModules)
data(mtcars)
dittoViz_yPlotInputsUI("yPlot", mtcars)

Description

This should be placed in the UI where the plot should be shown.

Usage

dittoViz_yPlotOutputUI(id, resizable = TRUE)

Arguments

Value

A Shiny plotlyOutput for the yPlot

Author(s)

Jared Andrews

Description

Server logic for yPlot module

Usage

dittoViz_yPlotServer(
  id,
  data,
  hide.inputs = NULL,
  hide.tabs = NULL,
  defaults = NULL
)

Arguments

Value

The moduleServer function for the yPlot module.

Author(s)

Jared Andrews, Jacob Martin

See Also

dittoViz::yPlot(), dittoViz_yPlotInputsUI(), dittoViz_yPlotOutputUI(), dittoViz_yPlotApp()

Description

The raster counterpart to draw_to_svg(), for the same job: letting a module whose output is not a plotly graph supply its own artwork to an export. Where draw_to_svg() yields markup to splice, this yields the bytes of a finished file.

Usage

draw_to_png(draw_fn, width, height, res = 72, scale = 2, bg = "white")

Arguments

Value

A raw vector holding a PNG file, or NULL if the requested size is not usable or the R build has no PNG support. An error raised by draw_fn itself propagates to the caller; the device is closed either way.

Author(s)

Jared Andrews

See Also

draw_to_svg() for the vector counterpart.

Examples

png_bytes <- draw_to_png(function() plot(1:10), width = 480, height = 360)
head(png_bytes, 4)

Description

Draws onto an SVG device and returns the markup, ready to be placed inside a larger SVG document. This is what lets a module whose output is not a plotly graph still contribute vector art to the Figure Builder's figure export: see the vector_svg attribute documented in figureBuilderServer().

Usage

draw_to_svg(draw_fn, width, height, res = 72, id_prefix = NULL, bg = "white")

Arguments

Details

svglite is used when it is installed, because it writes real ⁠<text>⁠ elements, so labels stay editable in a vector editor. The cairo device (grDevices::svg()) is the fallback: still vector, but it converts text to glyph paths, which cannot be edited or restyled afterwards.

Value

A character scalar holding an ⁠<svg>⁠ element, or NULL if the requested size is not usable or the R build can reach neither SVG device (no svglite installed and no working cairo – which on macOS needs XQuartz). An error raised by draw_fn itself (a panel dragged too small to leave any plotting room, say) propagates to the caller, which is better placed to decide whether to drop that panel or fail the whole export; the device is closed either way.

The result is a fragment: it carries no XML declaration and no xmlns, because it is meant to be spliced into a document that already declares them. That makes it unopenable as a file on its own – writing one out directly needs the namespace restated first.

Author(s)

Jared Andrews

See Also

draw_to_png() for the raster counterpart.

Examples

svg <- draw_to_svg(function() plot(1:10), width = 480, height = 360)
substr(svg, 1, 24)

Description

Generates a customizable interactive dumbbell plot using plotly. Supports single dot mode (1 x variable) or dumbbell mode (2 x variables), with flexible coloring by either X or Y variables, faceting, and transformations.

Usage

dumbbellPlot(
  data,
  x,
  y,
  colour.by = "X variables",
  palette.selection,
  show.legend = TRUE,
  facet.by = NULL,
  line.colour = "gray80",
  point.size = 12,
  facet.scales = "fixed",
  subplot.margin = 0.05,
  axis.showline = TRUE,
  axis.mirror = TRUE,
  axis.linecolor = "black",
  axis.linewidth = 0.5,
  axis.tickfont.size = 12,
  axis.tickfont.color = "black",
  axis.tickfont.family = "Arial",
  axis.tickangle.x = 0,
  axis.tickangle.y = 0,
  axis.ticks = "outside",
  axis.tickcolor = "black",
  axis.ticklen = 5,
  axis.tickwidth = 1,
  axis.title.font.size = 18,
  axis.title.font.color = "black",
  axis.title.font.family = "Arial",
  show.grid.x = TRUE,
  show.grid.y = TRUE,
  grid.color = "#CCCCCC",
  facet.title.font.size = 18,
  facet.title.font.color = "black",
  facet.title.font.family = "Arial",
  title.text = "",
  title.font.size = 26,
  title.font.family = "Arial",
  title.font.color = "black",
  title.x.position = 0.47,
  y.title = NULL,
  x.title = NULL,
  flip.x = FALSE,
  flip.y = FALSE,
  x.adjustment = NULL,
  order.by = NULL
)

Arguments

Details

The dumbbell plot is designed for comparing two values across categories.

Modes:

• Single dot mode (1 x variable): Shows one marker per y category

• Dumbbell mode (2 x variables): Shows two markers connected by a line per y category

Coloring options:

• By X variables: Each x variable gets a different color (e.g., Male=blue, Female=pink)

• By Y variables: Each y category gets a different color (e.g., School A=red, School B=blue)