glmmrBase (version 0.4.6)

Covariance: 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

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$check()

• Covariance$update_parameters()

• Covariance$print()

• Covariance$subset()

• Covariance$get_chol_D()

• Covariance$log_likelihood()

• Covariance$simulate_re()

• Covariance$sparse()

• Covariance$parameter_table()

• 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, verbose = TRUE)

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.

verbose

Logical whether to provide detailed output.

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 check()

Check if anything has changed and update matrices if so.

Usage

Covariance$check(verbose = TRUE)

Arguments

verbose

Logical whether to report if any changes detected.

Returns

NULL

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.03,0.8),
                      data= df)
cov$parameters <- c(0.25,0.1)
cov$check(verbose=FALSE)

---

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 get_chol_D()

Returns the Cholesky decomposition of the covariance matrix D

Usage

Covariance$get_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)

Arguments

sparse

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

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 clone()

The objects of this class are cloneable with this method.

Usage

Covariance$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

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. If using direct assignment, call `self$check()` afterwards.

Examples

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

# \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 `Covariance$check`
## ------------------------------------------------

# \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.03,0.8),
                      data= df)
cov$parameters <- c(0.25,0.1)
cov$check(verbose=FALSE)

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

# \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 `Covariance$subset`
## ------------------------------------------------

# \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)