psd (version 2.1.2)

psd-utilities: Various utility functions.

Description

The various utility functions are:

na_locf is meant as a simple replacement for zoo::na.locf which carries the last observation forward; here we force both directions, meaning the first observation is carried backwards as well.

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

Usage

na_locf(x)
# S3 method for matrix
na_locf(x)
# S3 method for default
na_locf(x)
vardiff(x, double.diff = FALSE)
varddiff(x)
# S3 method for spec
varddiff(x)
# S3 method for default
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)

Value

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).

Arguments

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

Author

A.J. Barbour

Details

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.

References

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/show_bug.cgi?id=14771

See Also

psd-package, as.tapers, modulo_floor

Examples

if (FALSE) #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)

#REX