Package {VizModules}

Title:	Flexible, Interactive 'shiny' Modules for Almost Any Plot
Version:	0.6.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:	colourpicker, dplyr, DT, readxl, shinyjs, scales, shinyjqui (≥ 0.4.0), ggplot2, htmltools, jsonlite, methods, shinyWidgets (≥ 0.7.0), htmlwidgets, rlang, 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-11-10 19:03:35 UTC; jandrews
Author:	Jared Andrews [aut, cre], Jacob Martin [aut]
Maintainer:	Jared Andrews <jared.andrews07@gmail.com>
Repository:	CRAN
Date/Publication:	2026-11-10 21:50:16 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,
  show.legend = TRUE
)

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,
  show.legend = TRUE
)

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

Add a linePlot ribbon to a figure

Description

Adds the outlines from .ribbon_rows() as filled traces with no edge line, one outline per .ribbon_part group. With a colour mapping, the ribbon uses the same color/colors as its lines plus plotly's alpha, so plotly gives each series' band its line's colour (one colour scale is trained over every trace in a figure). A single series is given series.colour directly. The ribbon never takes a legend entry of its own; it joins its line's legendgroup, so the line's entry toggles both. Hovering a vertex shows that bound.

Usage

.add_ribbon_trace(
  fig,
  ribbon,
  x,
  y,
  color,
  colors,
  series.colour,
  opacity,
  legendgroup
)

Arguments

Value

fig with the ribbon added.

Author(s)

Jared Andrews

Draw trajectory arrows between group medians on a plotly figure

Description

Draws each trajectory as a path through the medians of the groups it names, ending in an arrowhead, as dittoViz::scatterPlot()'s add.trajectory.by.groups does. dittoViz draws that path with a ggplot arrow, which ggplotly() drops, so the scatter module draws trajectories itself.

Usage

.add_trajectory_arrows(
  fig,
  df,
  x.col,
  y.col,
  group.col,
  trajectories,
  split.by = NULL,
  arrow.size = 0.1,
  color = "#000000",
  width = 1.89
)

Arguments

Details

Each path is a line trace, and hovering over a median names its group. Its head is an annotation arrow over the last segment, with both ends in data coordinates (axref/ayref name the panel's axes), so it stays pointed the right way through zooming and resizing and is drawn above WebGL points. plotly does not clip annotations to the plot area, so the annotation's own line is a hairline under the trace, which is clipped: zoomed in, the path stops at the panel's edge, though a head just past it is still drawn.

Medians are taken from the values as plotted, separately for each facet panel from the rows that panel draws, and a path is left out of any panel that lacks one of its groups.

Value

The figure with a "Trajectory" line trace and a head annotation added for each path drawn in each panel.

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

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

Value-axis limits for a bar plot, as plotthis draws it

Description

plotthis::BarPlot() never aggregates y, so how tall a bar is depends on how the rows sharing an x are placed. With group_by and at most five groups, its default position = "auto" dodges them, and every row is a bar of its own. Otherwise (no groups, more than five, or fill_by) the rows sharing an x stack, within each facet panel, positives upward and negatives downward. The limits follow suit, so the axis fits the bars actually drawn rather than the total of every group at an x.

Usage

.bar_range(
  df,
  x,
  y,
  group.by = NULL,
  fill.by = NULL,
  facet.by = NULL,
  axis_scale_factor = 1
)

Arguments

Value

list(min = , max = ), or NULL when the columns are missing or y is not numeric.

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

The box plot's data with its x levels in the order drawn

Description

A Sort X By key wins over the dragged X Order. Either way the order is set on the frame as factor levels, which plotthis keeps, and which the tests and brackets read, so all three agree. The key is evaluated once per x level over all the data, as plotthis::BoxPlot()'s sort_x does, so a faceted plot shares one order across its panels.

Usage

.box_ordered_data(df, x, sort.text, x.order = NULL)

Arguments

Value

list(data, sort.ok); sort.ok is FALSE when a non-blank key was rejected or could not be evaluated, and was therefore ignored.

Author(s)

Jared Andrews

The x levels ordered by a sort key

Description

Mirrors plotthis::BoxPlot()'s sort_x: the key is summarised per x level and the levels are arranged by it, ascending, ties kept in their default order.

Usage

.box_sort_levels(df, x, sort.x)

Arguments

Value

A character vector of levels, or NULL when there is no key or it does not give one value per level.

Author(s)

Jared Andrews

The brackets-skipped notification, for a structure step to return

Description

The brackets-skipped notification, for a structure step to return

Usage

.brackets_skipped_note()

Value

A .structure_note().

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

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

Build a plotly figure unless it is already built

Description

plotly::plotly_build() is idempotent, but not free: every call re-runs its verification passes over all traces, and the post-processing helpers each need a built figure to read. A figure built here is marked, and building it again is skipped while nothing has been queued on it since (no layout() updates in layoutAttrs, no unevaluated traces in attrs). Direct writes to fig$x$data or fig$x$layout need no build, so they keep the mark.

Usage

.ensure_built(fig)

Arguments

Value

The built figure.

Author(s)

Jared Andrews

Error bars spanning each row's interval

Description

The bars run from the plotted value to each bound, so an interval from columns can be asymmetric. A bound on the wrong side of the value draws no bar on that side.

Usage

.error_y_spec(df, y, colour = NULL, width = NULL)

Arguments

Value

A list for a trace's error_y.

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...", with ⁠<br />⁠ as the line break in the text of a plotly::ggplotly() figure drawn with tooltip = "text".

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

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

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

Whether any row of a linePlot frame has an interval to draw

Description

Whether any row of a linePlot frame has an interval to draw

Usage

.has_interval(df)

Arguments

Value

TRUE if at least one row has both bounds.

Author(s)

Jared Andrews

Does an object hold JavaScript for htmlwidgets to evaluate?

Description

Does an object hold JavaScript for htmlwidgets to evaluate?

Usage

.has_js(x)

Arguments

Value

TRUE if any element is an htmlwidgets::JS() string.

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

Resolve multiDynamicInput annotation rows into the tracks they draw

Description

The tracks hold what is drawn, not how it was asked for: nothing of a row's key survives, and a label field left out is filled in here, so two sets of rows drawing the same thing compare identical() (rows a client reports carry every field, under keys of its own; a defaults entry may not).

Usage

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

Arguments

Value

A list of tracks named by column, each with column, values, mapping, side, size and show_legend. Empty if no row is usable.

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, n_slices = 1L)

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

Typed text is always drawn as typed. On a split axis, Heatmap() evaluates a single title holding {...} or ⁠@{...}⁠ as R code (with glue::glue() and GetoptLong::qq()), so such a title is passed once per slice instead, which it draws as given.

Value

text when it is non-blank (repeated once per slice when it would be evaluated otherwise); 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

The number of slices a resolved split divides an axis into

Description

The number of slices a resolved split divides an axis into

Usage

.heatmap_slice_count(res)

Arguments

Value

An integer: res$km for a k-means split, the requested count for a hierarchical one, the number of distinct value combinations for an annotation one, and 1 when the axis is not split.

Author(s)

Jared Andrews

Build a row or column HeatmapAnnotation from resolved tracks

Description

Build a row or column HeatmapAnnotation from resolved tracks

Usage

.heatmap_tracks_annotation(tracks, which = c("row", "column"))

Arguments

Value

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

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

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

Normalize colors to hex strings

Description

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

Usage

.normalize_hex(x)

Arguments

Value

A character vector of uppercase hex colors.

Author(s)

Jared Andrews

Package on-load hook

Description

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

Usage

.onLoad(libname, pkgname)

Arguments

Enumerate the comparisons a pairwise run will produce

Description

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

Usage

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

Value

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

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

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

Find a function's parsed help page

Description

A package loaded with pkgload is read from its source ⁠man/⁠ directory (the installed copy, if any, may be out of date); any other from its installed help database, which is parsed once and kept.

Usage

.rd_page(pkg, fn)

Arguments

Value

The parsed Rd object, or NULL when there is none.

Author(s)

Jared Andrews

Parameter descriptions from a function's help page

Description

Parameter descriptions from a function's help page

Usage

.rd_params(pkg, fn)

Arguments

Value

A named character vector, one plain-text description per parameter. Co-documented parameters each get the shared description.

Author(s)

Jared Andrews

Render an Rd fragment as plain tooltip text

Description

Code (⁠\code{}⁠, ⁠\verb{}⁠ and the like) is set in backticks, links and emphasis keep their text, quotes become quotes, and whitespace is collapsed.

Usage

.rd_text(x)

Arguments

Value

A single string.

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

The axis pairs reference lines are drawn on

Description

One per panel the figure's traces are drawn on, skipping overlay panels drawn beside the plot (marginal distributions; see add_marginal_plots()), whose axes measure something else.

Usage

.reference_axis_pairs(fig)

Arguments

Value

A list of list(x = , y = ) axis references, such as list(x = "x2", y = "y2").

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

The closed outlines of a linePlot ribbon

Description

Turns the rows a line is drawn through into the outline of the band around it, for a fill = "toself" trace. Each series (each level of colour) is walked in the order its line is drawn. Every unbroken run of rows with both bounds becomes one closed outline, the upper bounds forward and then the lower bounds back, numbered in .ribbon_part. Grouping by that column has plotly draw each outline separately, so a row without an interval leaves a gap in the band rather than one being drawn across it.

Usage

.ribbon_rows(df, y, colour = NULL)

Arguments

Details

The rows keep all of df's columns and their types, so the same x, y and colour mappings, axis titles and colour levels apply as for the line itself.

Value

df's rows rearranged into outlines, with a .ribbon_side column ("Upper" or "Lower") and a .ribbon_part column numbering the outlines within each series, or NULL if no row has an interval.

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

Send a figure whose traces have not changed as a layout-only update

Description

Compares the figure with the one last sent to the output being rendered. If everything but the layout is identical (traces, config, frames, event wiring, dependencies, and render hooks), the layout is sent in a vizmodules-plotly-layout message, which plotlyUpdate.js applies with Plotly.react() over the traces already drawn, and the render is cancelled, so the browser keeps its plot and the trace data is not sent again. Otherwise the figure is recorded and returned, to be sent whole.

Usage

.send_layout_only(fig, store, session)

Arguments

Details

identical() compares unchanged vectors by pointer, so the comparison is cheap when the traces come from a cached figure. A layout holding JavaScript (htmlwidgets::JS()) is always sent whole, since only the widget evaluates it.

A figure without a layout.uirevision of its own is given one that changes only when the figure is sent whole, so the user's zoom survives a styling change in modules not drawn through cached_structure() too.

A changed layout.uirevision is sent whole however little else changed, such as a redraw that only adds the annotations for a selection. It means a new plot, whose view resets, and the traces in the browser hold part of that view: plotly keeps the selected points and hidden legend entries on them, so a selection would stay dimmed over an update that kept them.

The browser asks for the whole figure (through the plot.refresh input that setup_manual_edits() observes) when it cannot apply the update: no plot drawn yet, or an error hiding it, which only a full render clears. The message is therefore sent even when the layout is unchanged.

Value

fig, when it is to be sent whole; otherwise the render is cancelled.

Author(s)

Jared Andrews

A reactive that only invalidates when its value changes

Description

Reactives invalidate their readers whenever anything they read changes, even if their value comes out the same. This passes one through a shiny::reactiveVal(), which ignores a value identical() to the one it holds, so an expensive reader runs only for a real change. It suits a reactive returning plain values; closures and environments never compare equal, so anything holding those always counts as a change.

Usage

.settled_reactive(x)

Arguments

Details

The value is read at priority = 1000, like other stores a render reads, so a change reaches its readers in the same flush. An error is held like a value and raised to the readers, so req() and validate() work through it as usual.

Value

A reactive returning x's value.

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, within each facet panel when the plot is faceted. 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,
  facet_col = NULL
)

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

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

A notification raised while drawing a plot

Description

The structure step is cached, so it cannot show notifications itself (a cache hit would skip them). It returns them instead, built with this, and the function .structure_notifier() returns shows them the first time the styling step sees each build.

Usage

.structure_note(message, id, type = "message")

Arguments

Value

A list.

Author(s)

Jared Andrews

Show the notifications a structure step returned

Description

Returns a function for the module's styling step to call with the cached step's value; it shows that value's notes the first time it sees each build, so restyling a plot does not repeat them but drawing (or restoring) one does. It is called from the styling step rather than an observer so the cached step is only evaluated when the plot is, never eagerly (an input frozen by an update mid-flush would otherwise stop it).

Usage

.structure_notifier(session)

Arguments

Value

A function of the cached step's value, whose notes is a list of .structure_note()s.

Author(s)

Jared Andrews

Input ids that only style a figure

Description

The ids apply_uniform_styling() reads. The cached plot step keys its cache only on the inputs it reads itself (see cached_structure()), so changing one of these re-uses the cached plot, unless a module's plot step reads it too (DotPlot draws its size legend in the legend fonts, for instance).

Usage

.style_input_ids

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

Trajectory paths from any form the scatter module takes them in

Description

The scatter module's Trajectories input reports a named list of rows, each holding the groups its path visits, in order: list(trajectories1 = list(groups = c("A", "B"))). defaults may instead give dittoViz's add.trajectory.by.groups form, a list of character vectors such as list(c("A", "B"), c("C", "D", "E")), or the bracketed text the module once took, "[A,B],[C,D,E]".

Usage

.trajectory_paths(x)

Arguments

Value

A list of character vectors, one per trajectory in the order given, each without blank or missing entries. Trajectories left empty are dropped.

Author(s)

Jared Andrews

Rows of the scatter module's Trajectories input for a set of paths

Description

Rows of the scatter module's Trajectories input for a set of paths

Usage

.trajectory_rows(paths)

Arguments

Value

A named list of rows, each list(groups = ), for the elements of multiDynamicInput() or updateMultiDynamicInput().

Author(s)

Jared Andrews

Have a plotly figure re-rendered in place

Description

Sets layout.transition to TRUE, which makes the plotly widget update an existing graph with Plotly.react() rather than purging and recreating it, and attaches plotlyUpdate.js, which clears the previous render's event listeners first (the widget re-attaches its own on every render).

Usage

.update_in_place(fig)

Arguments

Details

The widget only checks that layout.transition is set. It is TRUE rather than a transition such as list(duration = 0) because plotly.js animates any react() whose changes are all animatable when given one, and an animated update restyles the traces without redrawing the legend: a colour change would leave the legend showing the old colours. plotly.js ignores a transition that is not an object, so each update is drawn in full.

Value

The figure.

Author(s)

Jared Andrews

Fit the Category Label Position slider to the value axis

Description

Sets the text.position slider to run from -extent to extent with a round step (a power of ten near a hundredth of the extent, no finer than 0.001), and rounds the ends to that step, so the slider shows tidy numbers instead of floating-point noise such as -0.8000000000000007.

Usage

.update_text_position_slider(session, extent)

Arguments

Value

Called for its side effect, the slider update.

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

How many points a plot draws before its point layers switch to WebGL

Description

Set with options(VizModules.webgl.threshold = n); 5000 by default.

Usage

.webgl_threshold()

Value

A single number.

Author(s)

Jared Andrews

Serialise part of a widget as its widget would be

Description

Uses the serialiser the widget declares (plotly's, for a plotly figure), with its arguments, as htmlwidgets does for the whole payload, so the part decodes in the browser exactly as it would inside a full render.

Usage

.widget_json(fig, value)

Arguments

Value

A json string, embedded verbatim in a Shiny message.

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)
if (requireNamespace("ComplexHeatmap", quietly = TRUE) &&
    requireNamespace("InteractiveComplexHeatmap", quietly = TRUE) &&
    requireNamespace("circlize", quietly = TRUE)) {
    # 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"))

Add marginal distribution plots to a scatter plot

Description

Draws the distribution of the plotted X values in a strip above a single-panel plotly figure, and of the Y values in a strip to its right, as a density curve, a histogram, a rug, or any combination of them. One trace is drawn per group, in that group's colour, and the rug gives each group its own lane so groups do not overplot.

Usage

add_marginal_plots(
  fig,
  x,
  y,
  groups = NULL,
  colors = "#000000",
  top = character(0),
  right = character(0),
  top.size = 0.15,
  right.size = 0.15,
  opacity = 0.5,
  bins = 30,
  binwidth = NULL,
  density.adjust = 1,
  rug.size = 0.3,
  rug.length = 0.8,
  rug.width = 1,
  gap = 0.02,
  show.axes = FALSE
)

Arguments

Details

The main panel is shrunk to make room, and each strip's value axis matches the main axis, so zooming or panning the plot moves its marginals with it. Paper-anchored shapes (such as the panel border ggplotly draws) and axis-title annotations from axis_titles_as_annotations() are moved into the shrunk panel.

Call this last, once everything else has been drawn: helpers that work per panel (fit lines, reference lines, axis styling) read the strips' extra axes as facet panels. It is not meant for a faceted figure.

A density and a histogram on the same side share one strip, the histogram drawn first and scaled to a density (count / (n * bin width)) so both share a scale; a histogram on its own shows counts. A rug sits in a strip of its own, between the main panel and any density or histogram. Densities, like ggplot2's, span each group's range of values. Every marginal is a line trace, so box and lasso selection pick only the plot's points, and each takes its group's legendgroup, so hiding a group from the legend hides its marginals too.

Value

The built plotly figure with the marginals added, or fig unchanged when top and right are both empty.

Author(s)

Jared Andrews

See Also

stats::density(), axis_titles_as_annotations()

Examples

library(plotly)
df <- example_iris
fig <- plot_ly(df,
    x = ~Sepal.Length, y = ~Sepal.Width, color = ~Species,
    type = "scatter", mode = "markers"
)
add_marginal_plots(fig,
    x = df$Sepal.Length, y = df$Sepal.Width, groups = df$Species,
    colors = c("#E69F00", "#56B4E9", "#009E73"),
    top = c("density", "rug"), right = "histogram"
)

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

Add a point-size legend to a plotly figure

Description

plotly drops the size legend when marker size encodes a numeric column (plotly.R#705), whether the figure comes from plotly::ggplotly() or is built by hand. This draws one in its place: a vertical column of circles with numeric labels, outside the right edge of the plot area in paper-referenced coordinates so it does not overlap the data. The breaks run evenly across the size scale's limits, and each circle is drawn at the size the scale gives its value, so the legend follows the plot's size scaling. The DotPlot and scatter plot modules use it, and a module in another package can too.

Usage

add_size_legend(
  fig,
  data,
  size.by,
  gap = 0.05,
  size.values = NULL,
  title = size.by,
  digits = NULL,
  title.size = NULL,
  text.size = NULL,
  start.y = 0.95,
  start.x = 1.02,
  font.family = NULL,
  font.color = NULL,
  limits = NULL,
  size.range = NULL,
  breaks = NULL
)

Arguments

Details

For a ggplot drawn with scale_size(range = r, limits = l), pass size.range = r and limits = l. Without size.range, the circles are read from the figure's own markers instead, taking its smallest and largest to be the data's minimum and maximum.

Call it after the figure's traces are complete. It builds the figure and appends its annotations to the built layout, so later plotly::plotly_build() calls (e.g. apply_legend_inputs() or axis_titles_as_annotations()) do not duplicate them. A module hiding its legend should pass size.by = NULL.

Value

The built plotly figure with size-legend annotations appended, or the unmodified figure when size.by is NULL/empty, not present in data, not numeric, or has no finite values.

Author(s)

Jacob Martin, Jared Andrews

Examples

library(plotly)
df <- data.frame(x = 1:5, y = c(2, 4, 3, 5, 1), n = c(10, 40, 25, 80, 55))
fig <- plot_ly(df, x = ~x, y = ~y, type = "scatter", mode = "markers",
    marker = list(size = sqrt(df$n) * 3))
add_size_legend(fig, df, size.by = "n", title = "Count", digits = 0)

# A ggplot with a fixed size scale: the legend runs 0, 25, ..., 100.
library(ggplot2)
p <- ggplot(df, aes(x, y, size = n)) +
    geom_point() +
    scale_size(range = c(2, 8), limits = c(0, 100))
add_size_legend(ggplotly(p), df, size.by = "n", limits = c(0, 100), size.range = c(2, 8))

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

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

See Also

adjustment_fn(), as_plotted(), adjust_column_values()

Examples

adjusted_values(c(1, 10, 100), adjustment = "z-score", adj.fxn = "log10")
adjusted_values(c(1, 2, 4), adjustment = "relative.to.max")

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

See Also

adjusted_values(), as_plotted()

Examples

fn <- adjustment_fn(adjustment = "z-score", adj.fxn = "log10")
fn(c(1, 10, 100))
adjustment_fn()

Set the padding between a figure's data and the edges of its plot area

Description

Sets each x and y axis range to the extent of the data drawn on it, widened at each end by a fraction of that extent: 0 makes the data fill the plot area, 0.05 matches ggplot2's default expansion. The extent is read from the figure's traces as drawn: points and lines, bars from their base, error bars, and fills down to zero. A categorical axis (as plotly::ggplotly() draws one) spans its categories' bands, each one unit wide, so 0 puts the outer bands' edges on the plot area's.

Usage

apply_axis_padding(fig, x = NULL, y = NULL, swap = FALSE)

Arguments

Details

Axes that share a scale (matched axes, or the identical ranges of a faceted plot's fixed scales) get the same range, so they still line up. Reversed axes stay reversed, and log axes are padded in log units. Axes holding dates or plotly categories, or with no numeric data on them, are left alone, as are axes marked with mark_overlay_axes().

Only what the traces draw counts. Annotations and shapes, such as significance brackets or reference lines, do not widen the range and can be cut off, so use axis limits instead on an axis that carries them.

Value

The built plotly figure with the axis ranges set.

Author(s)

Jared Andrews

See Also

apply_uniform_styling(), which applies this from the Axes tab's "X Axis Padding" and "Y Axis Padding" inputs.

Examples

fig <- plotly::plot_ly(mtcars,
    x = ~wt, y = ~mpg, type = "scatter", mode = "markers"
)
# Points reaching the edges of the plot area.
apply_axis_padding(fig, x = 0, y = 0)$x$layout$xaxis$range

# A ggplot area plot with its default expansion removed along x only.
df <- data.frame(year = 2000:2020, n = cumsum(c(5, rep(1, 20))))
p <- ggplot2::ggplot(df, ggplot2::aes(year, n)) +
    ggplot2::geom_area()
apply_axis_padding(plotly::ggplotly(p), x = 0)

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)

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

See Also

uniform_annotation_inputs_ui(), parse_highlight_values(), create_highlight_annotations()

Examples

## Not run: 
fig <- apply_highlight_styling(
    fig, annotate.by = "name", highlight_vals = c("Mazda RX4", "Fiat 128"),
    style = list(color = "#FF0000", size = 14, border.color = "#000000", border.width = 2)
)

## End(Not run)

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

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)

Reorder the levels of a categorical column

Description

Re-levels data[[column]] as a factor whose levels follow order, which is how the plot modules set the order of a categorical axis: the plot functions, the statistics and their brackets all take the axis order from the column's levels, so they stay in step.

Usage

apply_level_order(data, column, order)

Arguments

Value

data, with column re-levelled. It is returned unchanged when order is empty or already the default order, or column is missing or numeric.

Author(s)

Jared Andrews

See Also

level_order_input(), level_order_choices(), setup_level_order()

Examples

df <- apply_level_order(example_iris, "Species", c("virginica", "setosa"))
levels(df$Species)

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.

Axes recorded as belonging to overlay panels drawn beside the plot, such as the marginal distributions add_marginal_plots() adds, are left alone.

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)

Set the notation of a figure's numeric tick labels

Description

Tick labels of large or small numbers can come out in scientific notation (1e+05) or not depending only on which breaks an axis happens to get, since a ggplot converted with plotly::ggplotly() carries the labels R's format() gave its breaks as fixed tick text. This sets the notation explicitly instead, for every x and y axis of the figure.

Usage

apply_tick_notation(fig, scientific = FALSE)

Arguments

Details

Fixed tick text is rewritten only on axes whose labels are all numbers that match the tick positions (or are 10, 2, or e raised to them, for a log scale), so categorical axes, even ones whose categories look like numbers, and formatted labels ("25%", "$1,000") are left alone. With scientific = FALSE, only labels already in scientific notation are rewritten; with TRUE, every numeric label is written as a power of ten (1.5 times 10 to the 5th). Axes plotly labels itself get exponentformat = "power" when scientific is TRUE, and are otherwise left to plotly, whose default abbreviates large numbers (⁠100k⁠) rather than using scientific notation.

Axes marked with mark_overlay_axes() are left alone.

Value

The built plotly figure with its tick labels updated.

Author(s)

Jared Andrews

See Also

apply_uniform_styling(), which applies this from the Axes tab's "Scientific Notation Ticks" input.

Examples

p <- ggplot2::ggplot(data.frame(x = c("a", "b"), y = c(1e5, 3e5)), ggplot2::aes(x, y)) +
    ggplot2::geom_col()
fig <- plotly::ggplotly(p)
apply_tick_notation(fig)$x$layout$yaxis$ticktext
apply_tick_notation(fig, scientific = TRUE)$x$layout$yaxis$ticktext

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)

Apply the uniform styling inputs to a module's figure

Description

The plot modules build their figures in two steps. The first draws the plot itself from the data and every input that changes what is drawn; that is the expensive part (a ggplot built and converted with plotly::ggplotly(), say), and it is cached. This function is the second step: it applies the inputs that only style the figure – titles, fonts, ticks and their notation, gridlines, the padding around the data, reference lines, the modebar, the shape-drawing tool, and the legend – to the figure the first step returned. Changing one of those inputs re-runs only this step, which takes a few milliseconds rather than a full rebuild.

Usage

apply_uniform_styling(
  fig,
  input,
  isolate_fn = isolate,
  facet.by = NULL,
  title_y = 0.95,
  include.modebar.buttons = TRUE,
  fig.fn = NULL,
  ggplot.axis.styling = TRUE,
  legend.position = NULL,
  padding.axes = c("x", "y")
)

Arguments

Details

The figure passed in is never modified (R copies on write), so each call styles the cached figure afresh and nothing appended here (reference lines, say) accumulates across calls.

Axes used only by overlay panels drawn alongside the plot (the scatter plot's marginal distributions, see add_marginal_plots()) keep their own styling and get no reference lines.

Value

The styled plotly figure.

Author(s)

Jared Andrews

See Also

apply_title_layout(), apply_subplot_axis_styling(), apply_tick_notation(), apply_axis_padding(), add_reference_lines(), add_plot_config(), apply_plotly_newshape(), apply_legend_inputs(), axis_titles_as_annotations()

Examples

fig <- plotly::plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers")
# The uniform inputs, as a module's `input` would hold them.
input <- list(
    title.font.size = 20, title.font.family = "Arial", title.font.color = "#000000",
    axis.title.horizontal.position = 0.5, axis.title.font.size = 16,
    axis.title.font.family = "Arial", axis.title.font.color = "#000000",
    axis.tickfont.size = 12, axis.tickfont.family = "Arial", axis.tickfont.color = "#000000",
    axis.tickangle.x = 0, axis.tickangle.y = 0, axis.ticks = "outside",
    axis.tickcolor = "#000000", axis.ticklen = 5, axis.tickwidth = 1,
    show.grid.x = TRUE, show.grid.y = FALSE, grid.color = "#CCCCCC",
    hline.intercepts = "20", hline.colors = "#D55E00",
    download.format = "svg", legend.text.size = 12, legend.title.size = 14
)
apply_uniform_styling(fig, input, isolate_fn = identity)

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

See Also

adjusted_values(), adjust_column_values()

Examples

as_plotted(data.frame(y = c(1, 10, 100)), "y", adjustment = "z-score", adj.fxn = "log10")

Draw a figure's point layers with WebGL

Description

SVG slows down badly with many points, where WebGL does not. This switches the figure's point traces (scatter traces drawn as markers only: jitter, the points of a scatter plot) to scattergl once, together, they hold at least threshold points. Lines, filled areas, boxes, and violins stay SVG, so they stay vector in SVG downloads; only the switched points become an embedded image there. Unlike plotly::toWebGL(), which switches every trace.

Usage

auto_webgl(fig, threshold = .webgl_threshold(), overlays = FALSE)

Arguments

Details

WebGL canvases sit above SVG traces, so a line drawn over the points (an ellipse, a contour) would end up beneath them. Set overlays = TRUE to switch a figure's unfilled line traces with its points, which keeps their order. The points alone decide whether the threshold is reached, and filled traces stay SVG either way.

Pair it with webgl_input(). The default threshold is 5,000 points, or options(VizModules.webgl.threshold = n).

Value

The figure.

Author(s)

Jared Andrews

See Also

webgl_input()

Examples

fig <- plotly::plot_ly(x = rnorm(100), y = rnorm(100), type = "scatter", mode = "markers")
fig <- plotly::plotly_build(fig)
auto_webgl(fig, threshold = 50)$x$data[[1]]$type

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)

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

Details

Anything that is not a single, non-NA, non-empty value gives NULL: an input that has not reported yet (NULL), NA, "" and a vector of more than one value alike. A multi-select therefore reads as "no selection", so handle those inputs explicitly.

Value

value, or NULL.

Author(s)

Jared Andrews

See Also

nz_value(), na_to_null()

Examples

blank_to_null("")
blank_to_null(NULL)
blank_to_null("Species")
blank_to_null("Sepal.Length", df = iris, numeric_is_null = TRUE)

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