Plot scan data — ir_plot_scans • isoreader2

Plots scan data from an ir_aggregate_isofiles() result or a plain data frame. The data is prepared with ir_generate_scans_tibble() (which, for an ir_aggregated_data object, inner-joins the $scans dataset with $metadata). The plot data must contain species, x, scan_type, x_units, mass, and an intensity.* column — an error is thrown if any are missing. A trace identifier ("<species>: <mass>") is always regenerated and the plotted value together with a data_type label ("intensity [UNITS]", or "ratios" for ratio rows) are added. scan_type and x_units are combined for the x axis label.

Usage

ir_plot_scans(
  dataset,
  scan_type = NULL,
  species = NULL,
  mass = NULL,
  ratio = NULL,
  facet = NULL,
  data_type_as_facet = auto(),
  scales = "free",
  nrow = NULL,
  ncol = 1,
  color = trace,
  linetype = NULL,
  color_values = palette.colors(),
  drop_unused_levels = FALSE,
  scientific = FALSE,
  x_window = NULL,
  n_x_breaks = 5,
  n_y_breaks = 5,
  ...
)

Arguments

dataset: an ir_aggregated_data object from ir_aggregate_isofiles() or a plain data frame with species, x, scan_type, x_units, mass, and an intensity.* column
scan_type: which scan type to plot (e.g. "high voltage"). Required when the data contains more than one scan type; an error lists the available types. If the data contains only one scan type, the parameter must either be NULL or match that type exactly.
species: optional vector to filter the displayed data to specific species (e.g. "CO2" or c("N2", "CO2")); default NULL shows all species.
mass: which masses to include as intensity traces: NULL (default) shows all masses, a vector (e.g. 44 or c(44, 45)) shows specific masses, and a zero-length vector (numeric(0)/character(0)) shows none. Note that c() is NULL in R (i.e. all masses).
ratio: which ratios to additionally include (computed with ir_calculate_ratios()): NULL (default) shows all available ratios, a character vector of ratio names (e.g. c("45/44", "46/44")) shows specific ones, and character(0) shows none. Requesting specific ratio names when ratios have not been calculated is an error pointing to ir_calculate_ratios() (with ratio = NULL and no ratios present, none are simply added). Ratio rows are plotted on the same value axis with data_type = "ratios"; the default facet = data_type (with free scales) separates them from the intensities.
facet: column or expression to facet by (default: NULL, no extra faceting). When data_type is used as a facet row (see data_type_as_facet), a single facet variable becomes the facet_grid column (data_type ~ facet) and a NULL facet gives data_type ~ .. Otherwise a plain column or expression (e.g. file_name or paste(species, mass)) is faceted with ggplot2::facet_wrap(), and a two-sided formula (e.g. species ~ mass) is faceted with ggplot2::facet_grid(). Set to NULL to suppress faceting.
data_type_as_facet: whether the data_type column (intensities vs ratios) is used as the ggplot2::facet_grid() row variable: auto() (default) uses it only when more than one data type is present; TRUE always uses it; FALSE never does. When used, the y axis label is dropped (the facet strip provides it) and the facet becomes data_type ~ . (a NULL facet) or data_type ~ facet (a single-variable facet). It is ignored when facet is a two-sided formula (a warning is issued if data_type_as_facet = TRUE is combined with a formula facet, since the two are mutually exclusive).
scales: whether facet scales should be "free" (default), "fixed", "free_x", or "free_y"; passed on to ggplot2::facet_wrap() / ggplot2::facet_grid().
nrow, ncol: number of rows and columns of facet panels (nrow default NULL lets ggplot2 choose; ncol default 1 stacks the panels in a single column). Only applies when facet is a single variable or expression (faceted with ggplot2::facet_wrap()); ignored when facet is a formula (faceted with ggplot2::facet_grid()), with a warning if you set them explicitly.
color: column or expression for the colour aesthetic (default: trace, the per-species/mass trace identifier, e.g. "CO2: 44"). When colouring by trace, traces that share the same species and (numerator) mass are given the same colour, so an intensity trace ("N2: 29") and its ratio traces ("N2: 29/28") match.
linetype: column or expression for the linetype aesthetic (default: NULL, i.e. no linetype aesthetic)
color_values: named or unnamed character vector of colours passed to ggplot2::scale_color_manual(), or NULL to use the ggplot2 default colour palette (default: palette.colors())
drop_unused_levels: whether to drop unused trace factor levels (e.g. traces that are absent after zooming to a window) from the colour scale and legend. Default FALSE keeps every level so the colour mapping stays stable across subsets of the same dataset; set to TRUE to show only the levels actually present in the plotted data.
scientific: whether to format y axis labels in scientific notation (default: FALSE)
x_window: optional numeric vector of length 2 giving the x axis display window c(min, max) (must have min < max). The data point just outside each edge of the window is retained so the clipped lines interpolate correctly across the window boundaries and y autoscales correctly at the edges; ggplot2::coord_cartesian() clips the display. A window that contains no data points of its own is allowed (the line is drawn between the bracketing points). Default NULL shows the full x range.
n_x_breaks: desired number of x axis tick marks (default: 5)
n_y_breaks: desired number of y axis tick marks (default: 5)
...: additional arguments passed on to ggplot2::facet_wrap() or ggplot2::facet_grid() (e.g. labeller)

Value

a ggplot object with ir_default_theme() applied. To customize the plot, add ggplot2 layers on top (e.g. + ggplot2::theme(...) or + ggplot2::labs(...)); attach ggplot2 with library(ggplot2) first.