psd-utilities: Various utility functions.
In williamdeleo/psd: Adaptive, Sine-Multitaper Power Spectral Density Estimation

Description Usage Arguments Details Value Note Author(s) References See Also Examples

The various utility functions are:

vardiff returns the variance of the first (or second) difference of the series. varddiff is a convenience wrapper to return variance for the second difference.

create_poly generates an x-y sequence compatible for use with polygon

dB returns an object converted to decibels.

vector_reshape reshapes a vector into another vector.

colvec returns the object as a vertically long vector; whereas rowvec returns the object as a horizontally long vector.

is.spec and is.amt report whether an object has class 'spec' or 'amt', as would one returned by, for example, spectrum or psdcore.

is.tapers reports whether an object has class 'tapers', as would one returned by, for example, as.tapers.

na_mat populates a matrix of specified dimensions with NA values.

zeros populate a column-wise matrix with zeros; whereas, ones populates a column-wise matrix with ones. Note that n is enforced to be at least 1 for both functions.

mod finds the modulo division of two values

vardiff(x, double.diff = FALSE)

varddiff(x)

## S3 method for class 'spec'
varddiff(x)

## Default S3 method:
varddiff(x)

create_poly(x, y, dy, from.lower = FALSE)

dB(Rat, invert = FALSE, pos.only = TRUE, is.power = FALSE)

vector_reshape(x, vec.shape = c("horizontal", "vertical"))

colvec(x)

rowvec(x)

is.spec(Obj)

is.amt(Obj)

is.tapers(Obj)

na_mat(nrow, ncol = 1)

zeros(nrow)

ones(nrow)

mod(x, y)

`x, y`	objects; in `create_poly` these are the vectors used to create a `polygon`-compatible sequence (`x` is sorted by default); in `mod` these are the "numerator" and "denominator", respectively.
`double.diff`	logical; should the double difference be used instead?
`dy`	numeric; the distance from `y` to the top and bottom of the polygonal surfaces; see `from.lower`
`from.lower`	logical; should the bottom be `y` instead of `y+dy`, so that `dy` represents the distance from the lower surface?
`Rat`	numeric; the values – ratios – to convert to decibels (`dB`).
`invert`	logical; assumes `Rat` is already in decibels, so return ratio
`pos.only`	logical; if `invert=FALSE`, sets negative or zero values to NA
`is.power`	logical; should the factor of 2 be included in the decibel calculation?
`vec.shape`	choice between horizontally-long or vertically-long vector.
`Obj`	An object to test for class inheritance.
`nrow, ncol`	integer; the number of rows and/or columns to create

Decibels are defined as 10 \log{}_{10} \frac{X_1}{X_2}, unless is.power=TRUE in which \mathrm{db} X^2 \equiv 20 \log{}_{10} X^2

colvec, rowvec are simple wrapper functions to vector_reshape.

Modulo division has higher order-of-operations ranking than other arithmetic operations; hence, x + 1 %% y is equivalent to x + (1 %% y) which can produce confusing results. mod is simply a series of trunc commands which reduces the chance for unintentionally erroneous results.

vector_reshape returns a "reshaped" vector, meaning it has had it's dimensions changes so that it has either one row (if vec.shape=="horizontal"), or one column ("vertical").

is.spec, is.amt, and is.tapers return the output of inherits.

na_mat returns a matrix of dimensions (nrow,ncol) with NA values, the representation of which is set by NA_real_

mod returns the result of a modulo division, which is equivalent to (x) %% (y).

The performance of mod has not been tested against the %% arithmetic method – it may or may not be slower for large numeric vectors.

A.J. Barbour

For mod: see Peter Dalgaard's explanation of the non-bug (#14771) I raised (instead I should've asked it on R-help): https://bugs.r-project.org/bugzilla3/show_bug.cgi?id=14771\#c2

psd-package, as.tapers, modulo_floor

## Not run: #REX
library(psd)

##
## Various utilities
##

set.seed(1234)
X <- rnorm(1e2)

#
# Matrix and vector creation:
#
# NA matrix
nd <- 5
na_mat(nd)
na_mat(nd,nd-1)

# zeros
zeros(nd)

# and ones
ones(nd)

#
# Check for tapers object:
#
is.tapers(X)
is.tapers(as.tapers(X))

#
# Check for spec object:
#
PSD <- spectrum(X, plot=FALSE)
plot(PSD)
# return is class 'spec'
is.spec(PSD) # TRUE
# but the underlying structure is just a list
PSD <- unclass(PSD)
is.spec(PSD) # FALSE

#
# decibels
#
dB(1) # signal is equal <--> zero dB
sig <- 1e-10
all.equal(sig, dB(dB(sig), invert=TRUE))
pow <- sig**2
all.equal(pow, dB(dB(sig, is.power=TRUE), invert=TRUE, is.power=TRUE))

# 
# Variance of difference series
#
vardiff(X) # first difference
varddiff(X) # second difference
all.equal(vardiff(X, TRUE), varddiff(X))

#
# modulo division
#
x <- 1:10
mc1a <- mod(1,2)
mc2a <- mod(1+x,2)
mc1b <- 1 %% 2
mc2b <- 1 + x %% 2
mc2c <- (1 + x) %% 2
all.equal(mc1a, mc1b) # TRUE
all.equal(mc2a, mc2b) # "Mean absolute difference: 2"
all.equal(mc2a, mc2c) # TRUE
# on a series
modulo_floor(1:10) # defaults to 2
modulo_floor(1:10, 3)


## End(Not run)#REX