psd (version 0.4-1)

psd-utilities: Various utility functions.

Description

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.

dB returns an object converted to decibels.

char2envir converts a character string of an environment name to an evaluated name; whereas, envir2char converts an environment name to a character string.

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 reports whether an object has class S3 class 'spec', as would one returned by, for example, spectrum.

is.tapers reports whether an object has S3 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 nrow is enforced to be at least 1 for both functions.

mod finds the modulo division of X and Y.

Usage

vardiff(Xd, double.diff = FALSE)
varddiff(Xd)
dB(Rat, invert = FALSE, pos.only = TRUE, is.power = FALSE)
char2envir(envchar)
envir2char(envir)
vector_reshape(x, vec.shape = c("horizontal", "vertical"))
## S3 method for class 'default':
vector_reshape(x, vec.shape = c("horizontal", "vertical"))
colvec(x)
rowvec(x)
is.spec(Obj)
is.tapers(Obj)
na_mat(nrow, ncol = 1)
## S3 method for class 'default':
na_mat(nrow, ncol = 1)
zeros(nrow)
## S3 method for class 'default':
zeros(nrow)
ones(nrow)
## S3 method for class 'default':
ones(nrow)
mod(X, Y)
## S3 method for class 'default':
mod(X, Y)

Arguments

Xd

object to difference

double.diff

logical; should the double difference be used instead?

Rat

numeric; A ratio 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?

envchar

An object with class 'character'.

envir

An object of class 'environment'.

x

An object to reshape (vector_reshape).

vec.shape

choice between horizontally-long or vertically-long vector.

Obj

An object to test for class inheritance.

nrow

integer; the number of rows to create.

ncol

integer; the number of columns to create (default 1).

X

numeric; the "numerator" of the modulo division

Y

numeric; the "denominator" of the modulo division

Value

• char2envir returns the result of evaluating the object: an environment object; envir2char returns the result of deparsing the environment name: a character string.

  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 and is.tapers both return logicals about whether or not the object does have class 'spec' or 'tapers', respectively

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

  For zeros or ones respectively, a matrix vector with nrow zeros or ones.

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

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

See Also

psd-package, as.tapers

Examples

#RDEX#\dontrun{
require(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)
# return is class 'spec'
is.spec(PSD) # TRUE
# but the underlying structure is just a list
PSD <- unclass(PSD)
is.spec(PSD) # FALSE
##
## Environment character strings
##
print(envname <- get_psd_env_name())
print(envir <- char2envir(envname))
try(char2envir("some nonexistent environment"), silent=TRUE) # error
# and environment objects:
print(.GlobalEnv)
envir2char(.GlobalEnv)
envir2char(envir)
try(envir2char(some_nonexistent_environment), silent=TRUE) # error
##
## 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)
varddiff(X)
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
##
#RDEX#}