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

## Description

rExamples2D() generates several example (locally) smooth target surfaces 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 5 in \insertCiteC18pdSpecEst.

## Usage

 1 2 3 rExamples2D(n, d = 2, example = c("smiley", "tvar", "facets", "peak"), replicates = 1, noise = "riem-gaussian", noise.level = 1, df.wishart = NULL) 

## Arguments

 n integer vector c(n1, n2) specifying the number of sampled matrices to be generated on a rectangular surface. d row- (resp. column-)dimension of the generated matrices. Defaults to d = 2. example the example target HPD matrix surface, one of 'smiley', 'tvar', 'facets' or 'peak'. replicates a positive integer specifying the number of replications of noisy HPD matrix surfaces to be generated based on the target surface of HPD matrices. Defaults to replicates = 1 noise noise distribution for the generated noisy surfaces 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. 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'). By default df.wishart is equal to the dimension d to guarantee positive definiteness of the generated noisy matrices.

## Details

The examples include: (i) a (d,d)-dimensional 'smiley' HPD matrix surface consisting of constant surfaces of random HPD matrices in the shape of a smiley face; (ii) a (d,d)-dimensional 'tvar' HPD matrix surface generated from a time-varying vector-auto- regressive process of order 1 with random time-varying coefficient matrix (Φ); (iii) a (d,d)-dimensional 'facets' HPD matrix surface consisting of several facets generated from random geodesic surfaces; and (iv) a (d,d)-dimensional 'peak' HPD matrix surface containing a pronounced peak in the center of its 2-d (e.g., time-frequency) domain.
In addition to the (locally) smooth target surface of HPD matrices, the function also returns a noisy version of the target surface 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 surface 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').

## Value

Returns a list with two components:

 f  a (d,d,n,n)-dimensional array, corresponding to the (n_1 \times n_2)-sized example target surface of (d,d)-dimensional HPD matrices. P  a (d,d,n,n)-dimensional array, corresponding to the (n_1 \times n_2)-sized surface of noisy (d,d)-dimensional HPD matrices centered around the smooth target HPD matrix surface f. If replicates > 1, P is a (d,d,n,n,length(replicates))-dimensional array, corresponding to a collection of replicated (n_1 \times n_2)-sized surfaces of noisy (d,d)-dimensional HPD matrices centered around the smooth target HPD matrix surface f.

## References

\insertAllCited

rExamples1D, pdPgram2D
 1 example <- rExamples2D(n = c(32, 32), example = "smiley")