dplR (version 1.6.8)

plotRings: Plot Rings

Description

Make a plot and/or animation of a cross section based on up to four ring-width series. Gives basic summary statistics (e.g. annual basal area, mean ring width) of an approximated stem disc.

Usage

plotRings(year, trwN, trwS = NA_real_,
          trwE = NA_real_, trwW = NA_real_, length.unit = "mm",
          animation = FALSE, sys.sleep = 0.2, year.labels = FALSE,
          d2pith = NA, col.inrings = "grey", col.outring = "black",
          x.rings = "none", col.x.rings = "red", xy.lim = NULL, 
          species.name = NA, saveGIF = FALSE, fname = "GIF_plotRings.gif")

Arguments

year

a numeric vector giving the years of the tree-ring records

trwN

a numeric vector giving the first tree-ring series to make the plot. It will be arbitrarily defined as North.

trwS

an optional numeric vector giving a tree-ring series to make the plot. It will be arbitrarily defined as South or 180 degrees from trwN.

trwE

an optional numeric vector giving a tree-ring series to make the plot. It will be arbitrarily defined as East or 90 degrees from trwN.

trwW

an optional numeric vector giving a tree-ring series to make the plot. It will be arbitrarily defined as West or 270 degrees from trwN.

animation

logical flag. If TRUE then each ring will be individually plotted as an animation within the R-GUI. A working copy of “ImageMagick” is required. See ‘Details’.

length.unit

a character string to to set the length unit of ring measurement. Possible values are "mm", "1/10 mm", "1/100 mm" and "1/10 mm".

sys.sleep

a numeric value defining the sleep pause in between rings during animation.

year.labels

logical flag. If TRUE the year labels will be shown at the bottom of the plot.

d2pith

numeric. The distance from the innermost ring to the pith of the tree. It is computed in the same unit as in the "length.unit" argument. If a value is assigned, a new row in the output table will be added at the first year

col.inrings

The color to be used for the interior rings. See section ‘Color Specification’ for suitable values.

col.outring

The color to be used for the outer ring. See section ‘Color Specification’ for suitable values.

x.rings

a character string to color narrow and wider rings of the series. Possible values are "none", "narrow.rings" to highlight the rings <= quantile 25%, and "wider.rings" to highlight the rings >= quantile 75%.

col.x.rings

The color to be used for the x.rings. See section ‘Color Specification’ for suitable values.

xy.lim

a numeric giving a single positive value for the axis limits. If NULL limits are calculated automatically. See examples.

species.name

an optional character string that defines the species name in the plot.

saveGIF

logical. If TRUE a GIF will be saved. A working copy of “ImageMagic” is required. See ‘Details’ and examples.

fname

character. Filename for GIF.

Value

A data.frame giving the original data of each tree-ring series ("trwN", "trwS", "trwE", "trwW"), a mean of all tree-ring series ("trw.means"), cumulative values from "trw.means" ("trw.acc"), the difference of North - South and East - West tree-ring series ("N_S", "E_W"), the basal area increment of "trw.acc" ("bai.acc"), and the bai for each individual tree ring ("bai.ind").

Details

This makes a plot, drawing all rings from tree-ring series on a Cartesian plane of up to four cardinal directions (N, S, E, W) defining the eccentricity of the stem. It can be plotted using only data from one ratio, or up to four different radii from same tree. This function can plot each individual ring as an animation within the R-GUI, as a GIF-file, or it can plot all rings at once.

Animations require a functional installation of ImageMagick [https://www.imagemagick.org] where the ImageMagick program convert is configured correctly in the PATH. At the moment, the saveGIF option in plotRings is stable but occassionaly fails. Should users encoutner issues saving a GIF, the problem might be related to the installation of ImageMagick the details of which depend on platform. See saveGIF for details.

Examples

# NOT RUN {
# with tree-ring series from Rothenburg data
data("anos1")

yrs <- time(anos1)
# Plot rings with data of two radii from same individual tree
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 species.name = "Cedrela odorata")

# change plot limits                 
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5], 
                 xy.lim = 100)

# Playing with colors
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 col.inrings = "tan", col.outring = "blue") 
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 col.inrings = terrain.colors(nrow(anos1))) 

#Setting the length.unit
res <- plotRings(yrs,  anos1[,4], trwW = anos1[,5],sp="Cedrela odorata", length.unit = "mm")
res <- plotRings(yrs,  anos1[,4], trwW = anos1[,5],sp="Cedrela odorata", length.unit = "1/100 mm")

# Specifying x.rings highlighting only narrow rings
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 x.rings = "narrow.rings") 

# Highlight and color wide rings
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 x.rings = "wider.rings", col.x.rings = "green") 

# }
# NOT RUN {
# Plot rings and animate. Requires ImageMagick to be installed.
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],year.labels = TRUE, 
                 animation = TRUE, sys.sleep = 0.1)
                 
# Plot rings, animate, save as GIF. Requires ImageMagick to be installed.
res <- plotRings(yrs, anos1[,4], trwW = anos1[,5],
                 saveGIF = TRUE, fname="GIF_plotRings.gif",sys.sleep = 0.1)
# }
# NOT RUN {
# with four fake tree-ring series 
trw <- data.frame(trw01.n = abs(rnorm(100, 10, 4)),  # North direction
                  trw01.s = abs(rnorm(100, 10, 2)),  # South direction
                  trw01.w = abs(rnorm(100, 10, 2)),  # West direction
                  trw01.e = abs(rnorm(100, 10, 2)),  # East direction
                  row.names = 1918:2017)
class(trw) <- c("rwl","data.frame")

yrs <- time(trw)

# Default plot with 2, 3 and 4 radii
res <- plotRings(yrs, trw[,1], trw[,2], trw[,3], trw[,4])

# with d2pith values (see the hole before the first rings in the plot)
res <- plotRings(yrs, trw[,1], trw[,2], trw[,3], trw[,4],
                 d2pith = 100)

# }