RunScatter plot

The runscatter function visualizes raw or processed feature signals across different sample/QC types along the analysis sequence. It helps identify trends, detect outliers, and assess analytical performance. Available feature variables, such as retention time (RT) and full width at half maximum (FWHM), can be plotted against analysis order or timestamps.

By default, all QC types present in the dataset will be plotted. User-defined QC types that have no predefined color or shape in mrmhub are assigned black shapes. To show specific QC types, use the qc_types argument.

To plot the feature values before the last applied drift/batch correction, add *_before to the variable name, e.g., intensity_before or conc_before. To plot the uncorrected feature values (before any drift/batch correction), add *_raw to the variable name, e.g., intensity_raw or conc_raw. To show corresponding fit curves, set show_trend = TRUE.

The function also supports visualizing analysis batches, reference lines (mean \(\pm\) SD), and trends. It offers customization options to display batch separators, apply outlier capping, show smoothed trend curves, add reference lines, and incorporate other features. Outlier capping is particularly useful to focus on QC or study sample trends that might otherwise be obscured by extreme values or high variability.

The runscatter function serves as a central QC tool in the workflow, providing critical insights into data quality.

Usage

plot_runscatter(
  data = NULL,
  variable,
  qc_types = NA,
  filter_data = FALSE,
  include_qualifier = TRUE,
  include_istd = TRUE,
  include_feature_filter = NA,
  exclude_feature_filter = NA,
  plot_range = NA,
  output_pdf = FALSE,
  path = NA,
  create_dir = TRUE,
  multithreading = FALSE,
  return_plots = FALSE,
  show_batches = TRUE,
  batch_zebra_stripe = FALSE,
  batch_line_color = "#b6f0c5",
  batch_fill_color = "grey93",
  cap_outliers = FALSE,
  cap_sample_k_mad = 4,
  cap_qc_k_mad = 4,
  cap_top_n_outliers = NA,
  show_reference_lines = FALSE,
  ref_qc_types = NA,
  reference_k_sd = 2,
  reference_batchwise = FALSE,
  reference_line_color = "#04bf9a",
  reference_sd_shade = FALSE,
  reference_fill_color = NA,
  reference_linewidth = 0.75,
  show_trend = FALSE,
  trend_color = "#22e06b",
  y_lim = c(0, NA),
  log_scale = FALSE,
  show_gridlines = FALSE,
  point_size = NULL,
  point_alpha = 1,
  point_border_width = NA,
  font_base_size = NULL,
  autoscale = TRUE,
  legend_position = NULL,
  legend_size = NULL,
  show_legend_title = NULL,
  title = NULL,
  strip_text_size = NULL,
  strip_bg_color = NULL,
  legend_bg_alpha = NULL,
  rows_page = 3,
  cols_page = 3,
  specific_page = NA,
  page_orientation = "LANDSCAPE",
  page_width = NULL,
  page_height = NULL,
  page_units = "mm",
  y_label_text = NA,
  pages_per_core = 1,
  use_dingbats = TRUE,
  show_progress = TRUE,
  remove_gaps = FALSE,
  collapse_excluded = FALSE,
  gap_line_color = "#e34a33",
  gap_line_width = 0.3,
  gap_label_size = 2.5,
  gap_scale = 1,
  label_wrap = FALSE,
  label_wrap_width = 25
)

Arguments

data: A MRMhubExperiment object.
variable: The variable to plot on the y-axis, one of 'intensity', 'norm_intensity', 'conc', 'rt', 'fwhm', 'area', 'height', 'response'. Add _before after the variable name to plot the feature values before the last applied drift/batch correction, (e.g., conc_before). Add _raw after the variable name to plot the raw uncorrected feature values (e.g., conc_raw).
qc_types: QC types to be plotted. Can be a vector of QC types or a regular expression pattern. NA (default) displays all available QC/Sample types.
filter_data: Logical, whether to use QC-filtered data based on criteria set via filter_features_qc().
include_qualifier: Logical, whether to include qualifier features. Default is TRUE.
include_istd: Logical, whether to include internal standard (ISTD) features. Default is TRUE.
include_feature_filter: Feature(s) to include by feature_id, as a character vector. Each element is matched exactly when it names an existing feature, otherwise treated as a regex; elements combine with OR. A full ID (e.g. "S1P d18:0 [M>60]") needs no escaping, while patterns like "PC|PE" still work. NA or "" ignores the filter.
exclude_feature_filter: Feature(s) to exclude by feature_id, matched the same way as include_feature_filter. NA or "" ignores the filter.
plot_range: Numeric vector of length 2, specifying the start and end indices of the analysis order to be plotted. NA plots all samples.
output_pdf: Logical, whether to save the plot as a PDF file.
path: File name for the PDF output.
create_dir: A logical value. If TRUE (the default) and output_pdf is TRUE, the parent directory of path is created if it does not yet exist.
multithreading: Logical, whether to use parallel processing to speed up plot generation.
return_plots: Logical, whether to return the list of ggplot objects.
show_batches: Logical, whether to show batch separators in the plot.
batch_zebra_stripe: Logical, whether to display batches with alternating shaded and non-shaded areas.
batch_line_color: Color of the batch separator lines.
batch_fill_color: Color for the shaded areas representing batches.
cap_outliers: Logical, whether to cap upper outliers based on MAD fences of SPL and QC samples.
cap_sample_k_mad: Numeric, k * MAD (median absolute deviation) for outlier capping of SPL samples.
cap_qc_k_mad: Numeric, k * MAD (median absolute deviation) for outlier capping of QC samples.
cap_top_n_outliers: Numeric, cap the top n outliers regardless of MAD fences. NA or 0 ignores this filter.
show_reference_lines: Whether to display reference lines (mean \(\pm\) n x SD).
ref_qc_types: QC type for which the reference lines are calculated.
reference_k_sd: Multiplier for standard deviations to define SD reference lines.
reference_batchwise: Whether to calculate reference lines per batch.
reference_line_color: Color of the reference lines.
reference_sd_shade: TRUE plots a colored band indicating the \(\pm\) n x SD reference range. FALSE (default) shows reference lines instead.
reference_fill_color: Fill color of the batch-wise reference ranges. If NA (default), the color assigned to the qc_type is used.
reference_linewidth: Width of the reference lines.
show_trend: If TRUE trend curves before or after drift/batch correction are shown.
trend_color: Color of the trend curve.
y_lim: Numeric vector of length 2, specifying the lower and upper y-axis limits. Default is c(0,NA), which sets the lower limit to 0 and the upper limit automatically.
log_scale: Logical, whether to use a log10 scale for the y-axis.
show_gridlines: Whether to show major x and y gridlines.
point_size: Size of the data points. Default is 1.5.
point_alpha: Alpha transparency of the data points.
point_border_width: Width of the data point borders.
font_base_size: Numeric. Base font size (in points) for plot text; all plot text scales proportionally with this value. NULL (default) uses the global default set by mrmhub_set_plot_defaults() if one is in effect, otherwise an automatic size (derived from the facet-column count on paged plots, or the per-plot default shown in the Usage section above).
autoscale: Logical. When TRUE (default), font_base_size and point_size left as NULL are sized automatically from cols_page (more facet columns per page give smaller text and points). Any value passed explicitly always takes precedence. When FALSE, unset sizes fall back to the single-plot defaults.
legend_position: Optional legend placement. One of "right", "left", "top", "bottom", "none"; a corner keyword "inside-tr", "inside-tl", "inside-br", "inside-bl"; or a numeric c(x, y) in [0, 1] coordinates. NULL (default) keeps the current placement, unless a global default is set with mrmhub_set_plot_defaults().
legend_size: Optional single multiplier of font_base_size (when <= 3) or absolute point size (when > 3) that scales the whole legend: text, title, key and the plotted symbols. NULL (default) leaves the legend unchanged.
show_legend_title: Logical. NULL (default) keeps the legend title, unless a global default is set with mrmhub_set_plot_defaults(); FALSE hides it, TRUE forces it shown.
title: Optional plot title. NULL (default) or NA shows no title; a character string is shown as the title.
strip_text_size: Optional facet strip text size, as a multiplier of font_base_size (when <= 3) or an absolute point size (when > 3). NULL (default) inherits from font_base_size.
strip_bg_color: Optional facet strip background fill colour. The strip text colour is set automatically for contrast (white on a dark fill, black on a light one). NULL (default) keeps the house dark-navy strips.
legend_bg_alpha: Optional opacity ([0, 1]) of a white legend background box, useful for a readable inside legend drawn over points. NULL (default) leaves the legend background unchanged.
rows_page: Number of rows per page.
cols_page: Number of columns per page.
specific_page: Show/save a specific page number only. NA plots/saves all pages.
page_orientation: Page orientation, "LANDSCAPE" or "PORTRAIT". Ignored when page_width and page_height are given.
page_width, page_height: Size of a PDF page, in page_units. Both must be given together. NULL (default) uses an A4 page of 280 x 200 mm, oriented by page_orientation. When an explicit size is given, page_orientation has no effect.
page_units: Unit of page_width and page_height: "mm" (default), "cm", "in" or "pt".
y_label_text: Override the default y-axis label text.
pages_per_core: Number of pages to be plotted by core when multithreading is enabled. Default is 6. Changing this number may improve performance.
use_dingbats: Logical, whether to use Dingbats font in the PDF output for improved plotting speed. Default is TRUE. Set to FALSE if your PDF viewer does not show points correctly.
show_progress: Logical, whether to show a progress bar. Default is TRUE.
remove_gaps: Logical. If TRUE, contiguous indices replace the original analysis_order on the x-axis so that missing/filtered samples no longer leave large gaps. Each gap is highlighted with a thick vertical line and annotated with the flanking analysis-order IDs. Default is FALSE.
collapse_excluded: Logical. If TRUE, gaps in the x-axis caused by QC types that were not selected (via qc_types) are collapsed, re-indexing x to a contiguous sequence. Default is FALSE.
gap_line_color: Color of the vertical gap-indicator lines. Default is "#e34a33".
gap_line_width: Line width of the vertical gap-indicator lines. Default is 0.3.
gap_label_size: Font size of the gap-boundary labels. Default is 2.5.
gap_scale: Numeric multiplication factor for the gap band width. Default is 1. Increase (e.g. 2) for wider gaps, decrease for narrower.
label_wrap: Logical. If TRUE, long feature_id labels are wrapped to multiple lines using label_wrap_width. Default is FALSE.
label_wrap_width: Integer. Maximum width in characters for wrapped labels when label_wrap = TRUE. Default is 25. Ignored when label_wrap = FALSE.

Value

A list of ggplot objects if return_plots = TRUE, otherwise NULL (the plots are drawn to the active device or written to a PDF).

Details

The outlier capping feature (cap_outliers) allows you to cap upper outliers based on median absolute deviation (MAD) fences of SPL and QC samples, or to remove the top n points. This can help to focus on the trends of interest when there are outlier or a high variability in the data, e.g. in the study samples.
When using log-scale (log_scale = TRUE), zero or negative values will be replaced with the minimum positive value divided by 5 to avoid log 0 errors
Reference lines/ranges corresponding to mean \(\pm\) k x SD can be shown across or within batches as lines or shaded stripes.
Trend curves can be displayed before or after drift/batch correction. In either case, a drift and/or batch correction must be applied to the data to enable plotting of trend curves. To show trend curves used for the last drift or batch correction, add "_before" to the variable name, e.g. conc_before or intensity_before and set show_trend = TRUE.

Preferred formats and devices

Purpose	Format	Device used	Typical `dpi`
Journal figure, vector (default choice)	`"pdf"`	`grDevices::cairo_pdf`, else `grDevices::pdf`	n/a
Figure for further editing (Illustrator, Inkscape)	`"svg"`	`svglite::svglite`, else `grDevices::svg`	n/a
Slides, Quarto HTML, GitHub	`"png"`	`ragg::agg_png`, else `grDevices::png`	150-300
Journal requiring raster submission	`"tiff"`	`ragg::agg_tiff`, else `grDevices::tiff`	300-600

Prefer a vector format (pdf, svg) for publication: text stays selectable and searchable, and lines stay sharp at any magnification.

Prefer a raster format (png, tiff) when a plot draws very many marks – a plot_runscatter() page covering several thousand analyses, or a dense plot_pca() score plot. Every point becomes a separate object in a PDF, so such figures produce very large files that are slow to open and to typeset. Saving them at 300-600 dpi instead keeps the file small with no visible loss.

The optional packages ragg and svglite are used automatically when installed, giving better text rendering, system-font support and smaller SVG files. When they are absent the equivalent grDevices device is used and the output is still correct. Installing both is recommended: install.packages(c("ragg", "svglite")).

PDF output uses the cairo device wherever R was built with cairo support (capabilities("cairo")), because plain grDevices::pdf() writes text in a single-byte encoding and silently transliterates anything outside it – an en dash becomes -, >= replaces the proper symbol. Unit labels such as umol/L and statistical annotations routinely depend on those glyphs.

Multi-page output from the paged plot functions (plot_runscatter(), plot_calibrationcurves(), plot_responsecurves(), plot_feature_correlations()) is PDF only, which is the only format that holds many pages in one file. Use save_plot() for single figures in any of the other formats.

Usage

Arguments

Value

Details

Preferred formats and devices

See also