randlsp {lomb}

Randomise Lomb-Scargle Periodogram

Description

randlsp is used to obtain robust p-values for the significance of the largest peak in a Lomb-Scargle periodogram by randomisation. The data sequence is scrambled repeatedly and the probability of random peaks reaching or exceeding the peak in the original (unscrambled) periodogram is computed.

Usage

randlsp(repeats=1000,x, times = NULL, from = NULL, to = NULL,
    type = c("frequency", "period"), ofac = 1, alpha = 0.01,
    plot = TRUE, trace = TRUE, ...)

Arguments

repeats

An integer determining the number of repeated randomisations. Large numbers (>=1000) are better but can make the procedure time-consuming.

x

The data to be analysed. x can be either a two-column numerical dataframe or matrix, with sampling times in columnn 1 and measurements in column 2, a single numerical vector containing measurements, or a single vector ts object (which will be converted to a numerical vector).

times

If x is a single vector, times can be provided as a numerical vector of equal length containing sampling times. If x is a vector and times is NULL, the data are assumed to be equally sampled and times is set to 1:length(x).

from

The starting frequency (or period, depending on type) to begin scanning for periodic components.

to

The highest frequency (or period, depending on type) to scan.

type

Either “frequency” (the default) or “period”. Determines the type of the periodogram x-axis.

ofac

The oversampling factor. Must be an integer >=1. Larger values of ofac lead to finer scanning of frequencies but may be time-consuming for large datasets and/or large frequency ranges (from...to).

alpha

The significance level. The periodogram plot shows a horizontal dashed line. Periodogram peaks exceeding this line can be considered significant at alpha. Defaults to 0.01. Only used if plot=TRUE.

plot

Logical. If TRUE, two plots are displayed (i) The periodogram of the original (unscrambled) data (ii) A histogram of peaks occurring by chance during sequence randomisation. A vertical line is drawn at the height of the peak in a periodogram of the original data.

trace

Logical. If TRUE, information about the progress of the randomisation procedure is printed during the running of randlsp.

...

Additional graphical parameters affecting the histogram plot.

Details

Function randlsp preserves the actual measurement intervals, which may affect the periodogram (see Nemec & Nemec 1985, below). Hence, this is a conservative randomisation procedure.

P-values from both randlsp and lsp increase with the number of frequencies inspected. Therefore, if the frequency-range of interest can be narrowed down a priori, use arguments “from” and “to” to do so.

Value

A named list with the following items:

scanned

A vector containing the frequencies/periods scanned.

power

A vector containing the normalised power corresponding to scanned frequencies/periods.

data

Names of the data vectors analysed.

n

The length of the data vector.

type

The periodogram type used, either “frequency” or “period”.

ofac

The oversampling factor used.

n.out

The length of the output (powers). This can be >n if ofac >1.

peak

The maximum power in the frequency/period interval inspected.

peak.at

The frequency/period at which the maximum peak occurred.

random.peaks

A vector of peaks (with length=repeats) of maximum power values computed from randomised data.

repeats

The number of randomisations.

p.value

The probability that the peak in the original data occurred by chance, computed from randomising the data sequence.

Author(s)

Thomas Ruf [e-mail]

References

Nemec A.F.L, Nemec J.M. (1985) A test of significance for periods derived using phase-dispersion-miminimization techniques. The Astronomical Journal 90:2317–2320

See Also

lsp

Examples

data(lynx)
set.seed(444)
rand.times <- sample(1:length(lynx),30) # select a random vector of sampling times
randlsp(repeats=1000,lynx[rand.times],times=rand.times)