=================================
Example 20: H-inverse and friends
=================================

This example illustrates features in WOMBAT to calculate relationship
matrices required for genomic evaluation.

Specifically: 
 a) the genomic relationship matrix (GRM) and its inverse, 
 b) the submatrix of the numerator relationship matrix (NRM)
    for genotyped animals and its inverse, 
 c) the inverse of the NRM including metafounders, and 
 d) the inverse of the combined  relationship for single step 
    evaluation (H-inverse).

NB: Calculations are based on marker counts strictly as supplied by
the user - no checks or quality control of these are performed!

A:  Illustrates calculation of complete H-inverse
    Simulated data for 370 genotypes and 750 animals in total. 

A1: as A, but with scaling of the GRM (method of Christensen 2012)

A2: as A, but estimating base population frequencies to center allele counts

A3: Shows calculation of the diagonal elements of H for H-inverse in A
    after it has been calulated, using special run option --hdiag.
    This inverts the H-inverse using sparse matrix inversion and writes out
    the diagonal elements for all inviduals.
    
A4: Shows calculation of the diagonal elements of H as an optional
    extra when calculating the H-inverse as in A, using the method of
    Legarra et al. (2020). 

A5: Shows 'standalone' calculation of the diagonal elements of H for A
    i.e. without setting up neither H nor G or A22 explicitly, using the
    method of Legarra et al. (2020). 

B:  Data as A. Illustrates calculation of GRM and GRM-Inverse only.

B1: as B, with eigen-decomposition of GRM.

C: Data as A. Illustrates calculation of A_22 only

D: As A, but augmenting H-inverse by equations for "implicit" genetic
   groups (Group proportions to be read from pedigree file)

D1: As D, but carrying through genetic group proportions needed to fit genetic
   groups explicitly to *.codes file

D2: As D, but reading unknown parent group (UPG) from colums 5 and 6 in pedigree
   file (must be coded 1 to number of groups) and writing them to colums 4 and 5
   in corresponding *.codes file

E: Data as A. Illustrates calculation of the GRM-Inverse only using 
   the Woodbury formula

F: Data as A. Illustrates calculation of the H-Inverse  using the
   Woodbury formula to obtain the inverse of the GRM 

G: as B, but approximating the GRM inverse using the APY algorithm

H: as A, but approximating the H-inverse using the APY algorithm

I: Illustrates computation of the inverse numerator relationship
   matrix with one metafounder. Example from Legarra et al 2015 (Genetics)

I1: Illustrates computation of the inverse numerator relationship
   matrix with two metafounders. Example from Legarra et al 2015.

J: Illustrates computation of the H-inverse using an NRM with two
   metafounders. Example from github.com/alegarra/metafounders

K: as A, but adding a metafounder to A^{-1}, estimating gamma using
   generalised least squares

L: as A, but adding multiple metafounders to A^{-1}, estimating Gamma
   using  the EM algorithm described by Garcia-Baccino et al. 2017

