Luminescence (version 1.3.1)

plot_AbanicoPlot: Function to create an abanico plot

Description

The abanico plot provides a comprehensive presentation of data precision and its dispersion around a central value, and can also display a kernel density estimate, histogram and/or dot plot of the dose values.

Usage

plot_AbanicoPlot(
  data,
  log.z = TRUE,
  z.0 = c("mean.weighted", "mean", "median"),
  dispersion = c("qr", "sd", "2sd"),
  plot.ratio = 0.75,
  rotate = FALSE,
  mtext = "",
  summary = c("n", "in.2s"),
  summary.pos = "sub",
  summary.method = c("MCM", "weighted", "unweighted"),
  legend = NULL,
  legend.pos = "topleft",
  stats = NULL,
  rug = FALSE,
  kde = TRUE,
  hist = FALSE,
  dots = FALSE,
  boxplot = FALSE,
  y.axis = TRUE,
  error.bars = FALSE,
  bar = NULL,
  bar.col = NULL,
  polygon.col = NULL,
  line = NULL,
  line.col = NULL,
  line.lty = NULL,
  line.label = NULL,
  grid.col = NULL,
  frame = 1,
  interactive = FALSE,
  ...
)

Value

Returns a plot object and, optionally, a list with plot calculus data.

Arguments

data

data.frame or RLum.Results object (required): for data.frame two columns: De (data[,1]) and De error (data[,2]). To plot several data sets in one plot the data sets must be provided as list, e.g. list(data.1, data.2). Rows with NA values will be removed prior to plotting.
For some RLum.Results objects, one or more lines (and corresponding labels) are drawn automatically:

• calc_AverageDose (ADM)

• calc_CentralDose (CDM)

• calc_MaxDose (MDM)

• calc_MinDose (MAM)

• calc_FiniteMixture Alternative labels can be set via the line.label option. This behaviour can be suppressed altogether by setting line = NA.

log.z

logical (with default): display the z-axis in logarithmic scale (TRUE by default). The setting is automatically reset to FALSE if any zero values appear in the De column.

z.0

character or numeric (with default): User-defined central value used for centring of data. One of "mean.weighted" (default), "mean"and "median", or a single numeric value (not its logarithm).

dispersion

character (with default): measure of dispersion used to draw the scatter polygon. Can be one of the following:

• "qr" (quartile range, default)

• "sd" (standard deviation)

• "2sd" (2 standard deviations)

• "pNN" (symmetric percentile range, with NN being the lower percentile, e.g. "p05" indicates the range between 5 and 95 %, or "p10" indicates the range between 10 and 90 %)

The default is "qr". Note that "sd" and "2sd" are only meaningful in combination with "z.0 = 'mean'" because the unweighted mean is used to centre the polygon.

plot.ratio

numeric (with default): Relative space, given to the radial versus the cartesian plot part, default is 0.75.

rotate

logical (with default): Option to turn the plot by 90 degrees.

mtext

character (with default): additional text below the plot title.

summary

character (with default): add statistic measures of centrality and dispersion to the plot. Can be one or more of several keywords. See details for available keywords. Results differ depending on the log-option for the z-scale (see details).

summary.pos

numeric or character (with default): optional position coordinates or keyword (e.g. "topright") for the statistical summary. Alternatively, the keyword "sub" may be specified to place the summary below the plot header. However, this latter option in only possible if mtext is not used.

summary.method

character (with default): keyword indicating the method used to calculate the statistic summary. One of "MCM" (default), "weighted" or "unweighted". See calc_Statistics for details.

legend

character vector (optional): legend content to be added to the plot.

legend.pos

numeric or character (with default): optional position coordinates or keyword (e.g. "topright") for the legend to be plotted.

stats

character: additional labels of statistically important values in the plot. Can be one or more of the following:

• "min"

• "max"

• "median"

rug

logical (with default): Option to add a rug to the KDE part, to indicate the location of individual values.

kde

logical (with default): Option to add a KDE plot to the dispersion part (TRUE by default). The smoothing bandwidth can be controlled by setting the bw argument ("SJ" by default; see stats::density for details).

hist

logical (with default): Option to add a histogram to the dispersion part. Only meaningful when only one data set is plotted. The number of cells in the histogram can be controlled by setting the breaks argument (see graphics::hist for details).

dots

logical (with default): Option to add a dot plot to the dispersion part. If number of dots exceeds space in the dispersion part, a square indicates this.

boxplot

logical (with default): Option to add a boxplot to the dispersion part, default is FALSE.

y.axis

logical (with default): option to hide standard y-axis labels and show 0 only, useful for data with small scatter. To suppress the y-axis entirely, use yaxt == 'n' (the standard graphics::par setting) instead.

error.bars

logical (with default): Option to show De-errors as error bars on De-points. Useful in combination with y.axis = FALSE, bar = FALSE.

bar

numeric or logical (with default): option to add one or more dispersion bars (i.e., bar showing the 2-sigma range) centred at the defined values. By default a bar is drawn according to "z.0". To omit the bar set "bar = FALSE".

bar.col

character or numeric (with default): colour of the dispersion bar. Default is "grey60".

polygon.col

character or numeric (with default): colour of the polygon showing the data scatter. Sometimes this polygon may be omitted for clarity. To disable it use FALSE or polygon = FALSE. Default is "grey80".

line

numeric or RLum.Results: numeric values of the additional lines to be added. This can be set to NA to suppress the line added automatically by some RLum.Results objects.

line.col

character or numeric: colour of the additional lines.

line.lty

integer: line type of additional lines.

line.label

character: labels for the additional lines.

grid.col

character or numeric (with default): colour of the grid lines (originating at [0,0] and stretching to the z-scale). To disable grid lines use FALSE. Default is "grey".

frame

numeric (with default): the plot frame type, one of the following:

• 0: no frame

• 1: frame originates at 0,0 and runs along min/max isochrons (default)

• 2: frame embraces the 2-sigma bar

• 3: frame embraces the entire plot as a rectangle

interactive

logical (with default): create an interactive abanico plot (requires the 'plotly' package).

...

further arguments and graphical parameters to control the plot output. Supported are: main, sub, ylab, xlab, zlab, xlim, ylim, zlim, cex, pt.cex (point size), lty, lwd, pch, col, at, bw, and breaks. xlab must be a vector of length two, specifying the upper and lower x-axis labels.

Please note that in the interactive mode, if you are using an expression, the zlab must use HTML tags, such as D<sub>e</sub> for D[e].

Function version

0.1.25

How to cite

Dietze, M., Kreutzer, S., Colombo, M., 2026. plot_AbanicoPlot(): Function to create an abanico plot. Function version 0.1.25. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., Steinbuch, L., de Boer, A., Bluszcz, A., 2026. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 1.3.1. https://r-lum.github.io/Luminescence/

Author

Michael Dietze, GFZ Potsdam (Germany)
Sebastian Kreutzer, F2.1 Geophysical Parametrisation/Regionalisation, LIAG - Institute for Applied Geophysics (Germany)
Marco Colombo, Institute of Geography, Heidelberg University (Germany)
Inspired by a plot introduced by Galbraith & Green (1990) , RLum Developer Team

Details

The abanico plot is a combination of the classic radial plot plot_RadialPlot and a kernel density estimate plot (e.g plot_KDE. It allows straightforward visualisation of data precision, error scatter around a user-defined central value and the combined distribution of the values, on the actual scale of the measured data (e.g. seconds, equivalent dose, years). The principle of the plot is shown in Galbraith & Green (1990). The function authors are thankful for the thought-provoking figure in this article.

The semi circle (z-axis) of the classic radial plot is bent to a straight line here, which actually is the basis for combining this polar (radial) part of the plot with any other Cartesian visualisation method (KDE, histogram, PDF and so on). Note that the plot allows displaying two measures of distribution. One is the 2-sigma bar, which illustrates the spread in value errors, and the other is the polygon, which stretches over both parts of the abanico plot (polar and Cartesian) and illustrates the actual spread in the values themselves.

Since the 2-sigma-bar is a polygon, it can be (and is) filled with shaded lines. To change density (lines per inch, default is 15) and angle (default is 45 degrees) of the shading lines, specify these parameters. See graphics::polygon for further help.

The proportion of the polar part and the cartesian part of the abanico plot can be modified for display reasons (plot.ratio = 0.75). By default, the polar part spreads over 75 % and leaves 25 % for the part that shows the KDE graph.

The abanico plot supports other than the weighted mean as measure of centrality. When it is obvious that the data is not (log-)normally distributed, the mean (weighted or not) cannot be a valid measure of centrality and hence central dose. Accordingly, the median and the weighted median can be chosen as well to represent a proper measure of centrality (e.g. centrality = "median.weighted"). Also user-defined numeric values (e.g. from the central age model) can be used if this appears appropriate.

Statistics summary

A statistic summary, i.e. a collection of statistic measures of centrality and dispersion (and further measures) can be added by specifying one or more of the following keywords in the summary argument:

• "n" (number of samples)

• "mean" (mean De value)

• "median" (median of the De values)

• "sd.abs" (absolute standard deviation)

• "sd.rel" (relative standard deviation in percent)

• "se.abs" (absolute standard error)

• "se.rel" (relative standard error)

• "in.2s" (percent of samples in 2-sigma range)

• "q.25" (25% percentile)

• "q.75" (75% percentile)

• "skewness" (skewness)

• "kurtosis" (kurtosis)

Note: the input data for the statistic summary is sent to the function calc_Statistics depending on the log-option for the z-scale. If "log.z = TRUE", the summary is based on the logarithms of the input data. If "log.z = FALSE" the linearly scaled data is used.

Note: calc_Statistics calculates these statistic measures in three different ways: unweighted, weighted and MCM-based (i.e., based on Monte Carlo Methods). By default, the MCM-based version is used. If you wish to use another method, indicate this with the appropriate keyword using the argument summary.method.

Other arguments

The optional parameter layout allows more sophisticated ways to modify the entire plot. Each element of the plot can be addressed and its properties can be defined. This includes font type, size and decoration, colours and sizes of all plot items. To infer the definition of a specific layout style cf. get_Layout or type, e.g. for the layout type "journal". A layout type can be modified by the user by assigning new values to the list object.

It is possible for the z-scale to specify where ticks are to be drawn by using the parameter at, e.g. at = seq(80, 200, 20), cf. function documentation of axis. Specifying tick positions manually overrides a zlim-definition.

References

Galbraith, R. & Green, P., 1990. Estimating the component ages in a finite mixture. International Journal of Radiation Applications and Instrumentation. Part D. Nuclear Tracks and Radiation Measurements 17 (3), 197-206.

Dietze, M., Kreutzer, S., Burow, C., Fuchs, M.C., Fischer, M., Schmidt, C., 2015. The abanico plot: visualising chronometric data with individual standard errors. Quaternary Geochronology. doi:10.1016/j.quageo.2015.09.003

See Also

plot_RadialPlot, plot_KDE, plot_Histogram, plot_ViolinPlot

Examples

## load example data and recalculate to Gray
data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <- ExampleData.DeValues$CA1

## plot the example data straightforward
plot_AbanicoPlot(data = ExampleData.DeValues)

## now with linear z-scale
plot_AbanicoPlot(data = ExampleData.DeValues,
                 log.z = FALSE)

## now with output of the plot parameters
plot1 <- plot_AbanicoPlot(data = ExampleData.DeValues)
str(plot1)
plot1$zlim

## now with adjusted z-scale limits
plot_AbanicoPlot(data = ExampleData.DeValues,
                 zlim = c(10, 200))

## now with adjusted x-scale limits
plot_AbanicoPlot(data = ExampleData.DeValues,
                 xlim = c(0, 20))

## now with rug to indicate individual values in KDE part
plot_AbanicoPlot(data = ExampleData.DeValues,
                 rug = TRUE)

## now with a smaller bandwidth for the KDE plot
plot_AbanicoPlot(data = ExampleData.DeValues,
                 bw = 0.04)

## now with a histogram instead of the KDE plot
plot_AbanicoPlot(data = ExampleData.DeValues,
                 hist = TRUE,
                 kde = FALSE)

## now with a KDE plot and histogram with manual number of bins
plot_AbanicoPlot(data = ExampleData.DeValues,
                 hist = TRUE,
                 breaks = 20)

## now with a KDE plot and a dot plot
plot_AbanicoPlot(data = ExampleData.DeValues,
                 dots = TRUE)

## now with user-defined plot ratio
plot_AbanicoPlot(data = ExampleData.DeValues,
                 plot.ratio = 0.5)
## now with user-defined central value
plot_AbanicoPlot(data = ExampleData.DeValues,
                 z.0 = 70)

## now with median as central value
plot_AbanicoPlot(data = ExampleData.DeValues,
                 z.0 = "median")

## now with the 17-83 percentile range as definition of scatter
plot_AbanicoPlot(data = ExampleData.DeValues,
                 z.0 = "median",
                 dispersion = "p17")

## now with user-defined green line for minimum age model
CAM <- calc_CentralDose(ExampleData.DeValues,
                        plot = FALSE)
plot_AbanicoPlot(data = CAM,
                 line.col = "darkseagreen")

## now create plot with legend, colour, different points and smaller scale
plot_AbanicoPlot(data = ExampleData.DeValues,
                 legend = "Sample 1",
                 col = "tomato4",
                 bar.col = "peachpuff",
                 pch = "R",
                 cex = 0.8)

## now without 2-sigma bar, polygon, grid lines and central value line
plot_AbanicoPlot(data = ExampleData.DeValues,
                 bar.col = FALSE,
                 polygon.col = FALSE,
                 grid.col = FALSE,
                 y.axis = FALSE,
                 lwd = 0)

## now with direct display of De errors, without 2-sigma bar
plot_AbanicoPlot(data = ExampleData.DeValues,
                 bar.col = FALSE,
                 ylab = "",
                 y.axis = FALSE,
                 error.bars = TRUE)

## now with user-defined axes labels
plot_AbanicoPlot(data = ExampleData.DeValues,
                 xlab = c("Data error (%)",
                          "Data precision"),
                 ylab = "Scatter",
                 zlab = "Equivalent dose [Gy]")

## now with minimum, maximum and median value indicated
plot_AbanicoPlot(data = ExampleData.DeValues,
                 stats = c("min", "max", "median"))

## now with a brief statistical summary as subheader
plot_AbanicoPlot(data = ExampleData.DeValues,
                 summary = c("n", "in.2s"))

## now with another statistical summary
plot_AbanicoPlot(data = ExampleData.DeValues,
                 summary = c("mean.weighted", "median"),
                 summary.pos = "topleft")

## now a plot with two 2-sigma bars for one data set
plot_AbanicoPlot(data = ExampleData.DeValues,
                 bar = c(30, 100))

## now the data set is split into sub-groups, one is manipulated
data.1 <- ExampleData.DeValues[1:30,]
data.2 <- ExampleData.DeValues[31:62,] * 1.3

## now a common dataset is created from the two subgroups
data.3 <- list(data.1, data.2)

## now the two data sets are plotted in one plot
plot_AbanicoPlot(data = data.3)

## now with some graphical modification
plot_AbanicoPlot(data = data.3,
                 z.0 = "median",
                 col = c("steelblue4", "orange4"),
                 bar.col = c("steelblue3", "orange3"),
                 polygon.col = c("steelblue1", "orange1"),
                 pch = c(2, 6),
                 angle = c(30, 50),
                 summary = c("n", "in.2s", "median"))

## create Abanico plot with predefined layout definition
plot_AbanicoPlot(data = ExampleData.DeValues,
                 layout = "journal")

## now with predefined layout definition and further modifications
plot_AbanicoPlot(
 data = data.3,
 z.0 = "median",
 layout = "journal",
 col = c("steelblue4", "orange4"),
 bar.col = adjustcolor(c("steelblue3", "orange3"),
                         alpha.f = 0.5),
 polygon.col = c("steelblue3", "orange3"))

## for further information on layout definitions see documentation
## of function get_Layout()

## now with manually added plot content
## create empty plot with numeric output
AP <- plot_AbanicoPlot(data = ExampleData.DeValues,
                       pch = NA)

## identify data in 2 sigma range
in_2sigma <- AP$data[[1]]$data.in.2s

## restore function-internal plot parameters
par(AP$par)

## add points inside 2-sigma range
points(x = AP$data[[1]]$precision[in_2sigma],
       y = AP$data[[1]]$std.estimate.plot[in_2sigma],
       pch = 16)

## add points outside 2-sigma range
points(x = AP$data[[1]]$precision[!in_2sigma],
       y = AP$data[[1]]$std.estimate.plot[!in_2sigma],
       pch = 1)