pyp_metrics contains a set of procedures for calculating metrics on PyPedal pedigree objects. These metrics include coefficients of inbreeding and relationship as well as effective founder number, effective population size, and effective ancestor number.

**a_coefficients(pedobj, a='', method='nrm')**⇒ dictionary [#]-
a_coefficients() writes population average coefficients of inbreeding and relationship to a file, as well as individual animal IDs and coefficients of inbreeding. Some pedigrees are too large for fast_a_matrix() or fast_a_matrix_r() -- an array that large cannot be allocated due to memory restrictions -- and will result in a value of -999.9 for all outputs.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*method*- If no relationship matrix is passed, determines which procedure should be called to build one (nrm|frm).
- Returns:
- A dictionary of non-zero individual inbreeding coefficients.

**a_effective_ancestors_definite(pedobj, a='', gen='')**⇒ float [#]-
a_effective_ancestors_definite() uses the algorithm in Appendix B of Boichard et al. (1996) to compute the effective ancestor number for a myped pedigree. NOTE: One problem here is that if you pass a pedigree WITHOUT generations and error is not thrown. You simply end up wth a list of generations that contains the default value for Animal() objects, 0. Boichard's algorithm requires information about the GENERATION of animals. If you do not provide an input pedigree with generations things may not work. By default the most recent generation -- the generation with the largest generation ID -- will be used as the reference population.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*gen*- Generation of interest.
- Returns:
- The effective ancestor number.

**a_effective_ancestors_indefinite(pedobj, a='', gen='', n=25)**⇒ float [#]-
a_effective_ancestors_indefinite() uses the approach outlined on pages 9 and 10 of Boichard et al. (1996) to compute approximate upper and lower bounds for f_a. This is much more tractable for large pedigrees than the exact computation provided in a_effective_ancestors_definite(). NOTE: One problem here is that if you pass a pedigree WITHOUT generations and error is not thrown. You simply end up wth a list of generations that contains the default value for Animal() objects, 0. NOTE: If you pass a value of n that is greater than the actual number of ancestors in the pedigree then strange things happen. As a stop-gap, a_effective_ancestors_indefinite() will detect that case and replace n with the number of founders - 1. Boichard's algorithm requires information about the GENERATION of animals. If you do not provide an input pedigree with generations things may not work. By default the most recent generation -- the generation with the largest generation ID -- will be used as the reference population.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*gen*- Generation of interest.
- Returns:
- The effective ancestor number.

**a_effective_founders_boichard(pedobj, a='', gen='')**⇒ float [#]-
a_effective_founders_boichard() uses the algorithm in Appendix A of Boichard et al. (1996) to compute the effective founder number for myped. Note that results from this function will not necessarily match those from a_effective_founders_lacy(). Boichard's algorithm requires information about the GENERATION of animals. If you do not provide an input pedigree with generations things may not work. By default the most recent generation -- the generation with the largest generation ID -- will be used as the reference population.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*gen*- Generation of interest.
- Returns:
- The effective founder number.

**a_effective_founders_lacy(pedobj, a='')**⇒ dictionary [#]-
a_effective_founders_lacy() calculates the number of effective founders in a pedigree using the exact method of Lacy.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
- Returns:
- A dictionary of results, including the effective founder number.

**common_ancestors(anim_a, anim_b, pedobj)**⇒ list [#]-
common_ancestors() returns a list of the ancestors that two animals share in common.

*anim_a*- The renumbered ID of the first animal, a.
*anim_b*- The renumbered ID of the second animal, b.
*pedobj*- A PyPedal pedigree object.
- Returns:
- A list of animals related to anim_a AND anim_b

**descendants(anid, pedobj, _desc)**⇒ list [#]-
descendants() uses pedigree metadata to walk a pedigree and return a list of all of the descendants of a given animal.

*anid*- An animal ID
*pedobj*- A Python list of PyPedal Animal() objects.
*_desc*- A Python dictionary of descendants of animal anid.
- Returns:
- A list of descendants of anid.

**effective_founder_genomes(pedobj, rounds=10)**⇒ float [#]-
effective_founder_genomes() simulates the random segregation of founder alleles through a pedigree. At present only two alleles are simulated for each founder. Summary statistics are computed on the most recent generation.

*pedobj*- A PyPedal pedigree object.
*rounds*- The number of times to simulate segregation through the entire pedigree.
- Returns:
- The effective number of founder genomes over based on 'rounds' gene-drop simulations.

**effective_founders_lacy(pedobj)**⇒ dictionary [#]-
effective_founders_lacy() calculates the number of effective founders in a pedigree using the exact method of Lacy. This version of the routine a_effective_founders_lacy() is designed to work with larger pedigrees as it forms "familywise" relationship matrices rather than a "populationwise" relationship matrix.

*pedobj*- A PyPedal pedigree object.
- Returns:
- A dictionary of results, including the effective founder number.

**fast_a_coefficients(pedobj, a='', method='nrm', debug=0, storage='dense')**⇒ dictionary [#]-
a_fast_coefficients() writes population average coefficients of inbreeding and relationship to a file, as well as individual animal IDs and coefficients of inbreeding. It returns a list of non-zero individual CoI.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*method*- If no relationship matrix is passed, determines which procedure should be called to build one (nrm|frm).
*storage*- Use dense or sparse matrix storage.
- Returns:
- A dictionary of non-zero individual inbreeding coefficients.

**founder_descendants(pedobj)**⇒ dictionary [#]-
founder_descendants() returns a dictionary containing a list of descendants of each founder in the pedigree.

*pedojb*- An instance of a PyPedal NewPedigree object.

**generation_intervals(pedobj, units='y')**⇒ dictionary [#]-
generation_intervals() computes the average age of parents at the time of birth of their first (oldest) offspring. This is implies that selection decisions are made at the time of birth of the first offspring. Average ages are computed for each of four paths: sire-son, sire-daughter, dam-son, and dam-daughter. An overall mean is computed, as well. IT IS IMPORTANT to note that if you DO NOT provide birthyears in your pedigree file that the returned dictionary will contain only zeroes! This is because when no birthyear is provided a default value (1900) is assigned to all animals in the pedigree.

*pedobj*- A PyPedal pedigree object.
*units*- A character indicating the units in which the generation lengths should be returned.
- Returns:
- A dictionary containing the five average ages.

**generation_intervals_all(pedobj, units='y')**⇒ dictionary [#]-
generation_intervals_all() computes the average age of parents at the time of birth of their offspring. The computation is made using birth years for all known offspring of sires and dams, which implies discrete generations. Average ages are computed for each of four paths: sire-son, sire-daughter, dam-son, and dam-daughter. An overall mean is computed, as well. IT IS IMPORTANT to note that if you DO NOT provide birthyears in your pedigree file that the returned dictionary will contain only zeroes! This is because when no birthyear is provided a default value (1900) is assigned to all animals in the pedigree.

*pedobj*- A PyPedal pedigree object.
*units*- A character indicating the units in which the generation lengths should be returned.
- Returns:
- A dictionary containing the five average ages.

**mating_coi(anim_a, anim_b, pedobj, gens=0)**⇒ float [#]-
mating_coi() returns the coefficient of inbreeding of offspring of a mating between two animals, anim_a and anim_b.

*anim_a*- The renumbered ID of an animal, a.
*anim_b*- The renumbered ID of an animal, b.
*pedobj*- A PyPedal pedigree object.
*gens*- The number of generations from the pedigree to be used for calculating CoI. By default, gens=-1, which uses the complete pedigree.
- Returns:
- The coefficient of inbreeding of the offpsring of anim_a and anim_b

**mating_coi_group(matings, pedobj, names=0, gens=0)**⇒ dictionary [#]-
mating_coi_group() returns the coefficients of inbreeding of offspring of a series of matings, as well as a list of minimum-inbreeding matings.

*matings*- A dictionary
*pedobj*- A PyPedal pedigree object.
*names*- Indicates if the identifiers in 'matings' are names or animalIDs
*gens*- The number of generations from the pedigree to be used for calculating CoI. By default, gens=-1, which uses the complete pedigree.
- Returns:
- he coefficient of inbreeding of the offpsring of anim_a and anim_b

**min_max_f(pedobj, a='', n=10, forma='dense')**⇒ list [#]-
min_max_f() takes a pedigree and returns a list of the individuals with the n largest and n smallest coefficients of inbreeding. Individuals with CoI of zero are not included.

*pedobj*- A PyPedal pedigree object.
*a*- A numerator relationship matrix (optional).
*n*- An integer (optional, default is 10).
*forma*- If A must be formed should dense or sparse matrices be used?
- Returns:
- Lists of the individuals with the n largest and the n smallest CoI in the pedigree as (ID, CoI) tuples.

**pedigree_completeness(pedobj, gens=4)**⇒ dictionary [#]-
pedigree_completeness() computes the proportion of known ancestors in the pedigree of each animal in the population for a user-determined number of generations. Also, the mean pedcomps for all animals and for all animals that are not founders are computed as summary statistics.

*pedobj*- A PyPedal pedigree object.
*gens*- The number of generations the pedigree should be traced for completeness.
- Returns:
- Dictionary of summary statistics

**related_animals(anim, pedobj)**⇒ list [#]-
related_animals() returns a list of the ancestors of an animal.

*anim_a*- The renumbered ID of an animal, a.
*pedobj*- A PyPedal pedigree object.
- Returns:
- A list of animals related to anim_a

**relationship(anim_a, anim_b, pedobj)**⇒ float [#]-
relationship() returns the coefficient of relationship for two animals, anim_a and anim_b.

*anim_a*- The renumbered ID of an animal, a.
*anim_b*- The renumbered ID of an animal, b.
*pedobj*- A PyPedal pedigree object.
- Returns:
- The coefficient of relationship of anim_a and anim_b

**theoretical_ne_from_metadata(pedobj)**⇒ integer [#]-
theoretical_ne_from_metadata() computes the theoretical effective population size based on the number of sires and dams contained in a pedigree metadata object. Writes results to an output file.

*pedobj*- A PyPedal pedigree object.
- Returns:
- True (1) on success, false (0) on failure