R: Windowed scale index

windowed_scale_index {wavScalogram}

R Documentation

Windowed scale index

Description

This function computes the windowed scale indices of a signal in the scale interval [s_0,s_1], for a given set of scale parameters s_1 and taking s_0 as the minimum scale (see Benítez et al. 2010).

The windowed scale index of a signal in the scale interval [s_0,s_1] centered at time tc and with time windows radius windowrad is given by the quotient

\frac{WS_{windowrad}(tc,s_{min})}{WS_{windowrad}(tc,s_{max})},

where WS_{windowrad} is the corresponding windowed scalogram with time windows radius windowrad, s_{max} \in [s_0,s_1] is the smallest scale such that WS_{windowrad}(tc,s)\le WS_{windowrad}(tc,s_{max}) for all s \in [s_0,s_1], and s_{min} \in [s_{max},2s_1] is the smallest scale such that WS_{windowrad}(tc,s_{min})\le WS_{windowrad}(tc,s) for all s \in [s_{max},2s_1].

Usage

windowed_scale_index(signal = NULL,
                            wsc = NULL,
                            wsc_coi = NULL,
                            dt = 1,
                            scales = NULL,
                            powerscales = TRUE,
                            s1 = NULL,
                            windowrad = NULL,
                            delta_t = NULL,
                            wname = c("MORLET", "DOG", "PAUL", "HAAR", "HAAR2"),
                            wparam = NULL,
                            waverad = NULL,
                            border_effects = c("BE", "INNER", "PER", "SYM"),
                            makefigure = TRUE,
                            time_values = NULL,
                            figureperiod = TRUE,
                            plot_wsc = FALSE,
                            xlab = "Time",
                            ylab = NULL,
                            main = "Windowed Scale Index",
                            zlim = NULL)

Arguments

`signal`	A vector containing the signal whose windowed scale indices are wanted.
`wsc`	A matrix containing the windowed scalograms from which the windowed scale indices are going to be computed (number of times x number of scales, as it is returned by the `windowed_scalogram` function). If `wsc` is not `NULL`, then `signal`, `windowrad`, `delta_t`, `waverad` and `border_effects` are not necessary and they are ignored.
`wsc_coi`	A vector of length `nrow(wsc)` (i.e. number of times) containing the values of the maximum scale at each time from which there are border effects in the windowed scalogram `wsc`. If `wsc` is `NULL`, then `wsc_coi` is not necessary and it is ignored.
`dt`	Numeric. The time step of the signal.
`scales`	A vector containing the wavelet scales at wich the windowed scalograms are computed. This can be either a vector with all the scales or, following Torrence and Compo 1998, a vector of 3 elements with the minimum scale, the maximum scale and the number of suboctaves per octave. In the first case, `powerscales` must be `FALSE` if the given scales are not power 2 scales. In the second case, `powerscales` must be `TRUE` in order to construct power 2 scales using a base 2 logarithmic scale). If `scales` is NULL, they are automatically constructed.
`powerscales`	Logical. It must be TRUE (default) only in these cases: If `scales` are power 2 scales, i.e. they use a base 2 logarithmic scale. If we want to construct power 2 scales automatically. In this case, `scales` must be `NULL`. If we want to construct power 2 scales from `scales`. In this case, `length(scales)` must be 3. Otherwise, it must be `FALSE`.
`s1`	A vector containing the scales `s_1`. The windowed scale indices are computed in the intervals `[s_0,s_1]`, where `s_0` is the minimum scale in `scales`. If `s1` are not power 2 scales, then `scales` should not be power 2 scales either and hence, `powerscales` must be `FALSE`.
`windowrad`	Integer. Time radius for the windows, measured in dt. By default, it is set to `ceiling(length(signal) / 20)`.
`delta_t`	Integer. Increment of time for the construction of windows central times, measured in `dt`. By default, it is set to `ceiling(length(signal) / 256)`.
`wname`	A string, equal to "MORLET", "DOG", "PAUL", "HAAR" or "HAAR2". The difference between "HAAR" and "HAAR2" is that "HAAR2" is more accurate but slower.
`wparam`	The corresponding nondimensional parameter for the wavelet function (Morlet, DoG or Paul).
`waverad`	Numeric. The radius of the wavelet used in the computations for the cone of influence. If it is not specified, it is asumed to be `\sqrt{2}` for Morlet and DoG, `1/\sqrt{2}` for Paul and 0.5 for Haar.
`border_effects`	A string, equal to "BE", "INNER", "PER" or "SYM", which indicates how to manage the border effects which arise usually when a convolution is performed on finite-lenght signals. "BE": With border effects, padding time series with zeroes. "INNER": Normalized inner scalogram with security margin adapted for each different scale. "PER": With border effects, using boundary wavelets (periodization of the original time series). "SYM": With border effects, using a symmetric catenation of the original time series.
`makefigure`	Logical. If TRUE (default), a figure with the windowed scale indices is plotted.
`time_values`	A numerical vector of length `length(signal)` containing custom time values for the figure. If NULL (default), it will be computed starting at 0.
`figureperiod`	Logical. If TRUE (default), periods are used in the figure instead of scales.
`plot_wsc`	Logical. If TRUE, it plots the windowed scalograms from which the windowed scale indices are computed.
`xlab`	A string giving a custom X axis label.
`ylab`	A string giving a custom Y axis label. If NULL (default) the Y label is either "s1" or "Period of s1" depending on the value of `figureperiod` if `length(s1) > 1`, or "Windowed Scale Index" if `length(s1) == 1`.
`main`	A string giving a custom main title for the figure.
`zlim`	A vector of length 2 with the limits for the z-axis (the color bar).

Value

A list with the following fields:

wsi: A matrix of size length(tcentral) x length(s1) containing the values of the corresponding windowed scale indices.
s0: The scale s_0.
s1: The vector of scales s_1.
smax: A matrix of size length(tcentral) x length(s1) containing the scales s_{max}.
smin: A matrix of size length(tcentral) x length(s1) containing the scales s_{min}.
wsc: A matrix of size length(tcentral) x length(scales) containing the windowed scalograms from which the windowed scale indices are computed.
scalog_smax: A matrix of size length(tcentral) x length(s1) containing the values of the corresponding scalograms at scales s_{max}.
scalog_smin: A matrix of size length(tcentral) x length(s1) containing the values of the corresponding scalograms at scales s_{min}.
tcentral: The vector of central times used in the computation of wsi.
windowrad: Radius for the time windows, measured in dt.
fourierfactor: A factor for converting scales into periods.
coi_maxscale: A vector of length length(tcentral) containing the values of the maximum scale at each time from which there are border effects.

References

R. Benítez, V. J. Bolós, M. E. Ramírez. A wavelet-based tool for studying non-periodicity. Comput. Math. Appl. 60 (2010), no. 3, 634-641.

Examples


dt <- 0.1
time <- seq(0, 50, dt)
signal <- c(sin(pi * time), sin(pi * time / 2))
# First, we try with default s1 scales (a vector with a wide range of values for s1).
wsi_full <- windowed_scale_index(signal = signal, dt = dt, figureperiod = FALSE)
# Next, we choose a meaningful s1 value, greater than all relevant scales.
wsi <- windowed_scale_index(signal = signal, dt = dt, s1 = 4, figureperiod = FALSE)

# Another way, giving the windowed scalograms instead of the signal:

wsc <- windowed_scalogram(signal = signal, dt = dt, figureperiod = FALSE,
                          energy_density = FALSE, makefigure = FALSE)
wsi_full <- windowed_scale_index(wsc = wsc$wsc, wsc_coi = wsc$coi_maxscale,
                                 scales = wsc$scales, time_values = wsc$tcentral,
                                 figureperiod = FALSE)
wsi <- windowed_scale_index(wsc = wsc$wsc, wsc_coi = wsc$coi_maxscale,
                            scales = wsc$scales, s1 = 4, time_values = wsc$tcentral,
                            figureperiod = FALSE)

[Package wavScalogram version 1.1.3 Index]