track_period: Track the period of a cycle in a wavelet or superlet...

In WaverideR: Extracting Signals from Wavelet Spectra

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

Description

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 = "rainbow",
  color_brewer = "grDevices",
  plot_horizontal = TRUE,
  plot_dir = TRUE,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  add_lines = NULL,
  add_points = NULL,
  add_abline_h = NULL,
  add_abline_v = NULL
)

Arguments

scalogram	A wavelet or superlet object created using analyze_wavelet or analyze_superlet.
astro_cycle	Duration (in kyr) of the astronomical cycle that is being tracked.
n.levels	Number of colour levels used for plotting. Default is 100.
track_peaks	Logical flag indicating whether tracking is restricted to spectral peaks (TRUE) or whether any point within the spectrum can be selected (FALSE). Default is TRUE.
periodlab	Label for the period axis. Default is "Period (metres)".
x_lab	Label for the x-axis. Default is "depth (metres)".
palette_name	Name of the colour palette used for plotting.
color_brewer	Name of the R package from which the colour palette is selected. Supported packages are RColorBrewer, grDevices, ColorRamps, and viridis. Default is "grDevices".
plot_horizontal	Logical flag indicating whether the spectrum is plotted horizontally or vertically. Default is TRUE.
plot_dir	Logical flag defining the direction of the record. If time increases with increasing depth (e.g. borehole data), set to TRUE. If time decreases with increasing depth, set to FALSE. Default is TRUE.
lowerPeriod	Lowest period value to be displayed.
upperPeriod	Highest period value to be displayed.
add_lines	Optional matrix of additional lines to overlay on the spectrum. The first column must be depth or time, and subsequent columns contain period values.
add_points	Optional matrix of additional points to overlay on the spectrum. The first column must be depth or time, and subsequent columns contain period values.
add_abline_h	Optional numeric vector specifying horizontal reference lines.
add_abline_v	Optional numeric vector specifying vertical reference lines.

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

Author(s)

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

References

Routines for astrochronologic testing, astronomical time-scale construction, and time series analysis. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.earscirev.2018.11.015")}

Examples

## Track the 405 kyr eccentricity cycle in a magnetic susceptibility record
mag_wt <- analyze_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
)

WaverideR documentation built on April 6, 2026, 5:06 p.m.