Package {VizModules}

Title:	Flexible, Interactive 'shiny' Modules for Almost Any Plot
Version:	0.5.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, svglite, 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-09-29 20:54:29 UTC; jandrews
Author:	Jared Andrews [aut, cre], Jacob Martin [aut]
Maintainer:	Jared Andrews <jared.andrews07@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-29 22:20: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

Dodge width plotthis builds its box plots with

Description

plotthis::BoxPlot() hardcodes position_dodge(width = 0.9) for its box layer and position_jitterdodge(dodge.width = 0.9) for its point layer. A module wrapping it must hand the same number to .align_box_positions() so the boxes land back on the coordinates ggplot2 gave the rest of the layers.

Usage

.PLOTTHIS_DODGE_WIDTH

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

Transform values the way the modules plot them

Description

The adjustment function (adj.fxn, e.g. log10) is applied first, then the adjustment rescales the result ("z-score" or "relative.to.max"). That is the order a transform and a standardisation are normally combined in: log first, then z-score. dittoViz applies them the other way round when given both, which turns every below-average value into log() of a negative number, so the modules hand dittoViz this whole transform as its function instead (see .adjustment_fn()).

Usage

.adjusted_values(values, adjustment = NULL, adj.fxn = NULL)

Arguments

Details

The rescaling is computed over the finite values only, so a value the function makes non-finite (log(0)) is dropped from the plot rather than turning the whole column into NaN.

Anything drawn over an adjusted plot (significance brackets, fit lines, axis limits) has to be computed from these values, not the raw column, or it lands in a different coordinate space from the data.

Value

The transformed values, unnamed.

Author(s)

Jared Andrews

The whole plotted transform as one function, for dittoViz

Description

dittoViz applies its ⁠*.adjustment⁠ before its ⁠*.adj.fxn⁠. Passing it this function as ⁠*.adj.fxn⁠, with no ⁠*.adjustment⁠, has it plot .adjusted_values() instead, while it still builds its adjusted columns, hover text and multi-variable reshape as usual.

Usage

.adjustment_fn(adjustment = NULL, adj.fxn = NULL)

Arguments

Value

A function of one vector, or NULL when neither is set.

Author(s)

Jared Andrews

Tooltip note on the order the adjustment inputs are applied in

Description

Tooltip note on the order the adjustment inputs are applied in

Usage

.adjustment_order_note(adjustment.label)

Arguments

Value

A character scalar.

Author(s)

Jared Andrews

Put box traces back on the positions ggplot2 dodged them to

Description

Rewrites the x of every box trace in a ggplotly() figure so the boxes sit where ggplot2 placed them, then switches boxmode to "overlay" so plotly.js leaves them alone.

Usage

.align_box_positions(fig, dodge.width = 1, box.width = 0.8)

Arguments

Details

plotly's boxplot conversion rebuilds box traces from the layer's prestats data, so they arrive carrying the raw x category index and none of ggplot2's dodge. Point, violin and errorbar traces keep the positions ggplot2 computed. boxmode = "group" then dodges the boxes by plotly.js' own rule – one slot per box trace in the subplot – while ggplot2 gave every other layer one slot per group present at that x position. Where a group is missing from some x categories the two disagree and the boxes no longer line up over their points.

Which x positions each box trace occupies is exactly the presence information needed to redo the dodge, so no data frame is required. Traces are ranked in the order ggplotly() emitted them, which follows factor level order, matching how ggplot2 assigns slots. Each facet panel is dodged independently, as ggplot2 does per panel, and a panel is identified by its pair of axes: ggplotly() gives every panel its own x axis only when the x scale is free, and otherwise shares one x axis down a whole facet column, so the x axis alone would merge the panels stacked in that column.

plotly only accepts one width per trace, so boxes are drawn a constant width everywhere (taken from the most crowded x position) rather than widening where a group is absent. This keeps the widths plotly.js was already drawing and matches the jitter cloud, whose width is also constant.

Value

The figure with explicit x and width on every box trace and boxmode = "overlay" in the layout.

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

Split an app dataset entry into its primary table and a rebuild function

Description

createModuleApp() filters one table and shows it in the Data Table, but a module may need more than one: ComplexHeatmap_Heatmap takes list(matrix = , column_annotations = ), where the matrix is what gets filtered and the per-sample metadata rides along untouched. Rather than give such modules a bespoke app, an entry of data_list may be either a plain data frame or a named list of them.

Usage

.app_entry_parts(entry, primary = NULL)

Arguments

Value

A list with primary (the data frame to filter and display) and rebuild, a function taking a replacement primary and returning the entry in its original shape. NULL if the entry holds no data frame at all.

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

Replace data columns with the values the modules plot for them

Description

Applies .adjusted_values() to each of cols in place, keeping the column names. Each column is transformed on its own over the whole frame, as dittoViz does before any row subsetting or multi-variable reshape, so the result can be passed wherever the raw frame was (statistics, model formulas that name the raw columns, axis-range calculations).

Usage

.as_plotted(df, cols, adjustment = NULL, adj.fxn = NULL)

Arguments

Value

df with cols transformed; unchanged when neither argument is set.

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

Build a plotly axis title spec carrying its font

Description

Plot functions that set an axis title as a bare string leave it without a font, so axis_titles_as_annotations() has nothing to carry over to the draggable annotation. This returns the list(text, font) form instead, omitting text when it is NULL so no empty title is serialised.

Usage

.axis_title_spec(text, font)

Arguments

Value

A named list suitable for a plotly axis title.

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

Does a box plot give each facet panel its own y scale?

Description

plotthis applies y_min/y_max only when the y scale is shared; under a free one each panel spans its own data, so its brackets must be measured per panel.

Usage

.box_free_y(facet.by, facet.scale)

Arguments

Value

TRUE when the plot is faceted and facet.scale is "free" or "free_y".

Author(s)

Jared Andrews

A box-geometry control's value, or its default when the control is blank

Description

A blank numericInput() reports NA, which would otherwise propagate into the dodge arithmetic and put every box at NA.

Usage

.box_num(value, default)

Arguments

Value

A single number.

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 finite column values using min() and max().

The maximum is padded by axis_scale_factor - 1 of its magnitude, which is max * axis_scale_factor for a positive maximum and still raises a negative one (e.g. log-transformed values below 1).

• 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,
  point.size = 12
)

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,
  font.family = NULL,
  font.color = NULL
)

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

Read the images the browser captured off the live plots

Description

Turns the payload sent by sourceExport.js into a list keyed by the name each image belongs to, ready for .write_source_zip() to match against its summaries. Anything malformed is dropped rather than failing the download: the archive is still worth having without a picture in it.

Usage

.decode_source_images(images, max_bytes = 8e+06)

Arguments

Value

A named list, one entry per key, of list(svg = , png = , width = , height = ). svg is a character scalar or NULL; png is a raw vector or NULL.

Author(s)

Jared Andrews

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

Pick the comparisons a defaults list asks for from those on offer

Description

The Comparisons selector is repopulated from the data whenever its grouping columns change, so a stat.pairs default cannot simply be written into the UI. The modules instead select, from each fresh set of choices, the ones defaults$stat.pairs names. A pair matches in either orientation, so "Mid vs Entry" selects the "Entry vs Mid" choice.

Usage

.default_stat_pairs(defaults, pair_strings)

Arguments

Value

The elements of pair_strings that defaults$stat.pairs names. When it names none, "", which is what the selector needs to show an empty selection (and means every pair is tested).

Author(s)

Jared Andrews

Half-width of a group's error bar

Description

What linePlot() draws either side of a group's mean. Missing values are dropped before n is counted, so the bar describes the values that went into the mean.

Usage

.error_bar_halfwidth(
  x,
  type = c("sd", "sem", "ci95"),
  ci.method = c("normal", "t")
)

Arguments

Value

A single number, or NA_real_ for fewer than two non-missing values, which have no spread to draw.

Author(s)

Jared Andrews

Bundled datasets offered by the gallery, the Figure Builder, and ⁠*App()⁠s

Description

The bundled example datasets, plus sales_by_region (an example_sales summary suited to the pie plot) and example_heatmap, a two-table entry pairing example_heatmap_matrix with its per-sample metadata so the ComplexHeatmap module's column annotations, splits and filters work.

Usage

.example_datasets()

Value

A named list of data frames, and of lists of data frames for multi-table entries.

Author(s)

Jared Andrews

The call names a user-typed expression is allowed to contain

Description

Shared by safe_eval_filter() and validate_expression(), which previously each carried their own verbatim copy of this list and of the AST walker in .expr_check_node(). Two copies of a security allowlist is one copy too many — widening one and forgetting the other is exactly how a sandbox develops a hole.

Usage

.expr_allowed_calls()

Details

Every entry is a pure function: no I/O, no environment or namespace access, no evaluation, no assignment. That is the property that makes the allowlist safe, and it is the bar any addition must clear. Notably absent and deliberately so: system, file, eval, parse, get, assign, ::, $, [, [[, @, function, and ⁠<-⁠.

Value

A character vector of permitted call names.

Author(s)

Jared Andrews

Walk a parsed expression and reject anything outside the allowlist

Description

The shared guard behind safe_eval_filter() and validate_expression(). Recurses the AST and permits only literals, symbols naming a column of the data (or a bare logical/NA/Inf constant), and calls whose name is in .expr_allowed_calls(). Anything else — an unknown symbol, a call to a function not on the list, a construct that is neither — returns FALSE.

Usage

.expr_check_node(node, col_names, allowed = .expr_allowed_calls())

Arguments

Details

Note that a function name reaches this as node[[1L]] of a call and is checked against the allowlist, never as a symbol, so allowing a call name does not also make it usable as a bare value.

Value

TRUE if every node is permitted, FALSE otherwise.

Author(s)

Jared Andrews

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

Resolve the paper-domain rectangle of each facet panel

Description

With shared axes plotly keeps only one axis per column (x) and one per row (y), so a per-facet ⁠xaxis{i}⁠/⁠yaxis{i}⁠ lookup comes up empty for every panel after the first 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 panels fill that grid row-major, as subplot() lays them out. This holds for shared and free axes alike.

Usage

.facet_panel_domains(fig, n_facets, ncol = NULL)

Arguments

Value

A list with one element per facet: ⁠list(x = <domain>, y = <domain>)⁠, or NULL for a panel outside the detected grid. NULL when the figure has no usable domains.

Author(s)

Jacob Martin, Jared Andrews

Collect vector art for Figure Builder panels the browser cannot export

Description

The canvas export reads an SVG straight out of a plotly graph client-side. A panel rendering anything else leaves it nothing to read, so the browser asks the server for those panels instead and this builds the answer.

Usage

.figure_builder_panel_svgs(panels, sources)

Arguments

Details

A module opts in by attaching a vector_svg attribute to the reactive its server returns – a ⁠function(width, height, res)⁠ yielding an ⁠<svg>⁠ element drawn at that pixel size. A panel whose module attaches nothing, or which has since been removed, is left out of the reply and simply contributes no artwork to the figure, exactly as it did before.

Value

An unnamed list of list(pid = , svg = ), holding only the panels that produced artwork.

Author(s)

Jared Andrews

Collect every panel's source summary for the Figure Builder's archive

Description

Gathers what each panel's module reports about itself and names each entry after the panel's label, so the archive reads the way the canvas looks.

Usage

.figure_builder_sources(ids, sources, labels)

Arguments

Details

Two things are added on the way through. Each summary is tagged with its panel id, because the browser photographs cards by id while the archive names them by the generated label, and create_source_download_handler() needs the two to meet. And a module that declares its renderers the older way – as attributes on the reactive, the vector_svg contract in figureBuilderServer() – has them copied onto the summary, so panels the browser cannot photograph still draw themselves.

Value

A named list of summaries, one per panel that produced one.

Author(s)

Jared Andrews

Which points of a trace have a drawable position?

Description

Which points of a trace have a drawable position?

Usage

.finite_coords(x, y)

Arguments

Value

A logical vector, one element per point.

Author(s)

Jared Andrews

Pair each facet panel of a figure with the rows of data drawn in it

Description

Fit lines are computed per panel from the rows that panel shows, then drawn on its axes. Neither the order rows appear in nor the axis numbers can pair a facet level with its panel: ggplot orders facets by factor level (or alphabetically for any other column), and ggplotly numbers axes per panel column and row rather than per panel. The strip labels can, since each sits over (or beside) the panel it names; this is the match the significance brackets use too (.build_facet_axis_map()). When the strips cannot all be matched, panels are taken in ggplot's row-major order instead.

Usage

.fit_panels(fig, df, split.by = NULL)

Arguments

Value

A list of panels, each list(pair = list(x = , y = ), df = ). An unfaceted figure gives one panel per axis pair, holding all of df. Panels with no rows are dropped.

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

The call names a user-typed model formula is allowed to contain

Description

The formula counterpart to .expr_allowed_calls(), for the custom fit-line models in .safe_build_model(). A formula needs a different vocabulary – ~ and the model-building operators, plus the handful of transforms that routinely appear on the right-hand side – but it needs the same walker, so the two lists differ and .expr_check_node() does not.

Usage

.formula_allowed_calls()

Details

The same purity bar applies: every entry is a mathematical transform or a formula operator, with no I/O, environment access, evaluation or assignment.

Value

A character vector of permitted call names.

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

The gallery's About tab

Description

The gallery's About tab

Usage

.gallery_about_tab(info)

Arguments

Value

A shiny::tabPanel().

Author(s)

Jared Andrews

The gallery's navbar header: styling, and the repo/docs/version links

Description

The gallery's navbar header: styling, and the repo/docs/version links

Usage

.gallery_header(info)

Arguments

Value

A shiny::tagList().

Author(s)

Jared Andrews

One module's gallery tab: its controls beside the plot and data table

Description

One module's gallery tab: its controls beside the plot and data table

Usage

.gallery_module_tab(id, mod)

Arguments

Value

A shiny::tabPanel().

Author(s)

Jared Andrews

Package details shown on the gallery's About tab and navbar

Description

Package details shown on the gallery's About tab and navbar

Usage

.gallery_package_info()

Value

A list with title, description, authors, version, repo_url, docs_url and cran_url.

Author(s)

Jared Andrews

Axis references for the rows and columns of a facet_grid() figure

Description

ggplotly gives a grid one x-axis per column and one y-axis per row. Column strips sit above their column and row strips (rotated) beside their row, so each strip names the axis nearest to it. Levels whose strip cannot be found fall back to position: columns left to right, rows top to bottom.

Usage

.grid_strip_axes(fig, rows, cols)

Arguments

Value

list(x = , y = ): named lists mapping each column level to an x-axis reference and each row level to a y-axis reference.

Author(s)

Jared Andrews

Sort rows the way plotly sorts them before splitting a discrete colour into traces

Description

Before it splits a discrete color into one trace per group, plotly dplyr::arrange()s its own copy of the data by that column (level order for a factor, sorted order for characters). Mapped variables such as x and y travel with that sort, but an array handed to a trace attribute by value, such as error_y$array, does not, and the trace that takes rows 1-4 of the sorted data would take entries 1-4 of the unsorted array: every group but one gets other groups' error bars. Sorting the data here first leaves plotly's sort with nothing to move, so the two stay in step. The sort is stable, so each trace is drawn exactly as before.

Usage

.group_rows_by_trace(df, col)

Arguments

Value

df, sorted by col.

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

Has a Shiny input reported an actual value?

Description

A Shiny input that has not reported yet is NULL, and every obvious test against one is logical(0) rather than FALSE – nzchar(NULL), NULL == "", is.na(NULL) alike. ⁠if (logical(0))⁠ is an ⁠argument is of length zero⁠ error, so each of those reads crashes the reactive it sits in. Module servers read column and size inputs constantly, and viz_select_input() is a custom binding that reports late, so the empty value is reachable far more often than it looks.

Usage

.has_value(x)

Arguments

Value

TRUE for a length-1, non-NA value; FALSE for anything else, NULL and character(0) included.

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

Extract one annotation column, aligned to a matrix axis

Description

Row and column annotations reach their values by different routes, and the difference is easy to get subtly wrong: row-annotation values sit in the matrix data frame itself and line up positionally with the matrix rows, while column-annotation values live in a separate per-sample table and are matched by value through a key column. Both .heatmap_build_annotation() and the "Annotation" split method need the same vector, so they share this rather than each re-deriving it.

Usage

.heatmap_annotation_values(source_df, col, key_values, key_col = NULL)

Arguments

Value

A vector of length(key_values) aligned to the matrix axis, or NULL when the column is unusable or does not line up.

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

Resolve a user filter expression into a keep-mask

Description

Thin wrapper over safe_eval_filter() that turns its result into something a caller can act on without guessing. safe_eval_filter() returns NULL both for "you typed nothing" and for "you typed something disallowed", which must not collapse into the same outcome: the first should keep every row, the second should surface an error rather than silently plotting unfiltered data.

Usage

.heatmap_apply_filter(expr_text, df, n_expected)

Arguments

Details

NA in the result counts as FALSE — a row whose filter value is unknown is not a row the user asked to see.

Value

A list with keep (a logical vector of length n_expected, or NULL when the expression was invalid) and status, one of "empty", "ok", or "invalid".

Author(s)

Jared Andrews

Whether the ComplexHeatmap module's Bioconductor dependencies are installed

Description

Whether the ComplexHeatmap module's Bioconductor dependencies are installed

Usage

.heatmap_available()

Value

A single logical.

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

Build the frame a column filter expression is evaluated against

Description

Matrix columns are sample names, not rows of a data frame, so a column filter has nothing to evaluate against on its own. This assembles one: a row per selected matrix column, in matrix order, carrying a synthetic column field with the matrix column name plus every field of the per-sample metadata table joined through key_col.

Usage

.heatmap_column_meta(column_data, key_col, matrix_cols)

Arguments

Details

That means column %in% c("Healthy_1", "Healthy_2") works with no metadata at all, while condition == "Disease" & batch == "B1" works as soon as a column_annotations table is supplied. If the metadata already has a field literally named column, the real one wins and no synthetic is added — shadowing a user's own column would be the more surprising behaviour.

Value

A data frame with one row per entry of matrix_cols, in the same order. Never NULL; a zero-column matrix_cols gives a zero-row frame.

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

Make a heatmap output panel fit its container's width

Description

Appends the call that rescales the widget once the page is ready, plus the dependency backing it.

Usage

.heatmap_fit_width(ui, id, scope, panels, output = FALSE, enable = TRUE)

Arguments

Value

ui, with the fitting script and dependency attached.

Author(s)

Jared Andrews

HTML dependency for the heatmap width fitting script

Description

Ships the script that rescales an InteractiveComplexHeatmap widget's panels to their container on load.

Usage

.heatmap_fit_width_dependency()

Value

An htmltools::htmlDependency object.

Author(s)

Jared Andrews

Keep a floating info panel from widening the page it sits on

Description

With output_ui_float = TRUE (which compact = TRUE implies), InteractiveComplexHeatmap detaches the click/brush info panel onto ⁠<body>⁠ and parks it at ⁠right: -10000px⁠ whenever it is idle. That box extends the document's scrollable width by ~10,000px, on every page of the app rather than only the one holding the heatmap. Appends the call that re-parks it to the left instead, where it contributes no overflow.

Usage

.heatmap_float_output(ui, id, enable = TRUE)

Arguments

Value

ui, with the re-parking script and dependency attached.

Author(s)

Jared Andrews

HTML dependency for the floating info panel script

Description

Ships the script that re-parks InteractiveComplexHeatmap's floating click/brush info panel so it stops widening the host page.

Usage

.heatmap_float_output_dependency()

Value

An htmltools::htmlDependency object.

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, split_values = NULL)

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.

A third method, "Annotation", splits on the values of one or more annotation columns instead of on a derived grouping, letting rows or columns be grouped by what they are (pathway, condition) rather than by how they cluster. It also makes drawing cheap when no clustering is wanted: the grouping needs no distance matrix. Several columns give nested slices, one per observed combination. It routes through row_split like the hierarchical method, so the never-both invariant above still holds.

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

Resolve a row/column title box + slice-title toggle into a Heatmap() title

Description

ComplexHeatmap::Heatmap() treats "", NA and character(0) alike: no title of its own, so a split axis is titled slice by slice with the group names (annotation values, or cluster numbers for k-means/hierarchical splits). Only NULL drops the titles, and the band they occupy with them. A blank title box therefore cannot switch the slice titles off by itself, which is what the "Show Row/Column Slice Titles" checkboxes are for.

Usage

.heatmap_resolve_title(text, show_slice_titles = TRUE)

Arguments

Details

Typed text always wins: Heatmap() cannot draw a spanning title and slice titles at once, so the text replaces the group names (a single string spans every slice; a ⁠%s⁠ in it is filled in with each group's name).

Value

text when it is non-blank; otherwise character(0) (group names shown, which is also no title at all when the axis is not split) or NULL (no title). Suitable for Heatmap(row_title = , column_title = ).

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

Element ID used by an InteractiveComplexHeatmap widget

Description

Mirrors InteractiveComplexHeatmap's internal validate_heatmap_id(), which is what actually decides the DOM ids the widget's markup and scripts use. A module namespace such as "heatmap-Heatmap" becomes "heatmap_Heatmap", so selectors must be built from this rather than from the id handed to the output functions.

Usage

.heatmap_widget_id(id)

Arguments

Value

A character scalar; the id as it appears in the rendered HTML.

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, row_spec = NULL)

Arguments

Value

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

Shape an elements list into the payload expected by the client

A list of lists, each with a fields element.

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

A module's example dataset and showcase defaults, for its ⁠*App()⁠

Description

A module's example dataset and showcase defaults, for its ⁠*App()⁠

Usage

.module_example(id)

Arguments

Value

A list with data_list (a one-entry named list holding the module's example dataset) and defaults.

Author(s)

Jared Andrews

The showcase registry: each module, its example dataset, and its defaults

Description

The showcase registry: each module, its example dataset, and its defaults

Usage

.module_showcase()

Details

Each entry is a list with:

• label - The module's name in the Figure Builder's picker.

• tab_label - The shorter name on its module gallery tab.

• dataset - The .example_datasets() entry its defaults are written for.

• inputs_ui, output_ui, server_fn - The module's three functions.

• defaults - The input defaults it opens on.

• primary.table, static_output_ui - Heatmap only: the table of its two-table dataset that gets filtered, and the plain output the Figure Builder uses in place of the interactive widget.

The heatmap entry is present only when its Bioconductor dependencies are installed, since its server stops outright without them.

Value

A named list of module entries, keyed by module id.

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 column values are carried over as given. dittoViz adjusts each variable before stacking, so pass a frame already run through .as_plotted() to get the values it plots.

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

Tell the user why significance brackets are missing from the plot

Description

Brackets are stacked above the data on the y-axis, so they cannot be drawn when the plotted values run along the x-axis (a rotated box plot, or a dittoViz plot containing a ridge plot). The tests are still run and shipped in the source-data download; this says so. The notification has a fixed id, so rebuilding the plot replaces it rather than stacking copies.

Usage

.note_brackets_skipped(session = shiny::getDefaultReactiveDomain())

Arguments

Value

Called for its side effect; NULL, invisibly.

Author(s)

Jared Andrews

Is an input's value a usable, non-empty string?

Description

.has_value() narrowed to the column-selecting inputs, whose "nothing chosen" state is the empty string rather than NULL.

Usage

.nz_value(x)

Arguments

Value

TRUE for a length-1, non-NA, non-empty character scalar; FALSE for anything else, NULL included.

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.

Axis pairs a figure's traces are drawn on, in row-major panel order

Description

Axis pairs a figure's traces are drawn on, in row-major panel order

Usage

.panel_axis_pairs(fig)

Value

A list of list(x = , y = ) axis references, top row first and left to right within a row, read off the axes' domains. list(list(x = "x", y = "y")) for a figure with no traces.

Author(s)

Jared Andrews

Parse a highlight string into the values it names

Description

Highlight values are typed as a comma- or newline-separated list, but they have also always been splittable on spaces, which left a value containing a space ("CD4 T", "Player A") impossible to name. Each comma- or newline-delimited entry is therefore kept whole when it is one of available, and split on whitespace as before otherwise.

Usage

.parse_highlight_values(x, available = NULL)

Arguments

Value

A character vector of unique, non-blank values, possibly empty.

Author(s)

Jared Andrews

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 three standard backends.

Description

Called from .onLoad() to seed the registry with the three 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

Discard every captured manual layout edit

Description

Used by module Reset buttons, so a dragged legend, annotation, axis title or colorbar goes back to where the rebuilt figure puts it. The store's fields are reactive values, so they are cleared in place; reassigning the list returned by setup_manual_edits() would only change a local copy.

Usage

.reset_manual_edits(store)

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, pair_strings = 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

Let axis limits given in defaults survive a module's startup

Description

Modules recompute an axis's limits from the data whenever the columns it shows change, and those observers also run as the controls first report in, which used to replace any limits given in defaults before the plot was ever drawn. Pass each recomputed range through the function this returns: while the columns are still the ones the module started on, the defaults limits win (either may be given alone); once they change, the data's range is used from then on, since the seeded limits described other columns.

Usage

.seed_axis_limits(defaults, min_key, max_key)

Arguments

Value

A function of ⁠(range, key)⁠, where range is a list(min = , max = ) computed from the data (or NULL) and key identifies the columns it was computed for (e.g. list(input$x.data, input$y.data)). It returns the range to use.

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"

Value

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

Author(s)

Jared Andrews

The call names a user-typed sort key is allowed to contain

Description

A sort key (the BoxPlot module's "Sort X By", handed to plotthis::BoxPlot()'s sort_x) is evaluated once per x group inside dplyr::summarise(), so it needs the summary functions that make it useful – mean(salary), -median(salary) – on top of the ordinary expression vocabulary in .expr_allowed_calls(). Every addition is pure, which is the bar the shared list sets.

Usage

.sort_allowed_calls()

Value

A character vector of permitted call names.

Author(s)

Jared Andrews

HTML dependency for the source download's image capture

Description

Ships the script that photographs a module's live plotly graph when its source download is clicked, so the archive can carry an image of the plot as it actually looks rather than only the interactive HTML.

Usage

.source_export_dependency()

Value

An htmltools::htmlDependency object.

Author(s)

Jared Andrews

Validate one reported image dimension

Description

The browser reports the on-screen size of each plot it photographs, which is the size the server draws at when it has to render a panel itself. Anything unusable – a hidden tab measuring zero, a graph that never laid out – is reported as NA so the caller can fall back.

Usage

.source_image_dim(x)

Arguments

Value

A positive numeric scalar of at least 10, or NA_real_.

Author(s)

Jared Andrews

Pick the size to draw a source image at

Description

Pick the size to draw a source image at

Usage

.source_image_size(img, fallback = c(1000, 700))

Arguments

Value

A length-2 numeric, width then height.

Author(s)

Jared Andrews

Drop the source download's own traffic from an input snapshot

Description

sourceExport.js hands the browser's photographs of a plot to the server as an input (⁠<output_id>_images⁠), so a module's reactiveValuesToList(input) carries every image of the last capture – up to tens of megabytes of SVG and base64 PNG. That is transport, not a setting the plot was drawn with, and written into the archive's inputs table it would bury the table and bloat the download. Entries are recognised by the payload's shape (a nonce and an images list) rather than by name alone, so an app input that merely ends in ⁠_images⁠ is kept.

Usage

.source_input_snapshot(inputs)

Arguments

Value

inputs without any image-capture payloads.

Author(s)

Jared Andrews

Value-axis limits for a split bar plot

Description

A split bar plot draws each category's bars outward from zero, positives on one side and negatives on the other, stacking a category's bars on each side. The axis is symmetric, so its half-width has to clear the longest stack on either side: the largest absolute per-category sum of that side's values. Summing signed values instead lets a long negative bar be cancelled by a short positive one, clipping it, and inverts the range when every value is negative.

Usage

.split_bar_range(df, value_col, category_col, scale_factor = 1)

Arguments

Value

list(min = , max = ) with min == -max, or NULL when the columns are missing or the value column is not numeric.

Author(s)

Jared Andrews

Park the browser's captured images until the download asks for them

Description

A download handler's content() cannot wait on the browser: Shiny serves one session on one thread, so blocking there to ask for an image would deadlock the very message it is waiting for. The capture therefore happens before the download starts – the script intercepts the button's first click, sends what it photographed here, and only re-fires the click once this replies.

Usage

.stage_source_images(store, session, output_id)

Arguments

Value

Invisibly NULL; called to set up the observer.

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,
  dodge.width = 1
)

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

Strip everything before an SVG document's root element

Description

An SVG file starts with an XML prolog, usually a DOCTYPE, and (for the cairo device) a comment banner. None of that may appear part-way through a larger document, so it is dropped before the markup is spliced into one.

Usage

.strip_svg_prolog(svg)

Arguments

Value

The markup from its ⁠<svg⁠ element onwards, or NULL if the input holds no root element.

Author(s)

Jared Andrews

Resolve the subplot spacing defaults

Description

Shared by .uniform_subplot_spacing_inputs_ui() and reset_plotly_inputs() so the controls start and reset to the same values. A subplot.margin entry sets both directions at once (linePlot uses it for its tighter default); subplot.margin.x/subplot.margin.y override it per direction.

Usage

.subplot_spacing_defaults(defaults)

Arguments

Value

A list with numeric x and y.

Author(s)

Jared Andrews

Namespace every id inside an SVG fragment

Description

Two SVG fragments dropped into one document share an id space. Both SVG devices mint ids of their own – clip paths for svglite, glyph symbols for cairo – and two panels drawn from similar data can easily mint the same one, at which point a ⁠url(#...)⁠ or href="#..." reference resolves to whichever came first and a panel is clipped or lettered with its neighbour's definitions.

Usage

.svg_namespace_ids(svg, prefix)

Arguments

Details

A self-contained fragment only ever references ids it defines itself, so prefixing the definition sites and the reference sites in one pass keeps every reference pointing where it did while making the whole set unique to the panel.

Value

svg with its ids namespaced.

Author(s)

Jared Andrews

Restate an SVG fragment's outer size in pixels

Description

Both SVG devices size the document in points while expressing its viewBox in a matching set of user units. Splicing that into a pixel-sized figure leaves the panel's on-page size at the mercy of whatever point-to-pixel ratio the reader applies, so the root element's width/height are restated in pixels here. The viewBox is left alone and does the scaling, exactly as it does for the plotly panels (which are asked for a pixel size directly).

Usage

.svg_set_px_size(svg, width, height)

Arguments

Value

svg with its root element resized, or unchanged if it carries no viewBox to scale against.

Author(s)

Jared Andrews

Make an SVG fragment openable on its own

Description

draw_to_svg() asks svglite for a fragment (standalone = FALSE), which drops the XML declaration and the default namespace – correct when the markup is about to be spliced into a document that declares them, fatal for a file written out on its own, which no browser or vector editor will open. This restates both. A document that already carries them – the cairo device's output, or a Plotly.toImage() result – is returned untouched.

Usage

.svg_standalone(svg)

Arguments

Value

svg as a standalone document, or unchanged if it holds no root element.

Author(s)

Jared Andrews

Match the title inputs to whether a plot is faceted

Description

A faceted plot titles each panel and has no main title (add_plot_config() disables it, as its placeholder sits over the panel titles), so the facet title inputs are shown and the main title inputs hidden. An unfaceted plot is the reverse.

Usage

.toggle_facet_title_inputs(session, faceted, extra = NULL, hidden = NULL)

Arguments

Value

NULL, invisibly. Called for its side effect.

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

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

Validate an expression string against a given call vocabulary

Description

The body of validate_expression(), parameterised on the allowlist so an expression with a different job (a sort key, say) can be checked by the same parser and walker rather than a second copy of them.

Usage

.validate_expression_with(expr_text, col_names, allowed)

Arguments

Value

The original expr_text string if safe, or NULL (with a warning for anything that was not simply empty).

Author(s)

Jared Andrews

HTML dependency for the shared module layout styles

Description

Carries the rules for the control grid and tab strip that organize_inputs() builds. Kept in a stylesheet rather than inline on every element so a host app can override them with ordinary specificity instead of !important.

Usage

.viz_modules_dependency()

Value

An htmltools::htmlDependency object.

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

Write one summary's plot images into the archive directory

Description

Each image comes from the browser when it could photograph the plot, and from the module itself otherwise. A module supplies its own by putting a vector_svg and/or raster_png function on its summary (or, for the older contract, on the reactive it returns); draw_to_svg() and draw_to_png() build one from any grid or base drawing.

Usage

.write_source_images(
  dir,
  safe,
  img,
  vector_svg = NULL,
  raster_png = NULL,
  res = 72
)

Arguments

Details

A capture of a plotly graph wins, because it is the plot as the user actually has it on screen – every plotly-layer edit included – whereas a server-side redraw only knows what the module can rebuild. The one exception is the screenshot the browser can scrape off a non-plotly renderPlot output, which carries no such advantage and is pinned to the on-screen device's resolution: a module's own raster_png displaces that. So the order is plotly capture, then the module's renderer, then the screenshot.

Value

Invisibly NULL; called for the files it writes. A format that cannot be produced or written warns and is skipped, so one bad image never costs the user the rest of the archive.

Author(s)

Jared Andrews

Build the source download archive

Description

The body of create_source_download_handler()'s download, split out so it can be exercised without a browser or a running app.

Usage

.write_source_zip(
  file,
  data_list_value,
  images = NULL,
  fallback_svg = NULL,
  fallback_png = NULL
)

Arguments

Value

Invisibly NULL; called for the archive it writes.

Author(s)

Jacob Martin, Jared Andrews

dittoViz::yPlot()'s default hover columns

Description

The module always passes hover.data, so when the user has made no Hover Data selection it passes the set dittoViz would have used, keeping the hover content unchanged from the package default. Columns that are not in the plotted data are ignored downstream by dittoViz.

Usage

.yplot_default_hover(
  var,
  group.by,
  color.by = NULL,
  shape.by = NULL,
  split.by = NULL
)

Arguments

Value

A character vector of column names.

Author(s)

Jared Andrews

Does a yPlot give each facet panel its own y scale?

Description

Mirrors the render's faceting: split.by facets the plot, and so do several Y variables shown with the "split" aesthetic.

Usage

.yplot_free_y(split.by, vars, multivar.aes, scales)

Arguments

Value

TRUE when the plot is faceted and its y scale is "free" or "free_y".

Author(s)

Jared Andrews

The frame yPlot's statistics are run on, holding the values as plotted

Description

dittoViz transforms the Y values (var.adjustment, then var.adj.fxn) before plotting them, and reshapes several Y variables into one long column. Tests are run on those values and the brackets are measured against them, so both the bracket headroom and the render build their stats frame here and cannot drift apart.

Usage

.yplot_stat_context(
  df,
  y.vars,
  var.adjustment = NULL,
  var.adj.fxn = NULL,
  split.by = NULL,
  per.facet = FALSE
)

Arguments

Value

list(df, y, facet.by, per.facet), or NULL when there is nothing numeric to test (e.g. var.adj.fxn = "as.factor"). Rows whose plotted value is not finite (the log of 0, say) are dropped, as ggplot drops them.

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

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

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

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

Value

A Shiny app object.

Author(s)

Jacob Martin, Jared Andrews

See Also

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

Examples

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

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

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)
if (requireNamespace("InteractiveComplexHeatmap", quietly = TRUE)) {
    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. Scaling happens after the Filter tab's row/column filters, so a Z-score describes only the rows and columns on screen.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Plot parameters implementing new functionality

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

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

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

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

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

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

Plot parameters not implemented

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

Author(s)

Jacob Martin, Jared Andrews

See Also

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

Examples

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

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,
  fit.width = TRUE,
  ...
)

Arguments

Value

A Shiny UI object for the main interactive heatmap panel.

Author(s)

Jacob Martin

See Also

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

Examples

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

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, fit.width = TRUE, ...)

Arguments

Details

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

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

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

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

Value

A Shiny UI object for the interactive heatmap.

Author(s)

Jacob Martin, Jared Andrews

See Also

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

Examples

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

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

Static (non-interactive) heatmap output UI component for the ComplexHeatmap module

Description

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

Usage

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

Arguments

Details

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

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

Value

A Shiny UI object for the static heatmap.

Author(s)

Jared Andrews

See Also

ComplexHeatmap_HeatmapOutputUI() for the interactive widget, ComplexHeatmap_HeatmapServer()

Examples

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

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,
  fit.width = TRUE,
  ...
)

Arguments

Value

A Shiny UI object for the sub-heatmap panel.

Author(s)

Jacob Martin

See Also

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

Examples

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

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

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

Value

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

Author(s)

Jacob Martin

Examples

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

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

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

Usage

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

Arguments

Details

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

Value

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

Author(s)

Jacob Martin, Jared Andrews

Examples

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

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

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 modules apply the adjustments (the adj.fxn first, then the recognized adjustment rescales the result), producing labels such as "z-score(log2(units))".

Usage

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

Arguments

Details

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

Value

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

Author(s)

Jared Andrews

Examples

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

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 the uniform Legend inputs to a plotly figure

Description

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

Usage

apply_legend_inputs(fig, input, isolate_fn = isolate)

Arguments

Value

The plotly figure with the legend inputs applied.

Author(s)

Jared Andrews

See Also

uniform_legend_inputs_ui(), reset_legend_inputs(), apply_legend_styling()

Examples

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

Apply uniform legend styling to a plotly figure

Description

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

Usage

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

Arguments

Details

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

Value

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

Author(s)

Jared Andrews

Examples

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

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.

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

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

Value

The modified plotly figure.

Author(s)

Jared Andrews

Examples

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

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

Details

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

Value

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

Author(s)

Jared Andrews

Examples

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

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,
  axis.title.font = NULL,
  facet.title.font = NULL
)

Arguments

Value

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

Author(s)

Jared Andrews

Examples

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

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

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

shinyApp(ui, server)

## End(Not run)

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",
  primary.table = NULL,
  sidebar.width = 4
)

Arguments

Details

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

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

Value

A shiny::shinyApp() object.

Author(s)

Jared Andrews

Examples

library(VizModules)

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

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

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, images of it, and its supporting data into a single .zip archive.

Usage

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

Arguments

Details

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

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

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

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

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

Value

A downloadHandler object suitable for assignment to a Shiny output.

Author(s)

Jacob Martin, Jared Andrews

See Also

collect_source_data(), module_tack_ui()

Examples

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

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

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

shinyApp(ui, server)

## End(Not run)

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,
  dodge.width = 1,
  free.y = FALSE
)

Arguments

Details

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

Value

A list with components:

annotations

List of plotly annotation objects.

shapes

List of plotly shape objects.

y.max

Numeric; maximum y value needed to accommodate all annotations.

y.min

Numeric; the smallest finite value of y.

y.range.by.axis

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

Author(s)

Jared Andrews, Jacob Martin

Examples

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

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

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

names(stat_result)

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