psd: psd-utilities – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

psd

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 class 'matrix'
na_locf(x)

## Default S3 method:
na_locf(x)

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)

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

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.

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

Note

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

Author(s)

A.J. Barbour

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

Examples

## 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

psd

Adaptive, Sine-Multitaper Power Spectral Density and Cross Spectrum Estimation

v2.1.0

GPL (>= 2)

Authors

Andrew J. Barbour [aut, cre] (<https://orcid.org/0000-0002-6890-2452>), Jonathan Kennel [aut] (<https://orcid.org/0000-0003-4474-6886>), Robert L. Parker [aut]

Initial release

2020-06-28