plot_OSLcurve {OSLdecomposition}

Advanced plot function for component resolved CW-OSL curves

Description

This function is used for plotting CW-OSL curves and its signal components. It can handle data returned by fit_OSLcurve or decompose_OSLcurve. Besides CW-OSL curves, pseudoLM-OSL curves and residual plots can also be plotted.

Usage

plot_OSLcurve(
  curve = NULL,
  components = NULL,
  display = "detailed",
  show.legend = TRUE,
  show.intervals = FALSE,
  show.crosssec = FALSE,
  show.initial = FALSE,
  theme.set = ggplot2::theme_classic(),
  title = NULL,
  hide.plot = FALSE,
  filename = NULL
)

Arguments

curve

data.frame or matrix or RLum.Data.Curve (optional): CW-OSL curve x-Axis: ⁠$time⁠ or first column as measurement time (must have constant time intervals); y-Axis: ⁠$signal⁠ or second column as luminescence signal. Other columns will be plotted as component curves, in case no input object components is defined. If no input is given, a CW-OSL curve will be simulated with the parameters of components

components

data.frame (optional): Table with OSL component parameters. The parameters are used to approximate separate signal decay curves for each component. Need to have at least the columns: ⁠$names⁠, ⁠$lambda⁠ and ⁠$n⁠. If an insufficient or no input object is provided, the 'curve“ object will be searched for component-related signal values.

display

character (with default): Sets the arrangement of graphs, see section Details.

show.legend

logical (with default): Draws a legend in the top right corner of the first graph.

show.intervals

logical (with default): Draws vertical lines into the residual plot showing the signal bin intervals (if available) for the CW-OSL decomposition with decompose_OSLcurve.

show.crosssec

logical (with default): Displays photoionisation cross section values in the component table (if available).

show.initial

logical (with default): Displays signal share at the first channel in the component table (if available).

theme.set

ggplot2 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.

title

character (with default): Plot title. Overwrites automatic titles but affects just the first (upper left) graph in case of multi-graph display setting. Set title = NULL for auto-title and title = "" for no title.

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.

filename

character (optional): File name or path to save the plot as image. If just a file name is given, the image is saved in the working directory. The image type is chosen by the file ending. Both, vector images as well as pixel images are possible. Allowed are .pdf, .eps, .svg (vector graphics), .jpg, .png, .bmp (pixel graphics) and more, see ggplot2::ggsave.

Details

Change graph types with parameter: display

"detailed"	(default) Output plot consists of: Linear CW-OSL plot, pseudoLM-OSL plot, residual curve and component table
"lin"	Linear CW-OSL plot only
"compare_lin"	Linear CW-OSL plot with residual curve below and component table on bottom. Useful if two CW-OSL measurements shall be compared side by side
"log"	CW-OSL plot with logarithmic y-Axis and linear x-Axis
"compare_log"	CW-OSL plot with logarithmic y-Axis with residual curve below and component table on bottom. Useful if two CW-OSL measurements shall be compared side by side
"loglog"	Double-logarithmic CW-OSL plot
"LM"	PseudoLM-OSL plot
"res"	Plot of residual curve: Measurement minus fitting model
"tab"	Table of component parameters as image
"raw"	Raw x-y plot without further data

PseudoLM-OSL curves are created using the transformation described by Bulur (2000). The stimulation ramp duration is twice the CW-OSL duration. See Bos and Wallinga (2012) for a detailed explanation and discussion.

Value

An invisible ggplot2::ggplot object containing the diagram will returned. "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-package methods or manually drawn by various functions like for example gridExtra::grid.arrange.

Last update

2021-03-29, DM: Hidden output objects are now ggplot2 objects if the plot is not a composite diagram

Author(s)

Dirk Mittelstraß, [e-mail]

Please cite the package the following way:

Mittelstraß, D., Schmidt, C., Beyer, J., Heitmann, J. and Straessner, A.: R package OSLdecomposition: Automated identification and separation of quartz CW-OSL signal components, 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

fit_OSLcurve, [RLum.OSL_decomposition, RLum.OSL_global_fitting, simulate_OSLcomponents

Examples

# Set some arbitrary decay parameter for a dim CW-OSL measurement of quartz
components <- data.frame(name = c("fast", "medium", "slow"),
                         lambda = c(2, 0.5, 0.02),
                         n = c(1000, 1000, 10000))

# Simulate a CW-OSL curve including some signal noise
curve <- simulate_OSLcomponents(components, simulate.curve = TRUE, add.poisson.noise = TRUE)

# Display the simulated curve
plot_OSLcurve(curve, components)