Package {corMLPE}

Correlation structure for symmetric relational data

Description

Correlation structure for symmetric relational data

Coerce a 'corMLPE' Object to a Correlation Matrix

Usage

corMLPE(value = 0.1, form = ~1, fixed = FALSE)

## S3 method for class 'corMLPE'
as.matrix(x, ...)

Arguments

Details

"Maximum likelihood population effects" (MLPE) is a correlation structure for dyadic, symmetric relational data: where each observation is a measurement for an unordered pair of elements from a set. For two (different) elements $i,j$, let E[y_{i,j}] be the expectation of the response variable (perhaps conditional on some random effects), and

y_{i,j} = E[y_{i,j}] + \alpha_{i} + \alpha_{j} + \epsilon_{i,j},

where \alpha are associated with unique elements of the set and are i.i.d zero-mean Gaussian random variables with standard deviation \tau; and \epsilon are i.i.d Gaussian errors with standard deviation \sigma. Marginally (after integrating out \alpha), the covariance between two observations y_{i,j} and y_{k,l} is

cov(y_{i,j}, y_{k,l}) = \tau^2 (\delta(i,k) + \delta(j,l))

where the function \delta evaluates to 1 when its arguments are equal and zero otherwise, and we order the indices so that i < j, k < l for convenience.

The marginal variance is var(y_{i,j}) = 2\tau^2 + \sigma^2. The corresponding correlation structure has a single parameter, \rho = \tau^2 / (2\tau^2 + \sigma^2) which is constrained to lie between 0 and 0.5.

The "form" argument of a corMLPE object must contain two variables that indicate the pair of elements associated with each observation, and can optionally contain a grouping factor that indicates the set to which the elements belong. Elements from different sets are treated as distinct even if they have the same label, and thus there is always a zero correlation between measurements across different sets.

For example, if "data.frame(elem1 = c(1,1,2), elem2 = c(2,3,4), grp = c(1,1,2))" were used as data with "form=~elem1 + elem2 | grp", then the first two observations would be correlated (because they are from the same group and share the element "1"), but would both be uncorrelated with the third observation (as the third observation is associated with the second set, despite involving an element "2" that is labelled identically to an element from the first set). The ordering within a pair does not matter. Multiple observations of the same pair of elements are allowed, as are missing combinations of pairs, but "self" comparisons are not (where both elements of a pair are the same).

It is important to note that this correlation structure does not directly incorporate a (dis)similarity metric (which could instead be included as a covariate in the regression model), but instead tries to account for the dependence between pairwise measurements taken between the same objects.

Value

'corMLPE()' returns an object of class 'corMLPE' and 'corStruct' for use as a correlation structure in 'nlme::gls()' or 'nlme::lme()'. The object stores the MLPE correlation parameter and the formula that identifies the two members of each pairwise observation. The 'as.matrix()' method returns the implied observation-level correlation matrix for an initialized 'corMLPE' object.

References

Clarke et al. 2002. Confidence limits for regression relationships between distance matrices: estimating gene flow with distance. Journal of Agricultural, Biological, and Environmental Statistics 7: 361-372.

Examples

dat <- simulate_IBD_corMLPE(sets = 1, elements = 5, seed = 1)
fit <- nlme::gls(
  y ~ x,
  data = dat,
  correlation = corMLPE(form = ~pop1 + pop2)
)
coef(fit$modelStruct$corStruct, unconstrained = FALSE)

Correlation Structure for Grouped Matern MLPE Models

Description

Correlation Structure for Grouped Matern MLPE Models

Usage

corMaternMLPE(
  value = c(0.1, 0.1),
  nu = 2,
  form = ~1,
  distances = FALSE,
  fixed = FALSE
)

## S3 method for class 'corMaternMLPE'
as.matrix(x, ...)

Arguments

Value

A 'corStruct' object of class 'corMaternMLPE'.

Correlation Structure for Clustered NMLPE Models

Description

Correlation Structure for Clustered NMLPE Models

Usage

corNMLPE(
  value = c(0.1, 0.1, 0.1, 0.1, 0.1),
  nu = 2,
  form = ~1,
  clusters = FALSE,
  distances = FALSE,
  fixed = FALSE
)

## S3 method for class 'corNMLPE'
as.matrix(x, ...)

Arguments

Value

A 'corStruct' object of class 'corNMLPE'.

Correlation Structure for Reduced-Basis NMLPE Models

Description

Correlation Structure for Reduced-Basis NMLPE Models

Usage

corNMLPE2(value = c(0.1, 0.1), form = ~1, clusters = FALSE, fixed = FALSE)

## S3 method for class 'corNMLPE2'
as.matrix(x, ...)

Arguments

Value

A 'corStruct' object of class 'corNMLPE2'.

Methods for Internal 'dgCMatrix_corMLPE' Objects

Description

These methods preserve class identity required for 'mgcv::gamm()' compatibility when sparse matrix operations are applied.

Usage

## S4 method for signature 'dgCMatrix_corMLPE'
t(x)

## S4 method for signature 'dgCMatrix_corMLPE,index,missing,logical'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'dgCMatrix_corMLPE,missing,index,logical'
x[i, j, ..., drop = TRUE]

Arguments

Value

The 't()' method returns a transposed 'dgCMatrix_corMLPE' object. The '[' methods return row- or column-subsets while preserving the 'dgCMatrix_corMLPE' class. These methods are used internally so sparse matrices generated by 'corMLPE' remain compatible with downstream model fitting code.

Examples

m <- Matrix::sparseMatrix(i = c(1, 2), j = c(1, 2), x = 1)
m <- methods::as(m, "dgCMatrix_corMLPE")
class(t(m))
class(m[1, , drop = FALSE])

Simulate data from an isolation-by-distance model with MLPE correlation structure

Description

Simulate data from an isolation-by-distance model with MLPE correlation structure

Usage

simulate_IBD_corMLPE(
  sets = 1,
  elements = rep(10, sets),
  intercept = 0,
  slope = 0.5,
  random_effects = diag(2),
  correlation = 0.25,
  residual_sd = 1,
  distances = NULL,
  seed = 1
)

Arguments

Value

A data frame with one row per pairwise observation and columns 'y', 'pop1', 'pop2', 'set', and 'x'. The response 'y' is simulated from an isolation-by-distance model with MLPE-correlated errors, 'pop1' and 'pop2' identify the paired elements, 'set' identifies the group, and 'x' is the pairwise distance. Model settings and simulated random effects are stored as attributes.

Examples

dat <- simulate_IBD_corMLPE(sets = 1, elements = 5, seed = 1)
head(dat)
attr(dat, "correlation")

Simulate data from a fitted corMLPE model

Description

Simulate data from a fitted corMLPE model

Usage

simulate_corMLPE_residuals(model, n = 1, seed = NULL)

Arguments

Value

A numeric matrix with one row per observation in 'model' and one column per simulation. Values are simulated residual vectors with the fitted 'corMLPE' dependence structure and the fitted residual standard deviation from the 'gls' model.

Examples

dat <- simulate_IBD_corMLPE(sets = 1, elements = 5, seed = 1)
fit <- nlme::gls(
  y ~ x,
  data = dat,
  correlation = corMLPE(form = ~pop1 + pop2)
)
sims <- simulate_corMLPE_residuals(fit, n = 2, seed = 2)
dim(sims)