From: ftp-bimas.cit.nih.gov                       Last mod: June 27, 1999

                  FASTLINK, version 4.1P

Each section in each README file starts with the string "|*|". To
browse the sections, use your file viewer to search for this unique
string. This is the top level README file.


|*| INTRODUCTION
    ------------

As described in the papers:

R. W. Cottingham Jr., R. M. Idury, and A. A. Schaffer, Faster Sequential 
Genetic Linkage Computations, American Journal of Human Genetics, 53(1993),
pp. 252-263.

and

A. A. Schaffer, S. K. Gupta, K. Shriram, and R. W. Cottingham, Jr.,
Avoiding Recomputation in Linkage Analysis, Human Heredity,
44(1994), pp. 225-237.

and

A. A. Schaffer, Faster Linkage Analysis Computations for Pedigrees
with Loops or Unused Alleles, Human Heredity, 46(1996), pp. 226-235.

and

A. Becker, D. Geiger, and A. A. Schaffer, Automatic Selection of
Loop Breakers for Genetic Linkage Analysis, Human Heredity, 48(1998),
pp. 49-60,

and

A. Becker, R. Bar-Yehuda, D. Geiger,
Random Algorithms for the Loop Cutset Problem,
Proceedings of the fifteenth conference on Uncertainty in
Artificial Intelligence, Sweden, 1999, pp. 49-56.



This directory and its subdirectories contain version 4.1P of faster
versions of the general pedigree programs of LINKAGE 5.1.  Several of our
users of earlier versions 1.0 and 1.1 have dubbed the new programs
FASTLINK.  A PostScript version of the papers can be found in the files
paper1.ps, paper2.ps, paper5.ps, paper6.ps, and paper7.ps.  
Please cite the first two papers (so that all participants in the
FASTLINK project get credit), if you use these programs
in a published experiment. You should continue to cite the original papers
on LINKAGE, listed below, if you use FASTLINK:

G. M. Lathrop, J.-M. Lalouel, C. Julier, and J. Ott, Strategies for
Multilocus Analysis in Humans, PNAS 81(1984), pp. 3443-3446.

G. M. Lathrop and J.-M. Lalouel, Easy Calculations of LOD Scores
and Genetic Risks on Small Computers, American Journal of Human Genetics,
36(1984), pp. 460-465.

G. M. Lathrop, J.-M. Lalouel, and R. L. White, Construction of Human
Genetic Linkage Maps: Likelihood Calculations for Multilocus Analysis,
Genetic Epidemiology 3(1986), pp. 39-52.


The FASTLINK code is available by anonymous ftp to a machines at 
NIH, Rice University, and EBI.  For instructions see the file README.install.

In addition to the two papers and this README file, the top level
directory contains various other pieces of documentation. Carol Haynes
(Duke) suggested that we split up the documentation into smaller
pieces. This file is primarily a roadmap to the documentation for FASTLINK.

README.allele --- explains the diagnostic that states that a pedigree or
                  dataset has unused alleles.

  |*| Diagnostic for extra alleles
  |*| Extra alleles in symbols and an example
  |*| Extra alleles and separating pedigrees
  |*| FASTLINK diagnostic error message

README.bugreport  --- suggest how to send in a bug report

  |*| How to Submit a Useful Bug report

README.checkpoint --- explains the checkpointing scheme for LODSCORE and
                      ILINK

  |*| Introduction to checkpointing
  |*| The Process
  |*| The Files
  |*| Modifying Scripts and Checkpointing
  |*| Using the Script-Level Checkpointing Facility
  |*| Important Caution on Breaking a ckpt Run

README.constants --- explains the mysteries of how to properly set some
                     of the constants in FASTLINK

  |*| Constant Definitions - VERY IMPORTANT!!
  |*| Setting Constants by Editing only the Makefile
  |*| Checking how constants are set for a given executable

README.diseq --- explains an option introduced in FASTLINK 4.1P
                 for modeling linkage disequilibrium

  |*| Baiscs of using conditional allele frequencies
  |*| Usage Suggestions

README.djgpp --- explains how to retrieve and install the djgpp C compiler
                 for those who want source code for FASTLINK for DOS.
                 The compiler is free.

  |*| File Retrieval for setting up the djgpp C compiler. 
  |*| Installing djgpp and compiling FASTLINK

README.ILINK ---

  |*| What does the output of ILINK and LODSCORE mean?

README.install -- explains basic facts about retrieving and installing FASTLINK

  |*| FTP Directions
  |*| Source Code Organization
  |*| Compilation

README.loopfile -- explains the syntax of the file loopfile.dat used to
                   transmit genotype inferences from unknown to the main
                   program when working with looped pedigrees

  |*| What is loopfile.dat?
  |*| Syntax of loopfile.dat


README.lselect -- explains the new easy automatic way to select loop breakers
  |*| Selecting loop breakers easily and automatically

README.makefile -- explains the structure of the Makefile in detail

  |*| Makefile, Introduction
  |*| Makefile, Variables
  |*| Makefile, Comments
  |*| FASTLINK, Memory Usage Options
  |*| Makefile, Editing
  |*| Makefile, Miscellaneous Variables
  |*| Makefile, Sequential Code Variables
  |*| Makefile, Parallel Code Variables
  |*| Makefile, Parallel Code Variables, TreadMarks specifics
  |*| Makefile, Parallel Code Variables, P4 specifics
  |*| Makefile, Parallel Code Variables, Parallel C Compiler Flags
  |*| Makefile, Unix Utilities on Your System
  |*| Makefile, Passing Extra Flags


README.mapfun  -- Explains how the mapping functions explained in Chapter 1
                  of Ott's book actually relate to what is in the code

  |*| Map Functions Used in LINKAGE/FASTLINK

README.memory  --- explains memory requirements

  |*| Memory Requirements

README.p4 -- explains how to obtain and install the p4 package, which is
             needed to run parallel FASTLINK on shared-memory parallel
             computers

  |*| P4, Background
  |*| FTP Instructions
  |*| Building P4
  |*| Building P4, Using SYSV_IPC
  |*| Building P4 for SOLARIS
  |*| Building P4 for IRIX
  |*| Building P4 for OSF
  |*| Hooking FASTLINK and P4 Together
  |*| Running P4 FASTLINK
  |*| Running P4 FASTLINK, Specifying number of processors
  |*| Running P4 FASTLINK, Specifying maxworkingset
  |*| Running P4 FASTLINK, Specifying memory usage
  |*| Running P4 FASTLINK, Analyzing memory usage
  |*| Parallel FASTLINK, Running times
  |*| P4, Troubleshooting
  |*| P4, Misc


README.parallel -- high level overview of  parallel versions of FASTLINK

  |*| Parallel Code, Introduction
  |*| Parallel FASTLINK, Operation
  |*| FASTLINK on shared-memory multiprocessors
  |*| FASTLINK on networks of workstations
  |*| Parallel FASTLINK, references
  see also paper3.ps and paper4.ps

README.portability --- contains summary of portability information
                       and refers to the following files for more
                       information regarding specific operating systems
                       Note: README.portability and the following
                       system-specific files are not included in the
                       diskette version of FASTLINK for DOS.

  README.AIX
  README.ALPHAVMS
  README.Digital (used to be called README.OSF)
  README.DOS
  README.IRIX
  README.Linux
  README.VAX
   |*| Instructions for DEC C Compiler
   |*| Instructions for VAX C Compiler
  README.VMS

README.scaling --- essay on the output likelihood values from FASTLINK
 
  |*| Output values from FASTLINK are scaled
  |*| Scaling Alert for LINKMAP users

README.time -- a short essay on estimating the running time of sequential
               FASTLINK runs.

README.TreadMarks -- briefly describes the TreadMarks package, which is
                     needed to run parallel FASTLINK on a network of
                     unix workstations.

  |*| Introduction
  |*| Retrieving and Installing TreadMarks
  |*| Hooking TreadMarks and FASTLINK together
  |*| Running TreadMarks FASTLINK
  |*| Running TreadMarks FASTLINK, Command line flags
  |*| Running TreadMarks FASTLINK, Specifying number of processors
  |*| Running TreadMarks FASTLINK, Specifying maxworkingset
  |*| Running TreadMarks FASTLINK, Analyzing memory usage
  |*| Parallel FASTLINK, Running times


README.trouble -- LINKAGE/FASTLINK Troubleshooting

  |*| Error Message  in LINKAGE Main Programs and  UNKNOWN
  |*| ERROR MESSAGES INTRODUCED in FASTLINK
  |*| Incompatibility Errors in UNKNOWN
  |*| LSP Error Messages
  |*| LRP Error Messages
 
README.unknown -- describes modifications to the UNKNOWN preprocessor
                  program first introduced in FASTLINK 2.3P, including improved
                  error reporting and a bugfix.

README.updates --- explains noticeable changes in different versions of
                   FASTLINK

  |*| Changes Introduced in version 1.1
  |*| Changes Introduced in version 2.0
  |*| Changes Introduced in version 2.1 and while maintaining 2.0
  |*| Changes Introduced in version 2.2 and while maintaining 2.1
  |*| Changes Introduced in version 2.3P and while maintaining 2.2
  |*| Changes Introduced while maintaining 2.3P
  |*| Changes Introduced in version 3.0P
  |*| Changes Introduced while maintaining 3.0P
  |*| Changes Introduced in version 4.0P
  |*| Changes Introduced while maintaining 4.0P   
  |*| Changes Introduced in version 4.1P   
  |*| Changes Introduced while maintaining 4.1P   

The following are PostScript files (traverse.ps takes a while to print)

traverse.ps --- explains the pedigree traversal algorithm in great detail
                with examples
loops.ps --- explains various aspects of loops in LINKAGE/FASTLINK.

unknown.ps --- explains how the UNKNOWN preprocessor program works.

Send suggestions for other FASTLINK documentation you would like to see to
schaffer@helix.nih.gov.


Please let us know if you have problems with the programs,
including if you are unhappy with the speedup and are willing to
share your data to the extent that we may be able to study the
problem. Note that this does not mean you have to tell us
anything about what disease you are studying. And of course we
will respect any request for confidentiality. We only wish to
consider studying problems to see if we can find improvements.

If you read README.updates you will see that lots of the updates are
suggested by users who are enthusiastic about FASTLINK, but would
like to see it improve. One of the best ways to encourage us to
work harder on FASTLINK is to send in your constructive suggestions.

There is a mailing list of over 200 FASTLINK users. If you wish
to be on this mailing list, send e-mail to schaffer@helix.nih.gov.
