1.5 Structure of the MORGAN package

It is not necessary to read this section in order to use MORGAN, to run the examples, or to modify them for your own use. However, for those who wish to modify MORGAN code, or to understand MORGAN more fully, it will be useful to have information on the directory structure, the README documentation, and the GOLD-standard documentaion, Makefiles, and examples. These are therefore described in this section, updated for the released version of MORGAN 2.9.

1. README documentation files

   Within the main MORGAN directory, there are program directories, and within these there the Gold-standard directories. At each level there are README files which provide additional documentation. In many cases, this information is duplicated in the tutorial, but whereas the Tutorial is focused to the user, README documentation is focused to the modifier and developer.

   1. README files in the main MORGAN directory

      These include README_readme, README_MORGAN, README_install, and README_relnotes.

      • README_readme describes the various README files throughout MORGAN.

      • README_MORGAN lists the MORGAN programs and describes briefly the analysis done by each program. It also lists the MORGAN V2.9 directories and libraries.

      • README_relnotes contains a summary of the changes and additions in recent releases of MORGAN.

      • README_install contains instructions for installing MORGAN executables.

      In some MORGAN releases there may be additional main-directory README files. For example, in the first release of MORGAN 2.9 there is a README_bugs_v2.9: these bugs are now fixed.

   2. README files in main program directories

      The main program dirctories of MORGAN 2.9 are PedComp, Genedrop, Autozyg, Lodscore, LR_Lods, and PolyEM. Each main program directory contains its own README_userdoc. This describes the inputs to be prepared for the programs, and the various program options. Most of this information is now included in the tutorial, but the README files may contain more detail in some cases.

      Occasionally, there may be additional README files. For example the Autozyg main program directory contains a file README_IMPORTANT, described the (few) parameter statements that must be changed when moving from older to newer versions of MORGAN.

      Most subroutine directories do not contain README files. An exception is the library of subroutines for the lm_twoqtl program, `/TwoQTL'. The README_twoqtl file in the `TwoQTL' subdirectory contains information about running lm_twoqtl. This information is not yet incorporated into the relevant main-program directory README_userdoc file.

      Additionally, the Autozyg main program directory contains a subdirectory `/Utils' of routines specific to the programs lm_ibdtests and lm_map which have not yet been incorporated into a library directory. There are two README files in `Utils': README_ibdtests and README_lm_map written by the authors of those programs. In this case, most of the relevant information is now incorporated into the README_userdoc in the Autozyg program directory.

   3. README files in Gold and Test subdirectories.

      Each main program directory contains a subdirectory, Gold, or in two cases both a Gold and a Gold1 subdirectory. These directories include examples that may be run to check correct installation of MORGAN, and to provide a wider array of example parameter files than are currently in the MORGAN_EXAMPLES files used in the tutorial. Each Gold and Gold1 subdirectory contains a README_gold file detailing the examples in that directory.

      Additionally, in some versions of MORGAN, Autozyg contains a TestGL subdirectory, with an example for testing installation of the real-time graphics display (if installed). The README_display file in this subdirectory provides information on this topic.

2. The subroutine library directories

   The subroutine library directories contain the code for the library routines. During installation of MORGAN, each creates a library file from which the required subroutines are loaded into the executable of each main program. The libraries can be divided broadly into four groups:

   • Lowest-level libraries required by all programs
     • Stuff: Routines for printing, allocating, freeing

     • Pars: Routines for processing MORGAN parameter statements

   • Low-levels libaries performing various groups of functions
     • CMF: A set of routines mainly for matrix manipulation, originally translated from the FORTRAN CM library

     • Peel: Routines for pedigree peeling computations

     • Rans: Routines for random number generation

   • Main libraries supporting genetic analysis programs
     • Pedchk: Routines for checking validity of input pedigrees. Routines for the the pedchk program in PedComp, but also called by all programs.

     • Nghds: Routines for constructing the pedigree neighborhood structures from input pedigree files. Used by all programs with input pedigree data files.

     • Quant: Routines for handling quantitative trait data. Used by PolyEM programs and others that use quantitative trait data. Relies on the CMF matrix manipulation library.

     • Markers: Contains routines for sorting and analysing marker and trait data. Also all the routines that allocate and set the underlying inheritance vector arrays used by MCMC-based programs.

     • Sample: Routines for MCMC sampling and related computations on pedigrees.

   • Extra specialist libraries
     • GLDisp: Routines for the real-time graphics display

     • TwoQTL: Routines for the Lodscore program lm_twoqtl

     In addition to the subroutine libraries, the subdirectory `Utils' of Autozyg contains code for subroutines that are directly incorporated into the lm_ibdtests and lm_map programs. Also, the subdirectory `NewRtnes' of Lodscore includes code directly incorporated into the lm_bayes program. These routines were written by the authors of those programs. They may eventually be incorporated into the MORGAN subroutine libraries.

     The header files for all libraries and programs are contained in the Headers subdirectory of MORGAN. Typically there is one or more header files associated with each library, and named accordingly. For example, the file `nghds.h' in `Headers' corresponds to the Nghds subroutine library. More complex libraries such as Pars have a large number of corresponding header files.

   • The main program directories

     The main program directories of MORGAN 2.9 are PedComp, Genedrop, Autozyg, Lodscore, LR_Lods, and PolyEM. When MORGAN is installed these directories contain the following executables:

     • PedComp: pedcheck, kin

     • Genedrop: genedrop, ibddrop, markerdrop

     • Autozyg: lm_auto, lm_pval, lm_ibdtests, lm_map

     • LR_Lods: lm_lods, lm_schnell

     • Lodscore: lm_bayes, lm_markers, lm_multiple, lm_twoqtl

     • PolyEM: univar, unibig, bivar, multivar

     More details about all of these executable programs can be found either in this tutorial or in the README_userdoc files of the relevant main program directory.

     To make room for new Lodscore programs, with MORGAN V2.8.2, the new directory LR_Lods was created to contain the two older programs lm_schnell and lm_lods. These two programs differ in several ways from newer programs, but the principal one is that they use the methods of combining likelihood ratios (LR) along the chromosome in order to estimate lod scores (see Thompson & Guo, 1991, IMA J Math Appl in Med & Biol).

   • GOLD-STANDARD directories, Makefiles and examples

     The Gold and Gold1 subdirectories of the main program directories PedComp, Genedrop, PolyEM, Autozyg, LR_Lods and Lodscore contain example runs of all the main programs in order to test various aspects of code and installation. Examples for a paticular main program are in the Gold and/or Gold1 subdirectory of that main program directory.

     In MORGAN V2.8.3, Gold replaces the previous Gold2 subdirectory, in Autozyg, LR_Lods, and Lodscore directories. Gold1 directories remain in Autozyg and LR_Lods directories since they provides the only tests of MCMC samplers on looped pedigrees. Gold1 gold standards were omitted from the released MORGAN V2.8.2, due to delays in checking looped pedigree peeling routines, but were reinstated from MORGAN V2.8.3.

     The Gold and Gold1 subdirectories typically contain numerous test parameter files, pedigee files, and marker data files. The tests are run via Makefiles, and the command make help.gold will provide details. Additionally, the `README_gold' file in each directory will give details of the examples.

     Examples may run using the make command. Typically the complete set of examples in any Gold or Gold1 directory is run using the command make all.gold. More detailed information is given by using make help.gold or by viewing the Makefile. Since the Gold tests and examples are intended primarily for developers, it is expected that viewing and modifying the Makefile examples will pose no difficulties.