Estimate rate of change

Estimate the Rate of Change (RoC) in community composition along a temporal sequence. RoC is defined as the dissimilarity between consecutive Working Units (WUs), standardised by the age difference between them.

Usage

estimate_roc(
  data_source_community,
  data_source_age,
  age_uncertainty = NULL,
  smooth_method = c("none", "m.avg", "grim", "age.w", "shep"),
  smooth_n_points = 5,
  smooth_age_range = 500,
  smooth_n_max = 9,
  working_units = c("levels", "bins", "MW"),
  bin_size = 500,
  number_of_shifts = 5,
  bin_selection = c("random", "first"),
  standardise = FALSE,
  n_individuals = 150,
  dissimilarity_coefficient = c("euc", "euc.sd", "chord", "chisq", "gower", "bray"),
  tranform_to_proportions = TRUE,
  rand = NULL,
  use_parallel = FALSE,
  interest_threshold = NULL,
  time_standardisation = NULL,
  verbose = FALSE,
  silent = FALSE
)

Arguments

data_source_community

data.frame. Community data with taxa as columns and samples as rows. The first column must be named sample_id (character).

data_source_age

data.frame with two columns:

sample_id - unique identifier of each level (character)
age - age of the level (numeric)

age_uncertainty

Optional age-uncertainty matrix from an age-depth model. Either:

A matrix with one column per sample and one row per age sequence drawn from a posterior age-depth model. One row is randomly selected at the start of each randomisation run.
NULL (default) - age uncertainties are not used.

smooth_method

character. Smoothing method applied to each taxon before RoC is computed.

"none" - no smoothing (default)
"shep" - Shepard's 5-term filter (Davis, 1986; Wilkinson, 2005)
"m.avg" - moving average
"age.w" - age-weighted average
"grim" - Grimm's smoothing (Grimm & Jacobson, 1992)

smooth_n_points

numeric. Number of points used for moving average, Grimm, and age-weighted smoothing. Must be an odd number.

smooth_age_range

numeric. Maximum age range (in years) for Grimm and age-weighted smoothing windows.

smooth_n_max

numeric. Maximum number of samples included in a Grimm smoothing window.

working_units

character. Strategy used to define Working Units between which dissimilarity is calculated.

"levels" - each stratigraphical level is its own WU.
"bins" - one representative level is selected from each time bin of width bin_size.
"MW" - moving-window binning: selective binning is repeated number_of_shifts times, shifting the window by bin_size / number_of_shifts years each time. All results are retained and summarised together.

bin_size

numeric. Width of each time bin in years. Used when working_units is "bins" or "MW".

number_of_shifts

numeric. Number of window shifts in moving-window binning (working_units = "MW").

bin_selection

character. Rule for selecting one level from each bin.

"random" (default) - a level is selected at random.
"first" - the level closest to the start of the bin is selected.

standardise

logical. If TRUE, assemblage counts in each WU are rarefied to n_individuals before dissimilarity is computed.

n_individuals

numeric. Number of individuals to rarefy to when standardise = TRUE. Automatically reduced to the smallest count in the sequence if any WU has fewer individuals.

dissimilarity_coefficient

character. Dissimilarity coefficient used to compare consecutive WUs. See vegan::vegdist() for details.

"euc" - Euclidean distance
"euc.sd" - standardised Euclidean distance
"chord" - Chord distance
"chisq" - Chi-squared coefficient
"gower" - Gower's distance
"bray" - Bray-Curtis dissimilarity

tranform_to_proportions

logical. If TRUE (default), community data are converted to proportions before dissimilarity is computed.

rand

numeric. Number of randomisation runs. Set to NULL (default) to skip randomisation and use a single deterministic run.

use_parallel

Controls parallel computation of randomisation runs.

FALSE (default) - single core only.
TRUE - number of cores detected automatically.
A positive numeric - use that many cores.

interest_threshold

numeric. Optional. Samples older than this age are excluded from the output.

time_standardisation

numeric. Time unit for RoC values. RoC is reported as dissimilarity per time_standardisation years. Defaults to bin_size when NULL.

verbose

logical. If TRUE, print progress messages during computation.

silent

logical. If TRUE, suppress all console output (overrides verbose).

Value

A tibble with one row per Working Unit pair, containing columns:

Age - mean age of the WU pair
ROC - median RoC score across all randomisation runs
ROC_up - 95th-quantile RoC score (upper uncertainty bound)

Details

RoC between two consecutive WUs is computed as dissimilarity divided by the age difference between the WUs, scaled by time_standardisation. When rand > 1, the full computation is repeated rand times; in each run, one age sequence is drawn at random from age_uncertainty (if supplied) and, when standardise = TRUE, assemblage counts are independently rarefied. The final RoC value for each WU pair is the median across all runs; the 95th quantile is returned as an upper uncertainty bound.

References

Birks, H.J.B., Gordon, A.D., 1985. Numerical Methods in Quaternary Pollen Analysis. Academic Press, London.

Davis, J.C., 1986. Statistics and Data Analysis in Geology, 2nd edn. J. Wiley & Sons, New York.

Grimm, E.C., Jacobson, G.L., 1992. Fossil-pollen evidence for abrupt climate changes during the past 18000 years in eastern North America. Clim. Dyn. 6, 179-184.

Wilkinson, L., 2005. The Grammar of Graphics. Springer-Verlag, New York.

Examples

if (FALSE) { # \dontrun{
data("example_data", package = "RRatepol")

# `rand = NULL` uses a single deterministic run. For robust results,
# increase to e.g. `rand = 1e3` with `use_parallel = TRUE`.
sequence_01 <-
  estimate_roc(
    data_source_community = example_data$pollen_data[[1]],
    data_source_age = example_data$sample_age[[1]],
    dissimilarity_coefficient = "chisq",
    rand = NULL # increase to e.g. `rand = 1e3` with `use_parallel = TRUE` for robust results
  )

plot_roc(
  data_source = sequence_01,
  age_threshold = 8e3,
  roc_threshold = 1
)
} # }