# rExamples1D: Several example curves of HPD matrices In pdSpecEst: An Analysis Toolbox for Hermitian Positive Definite Matrices

## Description

`rExamples1D()` generates several example (locally) smooth target curves of HPD matrices corrupted by noise in a manifold of HPD matrices for testing and simulation purposes. For more details, see also Chapter 2 and 3 in \insertCiteC18pdSpecEst.

## Usage

 ```1 2 3 4``` ```rExamples1D(n, d = 3, example = c("bumps", "two-cats", "heaviSine", "gaussian", "mix-gaussian", "arma", "peaks", "blocks"), user.f = NULL, return.ts = FALSE, replicates = 1, noise = "riem-gaussian", noise.level = 1, df.wishart = NULL, nblocks = 10) ```

## Arguments

 `n` number of sampled matrices to be generated. `d` row- (resp. column-)dimension of the generated matrices. Defaults to `d = 3`. `example` the example target HPD matrix curve, one of `'bumps'`, `'two-cats'`, `'heaviSine'`, `'gaussian'`, `'mix-gaussian'`, `'arma'`, `'peaks'` or `'blocks'`. `user.f` user-specified target HPD matrix curve, should be a (d,d,n)-dimensional array, corresponding to a length n curve of (d,d)-dimensional HPD matrices. `return.ts` a logical value, if `return.ts = TRUE` the function also returns time series observations generated via the Cramer representation based on the transfer function of the example HPD spectral matrix and complex normal random variates. Defaults to `return.ts = FALSE`. `replicates` a positive integer specifying the number of replications of noisy HPD matrix curves to be generated based on the target curve of HPD matrices. Defaults to `replicates = 1` `noise` noise distribution for the generated noisy curves of HPD matrices, one of `'riem-gaussian'`, `'log-gaussian'`, `'wishart'`, `'log-wishart'` or `'periodogram'`, defaults to `'riem-gaussian'`. Additional details are given below. `noise.level` parameter to tune the signal-to-noise ratio for the generated noisy HPD matrix observations, only used if `noise != 'periodogram'`. If `noise.level = 0`, the noise distributions are degenerate and the noisy HPD matrix observations coincide with the target HPD matrices. Defaults to `noise.level = 1`. `df.wishart` optional parameter to specify the degrees of freedom in the case of a Wishart noise distribution (`noise = 'wishart'` or `noise = 'log-wishart'`); or the number of DPSS tapers in the case of generated periodogram matrices if `noise = 'periodogram'`. By default `df.wishart` is equal to the dimension `d` to guarantee positive definiteness of the generated noisy matrices. `nblocks` optional parameter to specify the number of constant segments in the `'blocks'` HPD matrix curve. Only used if `example = 'blocks'`.

## Details

The examples include: (i) a (3,3)-dimensional `'bumps'` HPD matrix curve containing peaks and bumps of various smoothness degrees; (ii) a (3,3)-dimensional `'two-cats'` HPD matrix curve visualizing the contour of two side-by-side cats, with inhomogeneous smoothness across the domain; (iii) a (3,3)-dimensional `'heaviSine'` HPD matrix curve consisting of smooth sinosoids with a break; (iv) a (2,2)-dimensional `'gaussian'` HPD matrix curve consisting of smooth Gaussian functions; (v) a (d,d)-dimensional `'mix-gaussian'` HPD matrix curve consisting of a weighted linear combination of smooth Gaussian functions; (vi) a (2,2)-dimensional `'arma'` HPD matrix curve generated from the smooth spectral matrix of a 2-dimensional stationary ARMA(1,1)-process; (vii) a (d, d)- dimensional `'peaks'` HPD matrix curve containing several sharp peaks across the domain; and (viii) a (d, d)-`'blocks'` HPD matrix curve generated from locally constant segments of HPD matrices.
In addition to the smooth target curve of HPD matrices, the function also returns a noisy version of the target curve of HPD matrices, corrupted by a user-specified noise distribution. By default, the noisy HPD matrix observations follow an intrinsic signal plus i.i.d. noise model with respect to the affine-invariant Riemannian metric, with a matrix log-Gaussian noise distribution (`noise = 'riem-gaussian'`), such that the Riemannian Karcher means of the observations coincide with the target curve of HPD matrices. Additional details can be found in Chapters 2, 3, and 5 of \insertCiteC18pdSpecEst. Other available signal-noise models include: (ii) a Log-Euclidean signal plus i.i.d. noise model, with a matrix log-Gaussian noise distribution (`noise = 'log-gaussian'`); (iii) a Riemannian signal plus i.i.d. noise model, with a complex Wishart noise distribution (`noise = 'wishart'`); (iv) a Log-Euclidean signal plus i.i.d. noise model, with a complex Wishart noise distribution (`noise = 'log-wishart'`); and (v) noisy periodogram observations obtained with `pdPgram` from a stationary time series generated via the Cramer representation based on the transfer function of the target HPD spectral matrix curve and complex normal random variates (`noise = 'periodogram'`). If `return.ts = TRUE`, the function also returns the generated time series observations, which are not generated by default if `noise != 'periodogram'`.

## Value

Depending on the input arguments returns a list with two or three components:

 `f ` a (d,d,n)-dimensional array, corresponding to the length n example target curve of (d,d)-dimensional HPD matrices. `P ` a (d,d,n)-dimensional array, corresponding to a length n curve of noisy (d,d)-dimensional HPD matrices centered around the smooth target HPD matrix curve `f`. If `replicates > 1`, `P` is a `(d,d,n,length(replicates))`-dimensional array, corresponding to a collection of replicated length n curves of noisy (d,d)-dimensional HPD matrices centered around the smooth target HPD matrix curve `f`. `ts ` generated d-dimensional time series observations, only available if `return.ts = TRUE`.

## Note

If `noise = 'wishart'`, the generated noisy HPD matrix observations are independent complex Wishart matrices, which can be interpreted informally as pseudo-periodogram matrix observations, as the periodogram matrices based on strictly stationary time series observations obtained with `noise = 'periodogram'` are asymptotically independent and asymptotically complex Wishart distributed, see e.g., \insertCiteB81pdSpecEst.

## References

\insertAllCited

`rExamples2D`, `pdPgram`, `rARMA`

## Examples

 ```1 2``` ```example <- rExamples1D(100, example = "bumps", return.ts = TRUE) plot.ts(Re(example\$ts), main = "3-d time series") # plot generated time series ```

pdSpecEst documentation built on Jan. 8, 2020, 5:08 p.m.