spaMM (version 4.5.0)

diallel: Random-effect structures for diallel experiments and other dyadic interactions

Description

ranGCA and diallel are random-effect structures designed to represent the effet of symmetric interactions between pairs of individuals (order of individuals in the pair does not matter), while antisym represents anti-symmetric interactions (the effect of reciprocal ordered pairs on the outcome are opposite, as in the so-called Bradley-Terry models). These random-effect structures all account for multiple membership, i.e., the fact that the same individual may act as the first or the second individual among different pairs, or even within one pair if this makes sense).

More formally, the outcome of an interaction between a pair \(i,j\) of agents is subject to a symmetric overall random effect \(v_{ij}\) when the effect “on” individual \(i\) (or viewed from the perspective of individual \(i\)) equals the effect on \(j\): \(v_{ij}=v_{ji}\). This may result from the additive effect of individual random effects \(v_{i}\) and \(v_{j}\): \(v_{ij}=v_i+v_j\), but also from non-additive effects \(v_{ij}=v_i+v_j+a_{ij}\) if the interaction term \(a_{ij}\) is itself symmetric (\(a_{ij}=a_{ji}\)). ranGCA and diallel effects represent such symmetric effects, additive or non-additive respectively, in a model formula (see Details for the semantic origin of these names and how they can be changed). Conversely, antisymmetry is characterized by \(v_{ij}=v_i-v_j=-v_{ji}\) and is represented by the antisym formula term.

If individual-level random effects of the form (1|ID1)+ (1|ID2) were included in the model formula instead of ranGCA(1|ID1+ID2) for symmetric additive interactions, this would result in different variances being fitted for each random effect (breaking the assumption of symmetry), and the value of the random effect would differ for an individual whether it appears as a level of the first random effect or of the second (which is also inconsistent with the idea that the random effect represents a property of the individual).

When ranGCA or antisym random effects are fitted, the individual effects are inferred. By contrast, when a diallel random effect is fitted, an autocorrelated random effect \(v_{ij}\) is inferred for each unordered pair (no individual effect is inferred), with correlation \(\rho\) between levels for pairs sharing one individual. This correlation parameter is fitted and is constrained by \(\rho < 0.5\) (see Details). ranGCA is equivalent to the case \(\rho= 0.5\). diallel fits can be slow for large data if the correlation matrix is large, as this matrix can have a fair proportion of nonzero elements. There may also be identifiability issues for variance parameters: in a LMM as shown in the examples, there will be three parameters for the random variation (phi, lambda and rho) but only two can be estimated if only one observation is made for each dyad.

Usage

## formula terms:
# ranGCA(1| <.> + <.>) 
# antisym(1| <.> + <.>) 
# diallel(1|  <.> + <.>, tpar, fixed = NULL, public = NULL)
## where the <.> are two factor identifiers, ** whose levels
## must be identical when representing the same individual **
## corrFamily constructors:
ranGCA() # no argument
antisym() # no argument
diallel(tpar, fixed = NULL, public = NULL)

Value

The functions return corrFamily descriptors whose general format is described in corrFamily. The ones produced by ranGCA and antisym are atypical in that only their Af element is non-trivial.

Arguments

tpar

Numeric: template value of the correlation coefficient for pairs sharing one individual.

fixed

NULL or fixed value of the correlation coefficient.

public

NULL, or an environment. When an empty environment is provided, a template CorNA for the correlation matrix (with NA's in place of \(\rho\)) will be copied therein, for inspection at user level.

Details

Although the symmetric random-effect structures may be used in many different contexts (including social network analysis, or “round robin” experiments in psychology; another possibly relevant literature keyword here is “multi membership”), their present names refer to the semantics established for diallel experiments (e.g., Lynch & Walsh, 1998, p. 611), because it is not easy to find a more general yet intuitive semantics. If the names ranGCA and diallel sound inappropriate for your context of application, you can declare and use an alternative name for them, taking advantage of the fact that they are random-effect structures defined through corrFamily constructors, which are functions named as the formula term. For example, symAdd(1|ID1+ID2) can be used in a model formula after the following two steps:

# Define the 'symAdd' corrFamily constructor (a function) by copy:
symAdd <- ranGCA     
# Associate the 'symAdd' function to 'symAdd' formula terms:
register_cF("symAdd")  

In diallel experiments, one analyzes the phenotypes of offspring from multiple crosses among which the mother in a cross can be the father in another, so this is an example of multiple-membership. The additive genetic effects of each parent's genotypes are described as “general combining abilities” (GCA). In case of non-additive effect, the half-sib covariance is not half the full-sib covariance and this is represented by the interaction \(a_{ij}\) described as “specific combining abilities” (SCA). The sum of GCA and SCA defines a synthetic random effect “received” by the offspring, with distinct levels for each unordered parental pair, and with correlation \(\rho\) between effects received by half-sibs (one shared parent). \(\rho\) corresponds to var(GCA)/[2*var(GCA)+var(SCA)] and is necessarily \(\le 0.5\).

See the X.GCA documentation for similar constructs for fixed effects.

References

Lynch, M., Walsh, B. (1998) Genetics and analysis of quantitative traits. Sinauer, Sunderland, Mass.

Examples

#### Simulate dyadic data

set.seed(123)
nind <- 10       # Beware data grow as O(nind^2)
x <- runif(nind^2) 
id12 <- expand.grid(id1=seq(nind),id2=seq(nind))
id1 <- id12$id1
id2 <- id12$id2
u <-  rnorm(nind,mean = 0, sd=0.5)

## additive individual effects:
y <-  0.1 + 1*x + u[id1] +  u[id2] + rnorm(nind^2,sd=0.2)

## Same with non-additive individual effects:
dist.u <- abs(u[id1] -  u[id2])
z <- 0.1 + 1*x + dist.u + rnorm(nind^2,sd=0.2)

## anti-smmetric individual effects:
t <-  0.1 + 1*x + u[id1] - u[id2] + rnorm(nind^2,sd=0.2)

dyaddf <- data.frame(x=x, y=y, z=z, t=t, id1=id1,id2=id2)
# : note that this contains two rows per dyad, which avoids identifiability issues.

# Enforce that interactions are between distinct individuals (not essential for the fit):
dyaddf <- dyaddf[- seq.int(1L,nind^2,nind+1L),] 


# Fits:

(addfit <- fitme(y ~x +ranGCA(1|id1+id2), data=dyaddf))
#
# practically equivalent to:
#
(fitme(y ~x +diallel(1|id1+id2, fixed=0.49999), data=dyaddf))

(antifit <- fitme(t ~x +antisym(1|id1+id2), data=dyaddf))

(distfit <- fitme(z ~x +diallel(1|id1+id2), data=dyaddf))