plot_MultiExponential: Advanced plot function for displaying component resolved...

In OSLdecomposition: Signal Component Analysis for Optically Stimulated Luminescence

Advanced plot function for displaying component resolved signal curves

Description

This function plots multi-exponentially decaying measurements and its signal components. plot_OSLcurve is a wrapper for this function.

This function was black-box tested prior release. These tests as well as code examples are available at: https://luminescence.de/OSLdecomposition/module_tests/Test_plot_MultiExponential.html

Usage

plot_MultiExponential(
  curve = NULL,
  components = NULL,
  fill.components = TRUE,
  linear.modulation = FALSE,
  xlog = FALSE,
  ylog = FALSE,
  main = NULL,
  xlab = "Time",
  ylab = "Signal",
  xlim = NULL,
  ylim = NULL,
  font.size = 10,
  graph.colors = NULL,
  graph.names = NULL,
  legend.position = "right",
  legend.justification = NULL,
  theme.set = ggplot2::theme_classic(),
  hide.plot = FALSE
)

Arguments

curve	data.frame or matrix or Luminescence::RLum.Data.Curve (optional): Measured signal curve. First column is used as x-axis, second column is used as y-axis. Further columns are ignored. If this argument is NULL but a component table is given, signal components and a modeled multi-exponential signal curve will be displayed nonetheless.
components	data.frame or numeric vector (optional) Either table with the signal component parameters or numeric vector with decay rates. The component parameter table is usually given by fit_OSLcurve or decompose_OSLcurve. If handmade, it needs the columns ⁠$names⁠, ⁠$lambda⁠ and ⁠$n⁠.T This argument also accepts numeric vectors, the component intensity will be calculated automatically using decompose_OSLcurve. If the vector elements are named, these names will be used as component names.
fill.components	logical (with default): If TRUE, signal components are displayed ad stacked areas. Otherwise they are displayed as line graphs.
linear.modulation	logical (with default): If TRUE, all graphs are transformed to linear modulated curves, a peak-like representation for decay curves. See Bulur (2000) and Bos and Wallinga (2012) for details.
xlog	logical (with default): If TRUE, x-axis is transformed to logarithmic scale.
ylog	logical (with default): If TRUE, y-axis is transformed to logarithmic scale.
main	character (optional): Plot title, drawn at the top left of the diagram.
xlab	character (optional): Axis title of the x-axis.
ylab	character (optional): Axis title of the y-axis.
xlim	numeric vector (optional): Minimum and maximum c(min, max) of the x-scale.
ylim	numeric vector (optional): Minimum and maximum c(min, max) of the y-scale.
font.size	numeric (with default): Scale factor for all text elements. Legend title and main title are one bigger
graph.colors	character vector (optional): Color for the graphs/stacked areas are defined in the following order: 1. Measurement, 2. Model, 3. Component 1, 4. Component 2, etc. The color vector is allowed to be shorter than the needed colors. For missing colors, the default colors will be used
graph.names	character vector (optional): Alternative graph names which shall be displayed in the legend. The names are defined in the following order: 1. Measurement, 2. Model, 3. Residual, 4. Component 1, 5. Component 2, etc.. For missing names, the default names will be used.
legend.position	character two-point numeric vector (with default): Position of the plot legend (for example "bottom" or c(1,1)). Set to "none" for not drawing a legend. This argument is forwarded to ggplot2::theme.
legend.justification	character two-point numeric vector (with default): Anchor point for positioning the legend (for example "right" or c(1,1)). This argument is forwarded to ggplot2::theme.
theme.set	ggplot2::ggplot2-package object (with default): Graphical theme of the output plot. This argument is forwarded to ggplot2::theme_set. Recommended themes are ggplot2::theme_minimal(), ggplot2::theme_classic() and ggplot2::theme_bw(), see ggplot2::theme_bw or here for a full list.
hide.plot	logical (with default): If true, plot is not drawn but can still be saved as file or caught by A <- plot_OSLcurve(...). If caught, the plot can be drawn manually for example by using gridExtra::grid.arrange.

Value

Returns an invisible ggplot2::ggplot object containing the plot "Invisible" means, the no value will be returned (e.g. no console printout) if the function is not assigned to a variable via ⁠<-⁠. If the function is assigned, the returned object can be further manipulated by ggplot2::ggplot2-package methods or manually drawn by various functions like for example gridExtra::grid.arrange.

Last update

2024-08-29, DM: Forked this function from plot_OSLcurve

Author(s)

Dirk Mittelstraß, [e-mail]

Please add the following references to your publication: Your currently used package version, obtained by citation("OSLdecomposition")

Mittelstraß, D., Schmidt, C., Kreutzer, S., Beyer, J., Straessner, A. and Heitmann, J.: R package OSLdecomposition: Automated signal component analysis of multi-exponential decays for optically stimulated luminescence applications., in preparation.

References

Bos, A. J. J. and Wallinga, J., 2012. How to visualize quartz OSL signal components, Radiation Measurements, 47(9)

Bulur, E., 2000. A simple transformation for converting CW-OSL curves to LM-OSL curves, Radiation Measurements, 32(2)

See Also

plot_OSLcurve, fit_OSLcurve, simulate_OSLcomponents

Examples

library(ggplot2)

# Set some arbitrary decay parameters
decay_rates <- c(Fast = 1.2, Medium = 0.2, Slow = 0.02)

# Simulate a CW-OSL curve including some signal noise and signal background
curve <- simulate_OSLcomponents(data.frame(lambda = decay_rates,
                                           n = c(1000, 2000, 10000)),
                                simulate.curve = TRUE,
                                add.poisson.noise = TRUE,
                                add.background = 10)

# Plot the simulated curve and its signal components
plot_MultiExponential(curve, decay_rates)

# For more examples, follow the link to the module tests given in the description section.

OSLdecomposition documentation built on Sept. 1, 2025, 1:09 a.m.