Package 'rtemis.draw'

Description

Create interactive statistical charts, network graphs and choropleth maps. Charts are rendered with 'ECharts', networks with 'Sigma.js' and maps with 'MapLibre GL JS'. Every visualization is an 'htmlwidgets' widget that automatically follows the light or dark theme of wherever it is shown, and can be exported to a Scalable Vector Graphics (SVG) file.

Statistical charts

• Distributions and comparisons: draw_scatter(), draw_line(), draw_bar(), draw_boxplot(), draw_violin(), draw_histogram(), draw_density(), draw_pie(), draw_heatmap(), draw_sankey().

• Time: draw_ts(), draw_xt(), draw_gantt(), draw_spectrogram().

• Three dimensions: draw_scatter3d(), with draw_add_surface().

• Model evaluation: draw_roc(), draw_calibration(), draw_confusion(), draw_fit(), draw_varimp(), draw_metric(), draw_learning_curve().

• Time-to-event: draw_survival(), draw_survfit().

• Significance testing: draw_volcano(), draw_manhattan(), draw_pvals().

• Sequences: draw_protein(), draw_a3().

Add fitted lines, reference lines, bands and labels with draw_add_fit() and draw_annotate(), and arrange several charts into one figure with draw_panels().

Network graphs

draw_network() draws a network from an adjacency or correlation matrix, or from an edge list, with 'Sigma.js'.

Choropleth maps

draw_choropleth() colors countries, U.S. states or U.S. counties by a value, with 'MapLibre GL JS'. Boundaries are bundled with the package, so maps need no network access.

Configuration

Each ⁠draw_*()⁠ function builds a validated 'S7' configuration object, e.g. from setup_ScatterConfig(), and renders it. Configurations can be written to and read from 'JSON' files with write_chart_config() and read_chart_config(), and chart_schema() returns the 'JSON' Schema that such files validate against. draw() renders a complete low-level option object directly.

Themes

By default, visualizations detect whether they are shown on a light or dark background in 'RStudio', 'VS Code', 'Quarto' and the browser, style themselves to match, and switch when the viewer changes theme, e.g. with the 'Quarto' light/dark toggle or the operating system setting. Networks and maps keep their current pan and zoom when they switch. Pass theme_light() or theme_dark() as theme to fix a theme.

Output

Visualizations display in the 'RStudio' and 'VS Code' viewers, 'R Markdown' and 'Quarto' documents, and 'shiny' apps (see drawOutput() and renderDraw()). All 'JavaScript' is bundled with the package, so HTML output works offline. save_drawing() exports a visualization to an SVG file using 'Node.js'.

Author(s)

Maintainer: E.D. Gennatas [email protected] (ORCID) [copyright holder]

Authors:

• E.D. Gennatas [email protected] (ORCID) [copyright holder]

See Also

Useful links:

• https://www.rtemis.org

• https://docs.rtemis.org/r/draw

• https://docs.rtemis.org/r/draw-api

• Report bugs at https://github.com/rtemis-org/draw/issues

Description

A serializable description of an A3 protein diagram. Build one with setup_A3Config() rather than calling this constructor directly.

Usage

A3Config(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  n_per_row = 21L,
  position_every = 10L,
  ptm_placement = "radial",
  zoom = TRUE,
  residue_spacing = 0.3,
  marker_size = 28,
  font_size = 18,
  line_width = 2,
  show_markers = TRUE,
  show_labels = TRUE,
  region_opacity = 0.3,
  residue_fill = NULL,
  residue_stroke = NULL,
  label_color = NULL,
  pos_label_color = NULL,
  variant_color = NULL,
  disease_variant_color = NULL
)

Arguments

Details

The bound data is an A3 object, created with rtemis.a3::create_A3().

Value

A3Config object.

Author(s)

EDG

Examples

setup_A3Config(n_per_row = 30L)@type

Description

Portable, materialized annotation geometry. Corresponds to MarkLineOption, MarkAreaOption, and ScatterSeriesOption in ECharts src/component/marker and src/chart/scatter. Coordinates are data values (epoch milliseconds for time axes); categorical coordinates may be category names. Layers are independent of group legend selection.

Usage

AnnotationLayer(
  hline = NULL,
  vline = NULL,
  x = numeric(0),
  y = numeric(0),
  text = NULL,
  bands = list(),
  color = "#888888",
  line_type = "dashed",
  opacity = 0.15,
  x_axis = 0L,
  y_axis = 0L
)

Arguments

Value

AnnotationLayer: Validated annotation geometry.

Examples

AnnotationLayer(hline = 0, text = "Peak", x = 2, y = 3)

Description

Fill styling for areas (polygons, area under curves, etc.).

Usage

AreaStyle(
  color = NULL,
  opacity = NULL,
  origin = NULL,
  shadow_blur = NULL,
  shadow_color = NULL,
  shadow_offset_x = NULL,
  shadow_offset_y = NULL
)

Arguments

Details

Corresponds to AreaStyleOption in src/util/types.ts (line 1169). ECharts docs: https://echarts.apache.org/en/option.html#series-line.areaStyle

Value

AreaStyle object.

Examples

AreaStyle(color = "#16a085", opacity = 0.3)

Description

Configuration for a cartesian axis (xAxis or yAxis). Combines fields from AxisBaseOptionCommon, NumericAxisBaseOptionCommon, CategoryAxisBaseOption, ValueAxisBaseOption, LogAxisBaseOption, and TimeAxisBaseOption.

Usage

Axis(
  type = NULL,
  show = NULL,
  inverse = NULL,
  name = NULL,
  name_location = NULL,
  name_rotate = NULL,
  name_gap = NULL,
  name_text_style = NULL,
  silent = NULL,
  trigger_event = NULL,
  min = NULL,
  max = NULL,
  scale = NULL,
  split_number = NULL,
  interval = NULL,
  min_interval = NULL,
  max_interval = NULL,
  align_ticks = NULL,
  log_base = NULL,
  boundary_gap = NULL,
  data = NULL,
  axis_line = NULL,
  axis_tick = NULL,
  minor_tick = NULL,
  axis_label = NULL,
  split_line = NULL,
  minor_split_line = NULL,
  split_area = NULL,
  axis_pointer = NULL,
  position = NULL,
  grid_index = NULL
)

Arguments

Details

Corresponds to AxisBaseOption in src/coord/axisCommonTypes.ts (line 376). ECharts docs: https://echarts.apache.org/en/option.html#xAxis

Value

Axis object.

Examples

Axis(type = "category", data = c("Mon", "Tue", "Wed"))

Description

Configuration for axis labels. Combines label-specific positioning with text styling (flattened in to_list like LabelOption).

Usage

AxisLabel(
  show = NULL,
  inside = NULL,
  rotate = NULL,
  margin = NULL,
  formatter = NULL,
  show_min_label = NULL,
  show_max_label = NULL,
  hide_overlap = NULL,
  interval = NULL,
  text_style = NULL
)

Arguments

Details

Corresponds to AxisLabelBaseOption in src/coord/axisCommonTypes.ts (line 312). ECharts docs: https://echarts.apache.org/en/option.html#xAxis.axisLabel

Value

AxisLabel object.

Examples

AxisLabel(show = TRUE, rotate = 45, margin = 8)

Description

Configuration for the axis line itself.

Usage

AxisLine(
  show = NULL,
  on_zero = NULL,
  on_zero_axis_index = NULL,
  symbol = NULL,
  symbol_size = NULL,
  symbol_offset = NULL,
  line_style = NULL
)

Arguments

Details

Corresponds to AxisLineOption in src/coord/axisCommonTypes.ts (line 231). ECharts docs: https://echarts.apache.org/en/option.html#xAxis.axisLine

Value

AxisLine object.

Examples

AxisLine(show = TRUE, line_style = LineStyle(color = "#888888"))

Description

Configuration for axis tick marks.

Usage

AxisTick(
  show = NULL,
  inside = NULL,
  length = NULL,
  align_with_label = NULL,
  line_style = NULL
)

Arguments

Details

Corresponds to AxisTickOption in src/coord/axisCommonTypes.ts (line 244). ECharts docs: https://echarts.apache.org/en/option.html#xAxis.axisTick

Value

AxisTick object.

Examples

AxisTick(show = TRUE, length = 5, align_with_label = TRUE)

Description

A serializable description of a bar chart. Build one with setup_BarConfig() rather than calling this constructor directly.

Usage

BarConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  legend_position = "top",
  legend_placement = "outside",
  x = NULL,
  y = NULL,
  order = "input",
  stack = FALSE,
  horizontal = FALSE,
  bar_width = NULL,
  palette = NULL,
  xlab = NULL,
  ylab = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL
)

Arguments

Details

x names the column holding the categories. y names one or more columns, one series each – a single column draws one set of bars, several draw a grouped or stacked chart with the column names as the series names. That is the difference from ScatterConfig, whose x and y each name exactly one column.

Fixed thickness maps to barWidth in ECharts' BaseBarSeriesOption (src/chart/bar/BaseBarSeries.ts). It applies to either orientation.

Value

BarConfig object.

Author(s)

EDG

Examples

setup_BarConfig(x = "cyl", y = "mpg")@type

Description

Configuration for a bar chart series.

Usage

BarSeries(
  name = NULL,
  data = NULL,
  x_axis_index = NULL,
  y_axis_index = NULL,
  stack = NULL,
  silent = NULL,
  legend_hover_link = NULL,
  color = NULL,
  z_level = NULL,
  z = NULL,
  clip = NULL,
  bar_width = NULL,
  bar_max_width = NULL,
  bar_min_width = NULL,
  bar_min_height = NULL,
  bar_gap = NULL,
  bar_category_gap = NULL,
  round_cap = NULL,
  show_background = NULL,
  item_style = NULL,
  label = NULL
)

Arguments

Details

Corresponds to BarSeriesOption in src/chart/bar/BarSeries.ts (line 68) and BaseBarSeriesOption in src/chart/bar/BaseBarSeries.ts (line 38). ECharts docs: https://echarts.apache.org/en/option.html#series-bar

Value

BarSeries object.

Examples

BarSeries(name = "Counts", data = c(3, 7, 2))

Description

A serializable description of a boxplot. Build one with setup_BoxplotConfig() rather than calling this constructor directly.

Usage

BoxplotConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  legend_position = "top",
  legend_placement = "outside",
  x = NULL,
  group = NULL,
  observation = NULL,
  order = "input",
  transform = "none",
  geometry = "box",
  bandwidth = NULL,
  adjust = 1,
  density_points = 128L,
  paired = FALSE,
  pair_alpha = 0.35,
  pair_width = 1,
  comparisons = NULL,
  quartiles = "linear",
  whisker = 1.5,
  boxpoints = "none",
  point_size = 5,
  point_alpha = 0.6,
  point_spread = 0.5,
  horizontal = FALSE,
  na_rm = TRUE,
  labels = NULL,
  palette = NULL,
  fill_alpha = 0.25,
  xlab = NULL,
  ylab = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL
)

Arguments

Details

x names one or more columns, one box each. group optionally names a column that splits every box into one per level. Statistics and point placement follow draw_boxplot(). Compiles to BoxplotSeriesOption and CustomSeriesOption in ECharts src/chart/boxplot/BoxplotSeries.ts and src/chart/custom/CustomSeries.ts.

Value

BoxplotConfig object.

Author(s)

EDG

Examples

setup_BoxplotConfig(x = c("mpg", "hp"))@type

Description

Configuration for a boxplot chart series.

Usage

BoxplotSeries(
  name = NULL,
  data = NULL,
  x_axis_index = NULL,
  y_axis_index = NULL,
  silent = NULL,
  legend_hover_link = NULL,
  color = NULL,
  z_level = NULL,
  z = NULL,
  layout = NULL,
  box_width = NULL,
  item_style = NULL,
  label = NULL
)

Arguments

Details

Corresponds to BoxplotSeriesOption in src/chart/boxplot/BoxplotSeries.ts (line 59). ECharts docs: https://echarts.apache.org/en/option.html#series-boxplot

Value

BoxplotSeries object.

Examples

# Each element is one box, given as its five-number summary.
BoxplotSeries(
  name = "Distribution",
  data = list(c(850, 940, 960, 980, 1070), c(750, 800, 840, 890, 1020))
)

Description

Bind binary observation records to a reliability diagram. Each row contains an observed outcome (zero or one) and its predicted probability, optionally grouped by sample or model. Configuration carries column names, not data.

Usage

CalibrationConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  legend_position = "top",
  legend_placement = "outside",
  observed = "observed",
  probability = "probability",
  group = NULL,
  n_bins = 10L,
  bin_method = "quantile",
  na_rm = TRUE,
  mode = "lines+markers",
  show_brier = TRUE,
  rug = TRUE,
  rug_size = 8,
  rug_opacity = 0.3,
  point_size = 7,
  line_width = 2,
  digits = 3L,
  diagonal = TRUE,
  diagonal_color = "#888888",
  palette = NULL,
  legend = TRUE,
  square = TRUE,
  xlab = "Mean predicted probability",
  ylab = "Observed proportion"
)

Arguments

Details

Compiles to LineSeriesOption in src/chart/line/LineSeries.ts and ScatterSeriesOption in src/chart/scatter/ScatterSeries.ts. ECharts docs: https://echarts.apache.org/en/option.html#series-line

Value

A CalibrationConfig object.

Statistical semantics

Bins are computed independently within each group. Equidistant bins partition the unit interval. Quantile bins use linear interpolation at positions (n - 1) * p + 1 in the sorted probabilities (R quantile type 7). Repeated boundaries are collapsed without splitting tied scores. Intervals include their lower boundary and exclude their upper boundary, except that the final interval includes its upper boundary. Constant probabilities form one bin. Empty bins are omitted; lines join the remaining bin means. Each point is the mean predicted probability and mean observed outcome in its bin. The Brier score is the mean squared probability error across all complete observations, before binning. It is not an average of bin errors. Missing pairs are removed together when na_rm is true; invalid finite ranges and infinite values are always rejected. A group with no complete observations is rejected. The probability rug uses those same complete observations and sits just inside the lower plotting edge. Both axes span zero to one. Display precision does not round plotted values. A one-bin curve remains visible as a point even in lines-only mode.

Examples

config <- setup_CalibrationConfig(n_bins = 2L, bin_method = "equidistant")
draw(config, data = data.frame(observed = c(0, 1), probability = c(.2, .8)))

Description

Convert a chart config to a plain list

Usage

chart_config_to_list(config, complete = FALSE)

Arguments

Details

Two forms, matching the two the schema publishes:

• complete = FALSE (default) drops unset properties, so an authored config stays as small as it was authored. type is always kept: it carries the document's shape and is the one key the schema requires.

• complete = TRUE keeps every property, unset ones included, so they serialize as explicit nulls – and stamps the writer. A consumer of such a document can read every key directly instead of reproducing this package's defaults. Requires a full origin map; see write_chart_config().

Value

Named list, ready for jsonlite::toJSON().

Author(s)

EDG

Examples

chart_config_to_list(setup_ScatterConfig(x = "wt", y = "mpg"))

Description

The family's entry point: a document is a chart if it matches exactly one of the leaf schemas, selected by its type.

Usage

chart_dispatcher_schema(classes, id, leaf_ids, title, description)

Arguments

Value

Named list: The JSON Schema, ready for jsonlite::toJSON().

Author(s)

EDG

Examples

schema <- chart_dispatcher_schema(
  classes = list(ScatterConfig, BarConfig),
  id = "https://schemas.rtemis.org/draw/chart.schema.json",
  leaf_ids = c(
    "https://schemas.rtemis.org/draw/scatter.schema.json",
    "https://schemas.rtemis.org/draw/bar.schema.json"
  ),
  title = "Chart",
  description = "Any rtemis.draw chart."
)
schema[["properties"]][["type"]][["enum"]]

Description

Maps each chart type to the class that models it and the ⁠setup_*⁠ that builds one. Read at run time by read_chart_config(), and at generation time by data-raw/generate_schemas.R, so the two cannot disagree about which chart types exist.

Usage

chart_registry()

Value

Named list, one entry per chart type, each with cls and setup.

Author(s)

EDG

Examples

names(chart_registry())

Description

Emits the schema for one ChartConfig subclass: every property it declares or inherits, typed from its PropertySpec, plus a constant for the type discriminator. The result is self-contained – it validates a chart document on its own, without the family dispatcher.

Usage

chart_schema(cls, id, title, description, complete = FALSE)

Arguments

Details

Two kinds, differing only in what they require:

• complete = FALSE (an input config) requires only type. The author sets a subset and the interface fills in the rest.

• complete = TRUE (an output config) requires every property, so a document that claims to be complete can be checked rather than trusted. The chart's own properties may still be null – "this chart has no title" is a fact worth recording – but the provenance maps may not: a document that cannot say where its values came from is not complete, whatever it claims.

Neither emits a default: what an interface fills in is not a fact about the document. Shared structural class rules are emitted in allOf, including inherited rules. Input schemas allow omitted values to be resolved by an interface; record schemas require every value. Numeric ordering, bound-column contents, and statistical/data-dependent checks still run during construction or compilation and cannot be inferred from JSON Schema validation alone.

Value

Named list: The JSON Schema, ready for jsonlite::toJSON().

Author(s)

EDG

Examples

schema <- chart_schema(
  ScatterConfig,
  id = "https://schema.rtemis.org/chart/scatter/v1/schema.json",
  title = "rtemis ScatterConfig",
  description = "Scatter chart."
)
names(schema[["properties"]])

Description

Abstract base for every chart config. Subclasses override type with a constant, which is the discriminator the published schema dispatches on.

Usage

ChartConfig(
  type = NULL,
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL
)

Arguments

Value

ChartConfig object.

Author(s)

EDG

Examples

# ChartConfig is abstract: build one of its subclasses.
config <- setup_ScatterConfig(x = "wt", y = "mpg")
S7::S7_inherits(config, ChartConfig)

Description

A serializable description of a choropleth map. Build one with setup_ChoroplethConfig() rather than calling this constructor directly.

Usage

ChoroplethConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  location = NULL,
  value = NULL,
  tooltip = NULL,
  resolution = "country",
  classification = "quantile",
  num_classes = 5,
  colormap = "blues",
  opacity = 1,
  show_boundaries = TRUE,
  outline_width = 0.2,
  show_legend = TRUE,
  legend_position = "bottom-right",
  tooltip_position = "top-right",
  value_label = NULL
)

Arguments

Value

ChoroplethConfig object.

Author(s)

EDG

Examples

setup_ChoroplethConfig(location = "st", value = "v")@type

Description

Turns a ChartConfig into the backend option object draw() renders – an EChartsOption for ECharts charts. This is where a config's column names are resolved against actual data.

Usage

compile(config, data = NULL, ...)

Arguments

Details

The generic does the two steps every chart needs before its own translation can start, so that no method can forget one: it materializes the data (from data, or from the config's dat_path) and resolve()s the config against it. Methods therefore always receive a resolved config and non-NULL data, and are pure translation.

Value

Render option object, e.g. EChartsOption.

Author(s)

EDG

Examples

config <- setup_ScatterConfig(x = "wt", y = "mpg")
option <- compile(config, data = mtcars)
option@x_axis@name

Description

Retains missing-label frequencies so omission is visible after serialization. Matrix dimnames carry class identity; columns are matched by name, never by an assumed diagonal position. No model dependency is needed for data inputs.

Usage

confusion_input(x, y = NULL, classes = NULL)

Arguments

Value

Data frame with reference, predicted, n, and optionally panel columns.

Examples

confusion_input(factor(c("yes", "no")), factor(c("yes", "yes")))

Description

Portable confusion counts with reference rows and predicted columns. Data consists of long records with class labels and a frequency, optionally grouped into panels. Missing class labels represent omitted pairs; absent class combinations have zero frequency. All panels use the same class order. Compiles to HeatmapSeriesOption in src/chart/heatmap/HeatmapSeries.ts, GridOption in src/coord/cartesian/GridModel.ts, and continuous visual maps. to_list() emits semantic config keys; compile() emits ECharts options. draw() fits square count cells with aligned marginal summaries to the available canvas. Missing-pair omissions are reported in the console. The cell counts show included observations without a separate sample-size label. Color fades and marginal backgrounds follow the active theme unless explicitly overridden.

Usage

ConfusionConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  reference = "reference",
  predicted = "predicted",
  count = "n",
  panel = NULL,
  classes = NULL,
  show_metrics = TRUE,
  digits = 2L,
  ncol = 2L,
  correct_color = "#0F6A66",
  incorrect_color = "#BE2E5F",
  low_color = NULL,
  summary_color = NULL,
  font_size = 12,
  xlab = "Predicted",
  ylab = "Reference"
)

Arguments

Value

A ConfusionConfig object.

Statistical semantics

Color intensity is the fraction within each reference row; labels show raw counts. Sensitivity, specificity, PPV, and NPV are one-versus-rest rates for each named class. Balanced accuracy is mean class recall, including every declared class. Zero denominators produce NA, never zero; consequently balanced accuracy is NA if any declared class has no reference observations. Summaries of pooled resamples describe pooled predictions, not mean fold performance. Repeated observations are counted each time they appear.

Examples

cfg <- setup_ConfusionConfig()
draw(cfg, data = data.frame(reference = c("yes", "no"),
  predicted = c("yes", "no"), n = c(8, 12)))

Description

Axis-range zoom component. ECharts renders dataZoom as an array; common usage pairs a "slider" (visible scrollbar) with an "inside" (mouse-wheel / drag) entry targeting the same axis. Unused styling / mouse-behavior fields stay NULL and are dropped from the serialized output.

Usage

DataZoom(
  type = "slider",
  id = NULL,
  disabled = NULL,
  x_axis_index = NULL,
  y_axis_index = NULL,
  radius_axis_index = NULL,
  angle_axis_index = NULL,
  single_axis_index = NULL,
  filter_mode = NULL,
  start = NULL,
  end = NULL,
  start_value = NULL,
  end_value = NULL,
  min_span = NULL,
  max_span = NULL,
  min_value_span = NULL,
  max_value_span = NULL,
  orient = NULL,
  throttle = NULL,
  range_mode = NULL,
  show = NULL,
  background_color = NULL,
  left = NULL,
  right = NULL,
  top = NULL,
  bottom = NULL,
  width = NULL,
  height = NULL,
  zoom_lock = NULL,
  zoom_on_mouse_wheel = NULL,
  move_on_mouse_move = NULL,
  move_on_mouse_wheel = NULL,
  prevent_default_mouse_move = NULL
)

Arguments

Details

Corresponds to DataZoomOption in src/component/dataZoom/DataZoomModel.ts (line 38), SliderDataZoomOption in src/component/dataZoom/SliderZoomModel.ts (line 38), and InsideDataZoomOption in src/component/dataZoom/InsideZoomModel.ts (line 23). ECharts docs: https://echarts.apache.org/en/option.html#dataZoom

Value

DataZoom object.

Examples

DataZoom(type = "slider", start = 0, end = 50)

Description

A serializable description of a kernel density chart. Build one with setup_DensityConfig() rather than calling this constructor directly.

Usage

DensityConfig(
  dat_path = NULL,
  title = NULL,
  origin = NULL,
  writer = NULL,
  legend_position = "top",
  legend_placement = "outside",
  x = NULL,
  group = NULL,
  mode = "overlap",
  order = "input",
  n = 512L,
  bw = "nrd0",
  bandwidth = NULL,
  kernel = "gaussian",
  adjust = 1,
  fill_alpha = 0.25,
  na_rm = TRUE,
  palette = NULL,
  xlab = NULL,
  ylab = NULL,
  margin_top = NULL,
  margin_right = NULL,
  margin_bottom = NULL,
  margin_left = NULL
)

Arguments

Details

x names one or more numeric columns. group optionally names a column to split it by, drawing one curve per level. The output uses LineSeriesOption in ECharts src/chart/line/LineSeries.ts.

Value

DensityConfig object.

Author(s)

EDG

Examples

setup_DensityConfig(x = "mpg")@type

Description

draw() renders chart configurations and backend option objects as interactive visualizations. It is an 'S7' generic that dispatches on the class of option:

Usage

draw(
  option,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  animation = NULL,
  ...
)

Arguments

Details

• ChartConfig subclasses -> compile the configuration with its data, then render using the corresponding backend.

• EChartsOption -> 'ECharts' (rtemis-draw widget).

• SigmaOption -> 'Sigma.js' (rtemis-graph widget).

• MapLibreOption -> 'MapLibre' (rtemis-map widget).

A plain named list is treated as a raw 'ECharts' option.

Theme handling is uniform across backends and lives on draw(), not on the option object: pass NULL (default) for light/dark auto-detection (from VS Code, RStudio, or the browser's prefers-color-scheme), NA for no theme (raw backend defaults), or a Theme / list to force one.

Value

htmlwidget: Widget object.

Chart configurations

Supported ChartConfig subclasses are A3Config, BarConfig, BoxplotConfig, CalibrationConfig, ChoroplethConfig, ConfusionConfig, DensityConfig, GanttConfig, HeatmapConfig, HistogramConfig, LineConfig, NetworkConfig, PieConfig, ROCConfig, SankeyConfig, ScatterConfig, Scatter3DConfig, SignificanceConfig, SpectrogramConfig, SurvivalConfig, and TimeSeriesConfig. Use their ⁠setup_*()⁠ functions to create configurations, then pass the data to draw() with ⁠data =⁠ or set dat_path on the configuration. See compile() to obtain the backend option without rendering it.

Examples

# Render a chart configuration with data.
config <- setup_ScatterConfig(x = "wt", y = "mpg")
draw(config, data = mtcars)

# Render a backend option directly.
option <- EChartsOption(
  x_axis = Axis(type = "category", data = c("Mon", "Tue", "Wed")),
  y_axis = Axis(type = "value"),
  series = BarSeries(data = c(120, 200, 150))
)
draw(option)

Description

Renders an A3 object (from rtemis.a3) as an interactive ECharts amino-acid sequence diagram. The sequence is wrapped into rows in a meander/serpentine path, with optional site, region, PTM, processing, and variant annotations overlaid as distinct series and collected in an upper-right annotation column, matching rtemislive. Legend headings use native rich text and remain available in vector SVG exports through save_drawing().

Usage

draw_a3(
  x,
  n_per_row = 21L,
  residue_spacing = 0.3,
  marker_size = 28,
  font_size = 18,
  line_width = 2,
  show_markers = TRUE,
  show_labels = TRUE,
  position_every = 10L,
  region_opacity = 0.3,
  ptm_placement = "radial",
  residue_fill = NULL,
  residue_stroke = NULL,
  label_color = NULL,
  pos_label_color = NULL,
  variant_color = NULL,
  disease_variant_color = NULL,
  enable_zoom = TRUE,
  title = NULL,
  grid = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

Details

The annotation column stays at the upper right on every surface. Residue markers, labels, and annotations shrink together to avoid overlap. Row wrapping remains fixed. Browser height follows the layout unless supplied; SVG and panel dimensions remain bounded. A custom grid retains its layout.

Corresponds to createA3EChartsOption() in src/lib/a3/visualization/echarts.ts.

Value

htmlwidget: Widget object.

Examples

if (requireNamespace("rtemis.a3", quietly = TRUE)) {
  a <- rtemis.a3::create_A3(
    "MAEPRQEFEVMEDHAGTYGLGDRK",
    site = list(
      Active_site = rtemis.a3::annotation_position(c(5L, 17L))
    ),
    region = list(
      Domain = rtemis.a3::annotation_range(
        matrix(c(3L, 10L, 15L, 22L), ncol = 2, byrow = TRUE)
      )
    )
  )
  draw_a3(a)
}

Description

Accepts predictions from any model without keeping a fitted R object in the chart. Existing axis limits are preserved, including explicitly requested limits. Annotate child drawings before composing panels. For built-in GLM or GAM estimation, use draw_scatter() or draw_fit().

Usage

draw_add_fit(
  plot,
  x = NULL,
  y = NULL,
  lower = NULL,
  upper = NULL,
  name = "Fit",
  color = "#6ca3a0",
  line_width = 2,
  opacity = 0.2,
  x_axis = 0L,
  y_axis = 0L,
  layer = NULL
)

Arguments

Value

htmlwidget: Drawing with native vector curve and interval layers.

Examples

draw_add_fit(draw_scatter(1:3, c(2, 4, 5)), 1:3, c(2.1, 3.8, 5.1), name = "Predicted")

Description

Fits are computed explicitly before drawing. Supply predictions from any model on a rectangular grid; fitted R objects and callbacks are not stored in the drawing. The prediction grid may extend the original axis ranges. Add surfaces before composing drawings with draw_panels().

Usage

draw_add_surface(
  plot,
  x = NULL,
  y = NULL,
  z = NULL,
  name = "Surface",
  color = "#6ca3a0",
  opacity = 0.35,
  layer = NULL,
  expand = TRUE
)

Arguments

Value

htmlwidget: Drawing with native interactive and vector surface layers.

Examples

x <- y <- seq(-1, 1, length.out = 5)
draw_add_surface(draw_scatter3d(c(-1, 1), c(-1, 1), c(-1, 1)),
  x, y, outer(x, y, `+`), name = "Predicted")

Description

Adds independent native ECharts layers to an existing drawing. For panels, annotate the children before composition. Annotation coordinates use the existing axes and may extend their automatic ranges; explicit limits remain authoritative. References and bands do not alter data summaries.

Usage

draw_annotate(
  plot,
  hline = NULL,
  vline = NULL,
  x = numeric(),
  y = numeric(),
  text = NULL,
  bands = list(),
  color = "#888888",
  line_type = "dashed",
  opacity = 0.15,
  x_axis = 0L,
  y_axis = 0L,
  layer = NULL
)

Arguments

Value

htmlwidget: The drawing with an additional vector annotation layer.

Examples

draw_annotate(draw_scatter(1:5, c(2, 3, 1, 5, 4)), hline = 3)

Description

Quick bar chart from x/y data.

Usage

draw_bar(
  x,
  y = NULL,
  palette = NULL,
  stack = FALSE,
  horizontal = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  bar_width = NULL,
  order = "input",
  legend_position = "top",
  legend_placement = "outside"
)

Arguments

Value

htmlwidget: Widget object.

Examples

draw_bar(x = c("A", "B", "C"), y = c(3, 7, 2), title = "Counts")

Description

Draw one box per numeric vector, optionally split by groups. Statistics use linear-interpolation quartiles (stats::quantile(type = 7)) or Tukey hinges (stats::fivenum()). Whiskers extend to observations within the quartiles plus/minus whisker times their difference, including the quartiles themselves. whisker = 0 uses the full observed range. Values strictly outside the fences are outliers; they are never removed from the quartiles.

Usage

draw_boxplot(
  x,
  labels = NULL,
  group = NULL,
  horizontal = FALSE,
  palette = NULL,
  fill_alpha = 0.25,
  na_rm = TRUE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  verbosity = 1L,
  element_id = NULL,
  filename = NULL,
  observation = NULL,
  quartiles = "linear",
  whisker = 1.5,
  boxpoints = "none",
  point_size = 5,
  point_alpha = 0.6,
  point_spread = 0.5,
  legend_position = "top",
  legend_placement = "outside",
  geometry = "box",
  bandwidth = NULL,
  adjust = 1,
  density_points = 128L,
  paired = FALSE,
  pair_alpha = 0.35,
  pair_width = 1,
  comparisons = NULL,
  order = "input",
  transform = "none"
)

Arguments

Details

All-NA and empty boxes retain their category without a mark; entirely unavailable input is an error. Missing values are reported in the console according to verbosity and never replaced with zero. Missing group assignments are excluded. Axis titles are centered. The category-axis baseline is shown only when the plotted value range includes zero. Every category label is shown so boxes remain identifiable in narrow plots. Use a horizontal layout or a larger figure for many or long category names. With point overlays, padded range endpoints are unlabeled; interior ticks retain the backend's numeric formatting and plotted values are unchanged. Points retain their exact value coordinate. Their perpendicular offsets use a deterministic base-two sequence in input row order within point_spread times the box width. Zero spread centers every point; coincident points can overlap. No random state is read or changed. Browser and SVG share the same named point renderer, including grouped-box offsets and legend filtering.

Violin densities use a Gaussian kernel with stats::bw.nrd0() unless a numeric bandwidth is supplied, multiplied by adjust. They are evaluated over the observed range and each is scaled to the same maximum width; widths do not encode sample size or comparable density across groups. Singleton and constant samples appear as crossbars, without an invented density. geometry = "both" overlays a narrow box on each violin.

Paired lines join matching explicit observation IDs in adjacent categories only, within groups for multiple grouped vectors. A missing measurement leaves a gap. IDs must be unique within each category/group. Lines meet visible observation points at their deterministic offsets.

Comparison records annotate supplied results; no statistical test or multiplicity adjustment is performed. from and to name categories; label supplies the displayed text. Multiple grouped vectors also require from_group and to_group. Optional finite position values place brackets on the value axis; otherwise brackets stack above the observed geometry. References must identify distinct, nonempty cells. Brackets disappear when either endpoint's group is hidden. Long labels may require a larger figure.

Value

htmlwidget: ECharts boxes with optional vector point overlays.

Examples

draw_boxplot(list(Training = c(.8, .9, .85), Test = c(.7, .8, .75)),
  boxpoints = "all", observation = c("Fold1", "Fold2", "Fold3"))
draw_boxplot(iris["Sepal.Length"], group = iris["Species"])

Description

Compare mean predicted probability with observed frequency. Accepts binary labels and probabilities, named lists of paired samples, or individual observation records with observed, probability, and optional group. Named lists are aligned by name. Binary class identity and probability columns follow draw_roc(): positive names the event, and otherwise the second factor level is selected. Named probability columns identify their classes. Samples must share the same positive class.

Usage

draw_calibration(
  true_labels,
  predicted_prob = NULL,
  positive = NULL,
  ...,
  group = NULL,
  legend_position = "top",
  legend_placement = "outside",
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

Value

An ECharts htmlwidget with vector SVG export.

Statistical semantics

Bins are computed independently within each group. Equidistant bins partition the unit interval. Quantile bins use linear interpolation at positions (n - 1) * p + 1 in the sorted probabilities (R quantile type 7). Repeated boundaries are collapsed without splitting tied scores. Intervals include their lower boundary and exclude their upper boundary, except that the final interval includes its upper boundary. Constant probabilities form one bin. Empty bins are omitted; lines join the remaining bin means. Each point is the mean predicted probability and mean observed outcome in its bin. The Brier score is the mean squared probability error across all complete observations, before binning. It is not an average of bin errors. Missing pairs are removed together when na_rm is true; invalid finite ranges and infinite values are always rejected. A group with no complete observations is rejected. The probability rug uses those same complete observations and sits just inside the lower plotting edge. Both axes span zero to one. Display precision does not round plotted values. A one-bin curve remains visible as a point even in lines-only mode.

Examples

labels <- factor(c("no", "yes", "no", "yes"), levels = c("no", "yes"))
draw_calibration(labels, c(.1, .8, .4, .9), n_bins = 2L)

Description

Render a choropleth map with MapLibre GL: regions shaded by a value, joined to vendored administrative boundaries (countries by ISO-A3, US states / counties by FIPS). No basemap tiles – boundaries render on the themed background, with light/dark auto-detection like the rest of ⁠draw_*⁠.

Usage

draw_choropleth(
  x,
  location,
  value,
  resolution = c("country", "state", "county"),
  tooltip = NULL,
  value_label = NULL,
  classification = "quantile",
  colormap = "blues",
  num_classes = 5,
  opacity = 1,
  show_boundaries = TRUE,
  outline_width = 0.2,
  show_legend = TRUE,
  legend_position = "bottom-right",
  tooltip_position = "top-right",
  title = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

Details

The location column is matched to the geometry in the renderer, which accepts ISO-A3 / ISO-A2 / country code for countries, and FIPS / postal abbreviation / full name for US states (5-digit FIPS for counties). A join report in the corner surfaces any unmatched keys.

Value

htmlwidget.

Examples

# Country choropleth from ISO-A3 codes
df <- data.frame(
  iso = c("USA", "CAN", "MEX", "BRA", "FRA"),
  gdp = c(25.5, 2.1, 1.4, 1.9, 2.9)
)
draw_choropleth(df, location = "iso", value = "gdp")

# US states by postal abbreviation, natural-breaks classification
states <- data.frame(
  st = state.abb,
  pop = as.numeric(state.x77[, "Population"])
)
draw_choropleth(
  states,
  location = "st",
  value = "pop",
  resolution = "state",
  classification = "jenks",
  colormap = "viridis"
)

Description

Accepts a square count matrix, a named list of count matrices, long frequency records (reference, predicted, n, optional panel), or paired reference and predicted label vectors. Model packages can add support for metrics objects through confusion_input(). Matrix columns are aligned by label identity; their physical order need not match rows. All panels share one class order.

Usage

draw_confusion(
  x,
  y = NULL,
  classes = NULL,
  ...,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

Value

An ECharts htmlwidget containing every requested panel.

Statistical semantics

Color intensity is the fraction within each reference row; labels show raw counts. Sensitivity, specificity, PPV, and NPV are one-versus-rest rates for each named class. Balanced accuracy is mean class recall, including every declared class. Zero denominators produce NA, never zero; consequently balanced accuracy is NA if any declared class has no reference observations. Summaries of pooled resamples describe pooled predictions, not mean fold performance. Repeated observations are counted each time they appear.

Examples

draw_confusion(factor(c("yes", "yes", "no")), c("yes", "no", "no"))
draw_confusion(matrix(c(8, 2, 1, 9), 2,
  dimnames = list(c("yes", "no"), c("yes", "no"))))

Description

Kernel density estimation plot from numeric data, with optional grouping for multiple traces. A list input creates one density trace per vector when ungrouped, or one trace per variable/group combination when group is supplied. Curves use stats::density() with its bandwidth-scaled kernels and evaluation range extending three bandwidths beyond the data. Empty samples retain their identity without a curve. Singleton and constant samples require an explicit bandwidth; no spread is inferred for them. Missing groups are excluded, and infinite/nonnumeric observations rejected.

Usage

draw_density(
  x,
  group = NULL,
  n = 512,
  bw = "nrd0",
  na_rm = TRUE,
  palette = NULL,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  verbosity = 1L,
  element_id = NULL,
  filename = NULL,
  legend_position = "top",
  legend_placement = "outside",
  bandwidth = NULL,
  kernel = "gaussian",
  adjust = 1,
  fill_alpha = 0.25,
  mode = "overlap",
  order = "input"
)

Arguments

Value

htmlwidget: Widget object.

Examples

draw_density(iris[["Sepal.Length"]], xlab = "Sepal length")

Description

Draw paired observations with a fitted line, standard-error band, and an identity line. The plotting box is square and both axes share an interval. Named lists support samples of different lengths, with one fit per sample.

Usage

draw_fit(
  x,
  y,
  group = NULL,
  fit = "glm",
  se = TRUE,
  se_times = 1.96,
  rsq = TRUE,
  diagonal = TRUE,
  diagonal_color = NULL,
  square = TRUE,
  equal_axes = TRUE,
  xlab = "True",
  ylab = "Predicted",
  ...,
  legend_position = "top",
  legend_placement = "outside"
)

Arguments

Details

The overlay uses the same implementation as draw_scatter() and ScatterConfig. The fit is GLM, GAM, or an rtemis learner named in fit; fit = NULL disables it. Missing pairs and observations with missing groups are dropped together. Infinite values, unequal pair lengths, and multiple response columns are rejected. List names are matched before drawing; unnamed lists are paired by position. Paired NULL entries in lists represent unavailable sets and are omitted.

The equivalent portable configuration is a ScatterConfig binding true, predicted, and sample columns, with fit, se, rsq, diagonal, square, and equal_axes set explicitly. Model objects are not needed to render it.

Value

htmlwidget: ECharts drawing.

Examples

draw_fit(1:5, c(1.2, 1.8, 3.3, 3.8, 5.2))
draw_fit(
  list(Training = 1:5, Test = 2:5),
  list(Training = c(1.2, 1.8, 3.3, 3.8, 5.2), Test = c(2.2, 2.7, 4.3, 4.8))
)

Description

Draw a timeline (Gantt) chart: one horizontal bar per task, positioned by start and end on a value or time x-axis and grouped into rows by label on the y-axis. Implemented as an ECharts custom series (ECharts has no native Gantt series).

Usage

draw_gantt(
  tasks,
  group = NULL,
  axis_type = "value",
  bar_height = 0.6,
  bar_radius = 0,
  guides = TRUE,
  zoom = TRUE,
  tooltip = NULL,
  border = NULL,
  border_color = "#E53935",
  border_width = 1.5,
  xlab = NULL,
  title = NULL,
  palette = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  legend_position = "top",
  legend_placement = "outside"
)

Arguments

Details

The legend uses the shared position/placement controls and reserves enough room for the time axis. Tick density follows the available plotting width, and long task labels are truncated. Default bar tooltips retain the full task text. Browser resizing, panel figures, and SVG export share this layout behavior. Increase height when a timeline contains many task rows.

Value

htmlwidget: Widget object.

Author(s)

EDG

Examples

tasks <- data.frame(
  label = c("load", "clean", "train", "predict"),
  start = c(0, 12, 30, 95),
  end = c(12, 30, 95, 100),
  status = c("ok", "ok", "ok", "error")
)
draw_gantt(tasks, group = "status")

Description

Low-level renderer: takes a GraphModel (or a plain list with nodes, edges, directed) and produces an interactive network htmlwidget backed by Sigma.js + graphology. Most users call draw_network() instead.

Usage

draw_graph(
  model,
  layout = "force",
  node_size = 10,
  edge_scale = 3,
  node_opacity = 0.95,
  edge_opacity = 0.4,
  show_labels = TRUE,
  scale_by_degree = TRUE,
  color_by_group = FALSE,
  resolution = 1,
  blend_edges = FALSE,
  palette = palette_colors(rtemis_colors),
  node_color = rtemis_colors[["teal"]],
  positive_color = rtemis_colors[["teal"]],
  negative_color = "#ff9e1f",
  title = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

Value

htmlwidget.

Examples

model <- GraphModel(
  nodes = list(GraphNode(id = "a"), GraphNode(id = "b")),
  edges = list(GraphEdge(source = "a", target = "b")),
  directed = FALSE
)
draw_graph(model)

Description

Quick heatmap from a numeric matrix. Designed to handle all common use cases including correlation matrices (square cells, diverging color scale), general rectangular heatmaps, and clustered heatmaps.

Usage

draw_heatmap(
  x,
  row_names = NULL,
  col_names = NULL,
  triangle = NULL,
  cluster_rows = FALSE,
  cluster_cols = FALSE,
  dist_method = "euclidean",
  hclust_method = "complete",
  show_row_dendro = TRUE,
  show_col_dendro = TRUE,
  dendro_row_width = 60,
  dendro_col_height = 60,
  dendro_color = NULL,
  dendro_uniform = FALSE,
  dendro_row_side = "right",
  dendro_col_side = "top",
  square_cells = NULL,
  colormap = NULL,
  zlim = NULL,
  show_values = FALSE,
  value_digits = 2L,
  show_colorbar = TRUE,
  colorbar_orient = "vertical",
  title = NULL,
  theme = NULL,
  margins = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  legend_position = if (colorbar_orient == "horizontal") "bottom" else "right",
  legend_placement = "outside",
  row_tree = NULL,
  col_tree = NULL,
  cell_notes = NULL,
  row_colors = NULL,
  col_colors = NULL,
  show_notes = FALSE,
  row_cut = NULL,
  col_cut = NULL
)

Arguments

Details

Color encoding is driven by a continuous VisualMap component. Hierarchical clustering is performed in R via hclust(); rows and columns are reordered accordingly. When cluster_rows or cluster_cols is TRUE (and the corresponding ⁠show_*_dendro⁠ flag is not FALSE), a dendrogram panel is rendered alongside the heatmap as an ECharts custom series.

Value

htmlwidget: Widget object.

Examples

draw_heatmap(cor(mtcars[, 1:5]), title = "Correlation")

Description

Histogram from numeric data, with optional grouping for multiple traces. Bins are computed using graphics::hist() with consistent break points across groups. Rectangles span their actual numeric intervals, including unequal widths. Grouped samples overlap with translucent fills. Intervals are right-closed, with the lowest edge included, using hist() boundary tolerance. Missing groups are excluded; empty samples have zero counts.

Usage

draw_histogram(
  x,
  group = NULL,
  breaks = "Sturges",
  palette = NULL,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  legend_position = "top",
  legend_placement = "outside",
  bins = NULL,
  bin_edges = NULL,
  normalization = "count",
  density = FALSE,
  n = 512L,
  bw = "nrd0",
  bandwidth = NULL,
  kernel = "gaussian",
  adjust = 1,
  fill_alpha = 0.25,
  na_rm = TRUE,
  verbosity = 1L,
  mode = "overlap",
  order = "input",
  bin_stat = "count",
  bar_mode = "overlay"
)

Arguments