The pyp_nrm Module

pyp_nrm contains several procedures for computing numerator relationship matrices and for performing operations on those matrices. It also contains routines for computing CoI on large pedigrees using the recursive method of VanRaden (1992).

Module Contents

a_decompose(pedobj) ⇒ matrices [#]

Form the decomposed form of A, TDT', directly from a pedigree (after Henderson, 1976; Thompson, 1977; Mrode, 1996). Return D, a diagonal matrix, and T, a lower triagular matrix such that A = TDT'.

pedobj
A PyPedal pedigree object.
Returns:
A diagonal matrix, D, and a lower triangular matrix, T.

a_inverse_df(pedobj) ⇒ matrix [#]

Directly form the inverse of A from the pedigree file - accounts for inbreeding - using the method of Quaas (1976).

pedobj
A PyPedal pedigree object.
Returns:
The inverse of the NRM, A, accounting for inbreeding.

a_inverse_dnf(pedobj, filetag='_a_inverse_dnf_') ⇒ matrix [#]

Form the inverse of A directly using the method of Henderson (1976) which does not account for inbreeding.

pedobj
A PyPedal pedigree object.
Returns:
The inverse of the NRM, A, not accounting for inbreeding.

a_matrix(pedobj, save=0) ⇒ array [#]

a_matrix() is used to form a numerator relationship matrix from a pedigree. DEPRECATED. use fast_a_matrix() instead.

pedobj
A PyPedal pedigree object.
save
Flag to indicate whether or not the relationship matrix is written to a file.
Returns:
The NRM as a NumPy matrix.

fast_a_matrix(pedigree, pedopts, save=0, method='dense', debug=0) ⇒ matrix [#]

Form a numerator relationship matrix from a pedigree. fast_a_matrix() is a hacked version of a_matrix() modified to try and improve performance. Lists of animal, sire, and dam IDs are formed and accessed rather than myped as it is much faster to access a member of a simple list rather than an attribute of an object in a list. Further note that only the diagonal and upper off-diagonal of A are populated. This is done to save n(n+1) / 2 matrix writes. For a 1000-element array, this saves 500,500 writes.

pedigree
A PyPedal pedigree.
pedopts
PyPedal options.
save
Flag to indicate whether or not the relationship matrix is written to a file.
method
Use dense or sparse matrix storage.
debug
Print NRM for debugging
Returns:
The NRM as Numarray matrix.

fast_a_matrix_r(pedigree, pedopts, save=0, method='dense') ⇒ matrix [#]

Form a relationship matrix from a pedigree. fast_a_matrix_r() differs from fast_a_matrix() in that the coefficients of relationship are corrected for the inbreeding of the parents.

pedobj
A PyPedal pedigree object.
save
Flag to indicate whether or not the relationship matrix is written to a file.
Returns:
A relationship as Numarray matrix.

form_d_nof(pedobj) ⇒ matrix [#]

Form the diagonal matrix, D, used in decomposing A and forming the direct inverse of A. This function does not write output to a file - if you need D in a file, use the a_decompose() function. form_d() is a convenience function used by other functions. Note that inbreeding is not considered in the formation of D.

pedobj
A PyPedal pedigree object.
Returns:
A diagonal matrix, D.

inbreeding(pedobj, method='tabular', gens=0, rels=0) ⇒ dictionary [#]

inbreeding() is a proxy function used to dispatch pedigrees to the appropriate function for computing CoI. By default, small pedigrees < 10,000 animals) are processed with the tabular method directly. For larger pedigrees, or if requested, the recursive method of VanRaden (1992) is used.

pedobj
A PyPedal pedigree object.
method
Keyword indicating which method of computing CoI should be used (tabular|vanraden).
gens
The number of generations from the pedigree to be used for calculating CoI. By default, gens=0, which uses the complete pedigree.
rels
Flag indicating whether or not summary statistics should be computed for coefficients of relationship.
Returns:
A dictionary of CoI keyed to renumbered animal IDs.

inbreeding_tabular(pedobj, gens=0, rels=0) ⇒ dictionary [#]

inbreeding_tabular() computes CoI using the tabular method by calling fast_a_matrix() to form the NRM directly. In order for this routine to return successfully requires that you are able to allocate a matrix of floats of dimension len(myped)**2.

pedobj
A PyPedal pedigree object.
gens
The number of generations from the pedigree to be used for calculating CoI. By default, gens=0, which uses the complete pedigree.
rels
Flag indicating whether or not summary statistics should be computed for coefficients of relationship.
Returns:
A dictionary of CoI keyed to renumbered animal IDs

inbreeding_vanraden(pedobj, cleanmaps=0, gens=0, rels=0) ⇒ dictionary [#]

inbreeding_vanraden() uses VanRaden's (1992) method for computing coefficients of inbreeding in a large pedigree. The method works as follows: 1. Take a large pedigree and order it from youngest animal to oldest (n, n-1, ..., 1); 2. Recurse through the pedigree to find all of the ancestors of that animal n; 3. Reorder and renumber that "subpedigree"; 4. Compute coefficients of inbreeding for that "subpedigree" using the tabular method (Emik and Terrill, 1949); 5. Put the coefficients of inbreeding in a dictionary; 6. Repeat 2 - 5 for animals n-1 through 1; the process is slowest for the early pedigrees and fastest for the later pedigrees.

pedobj
A PyPedal pedigree object.
cleanmaps
Flag to denote whether or not subpedigree ID maps should be deleted after they are used (0|1).
gens
The number of generations from the pedigree to be used for calculating CoI. By default, gens=0, which uses the complete pedigree.
rels
Flag indicating whether or not summary statistics should be computed for coefficients of relationship.
Returns:
A dictionary of CoI keyed to renumbered animal IDs

recurse_pedigree(pedobj, anid, _ped) ⇒ list [#]

recurse_pedigree() performs the recursion needed to build the subpedigrees used by inbreeding_vanraden(). For the animal with animalID anid recurse_pedigree() will recurse through the pedigree myped and add references to the relatives of anid to the temporary pedigree, _ped.

pedobj
A PyPedal pedigree.
anid
The ID of the animal whose relatives are being located.
_ped
A temporary PyPedal pedigree that stores references to relatives of anid.
Returns:
A list of references to the relatives of anid contained in myped.

recurse_pedigree_idonly(pedobj, anid, _ped) ⇒ list [#]

recurse_pedigree_idonly() performs the recursion needed to build subpedigrees.

pedobj
A PyPedal pedigree.
anid
The ID of the animal whose relatives are being located.
_ped
A PyPedal list that stores the animalIDs of relatives of anid.
Returns:
A list of animalIDs of the relatives of anid contained in myped.

recurse_pedigree_idonly_side(pedobj, anid, _ped, side='s') ⇒ list [#]

recurse_pedigree_idonly_side() performs the recursion needed to build a subpedigree containing only animal IDs for either all sires or all dams. That is, a pedigree would go sire-paternal grandsire-paternal great-grandsire, etc.

pedobj
A PyPedal pedigree.
anid
The ID of the animal whose relatives are being located.
_ped
A PyPedal list that stores the animalIDs of relatives of anid.
side
The side of the pedigree to follow ('s'|'d').
Returns:
A list of animalIDs of the relatives of anid contained in myped.

recurse_pedigree_n(pedobj, anid, _ped, depth=3) ⇒ list [#]

recurse_pedigree_n() recurses to build a pedigree of depth n. A depth less than 1 returns the animal whose relatives were to be identified.

pedobj
A PyPedal pedigree.
anid
The ID of the animal whose relatives are being located.
_ped
A temporary PyPedal pedigree that stores references to relatives of anid.
depth
The depth of the pedigree to return.
Returns:
A list of references to the relatives of anid contained in myped.

recurse_pedigree_onesided(pedobj, anid, _ped, side) ⇒ list [#]

recurse_pedigree_onesided() recurses to build a subpedigree from either the sire or dam side of a pedigree.

pedobj
A PyPedal pedigree.
side
The side to build: 's' for sire and 'd' for dam.
anid
The ID of the animal whose relatives are being located.
_ped
A temporary PyPedal pedigree that stores references to relatives of anid.
Returns:
A list of references to the relatives of anid contained in myped.