Package {maidr}

maidr: Multimodal Access and Interactive Data Representation

Description

The 'maidr' package provides accessible, interactive visualizations through the MAIDR (Multimodal Access and Interactive Data Representation) system. It converts 'ggplot2' and Base R plots into accessible HTML/SVG formats with keyboard navigation, screen reader support, and sonification capabilities. This enables users with visual impairments to independently explore and understand data visualizations through multiple sensory modalities.

Main Functions

• show: Display an interactive MAIDR plot in the browser or RStudio Viewer

• save_html: Save a plot as a standalone HTML file

• run_example: Run interactive example plots

• maidr_on: Enable automatic MAIDR interception in RMarkdown

• maidr_off: Disable automatic MAIDR interception

• render_maidr: Render MAIDR plots in Shiny applications

• maidr_output: Create MAIDR output container for Shiny UI

Supported Plot Types

The package supports a wide variety of plot types from both 'ggplot2' and Base R plotting systems:

ggplot2 plots:

• Bar charts (simple, grouped, stacked) - geom_bar(), geom_col()

• Pie charts - geom_col() / geom_bar() with coord_polar("y")

• Histograms - geom_histogram()

• Scatter plots - geom_point()

• Line plots - geom_line()

• Step plots - geom_step()

• Box plots - geom_boxplot()

• Violin plots - geom_violin()

• Heat maps - geom_tile()

• Candlestick (OHLC) charts - tidyquant::geom_candlestick()

• Density/smooth curves - geom_density(), geom_smooth()

• Faceted plots - facet_wrap(), facet_grid()

• Multi-panel layouts (via 'patchwork' package)

• Multi-layered plot combinations

Base R plots:

• Bar plots (simple, grouped, stacked) - barplot()

• Pie charts - pie()

• Histograms - hist()

• Scatter and line plots - plot(), points(), lines()

• Step plots - plot(type = "s"), plot(type = "S")

• Box plots - boxplot()

• Heat maps - image(), heatmap()

• Contour plots - contour()

• Candlestick (OHLC) charts - quantmod::chartSeries()

• Multi-panel layouts - par(mfrow), par(mfcol)

Experimental plot types: The types above are stable. The package also reads a longer list of charts as prototypes: none has been through a user study, and each may change without a deprecation period. In these docs an experimental type is marked [experimental] after its name; a type with no mark is stable. Among them:

• ggplot2 area charts [experimental]

• ggplot2 contour plots - geom_contour() [experimental]

• ggplot2 error bars [experimental]

• ggplot2 Gantt charts - maidr_gantt() [experimental]

• ggplot2 hexbin plots [experimental]

• ggplot2 ROC curves - maidr_roc() [experimental]

• Base R correlograms [experimental]

• Base R Q-Q plots [experimental]

• Base R radar charts - stars() [experimental]

• Base R mosaic plots [experimental]

• Base R violin plots - vioplot::vioplot() [experimental]

• Base R word clouds [experimental]

The full list is under "Experimental Plot Types" in the README.

Accessibility Features

• Keyboard Navigation: Use arrow keys to explore data points

• Screen Reader Support: ARIA labels and live regions for announcements

• Sonification: Audio representation of data patterns

• Text Summaries: Automatic statistical descriptions

• Grid Navigation: Efficient exploration of scatter plots

Integration

The package integrates seamlessly with:

• RStudio: Direct display in the Viewer pane

• RMarkdown/Quarto: Automatic rendering with maidr_on()

• Shiny: Interactive plots in Shiny apps via render_maidr()

• Standalone HTML: Export plots for sharing with save_html()

Getting Started

To create your first accessible plot:

library(maidr)
library(ggplot2)

# Create a ggplot2 plot
p <- ggplot(mtcars, aes(x = factor(cyl), y = mpg)) +
  geom_boxplot()

# Display as interactive MAIDR plot
show(p)

# Or save to HTML file
save_html(p, file = "my_plot.html")

For Base R plots:

library(maidr)

# Create a Base R plot
barplot(table(mtcars$cyl))

# Display as interactive MAIDR plot
show()

Learn More

• Package website: https://r.maidr.ai/

• MAIDR project: https://maidr.ai/

• GitHub repository: https://github.com/xability/r-maidr

• Get started: vignette("getting-started", package = "maidr")

• Shiny integration: vignette("shiny-integration", package = "maidr")

Author(s)

Maintainer: JooYoung Seo jseo1005@illinois.edu [copyright holder]

Authors:

• JooYoung Seo jseo1005@illinois.edu [copyright holder]

• Niranjan Kalaiselvan nk46@illinois.edu

See Also

Useful links:

• https://github.com/xability/r-maidr

• https://r.maidr.ai/

• Report bugs at https://github.com/xability/r-maidr/issues

Function Classification Maps

Description

Maps of function names to their classification levels

Usage

.base_r_function_classes

One rebuilt frame per layer, so a facet does not pay for it per panel

Description

process_facet_panel() runs once per panel, so a jittered layer asked for its undisplaced positions once per panel too – and each of those rebuilds the whole plot, every panel of it. Measured by counting ggplot2::ggplot_build calls through a facet of P panels: 3, 5 and 9 calls for P of 2, 4 and 8. One build is the original; the other P are the same answer computed P times over, so the work is quadratic in the panel count while the answer never varies – undisplaced_layer_data() depends only on the plot and the layer index.

Usage

.jitter_cache

Details

Keyed on the layer itself rather than on the plot. ggplot2 Layer objects are ggproto, ggproto objects are environments, and identical() on two environments is a pointer comparison – so the lookup is O(1) and exact, where hashing or deep-comparing the plot could cost as much as the rebuild it saves. A layer belongs to one plot, so its identity settles the question.

One entry per layer index, each holding the layer it was computed from, and the whole cache emptied when a plot starts being processed.

All three parts are load-bearing. The index bounds the cache at the number of layers a plot has and stops two jittered layers evicting each other once per panel, which is the cost this exists to remove. The layer catches the ordinary case of a second plot built from its own geom_jitter(). And the reset catches the case the layer cannot: ggplot2 documents a layer as reusable across plots, and +.gg appends the same ggproto object rather than a clone, so

shared <- geom_jitter()
p1 <- ggplot(df1, aes(g, score)) + shared
p2 <- ggplot(df2, aes(g, score)) + shared

gives two plots that are identical() at that layer. Measured before the reset went in: p2 was announced with every one of df1's values, and the row-count check waved it through because the two frames were the same length.

Base R Device-Scoped Storage

Description

This module provides device-scoped storage for Base R plot calls, enabling proper isolation between devices and preventing call accumulation.

Usage

.maidr_base_r_session

chartSeries TA Advisory Warning State

Description

Environment used to suppress repeat chartSeries TA advisory warnings within a single session.

Usage

.maidr_chartseries_ta_warned

fourfoldplot() Decline Advisory State

Description

Environment holding the decline reasons already explained in this session, so the advisory below is not repeated for every call.

Usage

.maidr_fourfoldplot_declined

Details

A character vector rather than the single flag .maidr_chartseries_ta_warned carries, because fourfoldplot() declines for three different reasons and a session that draws a default-std chart and then a 2x2xk one should hear both explanations rather than only the first.

ggplot2 Print Method Interception

Description

Intercepts ggplot2's print method so that typing a ggplot object name at the console automatically renders it in the MAIDR interactive viewer.

Usage

.maidr_ggplot_state

Base R Function Patching System

Description

This module provides function patching capabilities for Base R plotting functions. It intercepts Base R plotting calls and records them for processing by the MAIDR system.

Usage

.maidr_patching_env

vioplot's default whisker reach, in interquartile ranges

Description

vioplot's default whisker reach, in interquartile ranges

Usage

.maidr_vioplot_default_range

Grobs vioplot draws, one of each per violin

Description

Measured by echoing a two-group call through gridGraphics::grid.echo():

Usage

.maidr_vioplot_grob_kinds

Details

graphics-plot-1-box-1      polygon  n=4     <- the plot frame, NOT a violin
graphics-plot-1-polygon-1  polygon  n=200   <- violin body
graphics-plot-1-lines-1    lines    n=2     <- whisker, lower to upper
graphics-plot-1-rect-1     rect     n=1     <- the quartile box
graphics-plot-1-points-1   points   n=1     <- the median dot

The body carries exactly twice the evaluation points sm.density returns, mirrored about the category position, which is what confirms the replayed curve is the drawn one.

The patterns below are anchored, which is defensive rather than a fix for anything observed. Measured, the two things it is tempting to credit it with are not true: graphics-plot-11-polygon-1 is excluded by the - delimiter whether the pattern is anchored or not, and graphics-plot-1-box-1 – the panel frame, which is a polygon grob – never enters this search because it is not named polygon. What the trailing $ genuinely excludes is a longer name beginning the same way, such as -polygon-1-extra; gridSVG emits none today, so this keeps a name it does not own from being collected if that ever changes.

Wrap vioplot's entry point once its namespace is available

Description

vioplot is in Suggests, so if it loads after maidr its vioplot() has not been wrapped yet and user calls would go unrecorded. Same shape as the quantmod hook above, and registered beside it in .onLoad.

Usage

.maidr_vioplot_onload_hook(...)

wordcloud()'s own defaults, replicated so the reading matches the drawing

Description

Only the two that decide which terms are drawn. The rest — scale, rot.per, colors — decide how they look, and a reading has nothing to do with them.

Usage

.maidr_wordcloud_defaults

Wrap wordcloud's entry point once its namespace is available

Description

Same shape and same reason as the vioplot hook above: wordcloud is in Suggests, so a call made after a late library(wordcloud) would otherwise go unrecorded entirely.

Usage

.maidr_wordcloud_onload_hook(...)

Base R System Adapter

Description

Adapter for the Base R plotting system. This adapter uses function patching to intercept Base R plotting calls and detect plot types.

Format

An R6 class inheriting from SystemAdapter

Super class

SystemAdapter -> BaseRAdapter

Methods

Public methods

• BaseRAdapter$new()

• BaseRAdapter$formula_frame_missing()

• BaseRAdapter$formula_call()

• BaseRAdapter$formula_scatter_readable()

• BaseRAdapter$can_handle()

• BaseRAdapter$detect_layer_type()

• BaseRAdapter$is_dodged_barplot()

• BaseRAdapter$is_stacked_barplot()

• BaseRAdapter$is_normalized_barplot()

• BaseRAdapter$create_orchestrator()

• BaseRAdapter$get_system_name()

• BaseRAdapter$get_adapter()

• BaseRAdapter$has_facets()

• BaseRAdapter$is_patchwork()

• BaseRAdapter$get_plot_calls()

• BaseRAdapter$clear_plot_calls()

• BaseRAdapter$initialize_patching()

• BaseRAdapter$restore_functions()

• BaseRAdapter$clone()

BaseRAdapter$new()

Initialize the Base R adapter

Usage

BaseRAdapter$new()

BaseRAdapter$formula_frame_missing()

Was a formula call recorded without the frame it drew from?

A formula reader takes its rows from the model frame kept at record time. When that frame could not be built – a subset written as an expression with nothing to evaluate it in, a data that no longer resolves – the reader has nothing to announce, and a claimed layer with nothing in it exports as an interactive chart that says nothing. Declining the type sends the chart to the picture instead.

Usage

BaseRAdapter$formula_frame_missing(layer)

Arguments

Returns

TRUE when the call carries a formula but no frame

BaseRAdapter$formula_call()

Was the call handed a formula?

Either written in the call, or – ⁠fmla <- y ~ x; plot(fmla)⁠ – bound to a name the recorder resolved.

Usage

BaseRAdapter$formula_call(layer)

Arguments

Returns

TRUE when the call carries a formula

BaseRAdapter$formula_scatter_readable()

Does a recorded formula plot() draw a numeric scatter?

plot.formula() draws a scatter only for a numeric response over one numeric predictor; a factor predictor reaches plot.factor() and a box plot, and a longer right-hand side is plot.default() over the first term. Only the two-column numeric frame is read as points.

Usage

BaseRAdapter$formula_scatter_readable(layer)

Arguments

Returns

TRUE when the frame is a numeric pair

BaseRAdapter$can_handle()

Check if this adapter can handle a plot object

Usage

BaseRAdapter$can_handle(plot_object)

Arguments

Returns

TRUE if Base R plotting is active, FALSE otherwise

BaseRAdapter$detect_layer_type()

Detect the type of a single layer from Base R plot calls

Usage

BaseRAdapter$detect_layer_type(layer, plot_object = NULL)

Arguments

Returns

String indicating the layer type (e.g., "bar", "dodged_bar", "stacked_bar", "smooth", "line", "point")

BaseRAdapter$is_dodged_barplot()

Check if a barplot call represents a dodged bar plot

Usage

BaseRAdapter$is_dodged_barplot(args)

Arguments

Returns

TRUE if this is a dodged bar plot, FALSE otherwise

BaseRAdapter$is_stacked_barplot()

Check if a barplot call represents a stacked bar plot

Usage

BaseRAdapter$is_stacked_barplot(args)

Arguments

Returns

TRUE if this is a stacked bar plot, FALSE otherwise

BaseRAdapter$is_normalized_barplot()

Check if a barplot call draws a 100% stacked bar

Base R has no position = "fill" to read: barplot() takes no normalisation argument at all, and the idiomatic way to draw a 100% stacked bar is to normalise the matrix first, as barplot(prop.table(m, 2)). The only signal left is the drawn geometry.

So this reads what the chart shows rather than guessing what the author meant, and the two are the same thing here: when every column sums to 1, every bar is drawn to a common full height and each segment is that category's share. A chart like that IS a 100% stacked bar whatever the numbers were before they reached barplot().

Deliberately narrow. It does not also accept columns summing to 100, because a matrix of raw counts can total 100 by coincidence and nothing about the drawing would distinguish that from percentages. And it needs two or more rows, because a single series stacked against nothing is not a stack.

Usage

BaseRAdapter$is_normalized_barplot(args)

Arguments

Returns

TRUE if every column of the height matrix sums to 1

BaseRAdapter$create_orchestrator()

Create an orchestrator for this system (Base R)

Usage

BaseRAdapter$create_orchestrator(plot_object = NULL)

Arguments

Returns

PlotOrchestrator instance

BaseRAdapter$get_system_name()

Get the system name

Usage

BaseRAdapter$get_system_name()

Returns

System name string

BaseRAdapter$get_adapter()

Get a reference to this adapter (for use by orchestrator)

Usage

BaseRAdapter$get_adapter()

Returns

Self reference

BaseRAdapter$has_facets()

Check if plot has facets (Base R doesn't support facets)

Usage

BaseRAdapter$has_facets(plot_object = NULL)

Arguments

Returns

FALSE (Base R doesn't support facets)

BaseRAdapter$is_patchwork()

Check if plot is a patchwork plot (Base R doesn't support patchwork)

Usage

BaseRAdapter$is_patchwork(plot_object = NULL)

Arguments

Returns

FALSE (Base R doesn't support patchwork)

BaseRAdapter$get_plot_calls()

Get recorded plot calls for processing

Usage

BaseRAdapter$get_plot_calls(device_id = grDevices::dev.cur())

Arguments

Returns

List of recorded plot calls

BaseRAdapter$clear_plot_calls()

Clear recorded plot calls (for cleanup)

Usage

BaseRAdapter$clear_plot_calls(device_id = grDevices::dev.cur())

Arguments

BaseRAdapter$initialize_patching()

Initialize function patching

Usage

BaseRAdapter$initialize_patching()

Returns

NULL (invisible)

BaseRAdapter$restore_functions()

Restore original functions

Usage

BaseRAdapter$restore_functions()

Returns

NULL (invisible)

BaseRAdapter$clone()

The objects of this class are cloneable with this method.

Usage

BaseRAdapter$clone(deep = FALSE)

Arguments

Base R Association Plot Layer Processor

Description

Processes Base R assocplot() layers – a Cohen–Friendly association plot, which draws one tile per cell of a two-way table whose signed height is that cell's Pearson residual, (observed - expected) / sqrt(expected).

Read as a heat layer, because a named grid of one number per cell is what the chart states and row-then-column is how a reader navigates a contingency table. Measured on assocplot(HairEyeColor[, , 1]), the rects the drawing produces carry the residuals exactly:

       Brown    Blue   Hazel   Green
Black  2.780  -2.059   0.184  -1.408
Brown  0.391  -0.246   0.185  -0.465
Red   -0.562  -0.658   0.532   1.485
Blond -3.273   3.271  -0.988   1.097

Nothing is inferred from the drawing: assocplot() is handed the table, so the recorded call carries every number the trace wants. It returns NULL, which is why the reading comes from the argument – the shape bxp()'s reading took in #265.

Two things this deliberately does not do

The tile width is dropped. Each tile is drawn sqrt(expected) wide, so the marginals are on the chart as a second encoding. A heat layer has no width, and the residual is what an association plot exists to show – the eye reads height and sign, and the width is why a cell's box is wider rather than a value the reader is asked to compare. Announcing it in z instead would replace the number the chart is about.

It is not a mosaic. mosaicplot() is read as one and the two look alike, but a mosaic's tiles tile the space and carry proportions of a whole. These float above and below a baseline and carry residuals, which are signed and sum to nothing. Calling it a mosaic would tell a reader the areas are shares of a total when they are a departure from an expectation.

Super class

LayerProcessor -> BaseRAssocplotLayerProcessor

Methods

Public methods

• BaseRAssocplotLayerProcessor$process()

• BaseRAssocplotLayerProcessor$needs_reordering()

• BaseRAssocplotLayerProcessor$extract_data()

• BaseRAssocplotLayerProcessor$pearson_residuals()

• BaseRAssocplotLayerProcessor$recorded_table()

• BaseRAssocplotLayerProcessor$extract_axis_titles()

• BaseRAssocplotLayerProcessor$extract_main_title()

• BaseRAssocplotLayerProcessor$generate_selectors()

• BaseRAssocplotLayerProcessor$clone()

BaseRAssocplotLayerProcessor$process()

Process the association plot layer.

Usage

BaseRAssocplotLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRAssocplotLayerProcessor$needs_reordering()

Whether the plot data must be reordered before drawing; a Base R layer is read from the recorded call and never is

Usage

BaseRAssocplotLayerProcessor$needs_reordering()

Returns

FALSE

BaseRAssocplotLayerProcessor$extract_data()

Read the residual grid out of the recorded call.

The grid is the table transposed, and its rows reversed. That is not a convention chosen here but the relation assocplot() has to its argument, measured from the drawn rects: the first dimension runs across the x axis and the second up the y axis, bottom to top. It is the same relation image() has to its matrix, and the heatmap processor transposes for the same reason.

A table with a zero margin has cells whose expected count is zero, and a residual there is 0/0. assocplot() draws nothing for such a cell; the grid has to keep a place for it, so it carries 0 – the departure from an expectation of nothing being nothing.

Usage

BaseRAssocplotLayerProcessor$extract_data(layer_info)

Arguments

Returns

List with points, x and y, empty when there is no table

BaseRAssocplotLayerProcessor$pearson_residuals()

The Pearson residual of every cell.

(observed - expected) / sqrt(expected), with the expected counts taken from the margins the same way assocplot() takes them.

Usage

BaseRAssocplotLayerProcessor$pearson_residuals(table)

Arguments

Returns

A numeric matrix of the same shape

BaseRAssocplotLayerProcessor$recorded_table()

The two-way table the call was handed, when it is one.

Only a two-dimensional table is read. assocplot() itself accepts no more – it stops on anything else – so this declines the same inputs the function does.

Usage

BaseRAssocplotLayerProcessor$recorded_table(layer_info)

Arguments

Returns

A 2-D table, or NULL

BaseRAssocplotLayerProcessor$extract_axis_titles()

Name the axes from the table's own dimension names.

assocplot() labels its axes with names(dimnames(x)) unless the author overrides them, so those are the words a reader should be given. z names what the numbers are rather than a dimension of the table: the grid holds residuals, and a reader told "Eye" for the value would be told a level name where a number is.

Usage

BaseRAssocplotLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRAssocplotLayerProcessor$extract_main_title()

The title the call was given, if any.

Usage

BaseRAssocplotLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character scalar, empty when the author wrote no title

BaseRAssocplotLayerProcessor$generate_selectors()

Address the tiles the chart drew.

assocplot() draws every cell into ONE rect grob – measured, a 4x4 table gives graphics-plot-N-rect-1 holding sixteen rects – so the cells need no picking out of the drawing the way a gantt's bars do.

Usage

BaseRAssocplotLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  extracted_data = NULL
)

Arguments

Returns

List of selectors, one per cell

BaseRAssocplotLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRAssocplotLayerProcessor$clone(deep = FALSE)

Arguments

Base R Bar Plot Layer Processor

Description

Processes Base R bar plot layers based on recorded plot calls

Super class

LayerProcessor -> BaseRBarplotLayerProcessor

Methods

Public methods

• BaseRBarplotLayerProcessor$process()

• BaseRBarplotLayerProcessor$is_horizontal()

• BaseRBarplotLayerProcessor$needs_reordering()

• BaseRBarplotLayerProcessor$extract_data()

• BaseRBarplotLayerProcessor$extract_axis_titles()

• BaseRBarplotLayerProcessor$extract_main_title()

• BaseRBarplotLayerProcessor$generate_selectors()

• BaseRBarplotLayerProcessor$find_rect_grobs()

• BaseRBarplotLayerProcessor$generate_selectors_from_grob()

• BaseRBarplotLayerProcessor$clone()

BaseRBarplotLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRBarplotLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRBarplotLayerProcessor$is_horizontal()

Check whether this barplot call used horiz = TRUE

Usage

BaseRBarplotLayerProcessor$is_horizontal(layer_info)

Arguments

Returns

Logical

BaseRBarplotLayerProcessor$needs_reordering()

Whether the plot data must be reordered before drawing; a Base R layer is read from the recorded call and never is

Usage

BaseRBarplotLayerProcessor$needs_reordering()

Returns

FALSE

BaseRBarplotLayerProcessor$extract_data()

One point per bar, read from the recorded height

Usage

BaseRBarplotLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of points

BaseRBarplotLayerProcessor$extract_axis_titles()

Extract the axis titles for this layer

barplot() writes no title of its own, so an author who wrote none leaves both axes nameless. A bar chart always plots categories against their measured heights, whether or not the heights arrived named, so that is what the defaults say. horiz = TRUE puts the heights on the visual x axis – the same swap extract_data() applies to the points.

Usage

BaseRBarplotLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRBarplotLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRBarplotLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRBarplotLayerProcessor$generate_selectors()

Generate the CSS selectors that address this layer's drawn elements

Usage

BaseRBarplotLayerProcessor$generate_selectors(layer_info, gt = NULL)

Arguments

Returns

List of selectors

BaseRBarplotLayerProcessor$find_rect_grobs()

Recursively find rect grobs in the grob tree (like ggplot2 does)

Usage

BaseRBarplotLayerProcessor$find_rect_grobs(grob, call_index)

Arguments

Returns

Character vector of grob names

BaseRBarplotLayerProcessor$generate_selectors_from_grob()

Generate selectors from grob tree (like ggplot2 does)

Usage

BaseRBarplotLayerProcessor$generate_selectors_from_grob(grob, call_index)

Arguments

Returns

List of selectors

BaseRBarplotLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRBarplotLayerProcessor$clone(deep = FALSE)

Arguments

Base R Biplot Processor

Description

Reads biplot() as the two things it draws: the observations in principal component space, and the variables' loadings on the same components.

It is a grid, and for a reason the other grids do not have. pairs(), lag.plot() and termplot() are read as grids because they draw several panels. A biplot draws its two halves on top of each other – but on two different pairs of axes, which is the whole trick of the chart. Measured, the two plot.xy calls run over different ranges, and the quantities behind them are different sizes again:

scores   PC1 range  -1.716 ..  2.199
loadings PC1 range  -0.962 .. -0.012

Announcing both against one axis pair would misstate every loading. So the two are given a cell each – one row, two columns – which is the only way the existing grammar can say "these have separate scales" without inventing a second axis on one layer.

It draws no points at all. Both plot.xy calls are type = "n"; every mark on the page is a label or an arrow. Measured on the export of a ten-observation, four-variable fit:

graphics-plot-1-text-1     10 children   the observations
graphics-plot-2-text-1      4 children   the variables
graphics-plot-2-arrows-1    4 children   the arrows

Both text grobs are addressable per datum, in data order, which is the shape lag.plot()'s labelled panels already established – one g per label rather than one use per symbol. The arrows are not emitted separately: an arrow and its label name the same variable and sit at the same place, so the label is the mark a reader is moved to.

The values are the caller's, not the drawing's. biplot() apportions the two halves between the axes so that both fit one page – it divides the scores by sdev * sqrt(n) and multiplies the loadings by it, so neither set is drawn at its own scale. What a reader wants is the pair that mean something: the scores, an observation's coordinate in component space, and the loadings, a variable's weight on each component. Those are announced. This is the same choice stars() makes, where the radii on the page are shares of a column's range and the reading hands over the readings instead.

Super classes

LayerProcessor -> BaseRPointLayerProcessor -> BaseRBiplotLayerProcessor

Methods

Public methods

• BaseRBiplotLayerProcessor$process()

• BaseRBiplotLayerProcessor$clone()

BaseRBiplotLayerProcessor$process()

Emit the observations and the variables, a cell each

Usage

BaseRBiplotLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

A multi-panel result, or NULL when nothing was read

BaseRBiplotLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRBiplotLayerProcessor$clone(deep = FALSE)

Arguments

Base R Boxplot Layer Processor

Description

Processes Base R boxplot layers by extracting statistical summaries and generating selectors for boxplot components.

Super class

LayerProcessor -> BaseRBoxplotLayerProcessor

Methods

Public methods

• BaseRBoxplotLayerProcessor$process()

• BaseRBoxplotLayerProcessor$read_stats()

• BaseRBoxplotLayerProcessor$extract_data()

• BaseRBoxplotLayerProcessor$generate_selectors()

• BaseRBoxplotLayerProcessor$extract_axis_titles()

• BaseRBoxplotLayerProcessor$extract_formula_labels()

• BaseRBoxplotLayerProcessor$extract_main_title()

• BaseRBoxplotLayerProcessor$determine_orientation()

• BaseRBoxplotLayerProcessor$clone()

BaseRBoxplotLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRBoxplotLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRBoxplotLayerProcessor$read_stats()

The five-number summaries the drawn boxes came from

A boxplot() call carries the observations, so the summaries have to be recomputed from them – which boxplot(plot = FALSE) does, using the same code path the drawing did, rather than a reimplementation of it here. graphics::boxplot is named directly so the replay does not go back through maidr's own wrapper and record a second call.

Overridable because bxp() is handed the summaries already computed and draws exactly the same marks from them: everything below this method – the outlier grouping, the polygon and segment indices, the shift each box with no outliers puts on the ones after it – is the same reading either way, and only where the summaries come from differs (#262).

Usage

BaseRBoxplotLayerProcessor$read_stats(args)

Arguments

Returns

The boxplot.stats-shaped list, or NULL when it cannot be had

BaseRBoxplotLayerProcessor$extract_data()

One five-number summary per group, recomputed from the recorded observations

Usage

BaseRBoxplotLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of box summaries

BaseRBoxplotLayerProcessor$generate_selectors()

Selectors for each box's polygon, whiskers, median and outliers

Usage

BaseRBoxplotLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  extracted_data = NULL
)

Arguments

Returns

List of selectors

BaseRBoxplotLayerProcessor$extract_axis_titles()

Extract the axis titles for this layer

boxplot() records no title unless the author wrote one, but the formula method derives both from the formula itself and draws them, so a y ~ g call already names its axes: the response on the value axis and the grouping terms on the category axis. Everything else falls back to what a box plot always shows – groups against their distributions. horizontal = TRUE swaps which visual axis is which, exactly as boxplot.formula()'s own defaults do.

Usage

BaseRBoxplotLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRBoxplotLayerProcessor$extract_formula_labels()

Read the axis titles boxplot.formula() derives from its formula

boxplot.formula() builds them out of the model frame's column names: the response column names the value axis and the remaining columns, joined with " : ", name the category axis. Building the same model frame reproduces the drawn titles for expressions (log(mpg) ~ cyl) and for . alike, where deparsing the formula's terms would not.

Usage

BaseRBoxplotLayerProcessor$extract_formula_labels(args, frame = NULL)

Arguments

Returns

List with response and groups, or NULL when this call is not the formula method or the model frame cannot be rebuilt

BaseRBoxplotLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRBoxplotLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRBoxplotLayerProcessor$determine_orientation()

Which way the boxes were drawn, from the recorded horizontal flag

Usage

BaseRBoxplotLayerProcessor$determine_orientation(layer_info)

Arguments

Returns

"horz" or "vert"

BaseRBoxplotLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRBoxplotLayerProcessor$clone(deep = FALSE)

Arguments

Base R bxp() Layer Processor

Description

Reads a graphics::bxp() call as the box plot it draws.

bxp() is the drawing half of boxplot(): boxplot.default() computes the five-number summaries and then hands them to bxp(), which puts the boxes, whiskers, medians and outliers on the page. Calling it directly is how a caller draws boxes from summaries they already have – from boxplot(plot = FALSE), from boxplot.stats(), or computed elsewhere entirely – and it is one of the twelve calls #262 found drawing while the save reported no plot at all.

What is the same, and what is not

The marks are identical. Drawn off-screen and echoed through gridGraphics, bxp(z) and the boxplot() call that produced z emit the same grob names in the same order – polygon-1, segments-1, points-1, ... – because the same code drew them. Every selector BaseRBoxplotLayerProcessor builds, including the index shift each box with no outliers puts on the boxes after it, therefore addresses a bxp() chart unchanged, and this class inherits all of it.

The one difference is where the summaries come from. boxplot() is handed observations, so its processor replays boxplot(plot = FALSE) to recover them; bxp() is handed the summaries themselves, in its first argument. Replaying boxplot() on that would read the six-element list as six groups of numbers and summarise them – so the only thing this class overrides is read_stats().

Two things bxp() shares with boxplot() are shared including their limits: horizontal = TRUE means the same thing to both, and ⁠at =⁠ repositions boxes without reordering the drawing in either, so a non-monotonic at reads in drawing order here exactly as it already does for boxplot().

Super classes

LayerProcessor -> BaseRBoxplotLayerProcessor -> BaseRBxpLayerProcessor

Methods

Public methods

• BaseRBxpLayerProcessor$read_stats()

• BaseRBxpLayerProcessor$clone()

BaseRBxpLayerProcessor$read_stats()

The summaries bxp() was handed

bxp()'s first formal is z, and it draws nothing without a numeric z$stats with five rows – so a recorded call that reached this package has one. It is still checked rather than assumed: a shape that does not answer leaves the layer empty and the figure falls back to the picture it already was, where reaching past it would raise out of process() with nothing to catch it.

The positional half looks for the first unnamed argument rather than for slot 1. match_recorded_args() keeps the author's order and leaves only the dispatch argument unnamed, wherever it was written, so bxp(horizontal = TRUE, z) records z in slot 2 – a call R itself accepts and draws. Reading slot 1 there hands TRUE to the check below and leaves the layer empty. resolve_xy_args() resolves a positional argument the same way, for the same reason. Raised in review of #265.

Usage

BaseRBxpLayerProcessor$read_stats(args)

Arguments

Returns

The boxplot.stats-shaped list, or NULL when it is not one

BaseRBxpLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRBxpLayerProcessor$clone(deep = FALSE)

Arguments

Base R Candlestick Layer Processor

Description

Processes Base R candlestick chart layers produced by quantmod::chartSeries(x, type = "candlesticks").

Each xts row becomes a single navigable CandlestickPoint with value, open, high, low, close, computed trend (Bull / Bear / Neutral), volatility (high - low) and optional volume (when quantmod::has.Vo() is TRUE).

Selectors are derived from the gridSVG export of the chartSeries grob (captured via ggplotify::as.grob()). chartSeries draws candle bodies via a single vectorized rect() call (each candle body is one SVG ⁠<rect>⁠ child of ⁠graphics-plot-<N>-rect-*⁠) and upper/lower wicks via segments() calls (one SVG ⁠<polyline>⁠ per wick under ⁠graphics-plot-<N>-segments-*⁠).

Super class

LayerProcessor -> BaseRCandlestickLayerProcessor

Methods

Public methods

• BaseRCandlestickLayerProcessor$process()

• BaseRCandlestickLayerProcessor$has_add_vo()

• BaseRCandlestickLayerProcessor$build_volume_layer()

• BaseRCandlestickLayerProcessor$generate_volume_selectors()

• BaseRCandlestickLayerProcessor$extract_data()

• BaseRCandlestickLayerProcessor$generate_selectors()

• BaseRCandlestickLayerProcessor$extract_axis_titles()

• BaseRCandlestickLayerProcessor$extract_main_title()

• BaseRCandlestickLayerProcessor$format_x_values()

• BaseRCandlestickLayerProcessor$collect_grob_names()

• BaseRCandlestickLayerProcessor$sort_ids()

• BaseRCandlestickLayerProcessor$find_grob_by_name()

• BaseRCandlestickLayerProcessor$grob_coord_count()

• BaseRCandlestickLayerProcessor$pick_largest_child_group()

• BaseRCandlestickLayerProcessor$clone()

BaseRCandlestickLayerProcessor$process()

Process the layer: the candlestick layer, plus a volume bar layer when addVo() was requested

Usage

BaseRCandlestickLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  layer_info = NULL
)

Arguments

Returns

A candlestick layer, or a multi-layer list with the volume bars

BaseRCandlestickLayerProcessor$has_add_vo()

Detect whether the chartSeries call draws the addVo() volume panel, which it does by default

Usage

BaseRCandlestickLayerProcessor$has_add_vo(layer_info)

Arguments

Returns

Logical

BaseRCandlestickLayerProcessor$build_volume_layer()

Build a "bar" layer carrying volume data

Usage

BaseRCandlestickLayerProcessor$build_volume_layer(layer_info, gt, candle_data)

Arguments

BaseRCandlestickLayerProcessor$generate_volume_selectors()

Generate selectors for the addVo() volume bar panel

chartSeries(TA = "addVo()") creates a second plotting window. In the gridSVG export that maps to a second ⁠graphics-plot-<N>⁠ group (typically N = 2). Returns a per-bar selector list so each volume bar can be individually highlighted on navigation; matches the bar layer contract used by the Base R barplot processor.

Usage

BaseRCandlestickLayerProcessor$generate_volume_selectors(
  layer_info,
  gt,
  n_bars
)

Arguments

Returns

List of selectors, one per volume bar

BaseRCandlestickLayerProcessor$extract_data()

Extract OHLC data points from the chartSeries call

Usage

BaseRCandlestickLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of CandlestickPoint dicts

BaseRCandlestickLayerProcessor$generate_selectors()

Generate CSS selectors for the candlestick layer

Returns ONE CandlestickSelector object (matching the maidr JS frontend contract in src/model/candlestick.ts::mapToSvgElements). The returned object has these named character-vector keys:

• body length-N vector, one per-candle body-rect selector

• wickHigh length-N vector, one per-candle upper-wick selector (omitted if only one segments group is present)

• wickLow length-N vector, one per-candle lower-wick selector (omitted if only one segments group is present)

• wick length-N vector, used as fallback when there is only one segments group (the frontend falls back to wick when wickHigh / wickLow are absent).

gridSVG emits a child id ⁠<group-id>.1.<i>⁠ for each primitive in a vectorized draw call. The frontend iterates each string array (collectElements(arr)) and picks the i-th element via ⁠getElementAt(*, i)⁠, so per-candle selectors are required for single-candle highlighting on arrow-key navigation.

IMPORTANT: do NOT return an array of objects (e.g. ⁠[[body, wick], ...]⁠). The frontend's Array.isArray() branch would then take selectors[0] (the first dict) and pass it to querySelectorAll, yielding a JS ⁠SyntaxError: '[object Object]' is not a valid selector⁠. The boxplot pattern of per-item dicts does NOT apply here because each chart model has its own contract.

Usage

BaseRCandlestickLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  extracted_data = NULL
)

Arguments

Returns

Named list (single CandlestickSelector) or list() when grobs cannot be located.

BaseRCandlestickLayerProcessor$extract_axis_titles()

The axis titles, defaulting to Date and Price

Usage

BaseRCandlestickLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRCandlestickLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRCandlestickLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRCandlestickLayerProcessor$format_x_values()

Format a vector of x-axis index values to character

Usage

BaseRCandlestickLayerProcessor$format_x_values(idx)

Arguments

Returns

Character vector

BaseRCandlestickLayerProcessor$collect_grob_names()

Recursively collect all grob names in a grob tree

Usage

BaseRCandlestickLayerProcessor$collect_grob_names(g)

Arguments

Returns

Character vector of grob names

BaseRCandlestickLayerProcessor$sort_ids()

Sort grob ids by trailing integer suffix

Usage

BaseRCandlestickLayerProcessor$sort_ids(ids)

Arguments

Returns

The ids in numeric order of their suffix

BaseRCandlestickLayerProcessor$find_grob_by_name()

Find the grob node whose name matches id

Usage

BaseRCandlestickLayerProcessor$find_grob_by_name(g, id)

Arguments

Returns

The grob, or NULL when no name matches

BaseRCandlestickLayerProcessor$grob_coord_count()

Count the number of primitive coordinates a grob carries

Usage

BaseRCandlestickLayerProcessor$grob_coord_count(g)

Arguments

Returns

Integer

BaseRCandlestickLayerProcessor$pick_largest_child_group()

Pick the rect-id whose grob has the most coordinates

Usage

BaseRCandlestickLayerProcessor$pick_largest_child_group(gt, ids)

Arguments

BaseRCandlestickLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRCandlestickLayerProcessor$clone(deep = FALSE)

Arguments

Base R Conditional Density Plot Layer Processor

Description

Reads cdplot() as the 100% stacked area chart it draws.

A conditional density plot shows, for each value of a numeric x, how the levels of a factor y divide up: the bands are stacked, they fill the whole height, and their shares sum to 1 at every x. That is a normalized stacked area, which Ggplot2AreaLayerProcessor already emits for position = "fill", so a cdplot() is read as stacked_normalized_area and the two adapters describe one chart the same way – each series a list of ⁠{x, y, z}⁠ where y is the band's own share and z names the level, and one selector per band.

Before this, cdplot() had no branch in detect_layer_type(), so the switch fell through to "unknown" and the chart degraded to a static image (#216, #251).

Where the curves come from

cdplot() has a plot argument, so it can be asked for what it drew without drawing it again. It returns the boundaries between the bands: nlevels(y) - 1 functions, each approxfun() over the density grid, named for the level below the boundary.

rval <- cdplot(x, y, plot = FALSE)
names(rval)          # "c" "b"   for a factor with levels a, b, c
rval[[1]](50)        # the cumulative share at x = 50

Stacking them the way cdplot() does – rbind(0, boundaries, 1), band i running from row i to row i + 1 – gives the shares back. Measured over three hundred random charts, every column's shares sum to 1 and no band comes out negative, so the boundaries do not cross in the drawn range.

graphics::cdplot by the qualified name, not the bare one: maidr patches the name on the search path, and a bare call would record the replay as a second chart. The same line BaseRSpineplotLayerProcessor draws.

Which x values were drawn

The returned functions interpolate over the density grid, which stats::density() pads past the data by three bandwidths. cdplot() throws that padding away before drawing:

y1 <- y1[, which(x1 >= min(x) & x1 <= max(x))]
x1 <- x1[x1 >= min(x) & x1 <= max(x)]

so the announced grid is trimmed the same way – 372 of the 512 points on a measured chart. Announcing the untrimmed grid would put readings either side of the data at x values the chart has no marks at.

The grid itself is read off the first returned function rather than recomputed: approxfun() keeps its knots, and environment(f)$x is the grid cdplot() built. Recomputing density() here would have to guess bw, n, from, to and weights back out of the recorded call, and a guess that differed by one point would shift every reading.

What the replay proves

A cdplot() that returned rather than stopping has already established most of what a reader here would otherwise have to check, because cdplot() checks it first and stops. Each was measured:

• y is a factor – "dependent variable should be a factor";

• x is finite – stats::density() stops on a missing or infinite value;

• a formula names exactly two variables – "'formula' should specify exactly two variables";

• the grid overlaps the data – a from/to that put it elsewhere stops with "need at least two non-NA values to interpolate";

• the factor has at least two levels – one stops with "subscript out of bounds".

The NULL checks that remain below are therefore not checking any of that. They are there so that a shape none of the above rules out cannot throw out of the pipeline, where declining to read leaves the static image the figure produces today. Where a check would only repeat one another check already makes, it is not written twice.

Super class

LayerProcessor -> BaseRCdplotLayerProcessor

Methods

Public methods

• BaseRCdplotLayerProcessor$process()

• BaseRCdplotLayerProcessor$extract_data()

• BaseRCdplotLayerProcessor$drawn_bands()

• BaseRCdplotLayerProcessor$replay()

• BaseRCdplotLayerProcessor$drawn_grid()

• BaseRCdplotLayerProcessor$band_levels()

• BaseRCdplotLayerProcessor$predictor()

• BaseRCdplotLayerProcessor$response()

• BaseRCdplotLayerProcessor$variables()

• BaseRCdplotLayerProcessor$default_variables()

• BaseRCdplotLayerProcessor$formula_variables()

• BaseRCdplotLayerProcessor$extract_axis_titles()

• BaseRCdplotLayerProcessor$extract_main_title()

• BaseRCdplotLayerProcessor$generate_selectors()

• BaseRCdplotLayerProcessor$clone()

BaseRCdplotLayerProcessor$process()

Build the layer

Usage

BaseRCdplotLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRCdplotLayerProcessor$extract_data()

One series per band, bottom to top

Bottom to top because that is the order cdplot() draws its polygons in, and the selector list is positional against those polygons.

Usage

BaseRCdplotLayerProcessor$extract_data(layer_info)

Arguments

Returns

A list of series, each a list of ⁠{x, y, z}⁠ points

BaseRCdplotLayerProcessor$drawn_bands()

The grid, the band names and their shares, or NULL

NULL rather than an empty list when the call cannot be read, so every caller degrades the same way: no data, no selectors, and the figure falls back to the static image it produces today.

Usage

BaseRCdplotLayerProcessor$drawn_bands(layer_info)

Arguments

Returns

A list of x, levels and shares (a bands-by-points matrix), or NULL

BaseRCdplotLayerProcessor$replay()

Ask cdplot() what it drew, without drawing it

Usage

BaseRCdplotLayerProcessor$replay(args)

Arguments

Returns

The list of boundary functions, or NULL

BaseRCdplotLayerProcessor$drawn_grid()

The x values the bands were drawn over

Usage

BaseRCdplotLayerProcessor$drawn_grid(boundaries, args)

Arguments

Returns

A numeric vector, or NULL

BaseRCdplotLayerProcessor$band_levels()

The band names, bottom to top

cdplot() names its boundaries for every level but the topmost, so the one it does not name is the one level of the response that is left. Derived that way rather than by reproducing the ylevels argument's reordering, which is cdplot()'s to define.

Declines unless exactly one level is left over. That is the one guard the step needs, and it does double duty: an ylevels naming a strict subset of the factor's levels leaves two over – measured, ylevels = c("a", "b") on a three-level factor – and unnamed boundaries would leave every level over. Either way the reading would be missing a band, and every selector after it would point at its neighbour.

An empty level name is not declined. factor(x, levels = c("b", "")) is a level like any other, setdiff() matches it like any other, and the chart draws a band for it – so it is announced with the empty name the axis shows rather than dropped.

Usage

BaseRCdplotLayerProcessor$band_levels(boundaries, args)

Arguments

Returns

A character vector, or NULL

BaseRCdplotLayerProcessor$predictor()

The numeric variable on the x axis

Usage

BaseRCdplotLayerProcessor$predictor(args)

Arguments

Returns

A numeric vector, or NULL

BaseRCdplotLayerProcessor$response()

The factor whose levels the bands are

Usage

BaseRCdplotLayerProcessor$response(args)

Arguments

Returns

A factor, or NULL

BaseRCdplotLayerProcessor$variables()

The two variables the call was given, whichever form it took

cdplot() has two methods and they name their variables differently: cdplot(x, y) and cdplot(y ~ x, data). The formula method builds a model frame and takes the response from column one and the predictor from column two, which is reproduced here because the recorded call carries the formula rather than the frame.

Memoised. process() reaches this three times – through response(), through predictor() and again for the axis names – and on the formula path each ask would rebuild a model frame and re-apply the subset. The same call BaseRSpineplotLayerProcessor makes about its replayed table, for the same reason. Nothing observable changes, which is why this is written down rather than left to be rediscovered.

Usage

BaseRCdplotLayerProcessor$variables(args)

Arguments

Returns

A list of x, y and names, or NULL

BaseRCdplotLayerProcessor$default_variables()

The variables of a cdplot(x, y) call

Usage

BaseRCdplotLayerProcessor$default_variables(args)

Arguments

Returns

A list of x, y and names, or NULL

BaseRCdplotLayerProcessor$formula_variables()

The variables of a cdplot(y ~ x, data) call

subset is carried through, because cdplot.formula builds its model frame with it and everything downstream is the subset's: measured on cdplot(b ~ a, data = d, subset = a > 45), the chart draws over 46.1 to 70.9 while the whole column runs from 25.5. Read without the subset, the grid would be trimmed to the wider range and a fifth of the announced points would sit left of the leftmost mark.

Usage

BaseRCdplotLayerProcessor$formula_variables(formula, data, subset = NULL)

Arguments

Returns

A list of x, y and names, or NULL

BaseRCdplotLayerProcessor$extract_axis_titles()

Name the axes

The band's number is a share of the column, not a position on the drawn y axis – which carries the level names, and is the fill dimension shown positionally. So ylab names z and y says what its numbers are, the same split BaseRMosaicLayerProcessor makes for the same reason.

Usage

BaseRCdplotLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

An axes payload

BaseRCdplotLayerProcessor$extract_main_title()

The chart's own title, where the call gave one

Usage

BaseRCdplotLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

The title, or an empty string

BaseRCdplotLayerProcessor$generate_selectors()

Address each band by the polygon that drew it

cdplot() writes one polygon grob per band, in draw order, which is the bottom-to-top order the series are in. The frame it draws around the plot is a polygon too, but gridGraphics names it -box-1 rather than -polygon-N, so the anchored pattern does not collect it.

Withheld entirely when the counts disagree, for the reason every processor here gives: a partial list hands a band its neighbour's element, and a user cannot tell that apart from a correct one.

Usage

BaseRCdplotLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  n_series = 0L
)

Arguments

Returns

A list of CSS selectors, one per band

BaseRCdplotLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRCdplotLayerProcessor$clone(deep = FALSE)

Arguments

Base R Contour Layer Processor

Description

Reads a base R contour() call as the contour it draws.

contour() had no processor. base_r_adapter mapped the call to the type "contour" and the factory fell through to the generic processor, so the layer shipped typed "unknown" – and the core's trace factory ends its dispatch with ⁠throw new Error("Invalid trace type: …")⁠, so the figure bound interactively and then failed to construct. #214 stopped that by typing the call "unknown" at the adapter, which degrades to a static image; this replaces the picture with the reading (#218).

The curves come from grDevices::contourLines(), which is the same computation contour() does and takes the same defaults, so nothing here is a guess about what was drawn:

contour.default(x = seq(0, 1, length.out = nrow(z)),
                y = seq(0, 1, length.out = ncol(z)),
                z, nlevels = 10, levels = pretty(zlim, nlevels),
                zlim = range(z, finite = TRUE))

The payload matches ggplot2_contour_layer_processor.R exactly – a list of curves, each a list of ⁠{x, y, level}⁠ – so the two adapters describe one chart the same way.

Super class

LayerProcessor -> BaseRContourLayerProcessor

Methods

Public methods

• BaseRContourLayerProcessor$process()

• BaseRContourLayerProcessor$read_curves()

• BaseRContourLayerProcessor$extract_data()

• BaseRContourLayerProcessor$contour_grid()

• BaseRContourLayerProcessor$default_nlevels()

• BaseRContourLayerProcessor$extract_axis_titles()

• BaseRContourLayerProcessor$extract_main_title()

• BaseRContourLayerProcessor$generate_selectors()

• BaseRContourLayerProcessor$find_contour_grobs()

• BaseRContourLayerProcessor$clone()

BaseRContourLayerProcessor$process()

Build the layer

Usage

BaseRContourLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRContourLayerProcessor$read_curves()

Read the drawn curves off the recorded call

Hands back which curves were kept as well as the curves themselves. gridGraphics draws from the same contourLines() output, so it writes one grob per curve before any filtering here – and comparing a filtered count against an unfiltered one would make the two disagree, which generate_selectors answers by withholding the whole layer's highlighting. Keeping the indices lets each announced curve take the grob that drew it, whatever was dropped.

Usage

BaseRContourLayerProcessor$read_curves(layer_info)

Arguments

Returns

data (curves of ⁠{x, y, level}⁠), kept (their indices among what contourLines() returned) and total (how many that was)

BaseRContourLayerProcessor$extract_data()

The curves alone, for callers that want only the payload

Usage

BaseRContourLayerProcessor$extract_data(layer_info)

Arguments

Returns

A list of curves, each a list of ⁠{x, y, level}⁠ points

BaseRContourLayerProcessor$contour_grid()

The grid and levels the call drew, or NULL when it drew none

Resolved the way contour.default resolves it, rather than by a rule of our own. Its arguments are ⁠(x, y, z, ...)⁠; a named argument claims its slot and the unnamed ones fill what is left, in order. Then, and only then:

  if (missing(z) && !missing(x) && !is.list(x)) { z <- x; x <- NULL }
  

which is what makes contour(m) a contour of m rather than a chart with m on the x axis.

Reproducing that matters because the wrapper records a partially named call: measured, contour(c(10, 20, 30), c(100, 200, 300), z) arrives as one unnamed argument plus ⁠y =⁠ and ⁠z =⁠. A rule that looked for the matrix and took the unnamed arguments before it found z already named, never looked at the unnamed one, and announced the caller's grid on the 0-1 default – every coordinate wrong, and nothing raised.

Usage

BaseRContourLayerProcessor$contour_grid(args)

Arguments

Returns

A list of x, y, z and levels, or NULL

BaseRContourLayerProcessor$default_nlevels()

How many levels the drawing function defaults to

contour.default defaults to 10 and filled.contour to 20, and the number decides the whole announced set: pretty(zlim, nlevels). The two are otherwise resolved identically, so the difference lives here rather than in a second copy of contour_grid().

Usage

BaseRContourLayerProcessor$default_nlevels()

Returns

The default nlevels for this call

BaseRContourLayerProcessor$extract_axis_titles()

Name the two axes

Only x and y. The level is not an axis here: it travels on every point of the curve it belongs to, which is where the frontend's contour trace reads it from – the same choice ggplot2_contour_layer_processor makes, so the two adapters describe one chart alike.

No default label. contour() prints the deparsed argument when the caller names nothing, and those names are gone by the time the wrapper has recorded evaluated values – so a guessed noun would be worse than none, and the axis is left to the renderer's generic.

Usage

BaseRContourLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

An axes payload

BaseRContourLayerProcessor$extract_main_title()

The chart's own title, where the call gave one

Usage

BaseRContourLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

The title, or an empty string

BaseRContourLayerProcessor$generate_selectors()

Address each curve by the element that drew it

gridGraphics writes one lines grob per curve, named ⁠graphics-plot-<group>-contour-<i>-<i>⁠, in the order contourLines() returns them – checked vertex count by vertex count, not assumed. A lines grob renders as a ⁠<polyline>⁠.

Withheld entirely when the count does not match what was announced. The frontend drops a layer whose selector list disagrees with its series count, and a partial list would hand a curve its neighbour's element – the defect #145 and #204 are both about.

Usage

BaseRContourLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  kept = integer(0),
  total = 0
)

Arguments

Returns

A list of CSS selectors, one per announced curve

BaseRContourLayerProcessor$find_contour_grobs()

Every contour grob this layer drew

Usage

BaseRContourLayerProcessor$find_contour_grobs(grob, group_index)

Arguments

Returns

A character vector of grob names

BaseRContourLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRContourLayerProcessor$clone(deep = FALSE)

Arguments

Base R Correlogram Layer Processor

Description

Processes the three correlogram entry points – acf(), pacf() and ccf(). Each draws one vertical spike per lag, from the zero line to the correlation at that lag, and joins nothing to anything.

Read as a lollipop layer, for the reason BaseRSpikeLayerProcessor gives: a line would say the samples are joined and that the space between two lags can be interpolated, which is the one relationship a correlogram is drawn to deny. The spikes even export under the same grob name – measured, plot(acf(v)) names them graphics-plot-1-spike-1 – so the inherited selector search needs no override.

What this adds is where the numbers come from. The recorded call holds the series, not the correlogram: measured, acf(v, lag.max = 5) records one HIGH call whose args are the 60 observations and lag.max. So the reading replays the call with plot = FALSE and takes ⁠$lag⁠ and ⁠$acf⁠ off the result, which is the same shape BaseRSpineplotLayerProcessor takes for a table it cannot read off the drawing either.

All three differ in what the lags are, and the replay answers that too rather than the reading assuming it. Measured on one 60-point series:

acf(v,  lag.max = 5)   lags  0  1  2  3  4  5
pacf(v, lag.max = 5)   lags     1  2  3  4  5
ccf(v, w, lag.max = 3) lags -3 -2 -1  0  1  2  3

acf starts at lag 0, whose correlation is 1 by construction and which the chart draws; pacf has no lag 0 at all; and a cross-correlation's lags are signed, because "x leads y" and "y leads x" are different statements. Announcing any of the three as another would misname every spike on the chart.

Super classes

LayerProcessor -> BaseRLineLayerProcessor -> BaseRSpikeLayerProcessor -> BaseRCorrelogramLayerProcessor

Methods

Public methods

• BaseRCorrelogramLayerProcessor$process()

• BaseRCorrelogramLayerProcessor$extract_data()

• BaseRCorrelogramLayerProcessor$extract_axis_titles()

• BaseRCorrelogramLayerProcessor$extract_main_title()

• BaseRCorrelogramLayerProcessor$clone()

BaseRCorrelogramLayerProcessor$process()

Process the correlogram layer.

Usage

BaseRCorrelogramLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRCorrelogramLayerProcessor$extract_data()

Read one point per lag the correlogram draws.

The lag on the category axis and the correlation as the magnitude, in the order they are drawn – which for ccf runs from the most negative lag rightwards, so the announced order is the drawn one.

Usage

BaseRCorrelogramLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of x/y points, empty when the replay states nothing

BaseRCorrelogramLayerProcessor$extract_axis_titles()

Name the lag axis and the quantity drawn against it.

A correlogram writes its own axis labels, so there is nothing the caller titled to read – and the inherited X/Y fallback would name a lag after a coordinate. The value axis follows what the replay says it computed: acf(type = "covariance") draws covariances, not correlations, and calling them correlations would announce a normalisation the chart never applied.

Usage

BaseRCorrelogramLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Named list with x and y

BaseRCorrelogramLayerProcessor$extract_main_title()

Title the chart the way the drawing does.

plot.acf() writes "Series v" above an acf and "v & w" above a ccf, and the replayed object carries those as ⁠$series⁠ and ⁠$snames⁠ – but not usefully. Both are deparse(substitute(x)), and the replay hands stats the recorded values rather than the name the caller wrote, so measured they come back as the whole series pasted in: ⁠Series c(-2.0715334064552, -0.117989125730012, ...)⁠. That is worse than no title at all.

The name is in the recorded call expression instead, which is kept as the source text of the call – measured, "acf(v, lag.max = 3)". It is used only when the argument is a bare symbol: a caller who wrote acf(rnorm(60)) named nothing, and titling the chart with the expression that produced it would announce a call rather than a series.

A caller's own ⁠main =⁠ wins, which is what the inherited reading already answers.

Usage

BaseRCorrelogramLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

The title, or NULL when the caller named nothing

BaseRCorrelogramLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRCorrelogramLayerProcessor$clone(deep = FALSE)

Arguments

Base R Cumulative Periodogram Processor

Description

Reads cpgram() as the staircase it draws: the cumulative periodogram against frequency, held across each interval and then jumping.

It is a step, not a line. cpgram() plots with type = "s", which draws the horizontal segment first – MAIDR's "hv". A line would imply the value slides between frequencies, which is not what a cumulative sum does, and the export agrees: the grob is step-1, not lines-1.

It does NOT use spectrum()'s estimate. This is the trap the reading exists to avoid. spectrum() defaults to ⁠taper = 0.1, detrend = TRUE, demean = FALSE⁠ and smooths; cpgram() computes its own periodogram – taper, FFT, zero the first ordinate, then normalise the cumulative sum – and the two disagree. Measured, the second step of the drawn curve is 0.0801 while spectrum()'s estimate gives 0.0817: close enough to look right and wrong enough to announce wrong numbers. So the computation below is cpgram()'s own, and it reproduces the traced plot.xy call exactly.

Super classes

LayerProcessor -> BaseRLineLayerProcessor -> BaseRCpgramLayerProcessor

Methods

Public methods

• BaseRCpgramLayerProcessor$process()

• BaseRCpgramLayerProcessor$clone()

BaseRCpgramLayerProcessor$process()

Emit the cumulative periodogram as a step

Usage

BaseRCpgramLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

A step layer, or NULL when nothing was read

BaseRCpgramLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRCpgramLayerProcessor$clone(deep = FALSE)

Arguments

Base R Dodged Bar Layer Processor

Description

Processes Base R dodged bar plot layers with proper ordering to match backend logic

Super class

LayerProcessor -> BaseRDodgedBarLayerProcessor

Methods

Public methods

• BaseRDodgedBarLayerProcessor$process()

• BaseRDodgedBarLayerProcessor$extract_data()

• BaseRDodgedBarLayerProcessor$generate_selectors()

• BaseRDodgedBarLayerProcessor$find_rect_grobs()

• BaseRDodgedBarLayerProcessor$generate_selectors_from_grob()

• BaseRDodgedBarLayerProcessor$extract_axis_titles()

• BaseRDodgedBarLayerProcessor$extract_main_title()

• BaseRDodgedBarLayerProcessor$clone()

BaseRDodgedBarLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRDodgedBarLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRDodgedBarLayerProcessor$extract_data()

One series per row of the recorded height matrix

Usage

BaseRDodgedBarLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of series

BaseRDodgedBarLayerProcessor$generate_selectors()

The selector for the bars, scoped to this layer's plot group

Usage

BaseRDodgedBarLayerProcessor$generate_selectors(layer_info, gt = NULL)

Arguments

Returns

List of selectors

BaseRDodgedBarLayerProcessor$find_rect_grobs()

Find the rect grobs drawn by the recorded call at call_index

Usage

BaseRDodgedBarLayerProcessor$find_rect_grobs(grob, call_index)

Arguments

Returns

Character vector of grob names

BaseRDodgedBarLayerProcessor$generate_selectors_from_grob()

Build this layer's selector from the grob tree

Usage

BaseRDodgedBarLayerProcessor$generate_selectors_from_grob(grob, call_index)

Arguments

Returns

A selector string, or an empty string when no grob matches

BaseRDodgedBarLayerProcessor$extract_axis_titles()

Extract the axis titles for this layer

Same shape as the stacked processor: barplot(beside = TRUE) writes no title, its points carry the column category on x and the bar height on y, and the group each bar belongs to travels with the point as z rather than as a named axis.

Usage

BaseRDodgedBarLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRDodgedBarLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRDodgedBarLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRDodgedBarLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRDodgedBarLayerProcessor$clone(deep = FALSE)

Arguments

Base R Dot Chart Layer Processor

Description

Processes Base R dotchart() layers – a Cleveland dot plot: one value per category, marked with a dot on a horizontal guide line, with the categories running down the page.

Read as a dot layer, which the core builds on BarTrace: a bar chart's reading with a different mark. The guide lines and the category labels are frame rather than data – gridGraphics draws them as ⁠-abline-h-⁠ and ⁠-mtext-left-⁠, and only the dots carry a value.

orientation is "horz", which is not a detail: dotchart() puts the categories on the vertical axis and the value along the horizontal one, and the core reads a horz layer's magnitude from x and its category from y. Without the key the layer defaults to vertical and reads the category name where the magnitude belongs – no number to pitch, and the announcement inverted (#184, #480).

The dots are emitted in the order dotchart() was handed them, which is bottom-up on the drawn chart – base R puts the first element at the bottom. That is the arrangement barplot(horiz = TRUE) already ships for the same reason, so the two horizontal base R charts read from the same end.

Selectors come from the points grob, which is the one thing a dotchart shares with a scatter: graphics-plot-N-points-1 holds one ⁠<use>⁠ per dot. So this inherits BaseRPointLayerProcessor and replaces what is read out of the call rather than how the marks are addressed.

Super classes

LayerProcessor -> BaseRPointLayerProcessor -> BaseRDotchartLayerProcessor

Methods

Public methods

• BaseRDotchartLayerProcessor$process()

• BaseRDotchartLayerProcessor$extract_data()

• BaseRDotchartLayerProcessor$clone()

BaseRDotchartLayerProcessor$process()

Process the dot chart layer.

Usage

BaseRDotchartLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title, axes and orientation

BaseRDotchartLayerProcessor$extract_data()

Read the dots out of the recorded dotchart() call.

dotchart(x, labels = NULL, ...) names its dots from labels when the caller gives them and from names(x) otherwise, which is what the chart draws down its left margin. A vector with neither is drawn against blank labels, and is emitted here against its positions so a reader still has something to navigate by.

x and y carry the magnitude and the category respectively, which is the arrangement a horz layer means – see the class note.

Usage

BaseRDotchartLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of x/y points, empty when there is nothing to read

BaseRDotchartLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRDotchartLayerProcessor$clone(deep = FALSE)

Arguments

Base R Filled Contour Layer Processor

Description

Reads a base R filled.contour() call as the contour it draws.

filled.contour draws the same level curves contour() does and fills the bands between them, so it is read the same way: one curve per level, from grDevices::contourLines(), which is the computation the drawing itself runs. One chart with two spellings gets one reading.

Two things differ from contour(), and only two:

The level default. contour.default takes nlevels = 10 and filled.contour takes nlevels = 20, and the number decides the whole announced set through pretty(zlim, nlevels). Everything else about resolving the call – the ⁠(x, y, z, ...)⁠ slots, the if (missing(z)) z <- x fallback, the list(x =, y =, z =) unpacking, the zlim default – is identical in both, so this class overrides the number and inherits the rest.

The chart cannot be highlighted, and the inherited code already knows it. contour() writes one lines grob per curve, which is what generate_selectors() pairs against. filled.contour writes one polygon grob for the entire field, and gridSVG exports it as a flat run of pieces. Measured on a 6x5 grid drawn at the 17 default levels:

grobs written    graphics-plot-2-filled-contour-1   (one)
SVG polygons     graphics-plot-2-filled-contour-1.1.1 .. .1.160
curves announced 40

160 pieces against 40 curves, and against 17 levels: the polygons are the grid's cells cut by the level crossings, not the bands and not the curves. Nothing pairs, so nothing is emitted – the inherited generate_selectors() finds no -contour-N-N grob, its count check fails, and it withholds the list, which is the same answer it gives a contour() whose grobs and curves disagree. A layer with no selectors is announced, sonified and navigated; it is the visual highlight alone that is missing, and that is the established degradation here (#89) rather than a reason to ship a picture.

Note also that the field is drawn in the second plot region: the call lays out a colour key as graphics-plot-1 and the field as graphics-plot-2. Nothing here depends on that, because nothing here addresses a grob, but a later attempt to highlight this chart will.

py-maidr declines the equivalent call. Its reason – recorded in maidr/patch/contour.py – is that contourf hands back the filled paths and "an outline of one runs along two different level curves", which is a statement about deriving curves from what was drawn. It does not apply here: R hands over contourLines(), so the curves announced are the level curves themselves rather than an inference from the fill, and every one of them is on the page as the boundary between two bands.

Super classes

LayerProcessor -> BaseRContourLayerProcessor -> BaseRFilledContourLayerProcessor

Methods

Public methods

• BaseRFilledContourLayerProcessor$default_nlevels()

• BaseRFilledContourLayerProcessor$clone()

BaseRFilledContourLayerProcessor$default_nlevels()

How many levels filled.contour() defaults to

Twice contour()'s, and the only number that separates the two.

Usage

BaseRFilledContourLayerProcessor$default_nlevels()

Returns

20

BaseRFilledContourLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRFilledContourLayerProcessor$clone(deep = FALSE)

Arguments

Base R Fourfold Display Layer Processor

Description

Processes Base R fourfoldplot() layers drawn with std = "ind.max" or std = "all.max" – a 2x2 contingency table drawn as four quarter-circles, one per cell, sized so the wedge's AREA is proportional to that cell's count.

Read as a heat layer, for the same reason assocplot() is: the drawing is a 2x2 grid of one number per cell, and row-then-column is how a reader navigates a contingency table. Measured on fourfoldplot(as.table(matrix(c(10, 40, 90, 160), 2)), std = "ind.max"), the radii and the counts they recover:

grob                       r        quadrant      r^2 * max(count)  cell
graphics-plot-1-polygon-1  0.250000 upper LEFT     10               [1, 1]
graphics-plot-1-polygon-2  0.500000 lower LEFT     40               [2, 1]
graphics-plot-1-polygon-3  0.750000 upper RIGHT    90               [1, 2]
graphics-plot-1-polygon-4  1.000000 lower RIGHT   160               [2, 2]

exactly, so radius / sqrt(count) is one constant (0.0790569415 here, with a relative spread of 1.755e-16). The table's FIRST dimension runs vertically and its SECOND horizontally – the transpose of assocplot()'s arrangement, and measured from the label grobs, which put names(dimnames(x))[1] at the top and bottom of the drawing and names(dimnames(x))[2] at the left and right.

Nothing is inferred from the drawing. fourfoldplot() is handed the table, so the recorded call carries every number the trace wants; the grobs are consulted only to decide whether the drawing on the page is the one the recorded call describes.

What this deliberately does not do

It is not a mosaic and it is not a bar. A mosaic's tiles tile a whole and carry proportions of it; these are four independent quarter-discs separated by space (default 0.2) that tile nothing. A bar trace would imply a value axis with a zero baseline and one categorical axis, while measured the radii are on a square-root scale and the quadrants are laid out in two dimensions.

The confidence arcs are dropped. Measured, a conf.level draws 8 unfilled arcs (polygon-5 .. polygon-12), arcs 4 + j and 8 + j being the lower and upper bound of cell c(tab)[j]. A heat layer has nowhere to carry an interval, so a reader is told the counts and not that the chart also draws a band around each. Unlike qqplot's band this does not justify declining: the arcs decorate numbers that ARE fully carried.

The odds ratio is never announced. There is no MAIDR trace for one scalar. Under ind.max/all.max a reader gets four counts and can compute it.

Where the two gates live, and what the second one cannot do

#268 asks that a chart whose geometry disagrees LOSE the reading rather than get a wrong one. That is not achievable here and this does not pretend it is. Verified against BaseRPlotOrchestrator$initialize(), which runs detect_layers(), resolve_fallback_scope(), create_layer_processors() and process_layers() at lines 122-125: the picture-versus-chart decision is frozen by line 123, which reads private$.layers[[i]]$type through unsupported_layer_flags(). That field is written only by the two private$.layers[[layer_counter]] <- list(type = ...) assignments at lines 147 and 169, both from detect_layer_type(), and is never rewritten from a processor result; line 124 does not even build a processor for a layer already typed "unknown" (line 219). A processor that answered type = "unknown" would ship that string with has_unsupported_layers() still FALSE – the #214 failure BaseRProcessorFactory$get_supported_types() records, where the figure binds and then fails to construct.

So the split is:

• the argument gate is fourfold_decline_reason(), called from detect_layer_type(), and it CAN lose the reading;

• the geometry gate is radii_agree() below, and it can only return list() from generate_selectors() – the numbers are still announced and nothing highlights. That is the shipped pie idiom: "a short list means these are not this pie's grobs. Filling the gap with a guessed id would silently highlight another panel's wedges."

What the geometry gate can and cannot see

Measured, and weaker than it looks:

• It is exactly scale-invariant. A drawing of tab * 3, or of tab * 1e6, checked against tab's counts gives a relative deviation of 1.755e-16 and passes. radius / sqrt(count) == 1 / sqrt(max(tab)) is an identity inside stdize(), so no table can falsify it and an upstream change to what ind.max means would go uncaught at runtime. That exposure is carried by the live-drawing assertions in test-base-r-fourfoldplot.R, the same bet the qqplot branch makes.

• It passes for a symmetric table drawn under the default std. Measured, ⁠9, 4, 4, 9⁠ under std = "margins" gives a relative deviation of 0.000e+00, and so does ⁠7, 7, 7, 7⁠; algebraically, with n11 = n22 = a and n12 = n21 = b, ⁠u / a == (1 - u) / b == 1 / (a + b)⁠. It recovers off symmetry fast – ⁠9, 4, 4, 9.0001⁠ gives 2.778e-06 and fails at 1e-8 – but this is why std is the first gate and the geometry only the second.

What it does catch is a grob tree that is not this call's: measured, fourfoldplot(UCBAdmissions, std = "ind.max") draws 78 polygons, and an asymmetric table's margins drawing checked against its own counts gives 7.616e-01.

Super class

LayerProcessor -> BaseRFourfoldLayerProcessor

Methods

Public methods

• BaseRFourfoldLayerProcessor$process()

• BaseRFourfoldLayerProcessor$needs_reordering()

• BaseRFourfoldLayerProcessor$recorded_table()

• BaseRFourfoldLayerProcessor$drawn_dimnames()

• BaseRFourfoldLayerProcessor$extract_data()

• BaseRFourfoldLayerProcessor$levels_of()

• BaseRFourfoldLayerProcessor$extract_axis_titles()

• BaseRFourfoldLayerProcessor$extract_main_title()

• BaseRFourfoldLayerProcessor$wedge_names()

• BaseRFourfoldLayerProcessor$radii_agree()

• BaseRFourfoldLayerProcessor$generate_selectors()

• BaseRFourfoldLayerProcessor$clone()

BaseRFourfoldLayerProcessor$process()

Process the fourfold display layer.

Usage

BaseRFourfoldLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRFourfoldLayerProcessor$needs_reordering()

Whether the plot data must be reordered before drawing; a Base R layer is read from the recorded call and never is

Usage

BaseRFourfoldLayerProcessor$needs_reordering()

Returns

FALSE

BaseRFourfoldLayerProcessor$recorded_table()

The 2x2 table of counts the call was handed, when it is one.

Guarded by fourfold_decline_reason(), the same predicate detect_layer_type() asks, so dispatch and extraction cannot disagree about which calls are readable.

Used for the COUNTS and the shape only. The level names and the axis names come from drawn_dimnames() instead, which is not the same thing – see there.

Usage

BaseRFourfoldLayerProcessor$recorded_table(layer_info)

Arguments

Returns

A 2x2 table, or NULL

BaseRFourfoldLayerProcessor$drawn_dimnames()

The dimnames fourfoldplot() itself labels the chart with.

NOT dimnames(recorded_two_way_table(...)), and the difference is the whole point. recorded_two_way_table() repairs dimnames through as.table(); graphics::fourfoldplot repairs them from dimnames(x) as handed, after reshaping a 2-D x to ⁠2 x 2 x 1⁠. Its own source:

if (length(dim(x)) == 2L)
    x <- if (is.null(dimnames(x))) array(x, c(dim(x), 1L))
         else array(x, c(dim(x), 1L), c(dimnames(x), list(NULL)))
dnx <- dimnames(x)
if (is.null(dnx)) dnx <- vector("list", 3L)
for (i in which(sapply(dnx, is.null))) dnx[[i]] <- LETTERS[seq_len(dim(x)[i])]
if (is.null(names(dnx))) i <- 1L:3L else i <- which(is.null(names(dnx)))
if (any(i)) names(dnx)[i] <- c("Row", "Col", "Strata")[i]

reproduced here rather than approximated. For an ftable the two disagree completely: dimnames(ftable(tb)) is NULL, so the chart is labelled Row: A, Col: A, Row: B, Col: B – measured off the text grobs – while as.table(ftable(tb)) reconstructs Treatment/Outcome and Drug/Placebo/Cured/Not. Reading the levels off as.table() would announce six strings that appear nowhere on the page, which is #268's own failure displaced from the numbers onto the labels.

The which(is.null(names(dnx))) line is upstream's, quirk included: is.null() returns one logical, so that expression is always integer(0) and the Row/Col default fires only when names(dimnames(x)) is entirely NULL. A PARTIALLY named dimnames is therefore never repaired, and measured, names(dimnames(t)) <- c("Answer", "") makes the chart literally draw ": hi" and ": lo". extract_axis_titles() substitutes "Col" there rather than announce an empty label – deliberately better than the chart, and the one place this reading is not identical to it. test-base-r-fourfoldplot.R pins the chart's wrong answer as well as ours.

Usage

BaseRFourfoldLayerProcessor$drawn_dimnames(layer_info)

Arguments

Returns

A length-3 named list of dimnames, or NULL

BaseRFourfoldLayerProcessor$extract_data()

Read the 2x2 grid of counts out of the recorded call.

Rows of the emitted grid are the table's FIRST dimension, top to bottom, and its columns the SECOND, left to right – measured from the drawing, where polygon-1 (cell ⁠[1, 1]⁠) is the upper-left quadrant and the top and bottom labels carry names(dimnames(x))[1]. That is the transpose of what assocplot() does with the same argument, and it is not a convention chosen here.

The level names come from drawn_dimnames(), so they are the strings the chart puts beside each quadrant.

Usage

BaseRFourfoldLayerProcessor$extract_data(layer_info)

Arguments

Returns

List with points, x and y, empty when there is no readable table

BaseRFourfoldLayerProcessor$levels_of()

The level names of one table dimension, as drawn.

drawn_dimnames() is NULL only when the recorded first argument has no 2-D dim() at all, which a readable call cannot have; the fallback is there so a malformed layer_info in a test yields level names rather than an error.

Usage

BaseRFourfoldLayerProcessor$levels_of(named, i, fallback)

Arguments

Returns

A character vector of level names

BaseRFourfoldLayerProcessor$extract_axis_titles()

Name the axes the way the chart places the dimensions.

x is the SECOND dimension, because measured the columns run left to right; y is the first, because the rows run top to bottom. z names what the numbers are rather than a dimension of the table – a reader told "Outcome" for the value would be given a level name where a number is.

"Count" is the contingency-table convention and not a claim that the values are whole numbers: measured, fourfoldplot() draws non-integer cells happily (⁠1.5, 2.5, 3.5, 4.5⁠ gives radii ⁠0.5774, 0.7454, 0.8819, 1.0000⁠ and the ratio check passes).

No recorded_axis_label() call, unlike the assocplot processor. Measured, names(formals(graphics::fourfoldplot)) is exactly ⁠x, color, conf.level, std, margin, space, main, mfrow, mfcol⁠ – no xlab, no ylab, no ... – and fourfoldplot(tab, xlab = "X") stops with "unused argument". Reading a label that the function rejects would be dead code asserting an argument that cannot exist.

Usage

BaseRFourfoldLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRFourfoldLayerProcessor$extract_main_title()

The title the call was given, if any.

Usage

BaseRFourfoldLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character scalar, empty when the author wrote no title

BaseRFourfoldLayerProcessor$wedge_names()

The four wedge grobs of one fourfold panel, or NULL.

Discriminated by polygon count and vertex count, NOT by gp$fill. Fill looks like the exact discriminator and is not: measured, fourfoldplot(tb, std = "ind.max", color = "steelblue") leaves two quadrants with fill = NA, because fourfoldplot() does not validate color's length and its draw calls index it as color[1 + (d > 1)] / color[2 - (d > 1)]. A fill-keyed search finds two wedges there and the layer would ship with no selectors at all, for a chart that is perfectly readable.

What is measured to be stable:

• one panel draws exactly 13 polygons (4 wedges, 8 confidence arcs, 1 frame) or exactly 5 when conf.level is 0 or FALSE. The arc count is 8 or 0 and never anything else – conf.level produces two ⁠for (j in 1:4)⁠ loops guarded by is.numeric(conf.level), and every other value (1, -0.1, NA, a length-2 vector, NULL) is rejected by fourfoldplot() itself. Measured, k panels draw ⁠13k⁠ or ⁠5k⁠: UCBAdmissions gives 78 and 30, so this count also refuses another figure's grob tree.

• the wedges are always the first four in find_graphics_plot_grobs() order, because drawPie() runs before the rings and before the frame at every conf.level;

• every quarter disc has 501 vertices (drawPie(n = 500) plus the centre point) and the frame is the only 4-vertex polygon.

Usage

BaseRFourfoldLayerProcessor$wedge_names(gt, plot_index)

Arguments

Returns

The four wedge grob names, or NULL when this is not one panel

BaseRFourfoldLayerProcessor$radii_agree()

Whether the wedges on the page are the counts in the call.

radius / sqrt(count) constant across the four quadrants, to a relative spread of 1e-8. Measured headroom on the worst-conditioned tables that fourfoldplot() will draw at all – c(1e-9, 1, 1, 1) (2.220e-16), c(1, 2, 3, 1e18) (2.068e-16) and the non-integer c(1.5, 2.5, 3.5, 4.5) (1.178e-16) – is eight orders below the threshold, while an asymmetric table's margins drawing checked against its counts gives 7.616e-01. (c(1, 1e15, 1, 1) is not in that list because radii_agree() is never asked about it – not because it errors. Measured, fourfoldplot() returns normally there with a "NaNs produced" warning and emits ZERO polygon grobs under ind.max and all.max, so wedge_names() refuses it on the polygon count first. Under the default margins the same table does draw 13 polygons – radii ⁠0.00017782794, 0.99999998, 0.99999998, 0.00017782794⁠ – but no margins call reaches a processor.)

A zero count makes radius / sqrt(count) 0/0, so those cells are held to radius == 0 instead – measured, a zero cell still emits a full 501-vertex polygon at the origin, so the grob is there and addressable.

The check is vacuous when fewer than two cells are non-zero: one non-zero cell makes the relative deviation identically 0 whatever the radius is. Measured, ⁠0, 0, 0, 160⁠ under ind.max draws radii ⁠0, 0, 0, 1⁠ and would pass an unguarded check against any table with the same three zeros. Two non-zero cells are required before the ratio is treated as evidence, so such a chart announces its counts and highlights nothing.

Usage

BaseRFourfoldLayerProcessor$radii_agree(gt, names, counts)

Arguments

Returns

TRUE when the drawing carries the recorded counts

BaseRFourfoldLayerProcessor$generate_selectors()

Address the quadrant the chart drew each count into.

Each quadrant is its own polygon grob, so each needs its own selector – the pie's situation, not the barplot's. Two orderings compose here, and they run in opposite directions:

• The drawing is column-major. Table cell ⁠[r, c]⁠ is polygon (c - 1) * 2 + r. Measured on the exported SVG of fourfoldplot(tb, std = "ind.max") with ⁠c(tab) = 10, 40, 90, 160⁠, the polygon centroids in screen coordinates (the root ⁠<g>⁠ carries ⁠translate(0, 360) scale(1, -1)⁠, so screen y is 360 - y) are polygon-1 (221, 158) upper LEFT, polygon-2 (190, 224) lower LEFT, polygon-3 (345, 114) upper RIGHT, polygon-4 (376, 268) lower RIGHT, and the count labels sit at 10 (90, 55), 40 (90, 305), 90 (414, 55), 160 (414, 305). So table row 1 is the TOP row on the page, which is the row extract_data() emits first.

• The heat trace reverses the numbers and not the selectors. In the bundled ⁠maidr-4.8.0/maidr.js⁠ the constructor is ⁠this.y=[...t.y].reverse(),this.heatmapValues=[...t.points].reverse()⁠, while mapToSvgElements()'s array-of-arrays branch walks e[i] index for index. Its bare-string branch immediately below DOES reverse (⁠let a=t-1-e⁠), which is what makes the asymmetry easy to miss. So highlightValues[0] lines up with points' LAST row.

Grid row 1 is therefore the BOTTOM wedges: ⁠[[polygon-2, polygon-4], [polygon-1, polygon-3]]⁠. The wrong answer is to emit it index-aligned with points, top row first – it reads correctly and highlights the vertically mirrored quadrant on every cell of every fourfold plot: ⁠row 0, col 0⁠ then announces Placebo / 40 while lighting the wedge drawn for Drug / 10. test-base-r-fourfoldplot.R pins the bottom-first order against that. image()/heatmap() is the precedent – measured on image(matrix(1:6, 2)), points[[1]] is the top row while selectors[[1]] is rect:nth-child(1), the lowest rect on the page – and NEWS.md records fixing the same mirror there.

Returns list() when the drawing and the recorded call disagree. The numbers are still announced – they are what the call was handed – and nothing highlights, rather than a highlight landing on another panel's quadrant.

Usage

BaseRFourfoldLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  extracted_data = NULL
)

Arguments

Returns

A 2x2 nested list of selectors, or an empty list

BaseRFourfoldLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRFourfoldLayerProcessor$clone(deep = FALSE)

Arguments

Base R Heatmap Layer Processor

Description

Processes Base R heatmap layers using the heatmap() function

Super class

LayerProcessor -> BaseRHeatmapLayerProcessor

Methods

Public methods

• BaseRHeatmapLayerProcessor$process()

• BaseRHeatmapLayerProcessor$extract_data()

• BaseRHeatmapLayerProcessor$compute_heatmap_ordering()

• BaseRHeatmapLayerProcessor$generate_selectors()

• BaseRHeatmapLayerProcessor$find_image_rect_grobs()

• BaseRHeatmapLayerProcessor$generate_selectors_from_grob()

• BaseRHeatmapLayerProcessor$extract_axis_titles()

• BaseRHeatmapLayerProcessor$extract_main_title()

• BaseRHeatmapLayerProcessor$clone()

BaseRHeatmapLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRHeatmapLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRHeatmapLayerProcessor$extract_data()

One row per cell of the recorded matrix, in drawn order

Usage

BaseRHeatmapLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of rows

BaseRHeatmapLayerProcessor$compute_heatmap_ordering()

Reproduce the row/column ordering heatmap() draws with

Usage

BaseRHeatmapLayerProcessor$compute_heatmap_ordering(args)

Arguments

Returns

List with rowInd/colInd, or NULL if unavailable

BaseRHeatmapLayerProcessor$generate_selectors()

Selectors for the image tiles, one per cell

Usage

BaseRHeatmapLayerProcessor$generate_selectors(
  layer_info,
  gt = NULL,
  extracted_data = NULL
)

Arguments

Returns

List of selectors

BaseRHeatmapLayerProcessor$find_image_rect_grobs()

Find the image-rect grobs drawn by the plot group at group_index

Usage

BaseRHeatmapLayerProcessor$find_image_rect_grobs(grob, group_index)

Arguments

Returns

Character vector of grob names

BaseRHeatmapLayerProcessor$generate_selectors_from_grob()

Build this layer's selector from the grob tree

Usage

BaseRHeatmapLayerProcessor$generate_selectors_from_grob(
  grob,
  group_index = NULL
)

Arguments

Returns

A selector string, or an empty string when no grob matches

BaseRHeatmapLayerProcessor$extract_axis_titles()

Extract the axis titles for this layer

heatmap() lays the matrix out one way round only – its columns run along x and its rows up y – so those two words are facts about the call. image() is not the same picture: it draws a coordinate grid, and image(x, y, z) puts the caller's own coordinates on those axes, so naming them after a matrix would be a guess. It gets no default.

Usage

BaseRHeatmapLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRHeatmapLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRHeatmapLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRHeatmapLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRHeatmapLayerProcessor$clone(deep = FALSE)

Arguments

Base R Histogram Layer Processor

Description

Processes Base R histogram plot layers using verified data extraction and selector generation logic.

Super class

LayerProcessor -> BaseRHistogramLayerProcessor

Methods

Public methods

• BaseRHistogramLayerProcessor$process()

• BaseRHistogramLayerProcessor$extract_data()

• BaseRHistogramLayerProcessor$recompute_histogram()

• BaseRHistogramLayerProcessor$is_frequency()

• BaseRHistogramLayerProcessor$generate_selectors()

• BaseRHistogramLayerProcessor$find_rect_grobs()

• BaseRHistogramLayerProcessor$generate_selectors_from_grob()

• BaseRHistogramLayerProcessor$extract_axis_titles()

• BaseRHistogramLayerProcessor$frequency_label()

• BaseRHistogramLayerProcessor$extract_main_title()

• BaseRHistogramLayerProcessor$clone()

BaseRHistogramLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRHistogramLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRHistogramLayerProcessor$extract_data()

One point per bin, from the histogram recomputed from the recorded call

Usage

BaseRHistogramLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of points

BaseRHistogramLayerProcessor$recompute_histogram()

Recompute the plotted histogram from the recorded call

Usage

BaseRHistogramLayerProcessor$recompute_histogram(args)

Arguments

Returns

A "histogram" object, or NULL when the call recorded no data

BaseRHistogramLayerProcessor$is_frequency()

Is this a frequency histogram rather than a density one?

The plotted y-axis shows counts only for frequency histograms; with freq = FALSE or probability = TRUE it shows densities. hist()'s own default is freq = TRUE only for equidistant breaks.

Usage

BaseRHistogramLayerProcessor$is_frequency(args, hist_obj = NULL)

Arguments

Returns

Logical

BaseRHistogramLayerProcessor$generate_selectors()

The selector for the bins, scoped to this layer's plot group

Usage

BaseRHistogramLayerProcessor$generate_selectors(layer_info, gt = NULL)

Arguments

Returns

List of selectors

BaseRHistogramLayerProcessor$find_rect_grobs()

Find the rect grobs drawn by the recorded call at call_index

Usage

BaseRHistogramLayerProcessor$find_rect_grobs(grob, call_index)

Arguments

Returns

Character vector of grob names

BaseRHistogramLayerProcessor$generate_selectors_from_grob()

Build this layer's selector from the grob tree

Usage

BaseRHistogramLayerProcessor$generate_selectors_from_grob(
  grob,
  call_index = NULL
)

Arguments

Returns

A selector string, or an empty string when no grob matches

BaseRHistogramLayerProcessor$extract_axis_titles()

Extract the axis titles for this layer

hist() derives both titles inside the call and so records neither: the x title is deparse(substitute(x)), which is gone by the time the evaluated arguments reach us, and the y title is "Frequency" or "Density" depending on what the bars measure. The y default therefore repeats hist()'s own choice – resolved by the same rule that decides which values extract_data() emits, so the noun always names the number being announced – while x says only what the axis certainly holds: the bins.

Usage

BaseRHistogramLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRHistogramLayerProcessor$frequency_label()

The title hist() itself would print above the counted axis

Usage

BaseRHistogramLayerProcessor$frequency_label(args)

Arguments

Returns

"Frequency" or "Density"

BaseRHistogramLayerProcessor$extract_main_title()

The main title of the recorded call, or an empty string

Usage

BaseRHistogramLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRHistogramLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRHistogramLayerProcessor$clone(deep = FALSE)

Arguments

Base R Interaction Plot Layer Processor

Description

Reads interaction.plot() as the set of lines it draws: one series per level of the trace factor, running across the levels of the x factor at fun(response) for each cell.

stats::interaction.plot computes that grid itself and hands it straight to matplot:

cells <- tapply(response, list(x.factor, trace.factor), fun)
matplot(xvals, cells, ..., type = type, ...)

which is the shape BaseRLineLayerProcessor already reads for matplot – one series per column, each point carrying its column name as z. So the whole reading is recomputing cells and handing it over; nothing about extracting a multi-series line is new here.

Recomputed rather than read back off the drawing, for the reason the correlograms recompute theirs (#276): a cell mean is not on the page in any form a grob carries, and the recorded arguments hold everything needed to get it exactly as the function did.

type is not consulted. It varies the marks – "l" draws lines, "p" points, "b"/"o"/"c" both – but every variant draws the same cell means in the same series, and reading a type = "p" chart as loose points would lose the trace grouping that makes it an interaction plot.

Super classes

LayerProcessor -> BaseRLineLayerProcessor -> BaseRInteractionLayerProcessor

Methods

Public methods

• BaseRInteractionLayerProcessor$extract_data()

• BaseRInteractionLayerProcessor$extract_axis_titles()

• BaseRInteractionLayerProcessor$clone()

BaseRInteractionLayerProcessor$extract_data()

One series per trace level, read from the grid of cell means

Usage

BaseRInteractionLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of series

BaseRInteractionLayerProcessor$extract_axis_titles()

The three labels the drawing writes, each explicit argument first.

All three of interaction.plot's own defaults are deparse1(substitute(...)) of an argument, so they name the expression the caller wrote. The wrapper records evaluated values, by which point substitute() is long gone – a factor's levels are not its name – so the expressions come off the recorded call text instead, the way the correlograms recover their series names (#276).

Usage

BaseRInteractionLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

An axes list from build_axes()

BaseRInteractionLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRInteractionLayerProcessor$clone(deep = FALSE)

Arguments

Base R Lag Plot Processor

Description

Reads lag.plot() as the grid of scatters it draws: one panel per series and lag, the series plotted against a shifted copy of itself.

A grid, not a layer. Like pairs(), this call lays out its own panels and hands nothing to the device's layout calls, so the grid has to come from the reading. It answers multi_panel = TRUE and places each layer at its own cell.

What a panel pairs. Measured by tracing graphics::plot.xy through a real call – the panel is plot(lag(X, k), X), and lag() shifts the time base back, so the pair at time t is

x = X[t + k]      the later reading, across
y = X[t]          the earlier one, up

over every t where both indices land inside the series. A negative lag works out of the same expression and was measured too: set.lags = -1 gives ⁠x = X[1..n-1]⁠ against ⁠y = X[2..n]⁠, and set.lags = 0 gives the series against itself.

The panels are numbered in draw order. The nested loop runs series outermost and lag innermost, and par(mfrow) fills row by row – measured against a grid.echo() export, a two-column matrix at lags = 2 writes graphics-plot-1 through graphics-plot-4 for ⁠(a,1) (a,2) (b,1) (b,2)⁠. So panel k sits at row (k - 1) %/% ncols + 1, column (k - 1) %% ncols + 1.

A panel's marks are symbols or labels, and labels decides which. lag.plot() writes the time index at each pair rather than a symbol when labels is true, and labels defaults to do.lines, which defaults to n <= 150 – so the default chart is the labelled one. Measured, the four combinations give:

labels  do.lines   grobs in a panel
FALSE   FALSE      points
FALSE   TRUE       points, lines
TRUE    FALSE      text
TRUE    TRUE       text, brokenline

So do.lines only adds the joining line and labels alone decides the mark, which is why the two are read separately rather than through the default that ties them together.

Both marks can be outlined, and the export is what says so. Measured on a real save_html() of a labelled call, the text grob comes out as one group per pair, in data order:

<g id="graphics-plot-1-text-1.1">
  <g id="graphics-plot-1-text-1.1.1" transform="translate(254.32, …)">
  <g id="graphics-plot-1-text-1.1.2" transform="translate(221.70, …)">

which is the same shape a points grob has, with use elements replaced by nested gs. So the selector differs only in the grob name and the child it reaches for.

Super classes

LayerProcessor -> BaseRPointLayerProcessor -> BaseRLagLayerProcessor

Methods

Public methods

• BaseRLagLayerProcessor$process()

• BaseRLagLayerProcessor$clone()

BaseRLagLayerProcessor$process()

Emit one point layer per drawn panel

Usage

BaseRLagLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

A multi-panel result, or NULL when nothing was read

BaseRLagLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRLagLayerProcessor$clone(deep = FALSE)

Arguments

Base R Line Plot Layer Processor

Description

Processes Base R line plot layers based on recorded plot calls

Super class

LayerProcessor -> BaseRLineLayerProcessor

Methods

Public methods

• BaseRLineLayerProcessor$process()

• BaseRLineLayerProcessor$needs_reordering()

• BaseRLineLayerProcessor$extract_data()

• BaseRLineLayerProcessor$get_axis_labels()

• BaseRLineLayerProcessor$extract_single_line_data()

• BaseRLineLayerProcessor$extract_multiline_data()

• BaseRLineLayerProcessor$extract_axis_titles()

• BaseRLineLayerProcessor$extract_abline_data()

• BaseRLineLayerProcessor$get_x_range_from_group()

• BaseRLineLayerProcessor$get_y_range_from_group()

• BaseRLineLayerProcessor$axis_extent()

• BaseRLineLayerProcessor$extract_main_title()

• BaseRLineLayerProcessor$generate_selectors()

• BaseRLineLayerProcessor$find_lines_grobs()

• BaseRLineLayerProcessor$selector_grob_type()

• BaseRLineLayerProcessor$generate_selectors_from_grob()

• BaseRLineLayerProcessor$clone()

BaseRLineLayerProcessor$process()

Process the layer: read its data, selectors, axis titles and main title from the recorded call

Usage

BaseRLineLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List describing the layer for the MAIDR payload

BaseRLineLayerProcessor$needs_reordering()

Whether the plot data must be reordered before drawing; a Base R layer is read from the recorded call and never is

Usage

BaseRLineLayerProcessor$needs_reordering()

Returns

FALSE

BaseRLineLayerProcessor$extract_data()

One series per line: a vector, each column of a matrix, a time series, or the endpoints of abline()

Usage

BaseRLineLayerProcessor$extract_data(layer_info)

Arguments

Returns

List of series

BaseRLineLayerProcessor$get_axis_labels()

Get custom axis labels from axis() LOW-level calls

Usage

BaseRLineLayerProcessor$get_axis_labels(layer_info, axis_side = 1)

Arguments

Returns

Character vector of labels or NULL if not found

BaseRLineLayerProcessor$extract_single_line_data()

The points of one line, pairing each x with its y

Usage

BaseRLineLayerProcessor$extract_single_line_data(x, y, x_labels = NULL)

Arguments

Returns

List holding one series

BaseRLineLayerProcessor$extract_multiline_data()

One series per column of y_matrix, named after the columns

Usage

BaseRLineLayerProcessor$extract_multiline_data(x, y_matrix, x_labels = NULL)

Arguments

Returns

List of series

BaseRLineLayerProcessor$extract_axis_titles()

The axis titles, taken from the HIGH-level call for an overlay such as abline()

Usage

BaseRLineLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRLineLayerProcessor$extract_abline_data()

The endpoints of an abline() call across the axis the HIGH-level call set up

Usage

BaseRLineLayerProcessor$extract_abline_data(layer_info)

Arguments

Returns

List holding one two-point series, or empty

BaseRLineLayerProcessor$get_x_range_from_group()

The x extent of the group's HIGH-level call, as the axis was drawn

Usage

BaseRLineLayerProcessor$get_x_range_from_group(group)

Arguments

Returns

Numeric vector of two, or NULL

BaseRLineLayerProcessor$get_y_range_from_group()

The y extent of the group's HIGH-level call, as the axis was drawn

Usage

BaseRLineLayerProcessor$get_y_range_from_group(group)

Arguments

Returns

Numeric vector of two, or NULL

BaseRLineLayerProcessor$axis_extent()

The extent of an axis the way plot.default() sets it: an explicit xlim/ylim, or the finite data extended by 4 % each way, which is what abline() draws its clipped line across.

Usage

BaseRLineLayerProcessor$axis_extent(limits, data)

Arguments

Returns

Numeric vector of two, or NULL when nothing finite was plotted

BaseRLineLayerProcessor$extract_main_title()

The main title, taken from the HIGH-level call for abline()

Usage

BaseRLineLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character string

BaseRLineLayerProcessor$generate_selectors()

One selector per polyline, in series order

Usage

BaseRLineLayerProcessor$generate_selectors(layer_info, gt = NULL)

Arguments

Returns

List of selectors

BaseRLineLayerProcessor$find_lines_grobs()

Find every grob of the given family drawn by the plot group at group_index

Usage

BaseRLineLayerProcessor$find_lines_grobs(
  grob,
  group_index,
  grob_type = "lines"
)

Arguments

Returns

Character vector of grob names

BaseRLineLayerProcessor$selector_grob_type()

Which family of grob names this layer's selectors are drawn from: "abline", "lines", "segments", "spike" or "step". Overridden by subclasses whose geometry lands under a different grob name (see BaseRStepLayerProcessor).

Usage

BaseRLineLayerProcessor$selector_grob_type(layer_info)

Arguments

Returns

"abline" or "lines"

BaseRLineLayerProcessor$generate_selectors_from_grob()

One selector per matching polyline, sorted by the grob number

Usage

BaseRLineLayerProcessor$generate_selectors_from_grob(
  grob,
  group_index,
  layer_info
)

Arguments

Returns

List of selectors

BaseRLineLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRLineLayerProcessor$clone(deep = FALSE)

Arguments

Base R Mosaic Plot Layer Processor

Description

Processes Base R mosaicplot() layers – a two-way contingency table drawn as tiles, where a column's width encodes that category's share of all observations and a tile's height its conditional proportion within the column.

Read as a mosaic layer, which exists for exactly this shape. Read as a stacked_bar it would lose the width entirely, and the width is half the table: the conditional proportions would arrive without the group sizes they were computed from, so a category of six observations and one of six hundred would read identically.

Nothing here is inferred from the drawing. mosaicplot() is handed the table itself, so the recorded call carries every number the trace wants – the counts, the margins they imply, and the level names from dimnames().

Super class

LayerProcessor -> BaseRMosaicLayerProcessor

Methods

Public methods

• BaseRMosaicLayerProcessor$process()

• BaseRMosaicLayerProcessor$needs_reordering()

• BaseRMosaicLayerProcessor$extract_data()

• BaseRMosaicLayerProcessor$recorded_table()

• BaseRMosaicLayerProcessor$extract_axis_titles()

• BaseRMosaicLayerProcessor$extract_main_title()

• BaseRMosaicLayerProcessor$generate_selectors()

• BaseRMosaicLayerProcessor$clone()

BaseRMosaicLayerProcessor$process()

Process the mosaic layer.

Usage

BaseRMosaicLayerProcessor$process(
  plot,
  layout,
  built = NULL,
  gt = NULL,
  grob_id = NULL,
  panel_id = NULL,
  panel_ctx = NULL,
  layer_info = NULL
)

Arguments

Returns

List with data, selectors, type, title and axes

BaseRMosaicLayerProcessor$needs_reordering()

Whether the plot data must be reordered before drawing; a Base R layer is read from the recorded call and never is

Usage

BaseRMosaicLayerProcessor$needs_reordering()

Returns

FALSE

BaseRMosaicLayerProcessor$extract_data()

Read the table out of the recorded mosaicplot() call.

The emitted shape is the segmented one the stacked bar processor already produces – data[[fill]][[category]] – because the core builds MosaicTrace on SegmentedTrace and navigates it category-then-series exactly as a stack. mosaicplot() splits along the first dimension into columns and each column along the second, so the first dimension is the category and the second the fill.

Each cell carries four numbers rather than one:

• y, the cell's conditional proportion within its column – the tile's height, and what a stack's value would be;

• width, the column's share of all observations – carried on every cell of the column, because the grammar's unit is the point and a flat list has nowhere else to put it;

• count, the cell's own count. A mosaic is drawn from counts and they are the numbers a reader would quote back;

• z, the fill level's name.

A column that observed nothing has no conditional proportions to report – dividing would give NaN for every cell – so its cells carry a proportion of 0 alongside their true count of 0. That is what the chart draws: a column of zero width and no tiles.

Usage

BaseRMosaicLayerProcessor$extract_data(layer_info)

Arguments

Returns

Nested list of points, empty when there is no table to read

BaseRMosaicLayerProcessor$recorded_table()

The two-way table the call was handed, when it is one.

Only a two-dimensional table is read. mosaicplot() accepts three and more, splitting recursively, and a mosaic layer has one category axis and one fill – so a deeper table has nowhere to put its later dimensions and is declined rather than flattened into a cross-classification the chart does not claim.

Usage

BaseRMosaicLayerProcessor$recorded_table(layer_info)

Arguments

Returns

A 2-D table, or NULL

BaseRMosaicLayerProcessor$extract_axis_titles()

Name the axes from the table's own dimension names.

mosaicplot() labels its axes with names(dimnames(x)) unless the author overrides them – "Hair" and "Eye" for HairEyeColor[, , 1] – so those are the two words a reader should be given for the two dimensions.

Which grammar axis each lands on is not the chart's own arrangement. The second dimension is what mosaicplot() draws up the y axis, but a segmented layer's y holds the magnitude and its z the fill, so the second dimension is named on z and y says what its numbers are. ylab follows the dimension it names rather than the axis it shares a letter with, for the same reason.

Usage

BaseRMosaicLayerProcessor$extract_axis_titles(layer_info)

Arguments

Returns

Canonical axes list

BaseRMosaicLayerProcessor$extract_main_title()

The title the call was given, if any.

mosaicplot() writes a default main of its own from the deparsed data expression, but the recorded call carries only what the author passed, and a title invented from a variable name is not something a reader can act on.

Usage

BaseRMosaicLayerProcessor$extract_main_title(layer_info)

Arguments

Returns

Character scalar, empty when the author wrote no title

BaseRMosaicLayerProcessor$generate_selectors()

Address the tiles the chart drew.

Measured on a rendered mosaicplot(HairEyeColor[, , 1]): gridGraphics draws one -polygon-N grob per cell and nothing else as a polygon – 16 grobs for a 4x4 table, with no frame among them. Their geometry says the order: polygon-1 to -4 share the leftmost column's x extent, -5 to -8 the next one's, and within a column the grob number runs down the fill levels in the table's own order. So the tile for row f of column c is the (c - 1) * fills + fth grob.

The grobs are found rather than named by formula, and a short list is declined: a guessed id resolves to nothing at best and to another panel's tiles at worst, and a mosaic with no highlight still reads – the outcome #145 established for a layer with nothing to point at.

Usage

BaseRMosaicLayerProcessor$generate_selectors(layer_info, gt = NULL)

Arguments

Returns

List of selectors, one per cell, or empty when unresolvable

BaseRMosaicLayerProcessor$clone()

The objects of this class are cloneable with this method.

Usage

BaseRMosaicLayerProcessor$clone(deep = FALSE)

Arguments

Base R Scatterplot Matrix Processor

Description

Reads pairs() as the grid of scatters it draws: one panel per ordered pair of columns, the column across plotted against the column down.

A grid, not a layer. Every other base R processor answers with one layer, or several layers in one cell. A scatterplot matrix is ⁠n x n⁠ panels, which is the figure's shape rather than a layer's, so this one answers with multi_panel = TRUE and places each layer at its own cell. That is the shape the same chart already gets elsewhere: sns.pairplot in py-maidr, and a plotly splom since xability/py-maidr#667.

The grid cannot come from the recording. Measured, pairs() sets its own par(mfrow) internally and restores it, so nothing lands in the device's layout calls – get_layout_calls() answers zero – and detect_panel_configuration() sees a single panel (#272). The grid is the reading's own, derived from the number of columns.

The panels are numbered column-major. Measured against a real grid.echo() export of a three-column matrix, gridGraphics writes nine graphics-plot-N groups – one per cell, diagonal included – and pairing them with a panel that recorded what it was handed gives

k    cell     drawn
1    (1,1)    text        the variable's name
2    (2,1)    points      x = column 1, y = column 2
3    (3,1)    points      x = column 1, y = column 3
4    (1,2)    points      x = column 2, y = column 1
5    (2,2)    text
6    (3,2)    points      x = column 2, y = column 3
7    (1,3)    points      x = column 3, y = column 1
8    (2,3)    points      x = column 3, y = column 2
9    (3,3)    text

– that is k = (col - 1) * n + row, and the panel at ⁠(row, col)⁠ plots column col horizontally against column row vertically.

The diagonal has no layer. A diagonal cell draws the variable's name and nothing else, which the orchestrator already has an answer for: a cell with no layers becomes a valid empty subplot. Giving it a histogram instead would announce a chart pairs() does not draw – its default diag.panel draws nothing at all.

Super classes

LayerProcessor -> BaseRPointLayerProcessor -> BaseRPairsLayerProcessor

Methods

Public methods

• BaseRPairsLayerProcessor$process()

• BaseRPairsLayerProcessor$extract_columns()

• BaseRPairsLayerProcessor$column_names()

• BaseRPairsLayerProcessor$panel_layer()

• BaseRPairsLayerProcessor$panel_selectors()

• BaseRPairsLayerProcessor$clone()