R: Calculate an inverse relationship matrix

ainverse {asreml} | R Documentation

## Calculate an inverse relationship matrix

### Description

Generates an inverse of a numerator relationship matrix in sparse triplet form from a pedigree data frame.

### Usage

    ainverse(
      pedigree,
      fgen = list(character(0), 0.01),
      gender = character(0),
      groups = 0,
      groupOffset = 0,
      selfing = NA,
      inBreed = NA,
      mgs = FALSE,
      mv = NULL,
      psort = FALSE,
      core_version = NULL
    )

### Arguments

`pedigree` | A data frame where the first three columns correspond to the identifiers for the individual, male parent and female parent, respectively. The row giving the pedigree of an individual must appear before any row where that individual appears as a parent. Founders or unknown parents use 0 (zero) or `NA` in the parental columns.
`fgen` | An optional list of length two where `fgen[[1]]` is a character string naming the column in `pedigree` that contains the level of selfing or the level of inbreeding of an individual. In `pedigree[,fgen[[1]]]`, 0 indicates a simple cross, 1 indicates selfed once, 2 indicates selfed twice, etc. A value between 0 and 1 for a base individual is taken as its inbreeding value. If the pedigree has implicit individuals (they appear as parents but not as individuals), they will be assumed base non-inbred individuals unless their inbreeding level is set with `fgen[[2]]`, where `0 < fgen[[2]] < 1` is the inbreeding level of such individuals.
`gender` | An optional character string naming the column of `pedigree` that codes for the gender of an individual. `pedigree[, gender]` is coerced to a factor and must only have two (arbitrary) levels, the first of which is taken to mean "male". An inverse relationship matrix is formed for the X chromosome as described by Fernando and Grossman, 1990 for species where the male is XY and the female is XX.
`groups` | An integer scalar (`g`) indicating genetic groups in the pedigree. The first `g` lines of the pedigree identify the genetic groups (with zero in both the male and female parent columns). All other rows must specify one of the genetic groups as the male or female parent if the actual parent is unknown (default `g=0`).
`groupOffset` | A numeric scalar e > 0 added to the diagonal elements of A^-1 pertaining to `groups`, shrinking the group effects by `e`. When a constant is added, no adjustment of the degrees of freedom is made for genetic groups. Set to -1 to add no offset but to suppress insertion of constraints where empty groups appear; the empty groups are then not counted in the degrees of freedom adjustment (default `e=0`).
`selfing` | A numeric scalar (s) allowing for partial selfing when the third field of `pedigree` is unknown. It indicates that progeny from a cross where the male parent is unknown is assumed to be from selfing with probability s and from outcrossing with probability (1-s). This is appropriate in some forestry tree breeding studies where seed collected from a tree may have been pollinated by the mother tree or pollinated by some other tree (Dutkowski and Gilmour, 2001). Do not use the `selfing` argument in conjunction with `inBreed` or `mgs`.
`inBreed` | A numeric scalar giving the inbreeding coefficient for base individuals. This argument generates the numerator relationship matrix for inbred lines. Each cross is assumed to be selfed several times to stabilize as an inbred line as is usual for cereal crops, for example, before being evaluated or crossed with another line. Since inbreeding is usually associated with strong selection, it is not obvious that a pedigree assumption of covariance of 0.5 between parent and offspring actually holds. The `inBreed` argument cannot be used in conjunction with `selfing` or `mgs` (default = `NA`).
`mgs` | If `TRUE`, the third identity in the pedigree is the male parent of the female parent (maternal grand-sire) rather than the female parent (default = `FALSE`).
`mv` | A character vector of missing value indicators; elements of `pedigree` that exactly match any of the members of `mv` are treated as missing. The values passed are used in addition to `"0"` and `"NA"` which are hardcoded as missing value indicators.
`psort` | If `TRUE`, the pedigree data frame is returned in founder order after any insertions and permutations (default = `FALSE`).
`core_version` | The version of the algorithmic core to use, not usually required.

### Details

Uses the method of Meuwissen and Luo, 1992 to compute the inverse relationship matrix directly from the pedigree.

### Value

A three-column matrix with class `ginv` holding the lower triangle of the inverse relationship matrix in sparse form. The first two columns are the row and column indices, respectively, and the third column holds the inverse matrix element itself. Sort order is columns within rows, that is, the lower triangle row-wise. This matrix has attributes:

`rowNames`

  A character vector of identifiers for the rows of the matrix.

`inbreeding`

  A numeric vector containing the inbreeding coefficient for each individual, calculated as `diag(A-I)`.

`geneticGroups`

  A numeric vector of length two containing the `groups` and `groupOffset` arguments.

`logdet`

  The log determinant.

### Examples

    ## Not run:

    # Simple pedigree
    ped <- data.frame(
      me  = c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10),
      dad = c(0, 0, 0, 1, 1, 2, 4, 5, 7, 9),
      mum = c(0, 0, 0, 1, 1, 2, 6, 6, 8, 9))
    p.ai <- ainverse(ped)

    # Known filial generation
    pdfg <- data.frame(
      me   = c(1, 2, 3, 4, 5, 6, 7),
      dad  = c(0, 0, 1, 1, 1, 1, 1),
      mum  = c(0, 0, 0, 2, 2, 2, 2),
      fgen = c(NA, 0.8, 0.0, 2.0, 0.0, 2.0, 3.0))
    pdfg.ai <- ainverse(pdfg, fgen = list("fgen", 0.4))
    pdfg.mat <- sp2mat(pdfg.ai)
    zapsmall(solve(pdfg.mat))
    zapsmall(cbind(pdfg.a$inbreeding, diag(pdfg.mat)))

    ## End(Not run)

[Package asreml version 4.2.0.480 Index]