Toeplitz {SuperGauss}

Constructor and methods for Toeplitz matrix objects.

Description

The Toeplitz class contains efficient methods for linear algebra with symmetric positive definite (i.e., variance) Toeplitz matrices.

Usage

is.Toeplitz(x)

as.Toeplitz(x)

## S3 method for class 'Toeplitz'
dim(x)

Arguments

x

An R object.

Details

An ⁠N x N⁠ Toeplitz matrix Tz is defined by its length-N "autocorrelation" vector acf, i.e., first row/column Tz. Thus, for the function stats::toeplitz(), we have Tz = toeplitz(acf).

It is assumed that acf defines a valid (i.e., positive definite) variance matrix. The matrix multiplication methods still work when this is not the case but the other methods do not (return values typically contain NaNs).

as.Toeplitz(x) attempts to convert its argument to a Toeplitz object by calling Toeplitz$new(acf = x). is.Toeplitz(x) checks whether its argument is a Toeplitz object.

Methods

Public methods

• Toeplitz$new()

• Toeplitz$print()

• Toeplitz$size()

• Toeplitz$set_acf()

• Toeplitz$get_acf()

• Toeplitz$has_acf()

• Toeplitz$prod()

• Toeplitz$solve()

• Toeplitz$log_det()

• Toeplitz$trace_grad()

• Toeplitz$trace_hess()

• Toeplitz$clone()

Method new()

Class constructor.

Usage

Toeplitz$new(N, acf)

Arguments

N

Size of Toeplitz matrix.

acf

Autocorrelation vector of length N.

Returns

A Toeplitz object.

Method print()

Print method.

Usage

Toeplitz$print()

Method size()

Get the size of the Toeplitz matrix.

Usage

Toeplitz$size()

Returns

Size of the Toeplitz matrix. ncol(), nrow(), and dim() methods for Toeplitz objects also work as expected.

Method set_acf()

Set the autocorrelation of the Toeplitz matrix.

Usage

Toeplitz$set_acf(acf)

Arguments

acf

Autocorrelation vector of length N.

Method get_acf()

Get the autocorrelation of the Toeplitz matrix.

Usage

Toeplitz$get_acf()

Returns

The autocorrelation vector of length N.

Method has_acf()

Check whether the autocorrelation of the Toeplitz matrix has been set.

Usage

Toeplitz$has_acf()

Returns

Logical; TRUE if Toeplitz$set_acf() has been called.

Method prod()

Toeplitz matrix-matrix product.

Usage

Toeplitz$prod(x)

Arguments

x

Vector or matrix with N rows.

Returns

The matrix product Tz %*% x. Tz %*% x and x %*% Tz also work as expected.

Method solve()

Solve a Toeplitz system of equations.

Usage

Toeplitz$solve(x, method = c("gschur", "pcg"), tol = 1e-10)

Arguments

x

Optional vector or matrix with N rows.

method

Solve method to use. Choices are: gschur for a modified version of the Generalized Schur algorithm of Ammar & Gragg (1988), or pcg for the preconditioned conjugate gradient method of Chen et al (2006). The former is faster and obtains the log-determinant as a direct biproduct. The latter is more numerically stable for long-memory autocorrelations.

tol

Tolerance level for the pcg method.

Returns

The solution in z to the system of equations Tz %*% z = x. If x is missing, returns the inverse of Tz. solve(Tz, x) and solve(Tz, x, method, tol) also work as expected.

Method log_det()

Calculate the log-determinant of the Toeplitz matrix.

Usage

Toeplitz$log_det()

Returns

The log-determinant log(det(Tz)). determinant(Tz) also works as expected.

Method trace_grad()

Computes the trace-gradient with respect to Toeplitz matrices.

Usage

Toeplitz$trace_grad(acf2)

Arguments

acf2

Length-N autocorrelation vector of the second Toeplitz matrix. This matrix must be symmetric but not necessarily positive definite.

Returns

Computes the trace of

solve(Tz, toeplitz(acf2)).

This is used in the computation of the gradient of log(det(Tz(theta))) with respect to theta.

Method trace_hess()

Computes the trace-Hessian with respect to Toeplitz matrices.

Usage

Toeplitz$trace_hess(acf2, acf3)

Arguments

acf2

Length-N autocorrelation vector of the second Toeplitz matrix. This matrix must be symmetric but not necessarily positive definite.

acf3

Length-N autocorrelation vector of the third Toeplitz matrix. This matrix must be symmetric but not necessarily positive definite.

Returns

Computes the trace of

solve(Tz, toeplitz(acf2)) %*% solve(Tz, toeplitz(acf3)).

This is used in the computation of the Hessian of log(det(Tz(theta))) with respect to theta.

Method clone()

The objects of this class are cloneable with this method.

Usage

Toeplitz$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# construct a Toeplitz matrix
acf <- exp(-(1:5))
Tz <- Toeplitz$new(acf = acf)
# alternatively, can allocate space first
Tz <- Toeplitz$new(N = length(acf))
Tz$set_acf(acf = acf)

# basic methods
Tz$get_acf() # extract the acf
dim(Tz) # == c(nrow(Tz), ncol(Tz))
Tz # print method

# linear algebra methods
X <- matrix(rnorm(10), 5, 2)
Tz %*% X
t(X) %*% Tz
solve(Tz, X)
determinant(Tz) # log-determinant