*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

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

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

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

.

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.

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

# 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) # } # NOT RUN { #REX # }