Skip to contents

Track the period of a cycle in a wavelet or superlet scalogram

Source: R/track_period.R
track_period.Rd

Interactively select points in a wavelet or superlet power spectrum to trace the evolution of a cycle with changing period.

The track_period function plots a time-frequency spectrum in which spectral peaks can be selected to track a ridge through time or depth. This allows the user to follow a cycle whose period varies along the record.

Tracking points are selected interactively and displayed as white dots. Previously selected points can be deselected by clicking them again, after which they are shown as red dots. Because points may be closely spaced, de-selection can be difficult. In such cases, delpts_tracked_period_wt can be used to remove points that were previously selected.

Usage

track_period(
  scalogram = NULL,
  astro_cycle = 405,
  n.levels = 100,
  track_peaks = TRUE,
  periodlab = "Period (metres)",
  x_lab = "depth (metres)",
  palette_name = "viridis",
  color_brewer = "viridis",
  plot_horizontal = TRUE,
  plot_dir = TRUE,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  add_lines = NULL,
  add_points = NULL,
  add_abline_h = NULL,
  add_abline_v = NULL,
  colour_brewer = NULL
)

Arguments

scalogram

Scalogram in which the cycle is tracked: a wavelet object (class analyze.wavelet) created with analyse_wavelet or a superlet object (class analyze.superlet) created with analyse_superlet. The elements x, y, Power, Period, axis.2 and Power.avg are used. Must be given (the NULL default fails). Default=NULL.

astro_cycle

Duration of the astronomical cycle that is tracked (numeric, > 0, in kyr, e.g. 405 for the long eccentricity cycle). It is used to convert the tracked period into the sedimentation rate of the output (period / astro_cycle * 100, i.e. cm/kyr for a record in metres). Default=405.

n.levels

Number of colour levels of the power scale (integer, > 1); the breaks are quantiles of the power. Default=100.

track_peaks

Restrict the selection to spectral peaks (logical, TRUE or FALSE). With TRUE the local power maxima along the period axis are drawn as black circles and a click selects the nearest one; with FALSE any point of the scalogram can be clicked (the click is snapped to the nearest depth of the scalogram and its period is used as clicked). In both modes clicking a selected point again removes it; finish with right-click/Esc (or "Finish" in RStudio). Default=TRUE.

periodlab

Label of the period axis (character). Default="Period (metres)".

x_lab

Label of the depth/time axis (character). Default="depth (metres)".

palette_name

Name of the colour palette of the power (colour) scale, a character string. Which names are valid depends on color_brewer:

  • color_brewer = "grDevices": "rainbow", "heat.colors", "terrain.colors", "topo.colors", "cm.colors", or any of the 115 hcl.colors palettes (list them with grDevices::hcl.pals()), for example "viridis", "Plasma", "Inferno", "YlOrRd", "Spectral", "Blue-Red", "Zissou 1".

  • color_brewer = "viridis": "viridis", "magma", "inferno", "plasma", "cividis", "rocket", "mako", "turbo".

  • color_brewer = "RColorBrewer": "BrBG", "PiYG", "PRGn", "PuOr", "RdBu", "RdGy", "RdYlBu", "RdYlGn", "Spectral", "Accent", "Dark2", "Paired", "Pastel1", "Pastel2", "Set1", "Set2", "Set3", "Blues", "BuGn", "BuPu", "GnBu", "Greens", "Greys", "Oranges", "OrRd", "PuBu", "PuBuGn", "PuRd", "Purples", "RdPu", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd" (also listed by wr_brewer_palettes()).

  • color_brewer = "colorRamps": "blue2green", "blue2green2red", "blue2red", "blue2yellow", "cyan2yellow", "green2red", "magenta2green", "matlab.like", "matlab.like2", "ygobb".

  • color_brewer = "scico" (all except "batlowK" need the scico package): "acton", "bam", "bamako", "bamO", "batlow", "batlowK", "batlowW", "berlin", "bilbao", "broc", "brocO", "buda", "bukavu", "cork", "corkO", "davos", "devon", "fes", "glasgow", "grayC", "hawaii", "imola", "lajolla", "lapaz", "lipari", "lisbon", "managua", "navia", "nuuk", "oleron", "oslo", "roma", "romaO", "tofino", "tokyo", "turku", "vanimo", "vik", "vikO".

Low power is drawn with the first colour of the palette and high power with the last. Default="viridis".

color_brewer

Palette family from which palette_name is taken, a character string: "grDevices", "viridis", "RColorBrewer", "colorRamps" or "scico" (the last one, except for "batlowK", needs the scico package). See palette_name for the palette names of each family. Default="viridis".

plot_horizontal

Layout of the plot (logical, TRUE or FALSE): TRUE depth/time on the x-axis and period on the y-axis; FALSE period on the x-axis and depth/time on the y-axis. The output is the same in both layouts. Default=TRUE.

plot_dir

Direction of the depth/time axis (logical, TRUE or FALSE): TRUE plots it from low to high values (e.g. borehole data that get older with increasing depth); FALSE reverses the axis (e.g. outcrop logs in which 0 m is the base of the section). Default=TRUE.

lowerPeriod

Shortest period shown on the period axis (numeric, in the depth/time unit of the record); NULL uses the shortest period of scalogram. Default=NULL.

upperPeriod

Longest period shown on the period axis (numeric, in the depth/time unit of the record); NULL uses the longest period of scalogram. Default=NULL.

add_lines

Optional lines to draw on the scalogram (matrix or data frame: depth/time in column 1, one or more columns of periods after it; one line per period column). Default=NULL.

add_points

Optional points to draw on the scalogram (matrix or data frame: depth/time in column 1, one or more columns of periods after it). Default=NULL.

add_abline_h

Optional horizontal reference lines (numeric vector, e.g. c(2, 3, 5)): periods in the horizontal layout, depths/times in the vertical layout (plot_horizontal = FALSE). Default=NULL.

add_abline_v

Optional vertical reference lines (numeric vector): depths/times in the horizontal layout, periods in the vertical layout. Default=NULL.

colour_brewer

British spelling of color_brewer, with the same options; if given (not NULL) it overrides color_brewer. Default=NULL.

Value

A data frame with three columns: first - depth - Depth or time of the tracked points second - period - Tracked period of the cycle third - sedrate - Estimated sedimentation rate based on the cycle duration

References

Routines for astrochronologic testing, astronomical time-scale construction, and time series analysis. doi:10.1016/j.earscirev.2018.11.015

Author

The function is based on and inspired by the traceFreq function from the astrochron package.

Examples

# \donttest{
if (interactive()) { # needs mouse input (identify())
## Track the 405 kyr eccentricity cycle in a magnetic susceptibility record
mag_wt <- analyse_wavelet(
  data = mag,
  dj = 1/100,
  lowerPeriod = 0.1,
  upperPeriod = 254,
  verbose = FALSE,
  omega_nr = 10
)

mag_track <- track_period(
  scalogram = mag_wt,
  astro_cycle = 405,
  track_peaks = TRUE
)
}# }