Plot standardized feature intensities grouped by QC type

This function creates a grouped beeswarm plot of standardized feature intensities, where each value is shown as a percentage of the feature's median over the plotted non-blank analyses (per batch with batchwise_normalization = TRUE). Points are grouped by qc_type and spread using quasirandom jitter. An ISTD signal higher in process blanks (ISTD without matrix) than in the samples may indicate ion suppression by the sample matrix. The spread between study samples and pooled QCs can reflect sample-to-sample differences in matrix effects.

Usage

plot_matrixeffects(
  data,
  variable = "intensity",
  qc_types = c("SPL", "TQC", "PBLK", "BQC"),
  batchwise_normalization = TRUE,
  include_qualifier = FALSE,
  only_istd = TRUE,
  include_feature_filter = NA,
  exclude_feature_filter = NA,
  min_median_value = NA,
  y_lim = c(-NA, NA),
  point_size = NULL,
  dodge_width = 0.6,
  point_alpha = 0.3,
  box_alpha = 0.3,
  box_linewidth = 0.5,
  font_base_size = NULL,
  legend_position = NULL,
  legend_size = NULL,
  show_legend_title = NULL,
  title = NULL,
  angle_x = 45
)

Arguments

data: A MRMhubExperiment object.
variable: A character string indicating the signal variable to plot. Must be one of: "area", "height", "intensity", "norm_intensity", "response", "conc", "conc_raw", "rt", "fwhm".
qc_types: A character vector specifying the QC types to plot. It must contain at least one element. The default NA plots any of the non-blank QC types ("SPL", "TQC", "BQC", "HQC", "MQC", "LQC", "NIST", "LTR") present in the dataset. A single value that is a QC type is matched exactly; any other single value is a regular expression, e.g. "QC$" for all QC types ending in "QC".
batchwise_normalization: A logical value indicating whether to normalize the signals by batch instead of globally.
include_qualifier: A logical value indicating whether to include qualifier features. Default is FALSE.
only_istd: A logical value indicating whether to show only internal standard (ISTD) features. Default is TRUE. Set to FALSE in combination with feature_filter parameters to show other features.
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.
min_median_value: Minimum median feature value across the selected QC-type samples required for a feature to be included. NA (default) applies no filtering. This is a fast way to exclude noisy features; for principled QC-based filtering use filter_features_qc().
y_lim: A numeric vector of length 2 specifying the y-axis limits.
point_size: A numeric value indicating the size of points in millimeters. Default is 0.5.
dodge_width: Numeric. Width used to dodge overlapping points by qc_type. Default is 0.6.
point_alpha: Numeric. Transparency of the plotted points. Default is 0.3.
box_alpha: Numeric. Transparency of the boxplot. Default is 0.3.
box_linewidth: Numeric. Width of the boxplot lines. Default is 0.5.
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).
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.
angle_x: Numeric. Angle of the x-axis text labels. Default is 45.

Value

A ggplot object showing the grouped standardized beeswarm plot.

Details

Include at least one QC type besides the study samples: the reference is computed from the plotted analyses, so with study samples only they centre on 100% by construction. The plot compares ISTD signals between samples; it does not measure the matrix effect itself.

Plot standardized feature intensities grouped by QC type

Usage

Arguments

Value

Details

See also