Compute a spectrogram based on Sokolove & Bushell's periodogram

spectrogram() computes a series of Sokolove & Bushell's (1978) \(\chi^{2}\) periodograms with the purpose of visualize differences in periodicities in a given interval of a tsibble object.

See ?periodogram to learn more about the periodogram computation.

spectrogram(
  data,
  col,
  p_unit = "minutes",
  p_min = 1000,
  p_max = 2500,
  p_step = 1,
  int_unit = "days",
  int_n = 7,
  int_step = 720,
  alpha = 0.05,
  print = TRUE
)

Arguments

data

A tsibble object.

col

A string indicating which column of data to use.

p_unit

(optional) a string indicating at which time unit the index must be aggregated. By aggregating the index, this will change the time series interval and, consequently, its p periods. Valid values are: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”, “quarters”, and “years”) (default: "minutes").

p_min

(optional) an integer number indicating the minimum period (\(p\)), with the same unit as p_unit, to compute the test (e.g., if p_unit = "minutes", p_min = 1 means a period of 1 minute) (default: 1000).

p_max

(optional) an integer number indicating the maximum period (\(p\)), with the same unit as p_unit, to compute the test (default: 2500).

p_step

(optional) an integer number indicating the range of values that must be skipped between computing one test and the next (e.g., when p_min == 1, p_max == 7, and p_step == 2, the test periods will be 1, 3, 5, and 7) (default: 1).

int_unit

(optional) a string indicating the interval unit. Valid values are: “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”, “quarters”, and “years”) (default: "days").

int_n

(optional) an integer number indicating the size of the intervals, with the same unit as int_unit (default: 7).

int_step

(optional) an integer number indicating the amount of epochs to advance at the end of each interval (default: 720).

alpha

(optional) a number, from 0 to 1, indicating the significant level required for the peaks. The spectrogram plot only shows the significant peaks (default: 0.05).

print

(optional) a logical value indicating if the function must print the spectrogram plot (default: TRUE).

Value

A list object with the following elements:

• periodograms: a list object with the periodogram data for each interval. See ?periodogram() to learn more about the list elements.

• spectrogram: a ggplot object with a heat map chart showing one periodogram per line (q_p)(y) by the period sequence (p_seq) (x).

References

Sokolove, P. G., & Bushell, W. N. (1978). The chi square periodogram: its utility for analysis of circadian rhythms. Journal of Theoretical Biology, 72(1), 131-160. doi:10.1016/0022-5193(78)90022-x .

See also

Other period analysis functions: periodogram()

Examples

if (FALSE) {
if (requireNamespace("curl", quietly = TRUE) &&
    requireNamespace("jsonlite", quietly = TRUE) &&
    requireNamespace("tools", quietly = TRUE)) {
        if (curl::has_internet()) {
            file <- get_from_zenodo(
                doi = "10.5281/zenodo.4898822", path = tempdir(),
                file = "processed.txt"
            )

            data <- read_acttrust(file, tz = "America/Sao_Paulo")
            spec <- spectrogram(data, "pim")
        }
}
}