spaMM (version 4.6.1)

dyad: Correlated random effects in dyadic interactions

Description

mmfn is a function to be used for specifying random effects in asymmetric multi-membership interactions. This feature is experimental and has only been tested for some dyadic interactions.

The simplest case is that of dyadic interactions between one focal individual and its partner in each dyad. The models declared in this way include correlation parameter(s) for the correlation of effects expressed by a given individual in different possible roles (such as focal vs. partner).

At the same time, correlation of effects expressed among individuals in the same role can also be specified. For example, the random effects may represent genetic influences on focal and partner effects. The correlation between effects expressed in the focal role may depend on the relatedness between individuals, and likewise for effects expressed in the partner role. This can be specified by a random-effect term corrMatrix( <LHS> | <RHS> ) where:

* the LHS expression includes an expression of the form mm(<id1>, <id2>), <id1> and <id2> being two factors in the data; and the RHS expression is of the form mmfn(<id1>, <id2>). A dummy variable can be used instead of the mm(<id1>, <id2>) expression (see Examples), the factors to be used being determined from the RHS expression;

* The LHS expression is interpreted as a random-coefficient specification, meaning that distinct random effects \(u_{\code{<id1>}(i)}\),\(v_{\code{<id2>}(i)}\),... affect the \(i\)th response, and that correlations between the effects are fitted by default, as for other random-coefficient terms. The elements \(u_{\code{<id1>}(i)}\),\(v_{\code{<id2>}(j)}\),... are correlated when \(\code{<id1>}(i)\) and \(\code{<id2>}(j)\) are identical, rather than when \(i=j\). This is illustrated in the Examples, where the two factors represents roles of individuals as focal individuals and as their mothers, so distinct but correlated random effects \(u_{k}\),\(v_{k}\), affecting different levels of the response (\(i\neq j\)), are assigned to a same individual \(k\) in these two roles;

* a corrMatrix specifies the correlations of random effects among individuals in either role (correlations as focal, or correlations as partner). The whole corrMatrix( <LHS> | <RHS> ) expression thus describes a composite-ranef controlled by two correlation models, one for within-role correlations, the other for among-role correlations.

If the LHS is a more complex expression than only the mm(...) term (as in the Example with interaction with sex), different random effects vectors are assigned to each term implied by the LHS (as for random-coefficient terms specified by other syntaxes), and the corrMatrix specifies the correlations between the effects within each vector;

* the RHS of the form mmfn(...) specifies the factors containing the levels to be matched to rows and columns of the corrMatrix, in the same way as other forms of RHS serve to identify rows and columns of the correlation matrix of correlated random effects.

PAIRfn is an alias for mmfn (its name suggests that it handles only dyadic interactions, but the mmfn aims to be more general).

The syntax using a dummy variable assumes that this variable is present in the input data, as the numeric constant 1 (see Examples). By default, this dummy variable is named PAIR, though this can be changed by the VAR argument of mmfn or PAIRfn.

Usage

mmfn(..., VAR = "PAIR", only.vars=TRUE)
PAIRfn(..., VAR = "PAIR", only.vars=TRUE)
## formula term:
# corrMatrix(  < LHS using mm(<.>, <.>) >| PAIRfn(<.>, <.>) ) 
# corrMatrix(  < LHS using dummy variable >| PAIRfn(<.>, <.>) )

Arguments

...

factors present in the data provided for the fit, identifying the individuals in the dyadic or multi-membership interaction.

VAR

character: name of dummy variable possibly used in LHS of random-effect term.

only.vars

For programming purposes, not documented.

See Also

diallel for (anti-)symmetric dyadic interactions.

Examples

if (spaMM.getOption("example_maxtime")>1) {

data("Gryphon")
fitme(BWT ~ 1+ corrMatrix(mm(ID,mother) | PAIRfn(ID,mother)), 
      data=Gryphon_df, corrMatrix=Gryphon_A)

# : same as using a PAIR dummy variable as follows:
#
# Gryphon_df$PAIR <- 1 # Do not try other values.
# fitme(BWT ~ 1+ corrMatrix(PAIR | PAIRfn(ID,mother)), 
#       data=Gryphon_df, corrMatrix=Gryphon_A)

if (spaMM.getOption("example_maxtime")>15) {
  # Distinct random effects for each role, and each sex of the focal: 
  #
  fitme(BWT ~ 1+ corrMatrix(mm(ID,mother)*sex | PAIRfn(ID,mother)), 
        data=Gryphon_df, corrMatrix=Gryphon_A)
  #
  # This is controlled as other rancom-coefficient terms. E.g.,
  #   fixed=list(ranCoefs=list("1"=c(NA,0,0,0,NA,0,0,NA,0,NA)))
  # could be used to fit only the variances.

}
}