Covariance {glmmrBase}

R6 Class representing a covariance function and data

Description

R6 Class representing a covariance function and data

R6 Class representing a covariance function and data

Details

For the generalised linear mixed model

Y \sim F(\mu,\sigma)

\mu = h^-1(X\beta + Z\gamma)

\gamma \sim MVN(0,D)

where h is the link function, this class defines Z and D. The covariance is defined by a covariance function, data, and parameters. A new instance can be generated with $new(). The class will generate the relevant matrices Z and D automatically. See glmmrBase for a detailed guide on model specification.

**Intitialisation** A covariance function is specified as an additive formula made up of components with structure (1|f(j)). The left side of the vertical bar specifies the covariates in the model that have a random effects structure. The right side of the vertical bar specify the covariance function 'f' for that term using variable named in the data 'j'. Covariance functions on the right side of the vertical bar are multiplied together, i.e. (1|f(j)*g(t)).

There are several common functions included for a named variable in data x. A non-exhaustive list (see glmmrBase for a full list): * gr(x): Indicator function (1 parameter) * fexp(x): Exponential function (2 parameters) * ar(x): AR function (2 parameters) * sqexp(x): Squared exponential (1 parameter) * matern(x): Matern function (2 parameters) * bessel(x): Modified Bessel function of the 2nd kind (1 parameter) For many 2 parameter functions, such as 'ar' and 'fexp', alternative one parameter versions are also available as 'ar0' and 'fexp0'. These function omit the variance parameter and so can be used in combination with 'gr' functions such as 'gr(j)*ar0(t)'.

Parameters are provided to the covariance function as a vector. The parameters in the vector for each function should be provided in the order the covariance functions are written are written. For example, * Formula: '~(1|gr(j))+(1|gr(j*t))'; parameters: 'c(0.05,0.01)' * Formula: '~(1|gr(j)*fexp0(t))'; parameters: 'c(0.05,0.5)'

Updating of parameters is automatic if using the 'update_parameters()' member function.

Using 'update_parameters()' is the preferred way of updating the parameters of the mean or covariance objects as opposed to direct assignment, e.g. 'self$parameters <- c(...)'. The function calls check functions to automatically update linked matrices with the new parameters.

Public fields

data

Data frame with data required to build covariance

formula

Covariance function formula.

parameters

Model parameters specified in order of the functions in the formula.

Z

Design matrix

D

Covariance matrix of the random effects

Methods

Public methods

• Covariance$n()

• Covariance$new()

• Covariance$update_parameters()

• Covariance$print()

• Covariance$subset()

• Covariance$chol_D()

• Covariance$log_likelihood()

• Covariance$simulate_re()

• Covariance$sparse()

• Covariance$parameter_table()

• Covariance$nngp()

• Covariance$hsgp()

• Covariance$clone()

Method n()

Return the size of the design

Usage

Covariance$n()

Returns

Scalar

Method new()

Create a new Covariance object

Usage

Covariance$new(formula, data = NULL, parameters = NULL)

Arguments

formula

Formula describing the covariance function. See Details

data

(Optional) Data frame with data required for constructing the covariance.

parameters

(Optional) Vector with parameter values for the functions in the model formula. See Details.

Returns

A Covariance object

Examples

\dontshow{
setParallel(FALSE) # for the CRAN check
}
df <- nelder(~(cl(5)*t(5)) > ind(5))
cov <- Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.7),
                      data= df)

Method update_parameters()

Updates the covariance parameters

Usage

Covariance$update_parameters(parameters)

Arguments

parameters

A vector of parameters for the covariance function(s). See Details.

Method print()

Show details of Covariance object

Usage

Covariance$print()

Arguments

...

ignored

Examples

\dontshow{
setParallel(FALSE) # for the CRAN check
}
df <- nelder(~(cl(5)*t(5)) > ind(5))
Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.8),
                      data= df)

Method subset()

Keep specified indices and removes the rest

Usage

Covariance$subset(index)

Arguments

index

vector of indices to keep

Examples

\dontshow{
setParallel(FALSE) # for the CRAN check
}
df <- nelder(~(cl(10)*t(5)) > ind(10))
cov <- Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.8),
                      data= df)
cov$subset(1:100)

Method chol_D()

Returns the Cholesky decomposition of the covariance matrix D

Usage

Covariance$chol_D()

Returns

A matrix

Method log_likelihood()

The function returns the values of the multivariate Gaussian log likelihood with mean zero and covariance D for a given vector of random effect terms.

Usage

Covariance$log_likelihood(u)

Arguments

u

Vector of random effects

Returns

Value of the log likelihood

Method simulate_re()

Simulates a set of random effects from the multivariate Gaussian distribution with mean zero and covariance D.

Usage

Covariance$simulate_re()

Returns

A vector of random effect values

Method sparse()

If this function is called then sparse matrix methods will be used for calculations involving D

Usage

Covariance$sparse(sparse = TRUE, amd = TRUE)

Arguments

sparse

Logical. Whether to use sparse methods (TRUE) or not (FALSE)

amd

Logical indicating whether to use and Approximate Minimum Degree algorithm to calculate an efficient permutation matrix so that the Cholesky decomposition of PAP^T is calculated rather than A.

Returns

None. Called for effects.

Method parameter_table()

Returns a table showing which parameters are members of which covariance function term.

Usage

Covariance$parameter_table()

Returns

A data frame

Method nngp()

Reports or sets the parameters for the nearest neighbour Gaussian process

Usage

Covariance$nngp(nn = NULL)

Arguments

nn

Integer. Number of nearest neighbours. Optional - leave as NULL to return details of the NNGP instead.

Returns

If 'nn' is NULL then the function will either return FALSE if not using a Nearest neighbour approximation, or TRUE and the number of nearest neighbours, otherwise it will return nothing.

Method hsgp()

Reports or sets the parameters for the Hilbert Space Gaussian process

Usage

Covariance$hsgp(m = NULL, L = NULL)

Arguments

m

Integer or vector of integers. Number of basis functions per dimension. If only a single number is provided and there is more than one dimension the same number will be applied to all dimensions.

L

Decimal. The boundary extension.

Returns

If 'm' and 'L' are NULL then the function will either return FALSE if not using a Hilbert space approximation, or TRUE and the number of bases functions and boundary value, otherwise it will return nothing.

Method clone()

The objects of this class are cloneable with this method.

Usage

Covariance$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

## ------------------------------------------------
## Method `Covariance$new`
## ------------------------------------------------


df <- nelder(~(cl(5)*t(5)) > ind(5))
cov <- Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.7),
                      data= df)

## ------------------------------------------------
## Method `Covariance$print`
## ------------------------------------------------


df <- nelder(~(cl(5)*t(5)) > ind(5))
Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.8),
                      data= df)

## ------------------------------------------------
## Method `Covariance$subset`
## ------------------------------------------------


df <- nelder(~(cl(10)*t(5)) > ind(10))
cov <- Covariance$new(formula = ~(1|gr(cl)*ar0(t)),
                      parameters = c(0.05,0.8),
                      data= df)
cov$subset(1:100)