| Title: | Sliding Window Discrete Fourier Transform (SWDFT) |
|---|---|
| Description: | Implements the Sliding Window Discrete Fourier Transform (SWDFT). Also provides statistical methods based on the SWDFT, and graphical tools to display the outputs. |
| Authors: | Lee F. Richardson [aut, cre] |
| Maintainer: | Lee F. Richardson <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.0 |
| Built: | 2025-02-11 04:13:08 UTC |
| Source: | https://github.com/cran/swdft |
Coefficients method for swdft_cosreg objects
## S3 method for class 'swdft_mod' coefficients(object, ...)## S3 method for class 'swdft_mod' coefficients(object, ...)
object |
A swdft_cosreg object |
... |
optional arguments to match generic function |
Complex Demodulation
complex_demod(x, f0, smooth = "butterworth", order = 5, passfreq = 0.1, match_swdft = FALSE, window_size = NULL)complex_demod(x, f0, smooth = "butterworth", order = 5, passfreq = 0.1, match_swdft = FALSE, window_size = NULL)
x |
numeric vector |
f0 |
numeric scalar. Frequency to demodulate |
smooth |
character. Type of smoothing to use, accepts either 'ma', 'double_ma', or 'butterworth' (the default) |
order |
moving average parameter if 'smooth' argument equals 'ma' or 'double_ma'. Defaults to 5 |
passfreq |
numeric scalar. Pass frequency used in butterworth low-pass filter. Defaults to .1 which corresponds to a pass frequency of 2 * f0. |
match_swdft |
logical. Only used to demonstrate equivalence w/ SWDFT when a moving average filter is used. Otherwise, never used. |
window_size |
defaults to NULL, only used when match_swdft=TRUE, so can ignore. |
An S3 'swdft_demod' object. See ?new_swdft_matching_demod for details.
Chapter 7 of 'Fourier Analysis of Time-Series' by Peter Bloomfield and this blog post: https://dankelley.github.io/r/2014/02/17/demodulation.html for the idea of using a butterworth filter.
Cosine signal with adjustable parameters
cosine(N, A = 1, Fr = 1, phase = 0)cosine(N, A = 1, Fr = 1, phase = 0)
N |
signal length |
A |
Amplitude |
Fr |
Frequency: Number of cycles in a length N period |
phase |
phase |
numeric vector with cosine function of x
Cosine bell data taper
cosine_taper(n, p = 0.1)cosine_taper(n, p = 0.1)
n |
length of time-series to taper |
p |
proportion of ends to taper |
length n cosine bell taper w/ proportion p
Cosine regression
cosreg(x, f)cosreg(x, f)
x |
numeric. Signal. |
f |
numeric. scalar or vector of frequencies to fit. |
S3 object of class 'swdft_cosreg'. See ?new_swdft_cosreg for details.
Covariance between two complex-numbered outputs
cov_swdft_cnum(k, l, delta, n, sigma)cov_swdft_cnum(k, l, delta, n, sigma)
k |
frequency of first coefficient |
l |
frequency of second coefficient |
delta |
window position shift of second coefficient |
n |
window size |
sigma |
white noise standard error |
complex-valued number of the covariance
Demodulate a Fourier Frequency with the SWDFT
demod_swdft(a, k)demod_swdft(a, k)
a |
swdft |
k |
frequency to demodulate |
Dirichlet Kernel (Weight) for arbitrary summation indices
dirichlet(x, phase = 0, a = 0, b = length(x) - 1)dirichlet(x, phase = 0, a = 0, b = length(x) - 1)
x |
numeric to evaluate |
phase |
defaults to 0 |
a |
start of summation index |
b |
end of summation index |
sum of a complex exponential sum
Dirichlet Kernel
dirichlet_kernel(x, n, dw = FALSE)dirichlet_kernel(x, n, dw = FALSE)
x |
variable evaluated by dirichlet kernel |
n |
size of Dirichlet kernel |
dw |
logical whether to add the Dirichlet Weight (DW) factor |
evaluation of the Dirichlet Kernel (D_n(x))
Fitted values method for swdft_cosreg objects
## S3 method for class 'swdft_mod' fitted(object, ...)## S3 method for class 'swdft_mod' fitted(object, ...)
object |
A swdft_cosreg object |
... |
optional arguments to match generic function |
Extract amplitude and phase
get_aphi(x, S, L, f)get_aphi(x, S, L, f)
x |
signal |
S |
start parameter |
L |
length pe |
f |
frequency |
Get range of frequencies to search
get_freq_range(a, kwidth)get_freq_range(a, kwidth)
a |
2D complex-valued array. The SWDFT to search |
kwidth |
integer. the width of frequencies to search |
Compute the log likelihood
get_loglik(x, fitted, sigma, N)get_loglik(x, fitted, sigma, N)
x |
signal |
fitted |
fitted values |
sigma |
estimated standard deviation |
N |
length of x |
Get the maximum DFT coefficient
get_max_freq(x)get_max_freq(x)
x |
numeric vector |
numeric of largest frequency. Will be between 0 and .5
Get range of P's to search
get_p_range(phat, n, N, pwidth, type = "around_max")get_p_range(phat, n, N, pwidth, type = "around_max")
phat |
integer. Window position with largest SWDFT coefficient |
n |
integer. window size |
N |
integer. Signal length |
pwidth |
integer. the range of window positions to search for each window size |
type |
character. either 'around max' or 'fullp'. |
Extract estimator of sigma
get_sigma(x, fitted, N)get_sigma(x, fitted, N)
x |
signal |
fitted |
fitted values |
N |
length of x |
Extract signal parameters
get_sl(n, p)get_sl(n, p)
n |
window size |
p |
window position |
Create taper for the SWDFT
get_taper(n, taper, p)get_taper(n, taper, p)
n |
window size |
taper |
taper type. Can be either 'none' (default) or 'cosine' |
p |
proportion to taper on each end, if cosine taper is used |
length n taper
Log Likelihood
lcr_loglik(f, x, S, L, ftype = "full")lcr_loglik(f, x, S, L, ftype = "full")
f |
frequency |
x |
signal |
S |
start parameter |
L |
length pe |
ftype |
what to return |
Local cosine regression
local_cosreg(x, lmin = 6, pwidth = 5, kwidth = 1, verbose = FALSE)local_cosreg(x, lmin = 6, pwidth = 5, kwidth = 1, verbose = FALSE)
x |
numeric signal to apply local cosine regression on |
lmin |
integer. minimum signal length (L parameter) to search |
pwidth |
integer. the range of window positions to search for each window size |
kwidth |
integer. the width of frequencies to search |
verbose |
logical. whether or not to print intermediate results |
S3 object of class 'swdft_local_cosreg'
Local Periodic Signal
local_signal(N, A = 1, Fr = 1, phase = 0, S = 0, L = N)local_signal(N, A = 1, Fr = 1, phase = 0, S = 0, L = N)
N |
signal length |
A |
Amplitude |
Fr |
Frequency: Number of cycles in a length N period |
phase |
phase |
S |
start of local signal |
L |
length of local signal |
length N local periodic signal
Matching Demodulation
matching_demod(x, n, thresh = 0.05, max_cycles = 5, smooth = "butterworth", order = 5, passfreq = 0.1, debug = FALSE)matching_demod(x, n, thresh = 0.05, max_cycles = 5, smooth = "butterworth", order = 5, passfreq = 0.1, debug = FALSE)
x |
numeric. Signal to demodulate |
n |
integer. Window size for SWDFT |
thresh |
numeric. Threshold to determine whether to continue demodulating |
max_cycles |
maximum number of demodulation cycles |
smooth |
character. Type of smoothing to use, accepts either 'ma', 'double_ma', or 'butterworth' (the default) |
order |
moving average parameter if 'smooth' argument equals 'ma' or 'double_ma'. Defaults to 5 |
passfreq |
numeric scalar. Pass frequency used in butterworth low-pass filter. defaults to .1 |
debug |
Logical. Whether to print out intermediate output. |
An S3 'swdft_matching_demod' object. See ?new_swdft_matching_demod for details.
Simple high pass filter
moving_average(x, order)moving_average(x, order)
x |
the vector or time-series |
order |
the order of the filter |
Constructor function for class 'swdft'
new_swdft(a, x, n, type, pad, taper_type, taper, p, smooth, m, num_convs)new_swdft(a, x, n, type, pad, taper_type, taper, p, smooth, m, num_convs)
a |
2D complex array of SWDFT coefficients. If there is smoothing, then this represents the smoothed squared modulus coefficients. |
x |
numeric input signal |
n |
window size |
type |
'fftw' or 'fft' |
pad |
whether or not it was padded |
taper_type |
type of taper |
taper |
numeric values of the taper |
p |
of cosine taper (if used) |
smooth |
type of smoother |
m |
width of kernel for smoothing (optional) |
num_convs |
number of kernel convolutions (optional) |
list w/ the same elements as the arguments, an S3 object of class 'swdft'
Constructor function for class swdft_mod
new_swdft_cosreg(coefficients, fitted, residuals, data)new_swdft_cosreg(coefficients, fitted, residuals, data)
coefficients |
matrix of coefficients for cosine regression model |
fitted |
fitted values of cosine regression model |
residuals |
residuals of cosine regression model |
data |
original signal used to fit cosine regression |
list with the following elements
coefficients. A matrix of parameters, the three columns are: 1. amplitude 2. phase, and 3. frequency. There is only more that one row used when multiple frequencies are fit sequentially.
fitted. fitted values of cosine regression model
residuals. residuals of cosine regression model
data. original signal used to fit cosine regression
Constructor function for class 'swdft_demod'
new_swdft_demod(x, f0, A_t, Phi_t, fitted, y, y_smooth, smooth, order, passfreq)new_swdft_demod(x, f0, A_t, Phi_t, fitted, y, y_smooth, smooth, order, passfreq)
x |
numeric vector |
f0 |
numeric scalar. Frequency to demodulate |
A_t |
extracted amplitude from y_smooth |
Phi_t |
extracted phase from y_smooth |
fitted |
fitted values |
y |
non-smoothed demodulated signal |
y_smooth |
smoothed demodulated signal |
smooth |
character. Type of smoothing to use, accepts either 'ma', 'double_ma', or 'butterworth' (the default) |
order |
moving average parameter if 'smooth' argument equals 'ma' or 'double_ma'. Defaults to 5 |
passfreq |
numeric frequency used as the passfreq in the low-pass filter |
list with the following elements
coefficients. A matrix of parameters, the three columns are: 1. amplitude 2. phase, and 3. frequency. There is only more that one row used when multiple frequencies are fit sequentially.
fitted. fitted values of cosine regression model
residuals. residuals of cosine regression model
data. original signal used to fit cosine regression
list with the filter used ('smooth') and parameters ('order' for 'ma' or 'double_ma', 'passfreq' for butterworth)
list w/ the demodulated signal, and smoothed demodulated signal
Constructor function for class 'swdft_local_cosreg'
new_swdft_local_cosreg(coefficients, fitted, residuals, data, window_params)new_swdft_local_cosreg(coefficients, fitted, residuals, data, window_params)
coefficients |
matrix of coefficients for cosine regression model |
fitted |
fitted values of cosine regression model |
residuals |
residuals of cosine regression model |
data |
original signal used to fit cosine regression |
window_params |
data frame of fitted coefficients for each window size |
list with the following elements
coefficients. A matrix of parameters, the three columns are: 1. amplitude 2. phase, and 3. frequency. There is only more that one row used when multiple frequencies are fit sequentially.
fitted. fitted values of cosine regression model
residuals. residuals of cosine regression model
data. original signal used to fit cosine regression
window_params. data frame of fitted coefficients for each window size
Constructor function for class 'swdft_matching_demod'
new_swdft_matching_demod(x, n, fitted, thresh, max_cycles, smooth, order, passfreqs, maxvals, freqs, khats, amps, phases, demods, cycle, resids, fits, return_rows)new_swdft_matching_demod(x, n, fitted, thresh, max_cycles, smooth, order, passfreqs, maxvals, freqs, khats, amps, phases, demods, cycle, resids, fits, return_rows)
x |
numeric. Signal to demodulate |
n |
integer. Window size for SWDFT |
fitted |
fitted values |
thresh |
numeric. Threshold to determine whether to continue demodulating |
max_cycles |
maximum number of demodulation cycles |
smooth |
character. Type of smoothing to use, accepts either 'ma', 'double_ma', or 'butterworth' (the default) |
order |
moving average parameter if 'smooth' argument equals 'ma' or 'double_ma'. Defaults to 5 |
passfreqs |
pass frequency used in each iteration |
maxvals |
Maximum SWDFT coefficient for each iteration |
freqs |
Frequencies used in each iteration |
khats |
Integer version of frequency. |
amps |
Instantaneous amplitude for each iteration |
phases |
Instantaneous phase for each iteration |
demods |
List of demodulated signal and smoothed demodulated signal for each iteration |
cycle |
Number of cycles used |
resids |
Residuals for each iteration |
fits |
Fitted values for each iteration |
return_rows |
Logical vector indicating which iterations occurred. Used for subsetting. |
list with the following elements
coefficients. coefficients from the R local signals with time-varying amplitude and phase model.
fitted. fitted values of cosine regression model
residuals. residuals of cosine regression model
data. original signal used to fit cosine regression
smooth. list with the filter used ('smooth') and parameters ('order' for 'ma' or 'double_ma', 'passfreq' for butterworth)
demod. list w/ the demodulated signal, and smoothed demodulated signal
thresh. Threshold used.
iterations. List of fits, residuals, and maximum values for each iteration
Constructor function for class 'swdft2d'
new_swdft2d(a, x, n0, n1, type)new_swdft2d(a, x, n0, n1, type)
a |
4D complex-valued array of 2D SWDFT coefficients |
x |
2D real or complex valued signal |
n0 |
window size in row direction |
n1 |
window size in column direction |
type |
algorithm to implement. defaults to "fftw", other option 'fft' for R's base FFT function. R's base fft function is used if |
S3 object w/ the same elements as arguments to this constructor function
Constructor function for class 'swdft3d'
new_swdft3d(a, x, n0, n1, n2, type)new_swdft3d(a, x, n0, n1, n2, type)
a |
4D complex-valued array of 2D SWDFT coefficients |
x |
3D real or complex-valued array |
n0 |
window size in dimension 0 |
n1 |
window size in dimension 1 |
n2 |
window size in dimension 2 |
type |
defaults to 'base', which is the only option |
S3 object w/ the same elements as arguments to this constructor function
Plot method for 'swdft' object
## S3 method for class 'swdft' plot(x, freq_type = "cycles", fs = NULL, hertz_range = NULL, take_log = FALSE, log_thresh = 1e-05, use_fields = TRUE, scale_shrink = 0.9, zlim = NULL, xlab = "Window Position", ylab = "Frequency (Cycles/Window)", title = "SWDFT", cex_main = 1, cex_lab = 1, cex_axis = 1, xaxis_subset = NULL, custom_xaxis = NULL, custom_yaxis = NULL, col = "grayscale", display = TRUE, ...)## S3 method for class 'swdft' plot(x, freq_type = "cycles", fs = NULL, hertz_range = NULL, take_log = FALSE, log_thresh = 1e-05, use_fields = TRUE, scale_shrink = 0.9, zlim = NULL, xlab = "Window Position", ylab = "Frequency (Cycles/Window)", title = "SWDFT", cex_main = 1, cex_lab = 1, cex_axis = 1, xaxis_subset = NULL, custom_xaxis = NULL, custom_yaxis = NULL, col = "grayscale", display = TRUE, ...)
x |
Object of class 'swdft'. If x$a is complex-valued, it is converted to the squared modulus. If x$a is real-valued, then we assume that it represents the squared |
freq_type |
Specify how to display the frequency axis. Either 'cycles' (default), 'fraction', or 'hertz' |
fs |
sample rate. Used if freq_type='hertz' |
hertz_range |
integer vector, given by (low, high). Specifies the range of hertz to display and is only used when freq_type='hertz' |
take_log |
logical. Whether to take the log before plotting |
log_thresh |
numeric. Threshold for smallest possible value. Defaults to .000001, and is used to keep plots from displaying of ~ -40. |
use_fields |
logical. Determines whether we use image.plot from the fields package, or 'image' from the graphics package. The advantage of image.plot is that we get a color scale, so the default is TRUE |
scale_shrink |
Proportion between 0 and 1 to shrink the scale |
zlim |
Custom z range |
xlab |
Custom x-label |
ylab |
Custom y-label |
title |
Custom title |
cex_main |
how large to make the title |
cex_lab |
how large to make the labels |
cex_axis |
how large to make the axis labels |
xaxis_subset |
subset of x-axis (time / window position) for plotting |
custom_xaxis |
Defaults to NULL. Otherwise, used to change the x-axis |
custom_yaxis |
Defaults to NULL. Otherwise, used to change the y-axis |
col |
defaults to grayscale, can also be 'tim.colors' from fields package |
display |
logical. Defaults to TRUE, only used for testing purposes, so it should always be TRUE. |
... |
optional arguments to match the plot generic function |
Plot method for swdft_mod object
## S3 method for class 'swdft_mod' plot(x, y = NULL, ...)## S3 method for class 'swdft_mod' plot(x, y = NULL, ...)
x |
A swdft_cosreg object |
y |
not used, but required by plot generic function |
... |
optional arguments to match the plot generic function |
The principal nth root of unity
prou(n)prou(n)
n |
integer root |
complex number
Residuals method for swdft_cosreg objects
## S3 method for class 'swdft_mod' residuals(object, ...)## S3 method for class 'swdft_mod' residuals(object, ...)
object |
A swdft_cosreg object |
... |
optional arguments to match generic function |
Sine signal with adjustable parameters
sine(N, A = 1, Fr = 1, phase = 0)sine(N, A = 1, Fr = 1, phase = 0)
N |
length signal |
A |
Amplitude |
Fr |
Frequency: Number of cycles in a length N period |
phase |
phase |
numeric vector with sine
Smooth SWDFT coefficients with a convolution
smooth_pgram(a, fft_weight = NULL)smooth_pgram(a, fft_weight = NULL)
a |
real-valued length n periodogram |
fft_weight |
optionally specify the pre-computed FFT of the weights |
smoothed coefficients
Smooth the SWDFT coefficients
smooth_swdft(a, ktype = "daniell", m = 2, num_convs = 1)smooth_swdft(a, ktype = "daniell", m = 2, num_convs = 1)
a |
real or complex-valued swdft. If real-valued, then we assume it's the squared modules already. If it's complex valued, we convert to the squared modulus. |
ktype |
either 'daniell' or 'modified.daniell' |
m |
kernel width from stats::kernel |
num_convs |
num_convs from stats::kernel |
Smooth squared modulues SWDFT coefficients
Sliding Window Discrete Fourier Transform
swdft(x, n, type = "fftw", pad = TRUE, taper_type = "none", p = 0.1, smooth = "none", m = 2, num_convs = 1)swdft(x, n, type = "fftw", pad = TRUE, taper_type = "none", p = 0.1, smooth = "none", m = 2, num_convs = 1)
x |
real or complex vector |
n |
integer window size. |
type |
algorithm to implement. defaults to "fftw", other option 'fft' for R's base FFT function. R's base fft function is used if |
pad |
optionally zero-pad the array to that the output array has the same dimension as the original time-series |
taper_type |
type of taper for each window position. defaults to 'none', can also be 'cosine'. |
p |
Proportion to be tapered at each end of the series. Argument copied from the spec.taper function in the default stats package. Defaults to .1. |
smooth |
Type of smoother. Defaults to 'none', can also be 'daniell' or 'modified daniell'. If smooth is 'none', then the SWDFT returns the smoothed squared modulus coefficients, not the complex numbers |
m |
width of kernel. Defaults to 2 |
num_convs |
Number of times to convolve the kernel. Defaults to 1 |
An S3 'swdft' object. See ?new_swdft for details.
x <- rnorm(n = 20) a <- swdft(x, n = 2^3)x <- rnorm(n = 20) a <- swdft(x, n = 2^3)
3D SWDFT using base R
swdft_base_3d(x, n0, n1, n2)swdft_base_3d(x, n0, n1, n2)
x |
3D real or complex-valued array |
n0 |
window size in dimension 0 |
n1 |
window size in dimension 1 |
n2 |
window size in dimension 2 |
Sliding Window Discrete Fourier Transform with base R
swdft_fft(x, n, taper)swdft_fft(x, n, taper)
x |
real or complex vector |
n |
integer window size. |
taper |
length n vector to multiply against the input data for each window position |
n x P array, where P = length(x) - n + 1
Sliding Window Discrete Fourier Transform using fftw
swdft_fftw(x, n, taper)swdft_fftw(x, n, taper)
x |
real or complex vector |
n |
integer window size. |
taper |
length n vector to multiply against the input data for each window position |
n x P array, where P = length(x) - n + 1
Convert the SWDFT to proportions of frequency
swdft_to_props(a)swdft_to_props(a)
a |
swdft |
2D Sliding Window Discrete Fourier Transform
swdft2d(x, n0, n1, type = "fftw")swdft2d(x, n0, n1, type = "fftw")
x |
2D input signal |
n0 |
window size in row direction |
n1 |
window size in column direction |
type |
algorithm to implement. defaults to "fftw", other option 'fft' for R's base FFT function. R's base fft function is used if 'fftwtools' library is not installed. |
An S3 'swdft2d' object. See ?new_swdft for details.
2D Sliding Window Discrete Fourier Transform using base R
swdft2d_fft(x, n0, n1)swdft2d_fft(x, n0, n1)
x |
2D input signal |
n0 |
window size in row direction |
n1 |
window size in column direction |
2D Sliding Window Discrete Fourier Transform using fftw
swdft2d_fftw(x, n0, n1)swdft2d_fftw(x, n0, n1)
x |
2D input signal |
n0 |
window size in row direction |
n1 |
window size in column direction |
3D Sliding Window Discrete Fourier Transform
swdft3d(x, n0, n1, n2, type = "base")swdft3d(x, n0, n1, n2, type = "base")
x |
3D real or complex-valued array |
n0 |
window size in dimension 0 |
n1 |
window size in dimension 1 |
n2 |
window size in dimension 2 |
type |
defaults to 'base', which is the only option |
An S3 'swdft3d' object. See ?new_swdft for details.
Phase unwrapping
unwrap_phase(p)unwrap_phase(p)
p |
vector of phases fit by demodulation |