asreml.ainverse

Calculate an inverse relationship matrix

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

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

Arguments:

• pedigree: A pandas data frame where the first three columns, corresponding to the identifiers for the individual, male parent and female parent, respectively. These columns can either be numerical or text. For indicating founders or unknown parents see missing_values. An ASReml data dictionary from define_categorical_variables can also be input.
• selfing_levels: A list of length two where the first entry is the name of a numerical column in pedigree the data frame that contains the level of selfing or the level of inbreeding of an individual. A value of 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 using the second element of selfing_levels, where 0 < selfing_levels[[2]] < 1 is the inbreeding level of such individuals.
• gender: The name of the column of pedigree that codes for the gender of an individual. This column must only have two (arbitrary) levels, the first of which is taken to mean "male". If this is a text column, then common labels such as ("male", "female"), ("stag", "hind"), ("ram", "ewe"), ("bull", "cow") will also be correctly handled. When gender is set, 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. Gender cannot be set if selfing_levels has been given.
• groups: An integer scalar, g, indicating the number of 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
• group_offset: 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 this 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
• 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 inbreeding or maternal_grand_sire.
• inbreeding: 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 inbreeding argument cannot be used in conjunction with selfing or maternal_grand_sire.
• maternal_grand_sire: (maternal grand-sire) If True, the third identity in the pedigree is the male parent of the female parent (maternal grand-sire) rather than the female parent.
• missing_values: A list of missing value indicators; elements of pedigree that exactly match any of the members of missing_values are treated as missing. The values passed are used in addition to "0" and "NA" which are always taken as missing value indicators.
• return_pedigree: If True, the pedigree data frame is returned.

Returns:

If return_pedigree is True, then the pedigree data frame is returned in founder order after any insertions and permutations, otherwise a sparse matrix data frame is returned, as described below. The 4 columns of the pedigree data frame are "id", "male", "female" and "ids", with an optional fifth column "gender" or "selfing_levels" giving the values for gender or selfing_levels if these have been set. The ids column is a text column giving the original ids supplied to function, and id, male, female hold numerical ids 1...n assigned to the unique individuals in the pedigree. The uids will be in alphabetical order apart from the requirement that parents must come before their progeny.

Otherwise a three-column pandas data frame 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. The relationship matrix is symmetric with zeros in any positions not specified in the data frame.