**********************************************************************
***  Description of Usage for crEDC_5g.c
***  Author: Pete Sullivan        July 2020
**********************************************************************

Purposes of the Program:
  Compute EDCs for submission to Interbull for MACE, allowing for
  Single or Multiple trait national models, for any number of traits.

General Usage:
  For a complete list of options specify -h on the command line.

Copyright (C) 2020 Lactanet Canada:
  This software is not to be re-distributed without the prior 
  approval of Lactanet Canada.

Warranty/Liability:
  This software is freely available, with NO warranty.

Available on-line:
  https://www.cdn.ca/software/mtedc.html

Please see README.TXT in the above zipfile for additional details.

**********************************************************************

Traits have direct + maternal effects or direct only.
Traits with direct + maternal effects must be listed first.

EDC traits are linear functions (i.e. indexes, K'g) of the genetic effects 
  included in the evaluation model, and should correspond to the trait(s)
  and heritabilities submitted to Interbull for MACE.

EDCs are computed for all EDC traits defined in the parameter file.

INPUTS: pedigree file, parameter file, incidence file.
OUTPUTS: EDC file or Reliabilities file, log/summary file.

Data in all input files can be space, comma, or tab delimited.  Repeated
  delimiters are treated as a single delimiter (i.e. NULL fields ignored).
Fields within brace brackets {} are either optional or are only
  required for certain models.

parameter file -> First row must contain 3 delimited integers:
                  (#_traits  #_traits_with_maternal_effects #_EDC_traits)
         Format = (#  #  #)  OR  (#,#,#)

                  Subsequent rows are ignored if there are no arguments
                       or if the first argument begins with the comment
                       character #.  Otherwise the first argument must
                       be a recognized code.  This allows blank and 
                       commented lines to improve readability, and checks
                       for misspelled codes.  The program will not run
                       if any errors are detected in the parameter file.

                  Valid CODES (case sensitive):
                  -------------------------------------------------------------

                  TRAITS => List of labels for all traits.
                    N.B. A trait label CANNOT include delimiters (e.g. spaces).
         Format = (TRAITS {tr1} {tr2} ...)

                  RR => row of R
                  Gd => direct effect row of G
                  Gm => maternal effect row of G
                  Ed => direct effect row of E=V(perm. env.)
                  Em => maternal effect row of E=V(perm. env.)
                  CG => row of CG=V(random CG effects)
         Format = (RR  #.#  #.# ...)  OR  (Gd  #.#  #.# ...) ...

                  I# => relative weights on genetic effects, followed by
                            heritability submitted to Interbull for the trait,
                            optionally followed by a label (e.g. milk yield).
                     => describes the #th EDC trait.
                    N.B. weights need not sum to 1
                    N.B. index labels can include delimiters.
         Format = (I#  #.#  #.# ... #.# {index label})

                  FPED => name of input pedigree file
                  FOBS => name of input data/observation file
                  FOUT => name for output EDC file
                  FLOG => name for output log file
                  FSTDOUT => name for file to capture redirected stdout
                  FSTDERR => name for file to capture redirected stderr
         Format = (FPED file_name)  OR  (FOBS file_name) ...

                  MODEL {Sire or Animal, case insensitive}
                  If MODEL not specified, Animal model is assumed.
         Format = (MODEL Sire)  OR  (MODEL Animal)

                  OPTION * => specify option *
                  * = ignore_h2_check => Accept index heritabilities as provided.
                  * = h2_within_CG => Calculate heritabilities within (random) CG.
                  * = ignore_MAXSIRES_check => Accept any number of sires per CG.
                  * = ignore_WTS_check => Accept any record weight as reasonable.
                  * = ignore_SIRExMGS => Simpler approximation for sire models.
                  * = include_traits=1+3+4  (e.g. to only include traits 1, 3 and 4)
         Format = (OPTION ignore_h2_check) OR  (OPTION h2_within_CG) ...
		  
                  -------------------------------------------------------------
      Notes:
         Matrices R and G are required, E and CG are optional.
         E and CG must be completely specified if included.
         Specify lower triangle of these symmetric matrices.
         Row orders must correspond to trait order in incidence file.
         Add all random effects in the model, except G, E, and CG, to R.
            (suggest adding W/c to R, where W=Var(x) and c=n(x),
             x is a random effect not in G, E or CG,
             n(x) is the average number of observations per level of x.
             e.g. x=sire*herd and n(x)=ave. #observations per sire*herd)

              e.g...

                   4  2  2 

                   TRAITS C_ease Stillbirth NRR_heifers NRR_cows

                   RR X
                   RR X X
                   RR X X X
                   RR X X X X

                   Gd X 
                   Gd X X
                   Gd X X X
                   Gd X X X X
                   Gm X X X X X
                   Gm X X X X X X

                   Ed X
                   Ed X X
                   Ed X X X
                   Ed X X X X
                   Em X X X X X
                   Em X X X X X X

                   I1 X X X X X X  .09	  Calving Ease
                   I2 X X X X X X  .123  NRR in cows

                   FPED /home/user/files/pedigree.HOL
                   FOBS /home/user/files/EDCdata.HOL
                   FOUT /home/user/Interbull/EDC.HOL
                   FLOG /home/user/logs/EDClog.HOL

                   # sire,mgs in SM replaces animal,dam from AM
                   MODEL Sire

For a Sire MODEL:
pedigree file -> (sire  sire_of_sire   mgs_of_sire)
              -> complete pedigree used for genetic evaluation
              -> sequential ids ... 1,2,...n
              -> sires can be numbered in any order
              -> N.B. unknown parents should be 0, not a genetic group number

parameter file -> Matrix G = covariances among sire {mgs} effects.
                         Gd => sire   Gm => mgs

incidence file -> (sire {mgs} CG1 CG2 ..CGt {S1 S2 .. St}
            {mgs} is required if any traits with maternal effects.
            {mgs}=sire of genetic dam for ETs if treated that way in
            the national evaluation, otherwise {mgs}=sire of recipient.
            CGi is zero for any trait not observed (or edited out).
            Si is variance scale factor in the national evaluation.
              e.g. 1.0 for a complete record, 0.6 for projected record
                   resid. var is R(i,i)/Si.
            If factors are not provided, program defaults all Si=1.
            Si are optional, but for ALL traits OR NONE being weighted.


For an Animal MODEL...
pedigree file -> (animal   sire   dam)
              -> complete pedigree used for genetic evaluation
              -> sequential ids ... 1,2,...n
              -> animals can be numbered in any order
              -> N.B. unknown parents should be 0, not a genetic group number

parameter file -> Matrix G = covariances among animal {dam} effects
                         Gd => animal   Gm => dam

incidence file -> (animal {dam} CG1 CG2 ..CGt {S1 S2 .. St}
            {dam} is required if any traits with maternal effects.
            {dam}=genetic dam for ETs only if treated that way in
            the national evaluation, otherwise {dam}=recipient.
            CGi is zero for any trait not observed (or edited out).
            Si is variance scale factor in the national evaluation.
              e.g. 1.0 for a complete record, 0.6 for projected record
                   resid. var is R(i,i)/Si
            If factors are not provided, program defaults all Si=1.
            Si are optional, but for ALL traits OR NONE being weighted.

  e.g. (animals 3 and 4 from dam 2, obs for traits 1,3,4 and 1,2,4)

  "   3   2      1  0  4  3    1.000 , 0.000 1.000 1.000"
  "   4   2   ,  1  1  0  3    0.750   0.750 0.000 0.600"

  multiple records per animal are allowed (e.g. repeatability models).

EDC (output) file -> (animal EDC1 EDC2 ... EDCn NP1 NP2 ... NPn)
         Default Formats:  an is I9 , NPi are I7;  EDCi are I7
	 (Use command-line option -R to write EDCi as F12.4 if desired)
 Any NPi or EDCi > 999999 are set = 999999.
 An EDC is computed for each specified index (I1, I2,... In).

Log/Summary (output) file -> printable/readable TEXT format

**********************************************************************
