Documentation for additional output files

8-13-97: Documentation is added for 3 additional output files, chrXX.unmapped, chrXX.current and chrXX.intervals. These are automatically written at the end of a mapping run, and provide additional information about the map. They can be turned off by setting the variable *extra-writes* to nil in the chrXX.input file. If you are saving results to a hash file (this is the default) production of these 3 files at the end of a run does not add much time to the analysis.

I.  Definitions for this documentation:

Framework map: a map against which addition markers will be localized.

Framework markers: those markers on the framework map.

Binned markers or interval markers: those markers whose exact map
position is not known but whose map position is indicated by a map
interval or bin.

II. Map construction:  can be done in one of two ways: 

A.  The map positions of additional markers are indicated, but no
additional markers are incorpoarted into the framework map.  Thus, the
1000:1 odds map positions of all non-framework markers are indicated
by an interval.  This interval may span the distance between two
neighboring markers, or may span multiple intervals.  Documentation
for this type of analysis is available upon request.

B.  The framework map is used a starting point for map
construction. In this case, where there is sufficient power,
additional markers may be added to the initial framework map.  The map
construction will end when no additional markers can be added to the
initial map with odds > 1000:1 (or some other pre-determined
threshold).  At this point, there may be some markers whose exact
position on the final map cannot be determined.  The map positions of
all such markers are indicated by an interval.  This interval may span
the distance between two neighboring markers, or may span multiple
intervals.  This approach is the default used by MultiMap.

III.  New output files.

A. chrX.unmapped

This output indicates where each binned marker lies with respect to
the framework or final map.  Each map interval in which a marker may
lie within the specified odds threshold (i.e. 1000:1) is indicated for
each binned marker.  For example, imagine a set of 6 markers (A B C D
E F) for which an imaginary map of 3 markers, L-END-A-C-F-R-END, has
been constructed.  L-end and R-end represent the left and right map
ends.  Now, suppose we identify the possible locations for the
remaining markers B,D,and E.  Using an odds threshold of 1000:1, we
might see the following output in the file chrX.unmapped:

B is most likely between A-C.
 	B is 500 times less likely to between C-F.

D is equally likely between A-C and C-F.

E is most likely between C-F.
 	E is 40 times less likely between F-L-TEL.

With regard to B, the odds are at least 1000:1 that B lies somewhere
between A and F (as opposed to lying on the left side of A or on the
right side of F).  However, the odds of B being in A-C are not 1000
times greater than of being in C-F, so we cannot say with certainty
whether B is in A-C or in C-F.  The likelihood difference (L-diff)
between B being in A-C and in C-F is ~2.7.  The odds for one interval
versus the other are computed as 10 raised to the power of the L-diff,
which equals 500.  So, B is 500 times less likely to be in C-F than in
A-C.

The odds are at least 1000:1 that D lies somewhere between
A-F. However, the likelihood and odds of D lying between A-C and C-F
are equal. Therefore, there is no power to determine the exact map
position of D.

E is at least 1000:1 times more likely to be somewhere to the right of
C.  E is 40 times more likely to be between C-F, than it is to be to
the right of F.

B.  chrX.intervals

This file lists which markers lie within each interval on the
framework or final map.  The interval markers are divided into 3
classes, which are given in 3 separate lists.  The first list, (1)
,which is NIL for many intervals, includes those markers that map only
the the given interval.  In other words, markers whose 1000:1 odds map
position includes only one interval; some of these markers could
theoretically be added to the map to fill in gaps or increase map
resolution. The second list, (2), indicates those markers for whom the
given map interval is the most likely interval. Note that some
interval markers may be equally to lie in more than one map interval,
and would thus appear in the second list of more than on interval. The
third list, (3), indicates those markers which may lie in the given
map interval, but for which the given map interval is not the most
likely interval.

For example, refer to the map of A-C-F against which markers B,D and E
were mapped.  The chrX.intervals file would look like this:

**   L-end -  A       NIL   NIL    NIL
**   A     -  C       NIL   (B D)  NIL
**   C     -  F       NIL   (D E)  (B)
**   F     -  R-end   NIL   NIL    (E)

Summary: 

L-end - A:  No markers map to this interval.

A - C:	    This interval is the most likely position for B and D.

C - F:      No markers map only to this interval.
            This interval is the most likely position for D and E.
	      (Note that D has 2 most likely intervals, because
       	      because D is equally likely to be in either interval.)

F - R-end:  No markers map only to this interval.
	    No markers are most likely to lie in this interval.
            E may lie in this interval.


C.  chrX.current

This file gives the same type of information as in chrX.intervals, but
is more detailed.  For each map interval on the framework or final
map, the size of the interval in Kosambi cM is givem, and a complete
list of markers whose 1000:1 map position includes the given interval
is listed, along with the priority of the interval.  For example, if a
marker may lie in one of 3 map intervals, then the most likely of the
3 is given a priority 1, the second most likely gets priority 2, and
the third is priority 3.

For example. using the same map example as above, the chrX.current
file would look like:

**  L-end -  A        map end
**     A  -  C          3.4    B-1  D-1
**     C  -  F          1.8    B-2  D-1  E-1
**     F  -  R-end    map end  E-2