Time uncertainty transfer function

This function implements an empirical Monte Carlo approach to estimate the spectral transfer function for the effect of time uncertainty on the spatial average of a common proxy signal recorded by a given core array. It requires the suggested package simproxyage; if the package is not installed, you will receive installation instructions upon calling this function.

Usage

CalculateTimeUncertaintyTF(
  t = 100:1,
  acp = c(t[1], NA),
  nt = length(t),
  nc = 1,
  ns = 100,
  model = "poisson",
  rate = 0.05,
  resize = 1,
  surrogate.fun = stats::rnorm,
  fun.par = NULL,
  pad = TRUE,
  df.log = NULL,
  verbose.output = FALSE,
  ...
)

Arguments

t: numeric vector of integer values providing a reference chronology for the age perturbations (starting with the youngest age).
acp: numeric vector of age control points where the age uncertainty is assumed to be zero. Per default, a two-element vector where the first element is the start age (t[1]) and the second element NA resulting in an unconstrained age perturbation process; see details for handling more age control points.
nt: the length of the records (i.e. the number of data points) to simulate; per default set to length(t).
nc: the number of cores in the modelled core array.
ns: the number of Monte Carlo simulations for estimating the transfer function.
model: name string of the random process to use for realising the age perturbations; must be either "poisson" (the default) or "bernoulli"; see Comboul et al. (2014) for details on the two models.
rate: numeric vector of probability rate(s) that an age band is perturbed; you can specify a vector of two rates where the first entry is the probability for a missing band and the second entry the probability for a double-counting of a band. If only a single value is specified (per default 0.05), symmetric perturbations are assumed.
resize: the resizing option in case of shorter/longer than original time axes: 0 = do not resize, -1 = resize to shortest realisation, 1 = resize to longest realisation (default).
surrogate.fun: the random number generator to use for creating the noise time series; per default, Gaussian white noise is created using the base R function rnorm.
fun.par: an otional list of additional parameters which are passed to surrogate.fun.
pad: Strong age perturbations may result in time series that do not reach the final age of the reference chronology – shall the resulting NA values (in case of resize = 1) be set to 0 for the spectral estimation? Defaults to TRUE. This should not influence the spectral estimation provided the number of NA values is small compared to the total length of the time series.
df.log: width of the Gaussian kernel in logarithmic frequency units to smooth the spectral estimates; NULL (the default) suppresses smoothing. In general, smoothing should not be necessary when a sufficiently large number of Monte Carlo simulations (parameter ns) is used; nevertheless, it can be switched on here when the transfer function still appears too noisy.
verbose.output: logical controlling the size of the return object; per default, only the transfer function spectrum is returned, else also the spectra whose ratio determines the transfer function (see Details).
...: additional parameters which are passed to the spectral estimation function SpecMTM.

Value

either a spectral object (?spec.object) of the transfer function if verbose.output = FALSE (default), or a list of the spectral objects input, stack and ratio, providing averages over the ns simulations of:

input:: the original spectrum of the surrogate data;
stack:: the spectrum of the spatial average of the age-perturbed records;
ratio:: their ratio (perturbed/unperturbed), i.e. the transfer function.

Details

The approach is described in detail in Münch and Laepple (2018). In brief, nc identical surrogate time series are created and age perturbed and the average of these time series is calculated. The process is repeated ns times. For each of the ns realisations, spectra of the average age-perturbed and original time series are calculated yielding the spectral transfer function.

The modelling of the time uncertainty follows the approach presented in Comboul et al. (2014) which is implemented in the package simproxyage. The package can be installed from GitHub via
remotes::install_github("EarthSystemDiagnostics/simproxyage")
or you can download the package repository from
https://doi.org/10.5281/zenodo.2025204
and install the package via devtools::install().

The spectral estimates are calculated using Thomson’s multitaper method with three windows with linear detrending before analysis.

Handling of age control points (see package simproxyage for more details):

The function allows one to model the age uncertainty with several age control points (ACP) where the age uncertainty evolves according to the model of Comboul et al. (2014) between the age control points but is forced back to zero time uncertainty at the ACPs following a Brownian Bridge process.

Per default, the start age (i.e. the youngest age at the core top) is assumed to be the first ACP, thus, if not set explicitly in the vector acp, the youngest age is added as its first element. You can specify an arbitrary number of additional ACPs. Between each pair of ACPs (starting at the core top), constrained age perturbation realisations are performed following the Comboul et al. (2014) model and the Brownian Bridge concept. If the last ACP equals the oldest age in t (i.e. the last proxy data point), the last core segment also follows a Brownian Bridge process. Alternatively, if the last ACP is younger than the final age, NA is added as the last element to the vector acp which results in an unconstrained age perturbation process for the last core segment.

ACPs lying outside the time interval defined by t will be removed from the vector acp with a warning.

References

Comboul, M., Emile-Geay, J., Evans, M. N., Mirnateghi, N., Cobb, K. M. and Thompson, D. M.: A probabilistic model of chronological errors in layer-counted climate proxies: applications to annually banded coral archives, Clim. Past, 10(2), 825-841, https://doi.org/10.5194/cp-10-825-2014, 2014.

Münch, T. and Laepple, T.: What climate signal is contained in decadal- to centennial-scale isotope variations from Antarctic ice cores? Clim. Past, 14, 2053–2070, https://doi.org/10.5194/cp-14-2053-2018, 2018.

Author