psd: pilot_spec – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

psd

pilot_spec

Calculate initial power spectral density estimates

Description

This PSD is used as the starting point – the pilot spectrum – for the adaptive estimation routine.

Usage

pilot_spec(x, ...)

## S3 method for class 'ts'
pilot_spec(x, ...)

## S3 method for class 'matrix'
pilot_spec(x, x.frequency, ...)

## Default S3 method:
pilot_spec(
  x,
  x.frequency = NULL,
  ntap = NULL,
  remove.AR = NULL,
  plot = FALSE,
  verbose = FALSE,
  fast = FALSE,
  ...
)

Arguments

`x`	vector; the data series to find a pilot spectrum for
`...`	additional parameters passed to `psdcore`
`x.frequency`	scalar; the sampling frequency (e.g. Hz) of the series
`ntap`	scalar; the number of tapers to apply during spectrum estimation
`remove.AR`	scalar; the max AR model to be removed from the data.
`plot`	logical; should a plot be created?
`verbose`	logical; should messages be given?
`fast`	logical; use fast method in `psdcore`?

Details

A fixed number of tapers is applied across all frequencies using psdcore, and subsequent taper-refinements are based on the spectral derivatives of this spectrum; hence, changes in the number of tapers can affect how many adaptive stages may be needed (though there are no formal convergence criteria to speak of).

The taper series of the returned spectrum is constrained using as.tapers(..., minspan=TRUE).

The default behavior (remove.AR <= 0) is to remove the standard linear model [f(x) = α x + β] from the data; however, the user can model the effect of an autoregressive process by specifying remove.AR.

Value

Invisibly, an object with class 'spec', and "pilot_psd" in the working environment.

Removing an AR effect from the spectrum

If remove.AR > 0 the argument is used as AR.max in prewhiten, from which an AR-response spectrum is calculated using the best fitting model.

If the value of remove.AR is too low the spectrum could become distorted, so use with care. Note, however, that the value of remove.AR will be restricted to within the range [1,100]. If the AR order is much larger than this, it's unclear how prewhiten will perform and whether the AR model is appropriate.

Note that this function does not produce a parametric spectrum estimation; rather, it will return the amplitude response of the best-fitting AR model as spec.ar would. Interpret these results with caution, as an AR response spectrum can be misleading.

Author(s)

A.J. Barbour

Examples

## Not run: #REX
library(psd)

##
## Pilot spectrum
##

data(magnet)

## simply calculate the pilot spectrum with a few tapers
plot(pilot_spec(xc <- magnet$clean), log="dB", 
     main="Pilot PSDs for MAGNET and its AR-innovations (red)")

## remove the effect of an AR model
# note: remove.AR -- the max AR model to be removed from the data
plot(pilot_spec(xc, remove.AR=10), log="dB", add=TRUE, col="red")


## End(Not run)#REX

psd

Adaptive, Sine-Multitaper Power Spectral Density and Cross Spectrum Estimation

v2.1.0

GPL (>= 2)

Authors

Andrew J. Barbour [aut, cre] (<https://orcid.org/0000-0002-6890-2452>), Jonathan Kennel [aut] (<https://orcid.org/0000-0003-4474-6886>), Robert L. Parker [aut]

Initial release

2020-06-28