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

              All about loopfile.dat
               by Dylan Cooper and
                  Alejandro A. Schaffer

|*| What is loopfile.dat?

Beginning with version 3.0 of FASTLINK we are making a fundamental
change in the way loops are handled. The most important manifestation
of the change is that the specifications for the preprocessor
program UNKNOWN have changed. In particular, for pedigrees with
loops, the new UNKNOWN will produce an extra output file to
assist the main program. This applies to ILINK, MLINK, and LINKMAP
where the standard scripts call UNKNOWN immediately before
calling the main program. The change does not apply to
LODSCORE for which the standard scripts do not use UNKNOWN.
The main programs will still work correctly if the extra file
is not present (in particular, if the old version of UNKNOWN
is used) and the extra file gets deleted when the main program
exits without a crash.

The file whose name is held in the macro LOOPFILE_NAME (probably
"loopfile.dat") is produced by the new unknown.c when LOOPSPEED is
defined.  This file is used to speed up runs of ILINK, LINKMAP, and MLINK
when at least one pedigree contains at least one loop.

The contents of the file and the method by which the speed up was 
obtained rely on the concept of a loop-breaker vector.  A loop-breaker
vector is an array of single locus genotypes which assigns one 
single locus genotype to each loop breaker. To understand more
about loop breakers, readers of this file are strongly encouraged
to read the FASTLINK documentation files traverse.ps and loops.ps.

|*| Syntax of loopfile.dat

loopfile.dat describes the contents of data structures that are created 
in unknown.c and used in ILINK, LINKMAP, and MLINK
The entries in the file are as follows:

Pedigree:  The pedigree for which the following information pertains.
	Pedigrees are numbered consecutively from 1.

fewer_vects_size:  Used for diagnostic output when a malloc fails.

num_loops_considered:  Due to space constraints, the number of loops
	considered in these data structures is bounded.  A noticeable
	speedup is achieved even when only some of the loops in the
	pedigree are considered.  Reducing the macro 
	'max_vectors_considered' in unknown.c may reduce the value
	of this variable.
                    
num_loop_vectors:  a table indexed by the locus numbers, holding the 
	number of loopbreaker vectors at that locus

loop_vectors:  a table indexed by the locus numbers, holding the
	loopbreaker vectors at each locus
	
unknown_poss:   a table indexed by person id, locus, loopbreaker 
	vector, and single locus genotype.  If the corresponding entry 
	is true, the person may have that genotype at that locus when
	the loopbreakers have been assigned the single locus genotypes
	specified in the loopbreaker vector.

Single locus genotypes are encoded in order by allele number,
discarding genotypes where the second allele is greater than the first
allele.  (These allele combinations are discarded because phase is
unimportant for the calculations.)  For example, if a locus has 4
alleles there are ten possible genotypes:

	allele 1  allele 2	genotype
	--------  --------	--------
	   1         1    	   0
	   1         2    	   1
	   1         3    	   2
	   1         4    	   3
	   2         2    	   4
	   2         3    	   5
	   2         4    	   6
	   3         3    	   7
	   3         4    	   8
	   4         4    	   9



Below is a commented
hypothetical file with comments indicating what each line means.
Due to the comments, the placement of white space may be distorted.

Starting in FASTLINK 4.1P, some improvements have been made to the
genotype inference code, so that information about some
loop breaker vectors that are not consistent (i.e.,
the asignment of the genotype to each loop breaker causes a
violation of Mendelian rules of inheritance) are not printed.
As a result, for some multi-loop pedigrees, loopfile.dat will
be much shorter be different from the loopfile.dat generated
by earlier versions of unknown.

Pedigree: 1                   : This information is for the first pedigree
fewer_vects_size: 800         : Used in error messages  
num_loops_considered: 3       : Three loops were considered
num_loop_vectors:
	0 : 6                 : 6 loopbreaker vectors at the locus 0
	1 : 2                 : 2 loopbreaker vectors at the locus 1
	2 : 3                 : 3 loopbreaker vectors at the locus 2
loop_vectors:
	L : 0             : at locus 0 
		0 : 1 0 0     :   loopbreaker vector 0 has single locus 
		1 : 2 0 0     :      genotype 1, 0, and 0 at loci 0, 1, 
		2 : 0 2 0     :      and 2 respectively
		3 : 1 2 0     :   etc
		4 : 2 2 0
		5 : 0 0 1
+
	L : 1
		0 : 0 0 0
		1 : 1 0 0
+
	L : 2
		0 : 0 0 0
		1 : 0 1 0
		2 : 0 0 1
+
unknown_poss:
id: 3                   : person 3 is unknown and has children
	L: 0                : at locus 0
		0 : 1          : person 3 can have single locus genotype 1
-                              : - indicates that person 3 is known at locus 0
	L: 1                : at locus 1      
		0 : 0 1        : if loopbreakers have vector 1, person 3 can
		1 : 0 1        :    have single locus genotype 0 or 1
+                              : + indicates unknown at locus 1
	L: 2
		0 : 0 1
		1 : 0 1
		2 :            : indicates that no genotypes are possible at
+                                this locus when the loopbreakers are assigned
                                 this loopbreaker vector 
id: 4
	L: 0
		0 : 0 1 2
		1 : 0 1 2
		2 :
		3 : 0 1 2
		4 : 0 1 2
		5 :
+
	L: 1
		0 : 0 1 2
-
	L: 2
		0 : 0 1 2
		1 : 0 1 2
		2 :
+












