Package 'riojaPlot'

Stratigraphic diagrams in R

Description

riojaPlot: An R package for plotting stratigraphic diagrams in R.

Details

The riojaPlot is an R package for plotting stratigraphic diagrams in R.

Index of help topics:

riojaPlot               Plot a stratigraphic diagram
riojaPlot-package       Stratigraphic diagrams in R

Author(s)

Steve Juggins

Maintainer: Steve Juggins <[email protected]>

---

Plot a stratigraphic diagram

Description

Plots a diagram of multiple biological, physical or chemical parameters agains depth or time, as used in geology & palaeoecology.

Usage

riojaPlot(x, y, selVars=NULL, groups=NULL, style=NULL, clust=NULL, 
          lithology=NULL, riojaPlot=NULL, verbose=TRUE, ...)

riojaPlot2(riojaPlot, x, y, selVars=NULL, groups=NULL, style=NULL, clust=NULL, 
          lithology=NULL, verbose=TRUE, ...)

addRPClust(riojaPlot, clust, xLeft=NULL, xRight=0.99, verbose=TRUE, ...)

addRPClustZone(riojaPlot, clust, nZone="auto", xLeft=NULL, xRight=NULL, 
               verbose=TRUE, ...)

addRPZone(riojaPlot, upper, lower=NULL, xLeft=NULL, xRight=NULL, col="red", 
          alpha=0.1, border=NA, verbose=TRUE, ...)

addRPZoneNames(riojaPlot, zones, showColumn=TRUE, xLeft=NULL, xRight=0.99, ...)

listStyles()

makeStyles(...)

Arguments

x	a data frame or tibble containing variables to plot.
y	a data frame or tibble containing depth and/or age variables for the y-axis.
selVars	a character vector of variable names to include in the plot.
groups	a data frame or tibble with 2 columns giving the variable name (col 1) and factor containing group membership (col 2), used to colour variables by group and / or to generate a summary cumulative plot of group totals.
clust	a constrained cluster object returned by chclust.
nZone	number of zones to include or "auto" to add number of zones suggested by a broken stick model (see details).
style	a riojaPlot style object to control visual aspects of the plot (see details).
riojaPlot	object returned by riojaPlot.
upper, lower	upper and lower values of a zone to add.
xLeft, xRight	left and right position of figure on page (as a fraction of page width).
verbose	show warnings (default TRUE).
col, alpha, border	colour, alpha value (transparency) and border colour of zones.
zones	a data frame with 2 columns, the first giving the y-value to draw the zone label and the second the zones names as character.
showColumn	draw a column around the zone names?
lithology	data frame or tibble that is passed to fun.lithology for plotting the lithological column.
...	additional arguments to control the style of the figure (see details below) or colour of zones.

Details

riojaPlot plots a set of variables in a stratigraphic diagram. Diagrams can be plotted as line graphs, silhouettes or bar charts. riojaPlot extends strat.plot in several ways: variables can be grouped and displayed with different colours, a cumulative summary plot can be added automatically based on the grouping, a cluster dendrogram and resulting zones can be added automatically, a secondary y-axis can be added to plot a depth and age axis, and the figures margins are determined automatically depending on the size and length of labels.

riojaPlot2 is just a wrapper around riojaPlot that takes a riojaPlot object as the first argument so it can be used with a pipe.

See vignette("riojaPlot") for a user guide or vignette("riojaPlotPDF") for a pdf version.

• yvar.name name of the variable to use for primary y-axis scale. If not specified the first column in the y table will be used. If the primary axis is character data text labels will be drawn at each sample position.

• sec.yvar.name name of the variable to use for an optional secondary y-axis scale.

• plot.sec.axis show secondary y-axis. Default FALSE.

• yLabel, secyLabel labels for the primary and secondary y-axes. Uses column names if not specified.

• scale.percent scale the diagram for percentage data (default TRUE).

• scale.minmax for non-percentage data, only label min and max values of x-axes to avoid crowding (default FALSE).

• y.rev reverse the y-axis (default TRUE).

• ymin, ymax, sec.ymin, sec.ymax minimum and maximum of primary and secondary y-axes.

• yinterval, sec.yinterval intervals for primary and secondary y-axes.

• ytks1, ytks2 numeric vector of y-values to print on primary and secondary y-axes.

• wa.order rearrange the curves to show trend from bottom left to top right (default FALSE).

• plot.bar, plot.line, plot.poly, plot.symb show bars, lines, polygons (silhouettes) and / or symbols (defaults to polygons with thin horizintal lines).

• lwd.bar, lwd.line, lwd.pol.line, lwd.cumul.line, lwd.zones thickness of bars and lines (default thickness for base graphics is 1).

• col.bar, col.poly.line, col.poly, col.symb, col.zones, col.zone.column, col.cumul.line, col.exag.line colour of bars, lines, polygon outlines and fills, symbols, zones and lines on cumulative plot.

• bar.back, plot horizontal bars on top or below shaded silhouettes (default TRUE).

• cex.xaxis, cex.yaxis, cex.ylabel, cex.xlabel, cex.cumul, font sizes (size relative to default of 1).

• tcl tick length for axes, in logical units (default -0.3).

• srt.xlabel, srt.ylabel angle (in degrees) of names (default=90).

• centre.xlabel centre the names when srt.xlabel is zero (ie. horizontal, default=FALSE).

• do.clust do a CONISS constrained clustering.

• clust.data.trans transform data before cluster analysis ("none", "sqrt", or "scale", default "none").

• clust.use.selected use selected variables (ie. those listed in selVars) or all variables when calculating cluster dendrogram (default FALSE).

• plot.clust add a CONISS cluster dendrogram.

• clust.width width of the dendrogram (as fraction of page width).

• plot.exag show exaggereted curves (default FALSE.

• col.exag colour for exaggerations, either a colour or "auto".

• exag.mult multiplication factor for exaggerations (default 2).

• exag.alpha alpha value for exaggeration curves.

• plot.groups show curves with different colours (default FALSE).

• plot.cumul add a cumulative summary based on groups on right of diagram (default FALSE).

• cumul.mult width of the cumulative plot (default 1.0).

• col.group character vector of 10 colours for groups (will be recycled to 10).

• xlabels character vector of labels for the plots (overrides column names).

• labels.break.long break long names (default TRUE).

• labels.break.n number of characters to break after (default 20).

• labels.italicize italicize names.

• xRight right hand position of plot (as fraction of page width).

• xLeft, xRight left and right hand position of plot (as fraction of page width). Will be determined automatically depending of label sizes, override to fine-tune.

• yTop, yBottom top and bottom positions of plot (as fraction of page height). Will be determined automatically depending of label sizes, override to fine-tune. yBottom default is 0.05, increase if axis labels are truncated.

• las.xaxis, las.xaxis orientation of x- and y-axis labels (1=horz, 2=vert, default 1).

• col.axis, col.baseline colour for x/y axes and basline, defaults black and darkgrey.

• fun.xback, fun.xfront custom functions of add elements to a plot above (fun.xfront) or behind (fun.xback) data. See below.

• fun.plotback, fun.yaxis custom functions of add elements to the plot background or to generate a custom y-axis. See below.

• x.pc.omit0 omit zero value of axis values when scaling for percent data (default TRUE).

• x.pc.inc for percentage diagrams single value or numeric vector of intervals for x-axes.

• min.width.pc for percentage diagrams the minimim data width of the x-axes.

• scale.minmax logical, for non-percentage diagrams show only mimimum and maximum values on the x-axis to avoid label crowding (default FALSE).

• minmax for non-percentage diagrams an optional dataframe with two columns containing the minimum and maximum values of the x-axis scale for each variable.

• graph.widths vector of relative widths for each graph (default 1).

• xSpace space between individual graphs (fraction of page width, default=0.01).

• xGap space between datasets plotted by repeated calls to riojaPlot (fraction of page width, default=0.01).

• ylabPos x-position of y-axis label when secondary y-axis is not used (use to tweak position of y-axis label, try values of 0.1-0.4).

• sep.bar plot different colours for bars for different levels? Default FALSE.

• col.sep.bar character vector with colours for bars for each sample.

• plot.top.axis, plot.bottom.axis show x-axes on top and/or bottom of plots (default FALSE, TRUE respectively.

• omitMissing Strip NAs from data before plotting (default TRUE). Setting to FALSE will leave gaps in lines with NA.

• cumulSpace gap to leave between top axis and cumulative plot legend. Default NA for riojaPlot to guess.

• fun.lithology function that passes a single dat frame or tibble of information for plotting the lithology column.

• lithology.width width of lithology column, as fraction of page width.

• user1, user2, user3, user4 pleceholders to supply additional objects (data frames, lists etc.) to custom functions.

fun.xback and fun.xfront are user-defined functions of the form 'myfun(x, y, i, nm, style)' that pass four arguments: x and y values, the index of the plot (i, from 1 to nplots, left to right) and the variable name (nm) to be plotted, as a named character vector. fun.lithology is a user-defined function of the form 'myfun(x, style)' where x is the data frame of lithological information passed to riojaPlot. fun.plotback is a user-defined function of the form 'fun.plotback(usr, fig, style)' where usr and fig provides the coordinates of the plotting area in data units(usr) and fractions of screen width and height (fig) (see ?par).

addRPClust adds a dendrogram to an existing riojaPlot diagram.

addRPZone adds user-defined horizontal zone lines to an existing diagram.

addRPClustZone adds zone lines from a constrained clustering to an existing riojaPlot diagram.

makeStyles creates a riojaPlot style object that can be applied to riojaPlots.

listStyles returns a list of modifiable styles and their default values.

These function uses base graphics and fig to split the screen and may be incompatible with par(mfrow) and split.screen.

Value

riojaPlot returns (invisibly) an object of class riojaPlot containing details of the overall diagram and individual curves and styles.

makeStyles returns an object of class riojaPlot.style.

Author(s)

Steve Juggins

See Also

strat.plot.

Examples

# use built-in data from Abernethy Forest
# see ?aber for citation

library(rioja)
data(aber)

# extract pollen percentages
spec <- aber$spec
# replace species codes with full taxon names
colnames(spec) <- aber$names$Name 
yvar <- aber$ages

# plot on depth scale
riojaPlot(spec, yvar, 
   yvar.name="Depth (cm)")

# scale for percentage data 
riojaPlot(spec, yvar, 
   yvar.name="Depth (cm)", 
   scale.percent=TRUE)
   
# reduce number of taxa and add exaggerations
# make a vector of taxon names with max abundance greater that 5 percent
mx <- apply(spec, 2, max)
selTaxa <- names(mx[mx > 5])

riojaPlot(spec, yvar, selTaxa,
   yvar.name="Depth (cm)", 
   scale.percent=TRUE,
   plot.exag=TRUE)

# group taxa by type and add cumulative graph
# extract types
types <- aber$names[, -1]
# convert pollen types to a factor
types$Group <- factor(types$Group, levels=c("Trees", "Shrubs", "Herbs"))
riojaPlot(spec, yvar, selTaxa, types,
   yvar.name="Depth (cm)", 
   scale.percent=TRUE,
   plot.groups=TRUE,
   plot.cumul=TRUE,
   plot.exag=TRUE)

# or plot on age scale with depth as secondary and italicise names
riojaPlot(spec, yvar, selTaxa, types,
   sec.yvar.name="Depth (cm)", 
   yvar.name="Age (years BP)",
   ymin=6000,
   ymax=14300,
   yinterval=500,
   scale.percent=TRUE,
   plot.sec.axis=TRUE, 
   plot.groups=TRUE, 
   plot.cumul=TRUE,
   plot.exag=TRUE,
   labels.italicise = TRUE)

# add a zonation

riojaPlot(spec, yvar, selTaxa, types,
   sec.yvar.name="Depth (cm)", 
   yvar.name="Age (years BP)",
   ymin=6000,
   ymax=14300,
   yinterval=500,
   plot.sec.axis=TRUE, 
   scale.percent=TRUE,
   plot.groups=TRUE, 
   plot.cumul=TRUE,
   plot.exag=TRUE, 
   do.clust=TRUE,
   plot.clust=TRUE, 
   plot.zones="auto", 
   labels.italicise = TRUE)

# save settings as a style and apply to figure, fine-tuning the y-axis:

mystyle <- makeStyles(
   plot.sec.axis=TRUE, 
   scale.percent=TRUE,
   plot.groups=TRUE, 
   plot.cumul=TRUE,
   plot.exag=TRUE, 
   plot.bar="full",
   plot.poly=TRUE,
   bar.back=TRUE,
   lwd.bar=0.5,
   col.bar="lightgrey",
   do.clust=TRUE,
   plot.clust=TRUE, 
   plot.zones="auto",
   srt.xlabel=45)

riojaPlot(spec, yvar, selTaxa, types, mystyle,
   sec.yvar.name="Depth (cm)", 
   yvar.name="Age (years BP)",
   ymin=6250,
   ymax=14300,
   yinterval=500, 
   ytks1=seq(6000, 14500, by=500))

---