03/31/06, sjn

//========
// Usage:
//========
[-c][-n][-p] MasterFile ComparatorFile

//================
// Input Details:
//================
1. Both MasterFile and ComparatorFile must be sorted BED files, consistent with
    the sort-bed program, written by Scott Kuehn, in CVS.
2. When using the -p option, both MasterFile and ComparatorFile must have at
    least 6 columns of data.  Of these, information must be present for
    chromosome, start index, stop index, and strand.  This corresponds to
    columns 1, 2, 3 and 6 in BED format (with counting beginning at 1).
    Columns 4 and 5 can be empty, but tabs must still delimit them.
3. When not using the -p option, both MasterFile and ComparatorFile must have
    at least 3 columns corresponding to the chromosome, start index and stop
    index.  This is not true, however if -c is used.
4. Optional parameter -n removes exact overlap comparisons.  In other words,
    if both of your input files contain the row:
       chr1	10	1000
    and -n has been specified, that row in the Comparator File will not be
    considered when looking for distances from the same row in the Master File.
   They must overlap 100% in order for -n to take affect.
5. Optional parameter -c adds a second column to the output: the id field
    of the Comparator File that qualifies as the nearest neighbor.  If no
    row of the Comparator File qualifies as this, then NAN is used.  When using
    -c, the target file must have at least 4 columns of information.  The 4th
    column is an identifier.
6. Optional parameter -p makes all distance calculations sensitive to strand
   polarity.

   NOTE: -n and -p may be used together.  In such a case, exact overlaps
         that are on opposite strands will result in a distance of 0.  You can
         also use -c in conjunction with either/or/together with -n and -p.
   NOTE: Use a dash (-) for either MasterFile or ComparatorFile to allow reading
         from STDIN.

//=========
// Output:
//=========
A single entry for each row of the Master File when the -c option is not used.
When valid, this entry will be the signed distance to the closest feature in the
Comparator File in bps (integer).  When no such distance exists, the output will
be of the form: no-data-chrN, where the 'N' is replaced with the chromosome
value found in the corresponding row of the Master File.
With the -c option, the id field of the closest segment from the Comparator
File is placed in the second column of output, or NAN when there is no such
qualifying feature.

NOTE: This program is case insensitive to alpha-numbered chromosomes
      (i.e., chrX == chrx).
NOTE: Ties go to the "left".


//=================
// Important Note:
//=================
We have decided to report distances from "left to left" which means the
5' end of a sequence on the + strand and 3' end of a segment on the -
strand.  This is consistent with an older script that has always been used
with the annotations pipeline.  In this case, consistency is preferred over
flexibility.  If a different type of distance calculation is needed, the input
data should be shifted to work with the left to left principle.
