Package {VizModules}

Title:	Flexible, Interactive 'shiny' Modules for Almost Any Plot
Version:	0.4.0
Description:	Offers a core selection of interactivity-first 'shiny' modules for many plot types meant to serve as flexible building blocks for applications and as the base for more complex modules. These modules allow for the rapid and convenient construction of 'shiny' apps with very few lines of code and decouple plotting from the underlying data. These modules allow for full plot aesthetic customization by the end user through UI inputs. Utility functions for simple UI organization, automated UI tooltips, and additional plot enhancements are also provided. Includes a multi-panel figure builder app for arranging multiple modules together in a free-form layout.
License:	MIT + file LICENSE
Depends:	shiny, dittoViz, plotly, R (≥ 4.5), shinyBS, plotthis (≥ 0.13.0)
Imports:	roclang, colourpicker, dplyr, DT, readxl, shinyjs, scales, shinyjqui, ggplot2, htmltools, jsonlite, methods, shinyWidgets (≥ 0.7.0), htmlwidgets, zip
Encoding:	UTF-8
LazyData:	true
Suggests:	drc, withr, ComplexHeatmap, InteractiveComplexHeatmap, circlize, grid, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
URL:	https://j-andrews7.github.io/VizModules/, https://github.com/j-andrews7/VizModules
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-08-28 20:12:02 UTC; jandrews
Author:	Jared Andrews [aut, cre], Jacob Martin [aut]
Maintainer:	Jared Andrews <jared.andrews07@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-28 20:50:02 UTC

Null-or-empty coalescing operator

Description

Returns the left-hand side unless it is NULL or has length zero, in which case the right-hand side is returned.

Usage

x %__% y

Arguments

Value

x when present, otherwise y.

Author(s)

Jared Andrews

Forward colorbar drag events to a Shiny input

Description

Continuous-colour legends (colorbars) live on a trace's marker, so dragging one fires a plotly_restyle event, which event_data() does not expose. This attaches an onRender listener that reports the dropped colorbar x/y to a Shiny input so the position can be captured and re-applied across rebuilds.

Usage

.add_colorbar_listener(fig, input_id)

Arguments

Value

The figure with the listener attached.

Author(s)

Jared Andrews

Add custom model line traces to all subplot panels

Description

Renders a named list of pre-fitted model objects as overlay lines on a plotly scatter figure. Each model is evaluated across the x range of the data using stats::predict() and added as a separate add_lines() trace. Handles faceted subplots by adding each model line to every panel.

Usage

.add_custom_model_lines_to_subplots(
  fig,
  df,
  x.col,
  custom.models,
  split.by = NULL,
  line_color = "#000000",
  line_width = 2,
  backend = NULL
)

Arguments

Details

Each entry in custom.models is a fitted model object (e.g. from lm(), glm(), loess(), or nls()). The list name becomes the legend label. Line colour and width are shared across all entries and controlled via the line_color and line_width arguments.

Value

The modified plotly figure with custom model lines added.

Author(s)

Jacob Martin

Add fit line traces to all subplot panels

Description

Adds linear or LOESS fit line traces to a plotly figure, handling subplot panels when faceting is applied. Determines subplot axes from existing traces and adds fit lines to each panel.

Usage

.add_fit_lines_to_subplots(
  fig,
  df,
  x.col,
  y.col,
  split.by = NULL,
  group.col = NULL,
  color_mapping = NULL,
  line_color = "#000000",
  fit_type = c("linear", "loess"),
  span = 0.75,
  line_width = 3
)

Arguments

Value

The modified plotly figure with fit lines added to all subplot panels.

Author(s)

Jared Andrews, Jacob Martin

Add multi-axis traces to a plotly figure

Description

Appends scatter traces for each element of a multi-valued x or multi-valued y vector to an existing plotly figure. Handles data ordering, line/marker styling, and palette colouring.

Usage

.add_multi_axis_traces(
  fig,
  data,
  x,
  y,
  order.cols,
  plot.mode,
  line.type,
  palette.selection,
  show.legend = TRUE
)

Arguments

Value

The modified plotly figure with added traces.

Author(s)

Jared Andrews

Derive a stable key for a manually-editable annotation

Description

Manual edits (drag/text changes) are captured against annotation indices, but those indices shift between rebuilds (e.g. when statistical brackets or reference labels are added/removed). To re-apply edits reliably, annotations are matched by a stable key derived from their content rather than position: draggable axis titles are keyed by axis side, all other annotations by their text. Returns NULL for annotations that cannot be keyed.

Usage

.annotation_edit_key(ann)

Arguments

Value

A character key (e.g. "axis:x", "axis:y", or "text:Sepal.Length"), or NULL if no stable key applies.

Author(s)

Jared Andrews

Build occurrence-disambiguated keys for a list of annotations

Description

Several annotations can share the same text (e.g. point labels for repeated categories), which would otherwise collapse to one key and cause a single drag to move every match. This appends a per-key occurrence index so each annotation maps to a distinct, rebuild-stable slot. Order is preserved across rebuilds because annotations are regenerated deterministically.

Usage

.annotation_edit_keys(anns)

Arguments

Value

A character vector the same length as anns; entries are NA for annotations that cannot be keyed.

Author(s)

Jared Andrews

Restyle highlighted points in a plotly figure

Description

Applies highlight marker styling (fill, size, border) to the points of a plotly figure whose annotate.by value appears in highlight_vals. Points are matched on their annotation value parsed out of the hover text rather than on coordinates, because ggplotly() encodes categorical axes as numeric positions that will not match the raw data values.

Usage

.apply_highlight_styling(
  fig,
  annotate.by,
  highlight_vals,
  style,
  default.size = NULL,
  show.others = TRUE,
  require.markers = FALSE
)

Arguments

Value

The plotly figure with highlight styling applied.

Author(s)

Jared Andrews

Is an axis limit present and already at or above a required minimum?

Description

Is an axis limit present and already at or above a required minimum?

Usage

.axis_limit_clears(limit, required)

Author(s)

Jared Andrews

Normalize a module's "no selection" column input to NULL

Description

Module selects use "" for "none". Statistics helpers expect NULL, and a grouping column that is numeric is a gradient rather than a nesting, which the renders already treat as no grouping.

Usage

.blank_to_null(value, df = NULL, numeric_is_null = FALSE)

Arguments

Value

value, or NULL.

Author(s)

Jared Andrews

Build palette select options

Description

Creates option and optgroup tags used by the palette selector input.

Usage

.build_palette_options(palette_source, selected_palette)

Arguments

Value

A tagList containing the option/optgroup elements.

Author(s)

Jared Andrews

Build trace-to-annotation mapping

Description

Creates a mapping between trace data and annotation values by parsing trace hover text. This is used for robust point matching when creating annotations.

Usage

.build_trace_anno_map(trace, annotate.by)

Arguments

Value

A data frame with columns:

• coord_id: Unique coordinate identifier string

• anno_value: Extracted annotation value Returns NULL if trace has no valid data.

Author(s)

Jared Andrews

Calculate axis range from data

Description

Computes a numeric range for the Y-axis based on specified columns in a data frame, applying a scaling factor to the maximum value. Handles both simple (non-stacked) and stacked bar scenarios, where stacking occurs when group.by or fill.by is numeric.

Usage

.calculate_range(
  df,
  data_col_x = NULL,
  data_col_y = NULL,
  axis_scale_factor,
  grouping = FALSE,
  stack_by = NULL
)

Arguments

Details

The function resolves the primary data column(s) from data_col_y or data_col_x and validates that they exist and are numeric in df. Blank and NA names are dropped first, and NULL is returned if nothing usable remains.

Behaviour depends on whether bars are stacked:

• Non-stacked (grouping = FALSE, categorical or absent stack_by): the Y range is computed directly from the raw column values using min() and max().

• Stacked (grouping = TRUE or stack_by is numeric): Y values are summed within each unique X category using tapply(), and the maximum of those sums is used. The minimum is fixed at 0 since stacked bars always originate from zero.

Non-finite results (e.g. from empty or all-NA columns) are replaced with default values of 0 for the minimum and 1 for the maximum.

Value

A named list with components min and max giving the lower and upper limits for the Y-axis, or NULL if any required column is missing, non-numeric, or otherwise invalid.

Author(s)

Jacob Martin

Capture manual plot edits from a plotly relayout event

Description

Reads a plotly_relayout event payload and records user-driven repositioning/edits of the legend and annotations (including draggable axis titles) into a persistent list. Annotation entries are keyed via .annotation_edit_key() so they survive index shifts on rebuild. Range/zoom and autosize keys are ignored so panning does not pin the axes.

Usage

.capture_manual_edits(edits, relayout, fig)

Arguments

Value

The updated edits list.

Author(s)

Jared Andrews

Compute predicted values from a custom model object

Description

Generates a smooth grid of predicted x/y values from any model object that supports stats::predict(). The x variable name used in predict() must match x.col so that newdata is constructed correctly.

Usage

.compute_custom_model_fit(model, df, x.col, n.points = 100, backend = NULL)

Arguments

Details

For models that require additional columns in newdata (e.g. mixed-effects models from lme4 that need random-effect grouping columns), all other numeric columns in df are included in newdata at their median value and all non-numeric columns at their first level/value. This allows predict(..., re.form = NA) (population-level predictions) to succeed for lmer/glmer models.

Note: lme4::lmer() must be called with an explicit ⁠data =⁠ argument when fitting the model, otherwise the formula environment cannot be resolved.

Value

A data.frame with columns x and y, or NULL on failure.

Author(s)

Jacob Martin

Compute linear regression fit line data

Description

Computes predicted values from a linear model for plotting a fit line. Can optionally compute separate fit lines for each group in a grouping variable.

Usage

.compute_linear_fit(df, x.col, y.col, group.col = NULL, n.points = 100)

Arguments

Value

If group.col is NULL, a data frame with columns x and y. If group.col is provided, a named list of data frames (one per group).

Author(s)

Jared Andrews

Compute LOESS smooth fit line data

Description

Computes predicted values from a LOESS model for plotting a smooth fit line. Can optionally compute separate fit lines for each group in a grouping variable.

Usage

.compute_loess_fit(
  df,
  x.col,
  y.col,
  group.col = NULL,
  span = 0.75,
  n.points = 100
)

Arguments

Value

If group.col is NULL, a data frame with columns x and y. If group.col is provided, a named list of data frames (one per group).

Author(s)

Jared Andrews

Create coordinate identifier for matching points

Description

Creates a unique coordinate identifier string for matching points between traces and data frames.

Usage

.create_coord_id(x, y, precision = 10)

Arguments

Value

Character vector. Coordinate identifiers in format "x_y".

Author(s)

Jared Andrews

Create a Dumbbell Plot for a Single Dataset

Description

Helper function that generates a plotly scatter plot in either single dot or dumbbell mode for one dataset (i.e., one facet). Called internally by dumbbellPlot().

Usage

.create_dumbbell_plot(
  data,
  x,
  y,
  colour.by,
  palette.selection,
  line.colour,
  show.legend
)

Arguments

Value

A plotly object representing the dumbbell (or single dot) plot for the supplied data.

Author(s)

Jacob Martin

Create annotations for highlighted points

Description

Creates plotly annotation objects for points highlighted by value matching. This function finds all points in the plot data that match the highlight values and creates annotations for them.

Usage

.create_highlight_annotations(
  plot_data,
  fig,
  annotate.by,
  highlight_vals,
  x_col,
  y_col,
  annotation_params,
  show.others = TRUE,
  require.markers = FALSE
)

Arguments

Value

List of plotly annotation objects, or NULL if no valid annotations.

Author(s)

Jared Andrews

Create annotations for selected points

Description

Creates plotly annotation objects for selected points from event_data("plotly_selected"). This function handles the complex logic of matching selected points to their corresponding traces and extracting annotation text.

Usage

.create_selected_annotations(
  selected_data,
  fig,
  annotate.by,
  annotation_params,
  show.others = TRUE,
  require.markers = FALSE
)

Arguments

Value

List of plotly annotation objects, or NULL if no valid annotations.

Author(s)

Jared Andrews

Add a custom bubble-size legend to a plotly figure

Description

Renders a manual size legend as a vertical column of HTML circle annotations alongside matching numeric labels. The legend is placed outside the right edge of the plot area using paper-referenced coordinates so it does not overlap data.

Usage

.custom_legend(
  fig,
  data,
  size_by,
  gap = 0.05,
  size_values = NULL,
  title.size = NULL,
  text.size = NULL,
  start_y = 0.95,
  start_x = 1.02
)

Arguments

Value

The plotly figure with size-legend annotations appended, or the unmodified figure when size_by is NULL/empty or not present in data.

Author(s)

Jacob Martin

Extract a caller-supplied group color mapping from defaults

Description

Looks up key in a module's defaults and returns it as a named vector of hex colors suitable for resolve_palette() and multiColorPicker(). Values may be given as R color names ("red") or hex codes; both are normalized to ⁠#RRGGBB⁠. Anything that is not a fully named character vector is ignored, consistent with get_default()'s silent-fallback contract.

Usage

.default_group_colors(defaults, key)

Arguments

Value

A named character vector of hex colors, or NULL when defaults supplies no usable mapping.

Author(s)

Jared Andrews

See Also

resolve_palette(), get_default()

Extract annotation text from trace hover text

Description

Parses the hover text of a plotly trace to extract the value of a specific annotation field.

Usage

.extract_annotation_from_text(trace_text, annotate.by)

Arguments

Details

The hover text is expected to be in the format: "field1: value1\nfield2: value2\n..." or "field1 value1\nfield2 value2\n..."

Value

Character. The extracted annotation value, or NULL if not found.

Author(s)

Jared Andrews

Extract marker sizes from a plotly figure

Description

Builds the figure (to consolidate any deferred trace attributes) and collects the numeric marker sizes across all traces. Used to derive a custom size legend that matches the plot's actual point sizes.

Usage

.extract_marker_sizes(fig)

Arguments

Value

A numeric vector of finite marker sizes, possibly empty.

Author(s)

Jared Andrews

Identify columns valid for faceting or splitting

Description

Scans a data frame and returns the names of columns that are appropriate choices for a facet/split selector. A column qualifies when it is categorical (character or factor) and has fewer than 50 unique values. This keeps facet/split inputs from offering numeric columns or high-cardinality categoricals that would produce an unwieldy number of panels.

Usage

.facet_check(data)

Arguments

Details

Intended to populate the choices of a facet/split viz_select_input() via update_viz_select() inside a module server, so that only sensible faceting variables are exposed to the user.

A column is considered valid when both of the following hold:

• It is categorical: is.character(col) or is.factor(col).

• It has fewer than 50 unique values (NAs excluded).

Numeric columns and categorical columns with 50 or more distinct values are always excluded.

Value

A character vector of column names suitable for faceting/splitting. Returns character(0) when no column qualifies.

Author(s)

Jacob Martin

Fix boxplot positioning across faceted subplots

Description

Sets the offsetgroup property on each box trace to ensure consistent positioning across faceted subplot panels. Without this, plotly.js may calculate different box offsets per subplot when boxmode = "group" is used, causing boxes in different facets to appear at different x-positions.

Usage

.fix_boxplot_facet_positions(fig)

Arguments

Details

When ggplotly converts a faceted ggplot, each facet becomes a subplot with its own axis pair. Plotly.js calculates box offsets independently per subplot unless offsetgroup is explicitly set on each trace. This function sets offsetgroup to the trace's name property (which corresponds to the color/grouping variable level), ensuring identical positioning of same-group boxes across all facet panels.

Value

The modified plotly figure with offsetgroup set on all box traces.

Author(s)

Jared Andrews

Flatten nested palette options

Description

Converts a nested list of palette choices into a single-level named list where each entry is a character vector of colors.

Usage

.flatten_palette_options(palettes)

Arguments

Value

A flattened named list of palettes.

Author(s)

Jared Andrews

Does every value of one column map to exactly one value of another?

Description

dittoViz::freqPlot() stop()s when group.by (or color.by) does not resolve to a single value per sample, so the module filters the offered choices rather than letting the plot call error out.

Usage

.freq_maps_one_per(keys, values)

Arguments

Value

TRUE when each distinct key carries exactly one distinct value.

Author(s)

Jared Andrews

Columns usable as sample.by for a given grouping

Description

A sample column must be categorical, have more than one level, must not be one of the grouping columns, and every one of its levels must sit inside a single level of each supplied grouping column.

Usage

.freq_sample_choices(data, group.cols = character(0))

Arguments

Details

Unlike the facet and grouping selectors this deliberately does not go through .facet_check(): samples are the unit of observation rather than a facet, so a study with more than fifty of them is perfectly reasonable. Columns with a level for (nearly) every row are excluded instead, since a row identifier would give one observation per "sample" and so a frequency of 0 or 1 everywhere.

Value

A character vector of column names, possibly empty.

Author(s)

Jared Andrews

Normalize the multi-select vars.use input

Description

.blank_to_null() returns NULL for anything that is not length one, so a multi-value selection would read as "no selection" and silently draw every facet. Empty entries are dropped and an empty result becomes NULL, which is dittoViz::freqPlot()'s "use them all".

Usage

.freq_selected_vars(x)

Arguments

Value

A character vector of selected levels, or NULL.

Author(s)

Jared Andrews

The nested grouping column statistics should use, if any

Description

The x-axis of the summarised frame is always its grouping column. A separate color.by nests boxes inside each group and so is a second grouping factor for the tests; a color.by that is unset or the same column as group.by is not.

Usage

.freq_stats_group_col(group.by, color.by)

Arguments

Value

The color column name, or NULL.

Author(s)

Jared Andrews

The frequency table dittoViz::freqPlot() actually plots

Description

freqPlot() does not plot columns of the incoming data; it tabulates the frequency of var within each sample and plots that summary. Axis limits, statistics and point annotations must therefore all be computed against this frame rather than against the input.

Usage

.freq_summary(
  data,
  var,
  sample.by = NULL,
  group.by,
  color.by = NULL,
  scale = "percent",
  max.normalize = FALSE,
  vars.use = NULL
)

Arguments

Details

freqPlot(data.only = TRUE) returns before applying its own vars.use subsetting, so the summary it hands back disagrees with the plot whenever vars.use is set. The subsetting is reapplied here.

Value

The summary data frame, or NULL when it cannot be computed.

Author(s)

Jared Andrews

Name of the summary column dittoViz::freqPlot() plots on the y-axis

Description

Name of the summary column dittoViz::freqPlot() plots on the y-axis

Usage

.freq_y_col(scale = "percent", max.normalize = FALSE)

Arguments

Value

A single column name.

Author(s)

Jared Andrews

Test whether a color vector names its groups

Description

Test whether a color vector names its groups

Usage

.has_group_names(x)

Arguments

Value

TRUE when x is non-empty and carries at least one non-empty name.

Author(s)

Jared Andrews

Build one annotation track's color mapping

Description

Numeric values get a continuous gradient from low_color/mid_color/ high_color, mirroring the main value palette's col_fun; anything else is treated as categorical and uses discrete_colors (a named vector, one hex color per level, as returned by multiColorPicker()) directly.

Usage

.heatmap_annotation_col(
  values,
  low_color = NULL,
  mid_color = NULL,
  high_color = NULL,
  discrete_colors = NULL
)

Arguments

Value

A circlize::colorRamp2() function for numeric values, a named character vector (one color per level) otherwise, or NULL when there's nothing usable to build a mapping from (no non-NA values, or the needed colors weren't supplied).

Author(s)

Jared Andrews

Summarize what color widget(s) one axis's annotation rows need

Description

A pure, input-agnostic reduction of input$row_annotations/ input$column_annotations plus the source data frame down to just what determines a row's color widget's shape: its column name, whether it's numeric, and (if not) its sorted distinct levels. Used to decide whether the dynamically-rendered color widgets need to be rebuilt at all — see ComplexHeatmap_HeatmapServer(), where this is wrapped in a shiny::reactiveVal() that only updates (and so only triggers a renderUI() rebuild) when the spec actually changes. Without that, a renderUI() keyed directly on the raw data frame would rebuild — and reset — every color widget whenever the data changes at all (e.g. an unrelated "Data Table" filter tweak), even when every annotated column's own values/levels are untouched.

Usage

.heatmap_annotation_spec(rows, df)

Arguments

Value

A named list (row name -> list(column, numeric, levels), levels present only when numeric is FALSE), omitting rows with no usable column picked. Never NULL (an empty list when there's nothing to show).

Author(s)

Jared Andrews

Id for one annotation row's dynamically-rendered color widget(s)

Description

The "Annotations" tab renders a color-control widget per multiDynamicInput row (Low/Mid/High colour pickers for a numeric column, a multiColorPicker() for a categorical one) in a renderUI() below the row list — see ComplexHeatmap_HeatmapServer(). This derives that widget's (unnamespaced) input id from the row's own name ("row1", "row2", ...), used identically by the renderUI that builds the widget and by the code that later reads its value back, so the two can never drift apart.

Usage

.heatmap_annotation_widget_id(prefix, row_name)

Arguments

Value

A single string, safe to use as an HTML id.

Author(s)

Jared Andrews

Build a row or column HeatmapAnnotation from multiDynamicInput rows

Description

Build a row or column HeatmapAnnotation from multiDynamicInput rows

Usage

.heatmap_build_annotation(
  rows,
  source_df,
  key_values,
  key_col = NULL,
  which = c("row", "column"),
  color_lookup
)

Arguments

Value

A ComplexHeatmap::rowAnnotation()/ComplexHeatmap::columnAnnotation() object, or NULL if there are no usable rows.

Author(s)

Jared Andrews

The heatmap module's default low/mid/high value colors

Description

Blue/white/red, used to seed the "Low Color"/"Mid Color"/"High Color" pickers (the source of truth for circlize::colorRamp2()) and the reset handler. A single constant rather than three repeated hex literals.

Usage

.heatmap_default_colors()

Value

A length-3 character vector: low, mid, high.

Author(s)

Jared Andrews

Normalize the ComplexHeatmap module's data argument

Description

data() accepts either a plain data frame (the module's original, single-table behavior: the matrix and any row-annotation columns all live in one data frame) or ⁠list(matrix = <data.frame>, column_annotations = <data.frame>)⁠ (adds a companion per-sample metadata table, keyed by a column matching the matrix's selected column names, for column annotations). This normalizes either shape to the list form.

Usage

.heatmap_resolve_data(d)

Arguments

Details

Deliberately does not use the shared .require_data_frame() — that helper coerces its input straight to one data frame via as.data.frame(), which would mangle the two-table list shape.

This is a plain function (no shiny::validate()/shiny::req()) so it can be called both from the server (inside a reactive(), where the caller is expected to have already validated d's shape) and from the UI function (a plain, non-reactive call at UI-build time).

Value

A list with matrix (data frame) and column_annotations (data frame or NULL).

Author(s)

Jared Andrews

Resolve a single row/column split method + count into Heatmap() arguments

Description

ComplexHeatmap::Heatmap() exposes two independent ways to split rows (or columns) into groups — row_km (k-means) and row_split (an integer cuts the hierarchical clustering dendrogram into that many groups) — and errors if both are supplied as more than their "no split" defaults at once ("You can not perform k-means clustering since you have already specified a clustering object."). This resolves the module's single ⁠*_split_by⁠/⁠*_split_n⁠ UI pair into exactly one of row_km/row_split (never both), so that error can't occur.

Usage

.heatmap_resolve_split(method, n, dim_n)

Arguments

Details

Both methods are clamped to the matrix dimension, but not to the same bound. k-means is clamped to one less than the dimension, not equal to it — confirmed empirically that row_km == nrow(mat) reliably errors ("number of cluster centres must lie between 1 and nrow(x)") while row_km == nrow(mat) - 1 does not. A bare hierarchical row_split count, by contrast, tolerates being equal to (or even greater than) the dimension without erroring.

Value

A list with km (integer, 1L when unused) and split (integer or NULL), suitable for Heatmap(row_km = res$km, row_split = res$split, ...).

Author(s)

Jared Andrews

Z-score a matrix by row or column

Description

base::scale() z-scores the columns of a matrix. This applies it either way, and to a zero-variance row/column (constant values, sd 0) — which scale() turns into NaN for every entry via a 0/0 division, not just where the input was already missing — pins the result to 0 (no deviation from the mean) instead. Missing (NA) input cells are left NA either way, so ComplexHeatmap::Heatmap()'s na_col still renders them as missing rather than as a z-score of zero.

Usage

.heatmap_scale_matrix(mat, scale = c("none", "row", "column"))

Arguments

Value

The (possibly) scaled matrix, with the same dimnames as mat.

Author(s)

Jared Andrews

Hide jitter points from plotly legend

Description

Hides jitter point traces from the legend by setting showlegend to FALSE. The jitter points remain visible in the plot but do not clutter the legend with individual point entries.

Usage

.hide_jitter_from_legend(fig)

Arguments

Details

This function iterates through all traces in the plotly figure and identifies scatter traces that represent jitter points (mode = "markers"). For each jitter trace, it sets showlegend to FALSE, preventing them from appearing in the legend while keeping them visible in the plot. Box traces and other trace types are returned unchanged.

Value

The modified plotly figure with jitter points hidden from the legend.

Author(s)

Jacob Martin

Prettify a field key into a label

Description

Prettify a field key into a label

Usage

.mdi_prettify(key)

Arguments

Value

A human-friendly label.

Author(s)

Jacob Martin

Resolve a field spec to an input constructor function

Description

Resolve a field spec to an input constructor function

Usage

.mdi_resolve_fn(spec)

Arguments

Value

An input constructor function.

Author(s)

Jacob Martin

Convert a rows value into the client JSON payload

Description

Convert a rows value into the client JSON payload

Usage

.mdi_value_to_payload(value, field_keys)

Arguments

Value

A list of ⁠{ fields: [{ key, value }, ...] }⁠ row objects.

Author(s)

Jacob Martin

Merge two sets of plotly point annotations

Description

Appends extra annotations to annos, skipping any that already describe the same point and text so a point selected by hand and also matched by a highlight value is only labelled once.

Usage

.merge_annotation_sets(annos, extra)

Arguments

Value

The combined list of annotation objects, or NULL when both are empty.

Author(s)

Jared Andrews

HTML dependency for the multi-color picker widget

Description

Points htmltools to the bundled JavaScript assets so Shiny can initialize the widget on the client.

Usage

.multi_color_picker_dependency()

Value

An htmltools::htmlDependency object.

Author(s)

Jared Andrews

HTML dependency for the multi-dynamic input widget

Description

HTML dependency for the multi-dynamic input widget

Usage

.multi_dynamic_input_dependency()

Value

An htmltools::htmlDependency object.

Author(s)

Jacob Martin

Stack several data columns into dittoViz's multi-variable long format

Description

Reproduces the reshape dittoViz::yPlot() performs internally when it is given more than one var: the data frame is repeated once per column, the column's values are gathered into var.multi, and the column's name is recorded in var.which. Downstream code (e.g. statistics computed per variable facet) can then work against the same rows the plot was built from.

Usage

.multivar_long_df(df, vars)

Arguments

Details

No data adjustment is applied here; the raw column values are carried over, matching how the module computes statistics from the unadjusted data.

Value

A data frame with length(vars) times as many rows as df, plus the var.multi (values) and var.which (source column name) columns.

Author(s)

Jared Andrews

Convert NA or empty string to NULL

Description

A helper function to convert NA values or empty strings to NULL. Used to handle Shiny input default values which return NA or "" instead of NULL when the input field is empty. numericInput returns NA, textInput returns "".

Usage

.na_to_null(x)

Arguments

Value

NULL if x is a single NA value or empty string, otherwise x unchanged.

Author(s)

Jared Andrews

Normalize colors to hex strings

Description

Converts color names or shorthand hex values to full ⁠#RRGGBB⁠ strings and returns empty strings for missing values.

Usage

.normalize_hex(x)

Arguments

Value

A character vector of uppercase hex colors.

Author(s)

Jared Andrews

Package on-load hook

Description

Registers built-in model backends when the package is loaded.

Usage

.onLoad(libname, pkgname)

Arguments

Enumerate the comparisons a pairwise run will produce

Description

The comparison set depends only on the grouping columns and the user's pair selection, never on the data values, so it can be worked out without running a single test. .compute_pairwise() fills these rows in with p-values, and stat_bracket_y_max() uses them to work out how much room the brackets need.

Usage

.pairwise_layout(sub_df, x, pairs, group.by, facet_level = NA_character_)

Value

A data frame with group1, group2, x_level and facet_level, or NULL when there is nothing to compare.

Find columns referenced by a plotly figure's trace attributes

Description

Walks a plotly object's x$attrs (the per-trace arguments captured at trace-construction time, e.g. ~mpg formulas or literal vectors/lists such as parcoords dimensions) to determine which columns of the plot's source data.frame are actually rendered. This works generically across both ggplotly()-converted figures (which encode mappings as .data[["col"]] formulas) and figures built directly with plot_ly()/add_trace() (which may use ~col formulas, literal label = "col" entries, or, as a last resort, raw data vectors matched back to full_data by value).

Usage

.plotted_vars_from_attrs(plot, full_data)

Arguments

Value

A character vector of column names in full_data referenced by plot.

Author(s)

Jared Andrews

Find columns referenced by module UI inputs

Description

Complements .plotted_vars_from_attrs() for columns that never make it into the built plotly figure, most notably split.by/facet.by variables (faceting is resolved before the ggplot-to-plotly conversion, so the facet column name is lost from the figure entirely). All plot modules name their column-selecting inputs with a consistent convention (e.g. x.by, color.by, x.value, x.data, labels, theta, group, dimensions), so inputs matching that convention are checked against the plot's source columns.

Usage

.plotted_vars_from_inputs(ui_inputs, cols)

Arguments

Value

A character vector of column names in cols referenced by ui_inputs.

Author(s)

Jared Andrews

Re-apply captured manual edits onto a freshly built plotly figure

Description

Merges legend position and annotation position/text edits (captured by .capture_manual_edits()) into a rebuilt figure so manual layout tweaks persist across re-renders. Annotations are matched by stable key, so edits are preserved even if their order changed.

Usage

.reapply_manual_edits(fig, edits, regen_keys = character(0))

Arguments

Value

The figure with manual edits re-applied.

Author(s)

Jared Andrews

Called from .onLoad() to seed the registry with the four standard backends.

Description

Called from .onLoad() to seed the registry with the four standard backends.

Usage

.register_builtin_backends()

Value

Invisibly returns NULL.

Author(s)

Jacob Martin

Register input handler for the multi-color picker

Description

Creates the VizModules.multiColorPicker input handler that turns the JavaScript payload into a named vector of hex codes.

Usage

.register_multi_color_picker_handler()

Value

Invisibly returns the result of registerInputHandler().

Author(s)

Jared Andrews

Register input handler for the multi-dynamic input

Description

Turns the JavaScript payload (an array of rows, each with a fields array of ⁠{key, value}⁠) into the named-list-of-named-lists R structure.

Usage

.register_multi_dynamic_input_handler()

Value

Invisibly returns the result of registerInputHandler().

Author(s)

Jacob Martin

Require a data frame from a module's data reactive

Description

Wraps the data reactive every module server receives so that downstream readers always see a data frame. A NULL value (which a parent app can emit briefly while switching datasets) becomes a silent shiny::req() skip rather than an error cascade through every observer, and anything else is coerced with as.data.frame() before use.

Usage

.require_data_frame(data)

Arguments

Value

A reactive returning a data frame with at least one column.

Author(s)

Jared Andrews

Restore a group color picker to its default mapping

Description

Used by module Reset buttons. When defaults supplies a mapping for inputId the picker is set back to it; otherwise the widget resets itself to the stock palette it was built with.

Usage

.reset_group_colors(session, inputId, defaults, groups, default_palette = NULL)

Arguments

Value

Invisibly NULL; called for its side effect.

Author(s)

Jared Andrews

Reset uniform stats inputs to defaults

Description

Resets all inputs created by .uniform_stats_inputs_ui() to their default values. Call inside an observeEvent(input$reset, ...) block.

Usage

.reset_stats_inputs(session, defaults = NULL)

Arguments

Value

Called for side effects; returns invisible(NULL).

Author(s)

Jared Andrews

Safely build a model from a user-supplied formula string

Description

Validates and fits a model from a user-typed formula string without evaluating arbitrary code. Intended for interactive contexts (e.g. a Shiny text input) where the formula originates from untrusted user input. The function only ever converts the text into a formula object — it never calls eval(parse(...)) on raw input — and rejects anything that is not a recognised formula built from allow-listed terms.

Usage

.safe_build_model(formula_text, data, fit_fn_name, ...)

Arguments

Details

Validation proceeds in stages, returning NULL (with a warning()) at the first failure:

1. The fit function name is looked up in the model backend registry via get_model_backend().

2. The text is parsed with parse() and required to be a single expression.

3. The expression's abstract syntax tree is walked recursively; only data-column symbols, a small set of literal keywords, and an allow-list of math/transform calls are permitted. Calls such as system, eval, or source are structurally rejected.

4. The text is converted with stats::as.formula() and confirmed to be of class "formula".

5. The model is fitted via the backend's fit function inside tryCatch() scoped to data, and the returned object's class is verified against the backend's validate_classes.

Value

A fitted model object whose class matches the backend's validate_classes, or NULL if the input is empty, unparseable, contains disallowed terms, or fails to fit.

Author(s)

Jacob Martin

Compare two axis-range values for practical equality

Description

The limits make a round-trip through the browser as JSON, so the value that comes back can differ from the one sent in the last bits of a double. An exact comparison would treat that echo as a change and rebuild the plot.

Usage

.same_axis_range(a, b)

Author(s)

Jared Andrews

Seed group colors from a palette

Description

Recycles palette values to cover all requested groups and names the result.

Usage

.seed_colors(groups, palette)

Arguments

Value

A named character vector of colors aligned to groups.

Author(s)

Jared Andrews

Check if a plotly trace should be included in annotations

Description

Determines whether a trace in a plotly figure should be included when processing annotations. "show.others" background traces are excluded.

Usage

.should_include_trace(trace, show.others = TRUE, require.markers = FALSE)

Arguments

Details

Background traces (show.others) are identified by checking for:

• name field containing "show.others"

• legendgroup field containing "show.others"

• Single text element (this check is REMOVED as it's unreliable)

Value

Logical. TRUE if the trace should be included in annotation processing, FALSE if it should be skipped.

Author(s)

Jared Andrews

Bracket headroom for a module, read straight off its Stats tab

Description

Wraps stat_bracket_y_max() with the geometry inputs every module's Stats tab carries, so the three modules that draw significance brackets share one call rather than three copies of the same argument list. Missing inputs fall back to the tab's own defaults, which matters while the tab has yet to be rendered.

Usage

.stat_bracket_headroom(
  df,
  x,
  y,
  group.by = NULL,
  facet.by = NULL,
  per.facet = TRUE,
  input
)

Arguments

Value

A single number, or NULL when no brackets would be drawn.

Author(s)

Jared Andrews

Parse a string indicating a set of vectors to a list of vectors.

Description

Used to parse text inputs into a list of vectors.

Usage

.string_to_list_of_vectors(x)

Arguments

Value

A list like list(c("a", "b", "c"), c("d", "e")). If the input is "", just returns "". If the input is NULL, returns NULL.

Author(s)

Jared Andrews

Parse a string delimited by commas, whitespace, or new lines to a vector.

Description

Used to parse text inputs into a vector.

Usage

.string_to_vector(x)

Arguments

Value

A vector of strings like c("a", "b", "c", "d", "e"). If the input is "", just returns "". If the input is NULL, returns NULL.

Author(s)

Jared Andrews

Generate uniform Stats input UI

Description

Creates a standardized tagList of statistical testing inputs for use across plot modules that support pairwise comparisons (BoxPlot, ViolinPlot, yPlot).

Usage

.uniform_stats_inputs_ui(ns, defaults = NULL)

Arguments

Value

A tagList containing the stats input UI elements.

Author(s)

Jared Andrews

Generate uniform subplot spacing input UI

Description

Creates a standardized tagList of the horizontal/vertical subplot spacing inputs. These controls only have an effect when faceting is active, so they are rendered within each module's "Facet" tab.

Usage

.uniform_subplot_spacing_inputs_ui(ns, defaults = NULL)

Arguments

Value

A tagList containing the subplot spacing input UI elements.

Author(s)

Jared Andrews

HTML dependency for viz_select_input

Description

Ships the small script that keeps Bootstrap's modal focus trap from stealing focus away from a body-rendered virtual-select dropdown.

Usage

.viz_select_dependency()

Value

An htmltools::htmlDependency object.

Author(s)

Jared Andrews

Evaluate a plot expression under a fixed random seed

Description

Builds a plot with a reproducible random stream so randomised layers (jitter, most notably) land in the same place on every rebuild. Without this, any input change re-draws the jitter offsets, which makes points appear to jump around and leaves anything anchored to a point's position pointing at stale coordinates. The caller's random stream is restored afterwards.

Usage

.with_stable_seed(expr, seed = 42L)

Arguments

Value

The value of expr.

Author(s)

Jared Andrews

Create an example Modular ComplexHeatmap Shiny Application

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 data_list is not provided (or NULL), the app launches with example_heatmap_matrix (a simulated gene x sample expression matrix) as an example dataset. 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() — except when column_data is supplied (see below), which needs a small bespoke app instead, since createModuleApp() always hands the module server a single data frame and can't carry the two-table list(matrix = , column_annotations = ) shape the module's column-annotation feature needs (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 with default example data (row annotations only):
app <- ComplexHeatmap_HeatmapApp()
if (interactive()) shiny::runApp(app)

# Launch with column annotations too:
app2 <- ComplexHeatmap_HeatmapApp(column_data = example_heatmap_column_data)
if (interactive()) shiny::runApp(app2)

Click/brush info output UI component for the ComplexHeatmap module

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)
ComplexHeatmap_HeatmapInfoOutputUI("heatmap", title = "Details")

Input UI components for the ComplexHeatmap module

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.

• 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", or "Hierarchical" (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 not "None" (UI: "Row Groups", default: NA; clamped to the number of matrix rows)

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

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

• 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: "")

• 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 and a side, Left or Right; 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.

• 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 and a side, Top or Bottom, with the same per-row color controls as row annotations; only shown when data supplies a column_annotations table; default: none)

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)

Main heatmap output UI component for the ComplexHeatmap module

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,
  ...
)

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)
ComplexHeatmap_HeatmapMainOutputUI("heatmap", title = "Heatmap")

Output UI components for the ComplexHeatmap module

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, ...)

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.

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)
# 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)

Server logic for the ComplexHeatmap module

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()

Sub-heatmap output UI component for the ComplexHeatmap module

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,
  ...
)

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)
ComplexHeatmap_HeatmapSubOutputUI("heatmap", title = "Selected region")

Build diagonal (abline) line shapes for a plotly figure

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")

Build horizontal line shapes for a plotly figure

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"))

Create default Plotly configuration

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()).

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)

Add reference lines to a plotly figure from Shiny inputs

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"
)

Build vertical line shapes for a plotly figure

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"))

Adjust numeric column values in a data frame using mathematical transformations

Description

Applies a named mathematical transformation to a specified numeric column in a data frame, adding the transformed values as a new column (original column name + ".adj"). The transformation 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 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
)

Arguments

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)

Build an adjustment-aware axis label

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 adjustments are applied in dittoViz (the recognized adjustment is applied first, then the adj.fxn), producing labels such as "log2(z-score(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")

Apply axis title font styling to shared facet axis annotations

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)

Apply custom subplot spacing to a faceted ggplotly figure

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)

Apply uniform legend font styling to a plotly figure

Description

Sets the legend title and entry-label font sizes on a plotly figure so the "Legend" UI inputs behave consistently across plot types. Existing legend settings (orientation, position, font family/colour) are preserved because plotly::layout() merges the supplied attributes into the current layout. NULL or NA sizes are ignored, leaving the corresponding font size untouched.

Usage

apply_legend_styling(fig, title.size = NULL, text.size = NULL, position = 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 does 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 sizes. This keeps the "Legend" controls functional for both categorical and continuous legends.

Value

The plotly figure with the requested legend font sizes applied. Returns the figure unchanged when fig is NULL or no valid sizes are 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)

Apply Plotly newshape styling from uniform Plotly inputs

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)

Apply standard render-time margin layout to a plotly figure

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)

Apply statistical annotation shapes and annotations to a plotly figure

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.

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)

Apply axis styling to all subplot axes in a plotly figure

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

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)

Apply plot title styling to a plotly figure

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)

Convert native cartesian axis titles to draggable annotations

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)

Build facet subplot annotations

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
)

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")

Build paper-anchored panel border shapes for a faceted plotly figure

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)

Build a dynamic row_spec from registered backends

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()

Clean and validate facet dimension value for lineplot module

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)

Collect plot and source data for download

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")
    })

    data_list <- collect_source_data(plot_reactive)
    output$my_plot <- renderPlotly(plot_reactive())
    output$download_data <- create_source_download_handler(reactive(data_list))
}

shinyApp(ui, server)

## End(Not run)

Compute pairwise statistical tests between groups

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)
)

Create an Example Module App from Any Module Trio

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"
)

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)

Create Plotly axis style list

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)

Create ggplot axis styling theme arguments

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)

Create download handler for plot with source data

Description

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

Usage

create_source_download_handler(data_list, filename_base = "source_data")

Arguments

Value

A downloadHandler object suitable for assignment to a Shiny output.

Author(s)

Jacob Martin

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")
    })

    data_list <- collect_source_data(plot_reactive)
    output$my_plot <- renderPlotly(plot_reactive())
    output$download_data <- create_source_download_handler(reactive(data_list))
}

shinyApp(ui, server)

## End(Not run)

Create plotly shapes and annotations for statistical test results

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
)

Arguments

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.

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)

Server logic for the dataFilter module

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)

UI component for the dataFilter module

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")

Color palette options for palettePicker

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)

Create an example Modular freqPlot Shiny Application

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 with example_composition as an example dataset, which has twelve donors nested inside two conditions - the shape dittoViz::freqPlot() needs to compare per-sample frequencies across groups.

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)

# Launch on the cell-type composition of each donor, split by disease state:
app2 <- dittoViz_freqPlotApp(
    defaults = list(
        var = "cell_type", sample.by = "sample", group.by = "condition"
    )
)
if (interactive()) runApp(app2)

Input UI components for the freqPlot module

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.

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)

• legend.show - Show legend (always TRUE; not directly settable)

• 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)

Parameters controlling additional functionality

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

• boxmode - Boxplot mode grouping (calculated: "group" or "overlay" based on color.by)

• 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)

• 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: "")

• 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

Author(s)

Jared Andrews

See Also

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

Examples

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

Output UI components for the freqPlot module

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()

Server logic for freqPlot module

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()

Create an example Modular scatterPlot Shiny Application

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 with gallery_sales as an example dataset. 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)

Input UI components for the scatterPlot module

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. "log2(z-score(units))"; plotly allows interactive editing)

• ylab - Y-axis label (auto-generated to reflect any applied Y adjustment, e.g. "log2(z-score(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 - Points to highlight (UI: "Points to Highlight", default: "")

• 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.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")

• 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)

Author(s)

Jared Andrews

See Also

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

Examples

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

Output UI components for the scatterPlot module

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

Server logic for scatterPlot module

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()

Create an example Modular yPlot Shiny Application

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 with gallery_demographics as an example dataset. 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)

Input UI components for the yPlot module

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.

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. "log2(z-score(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 (UI: "Y Axis Min", auto-calculated)

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

• 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")

• 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 legend (always TRUE; not directly settable)

Parameters controlling additional functionality

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

• boxmode - Boxplot mode grouping (calculated: "group" or "overlay" based on color.by)

• 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)

• 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: "")

• 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)

Output UI components for the yPlot module

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

Server logic for yPlot module

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()

Create an Interactive Dumbbell Plot with plotly

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",
  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,
  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)

Value

A plotly object representing the interactive dumbbell plot.

Author(s)

Jacob Martin

Examples

data <- data.frame(
    School = c("MIT", "Stanford", "Harvard"),
    Women = c(152, 96, 112),
    Men = c(95, 151, 165)
)

fig <- dumbbellPlot(
    data = data,
    x = c("Women", "Men"),
    y = "School",
    colour.by = "X variables",
    palette.selection = c("green", "blue"),
    show.legend = TRUE,
    line.colour = "gray80"
)

Create a Shiny App for Dumbbell Plots

Description

This function generates a Shiny application for interactive dumbbell plots. 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 dumbbell plot.

Usage

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

Arguments

Details

When data_list is not provided (or NULL), the app launches with example_school_earnings as an example dataset. 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)

Jacob Martin, Jared Andrews

See Also

dumbbellPlot(), dumbbellPlotInputsUI(), dumbbellPlotOutputUI(), dumbbellPlotServer()

Examples

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

# Launch with custom data:
data <- data.frame(
    School = c("MIT", "Stanford", "Harvard"),
    Women = c(94, 96, 112),
    Men = c(152, 151, 165),
    Group = c("A", "B", "A")
)
app2 <- dumbbellPlotApp(list("School Earnings" = data))
if (interactive()) runApp(app2)

Input UI components for the dumbbellPlot module

Description

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

Usage

dumbbellPlotInputsUI(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.

Value

A Shiny tagList containing the UI elements

Plot parameters not implemented or with altered functionality

The following dumbbellPlot() parameters are not exposed as UI inputs:

• order.by - Order rows by a Y value; not currently wired to a UI input (use defaults to set)

Plot parameters and defaults

The following dumbbellPlot() parameters can be accessed via UI inputs:

• x - X values (UI: "X Values (max 2)", defaults key: x.value, multiple: TRUE, max 2 enforced)

• y - Y value (UI: "Y Value", defaults key: y.value, single selection)

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

• colour.by - Color by X or Y (UI: "Colour By", default: "X variables")

• facet.by - Faceting variable (UI: "Facet By", default: "")

• facet.scales - Facet scale behavior (UI: "Facet Scales", default: "fixed")

• line.colour - Color of connecting lines (UI: "Colour of Connectors", default: "gray30")

• palette.selection - Color palette (UI: palette picker)

Parameters controlling additional functionality

The following parameters controlling plotly-specific features and styling are also available:

• flip.x - Flip X-axis (UI: "Flip X Axis", default: FALSE)

• flip.y - Flip Y-axis (UI: "Flip Y Axis", default: FALSE)

• 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")

• 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")

• margin.t - Top margin in pixels (UI: "Margin Top", default: 70)

• margin.b - Bottom margin in pixels (UI: "Margin Bottom", default: 70)

• margin.l - Left margin in pixels (UI: "Margin Left", default: 70)

• margin.r - Right margin in pixels (UI: "Margin Right", default: 70)

• subplot.margin.x - Horizontal spacing between facet panel columns (UI: "Subplot Spacing (Horizontal)")

• subplot.margin.y - Vertical spacing between facet panel rows (UI: "Subplot Spacing (Vertical)")

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

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

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

• shape.linetype - Line dash style for drawn shapes (UI: "Shape Linetype", default: "solid")

• shape.opacity - Opacity for drawn shapes (UI: "Shape Opacity", 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.

Author(s)

Jacob Martin

See Also

dumbbellPlot(), organize_inputs(), dumbbellPlotOutputUI(), dumbbellPlotServer(), dumbbellPlotApp()

Examples

library(VizModules)
data <- data.frame(
    School = c("MIT", "Stanford", "Harvard"),
    Women = c(94, 96, 112),
    Men = c(152, 151, 165)
)
dumbbellPlotInputsUI("dumbbellPlot", data)

Output UI components for the dumbbellPlot module

Description

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

Usage

dumbbellPlotOutputUI(id, resizable = TRUE)

Arguments

Value

A Shiny plotlyOutput for the dumbbellPlot

Author(s)

Jacob Martin, Jared Andrews

Server logic for dumbbellPlot module

Description

Server logic for dumbbellPlot module

Usage

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

Arguments

Value

The moduleServer function for the dumbbellPlot module.

Author(s)

Jacob Martin

See Also

dumbbellPlot(), dumbbellPlotInputsUI(), dumbbellPlotOutputUI(), dumbbellPlotApp()

Create an empty ggplot2 plot or plotly plot with input text

Description

This function creates an empty ggplot2 or plotly plot and places a user-provided text string in the middle of the plot.

Usage

empty_plot(text = NULL, plotly = FALSE)

Arguments

Value

Either a ggplot object or a plotly object if plotly = TRUE.

Author(s)

Jared Andrews

See Also

ggplot2::geom_text(), ggplot2::theme_void()

Examples

library(VizModules)
empty_plot("No data to display")

Bar dataset for bar and split bar plot examples

Description

A small dataset with five groups, two categorical variables, and three numeric variables. Used as the default data for plotthis_BarPlotApp() and plotthis_SplitBarPlotApp().

Usage

example_bar

Format

A data frame with 5 rows and 5 columns:

Group

Group label (A through E)

Type

Category type (Alpha, Beta, or Gamma)

Values

Primary numeric values (positive)

Numbers

Secondary numeric values (can be negative)

Score

Tertiary numeric values (can be negative)

Author(s)

Jacob Martin

Source

Generated in data-raw/generate_example_data.R.

Example single-cell-style composition data for the freqPlot module

Description

A per-cell record table from a simulated 12-donor immune profiling experiment, shaped for dittoViz::freqPlot(). Each donor (sample) contributes 150 cells and maps to exactly one condition and one batch, which is the nesting freqPlot() requires to compare per-sample cell-type frequencies across groups. batch is crossed with condition (three donors each), so it works as a color.by without confounding the comparison.

Usage

example_composition

Format

A data frame with 1800 rows and 7 columns:

cell_id

Unique cell identifier (character)

sample

Donor identifier, P01-P12 (factor); 150 cells each

condition

Disease state, Healthy or Disease (factor); six donors each

batch

Processing batch, B1 or B2 (factor); crossed with condition

cell_type

Annotated cell type (factor), the variable whose per-sample frequency freqPlot() tabulates

n_genes

Number of genes detected in the cell (integer)

percent_mito

Percentage of mitochondrial reads (numeric)

Details

Composition differs between the two conditions: the Disease donors show an expanded monocyte compartment and depleted CD4 T cells relative to Healthy.

Author(s)

Jared Andrews

Source

Simulated. Per-donor compositions are Dirichlet draws around condition-specific means, with cell counts drawn multinomially. See data-raw/generate_example_data.R.