What does the output of ILINK and LODSCORE mean?

ILINK uses the GEMINI optimization procedure to find a locally optimal value of the theta vector of recombination fractions. If you use the default scripts produced by lcp, your initial guess for theta is .1 in every dimension. GEMINI evaluates each theta by its likelihood, seeking to find theta vectors that have a higher pedigree likelihood.

The GEMINI procedure has multiple iterations. Each iteration corresponds to one line of output. Each iteration includes multiple likelihood function evaluations. Each iteration has two phases. In Phase I GEMINI seeks to improve the current best theta. In Phase II, GEMINI estimates the gradient of the likelihood with respect to the current best theta vector. In the first iteration, Phase I only evaluates the likelihood at the initial candidate theta.

When ILINK prints out a line such as: maxcensor can be reduced to -32767, it has completed the first likelihood function evaluation. On long runs, this fact can be used to estimate running time. A reasonable rough estimate for the number of function evaluations is 10*(number of dimensions of theta vector). The number of dimensions of the theta vector is one fewer than the number of loci in most cases. If maletheta and femaletheta are allowed to differ (sexdif is set to 1), then the number of dimensions doubles to 2 * (number of loci - 1). Estimating other parameters (with fitmodel set to true) can also increase the number of dimensions.

After each iteration, ILINK prints out one line with four pieces of information:

ITERATION is a positive integer showing the number of the iteration just completed.

T is an indication of the step size that the GEMINI procedure takes in updating theta. Sometimes, very small T indicates that GEMINI did many updates (and hence the iteration probably took longer than average) each of which requires a likelihood function evaluation.

NFE is a positive integer indicating how many likelihood function evaluations have been done through that iteration.

F is a scaled representation of -2log(likelihood) at the current best theta. Because of the - sign, the value of F decreases until it reaches a local minimum.

After the last printed iteration, ILINK in FASTLINK does one more likelihood function evaluation for the purpose of computing Ott's Generalized LODSCORE which shows up in final.dat (transferred to final.out by the default pedin scripts). Ott's generalized LODSCORE compares -2log(likelihood) at the locally optimal theta to -2log(likelihood) at a theta that is .5 in every component (i.e. each locus unlinked to all the rest). In LINKAGE ILINK more likelihood function evaluations are done after the last printed iteration line, but these likelihood function evaluations are unnecessary (see paper2.ps from the FASTLINK distribution for more details).

Some users run ILINK and LODSCORE with execution scripts that do not delete the output file outfile.dat upon termination. The file outfile.dat is primarily useful in storing information about the values of certain variables at each iteration; these variables are not of interest, except for those who wish to modify the code. Of interest to users is the last thing in outfile.dat which is some description of the condition under which LODSCORE and ILINK terminated. This is a code stored in the variable idg and takes one of 8 values:

 1: Maximum possible accuracy reached
 2: Search direction no longer downhill
 3: Accumulation of rounding error prevents further progress
 4: All significant differences lost through cancellation in conditioning
 5: Specified tolerance on normalized gradient met
 6: Specified tolerance on gradient met
 7: Maximum number of iterations reached
 8: Excessive cancellation in gradient

Under all circumstances it should be emphasized that if ILINK or LODSCORE is used with only a single starting theta, the output value is only a local optimum and not a global optimum. It is a good idea to try with several different starting thetas. It is perfectly valid to compare the local optima from different starting points and choose the one that gives the best value of -2*log(likelihood); the more staring points tried, the more likely that the best value will be a global optimum.

If ILINK or LODSCORE exits with condition 5 or 6, the output value is pretty safe as a local optimum.

If ILINK or LODSCORE exits with condition 7, the output values are completely unsafe. The source code must be modified to increase iterationMultiple, which is #defined in gemdefs.h.

If ILINK or LODSCORE exits with conditions 1,2,3,4, or 8 the situation is more nebulous, but it is a good idea to try more experiments to test how robust the output values are. Try starting from different initial thetas. One might also try increasing the constant tol in gemdefs.h Increasing tol will have the effect of relaxing the convergence criteria, so that ILINK and LODSCORE may come close to a local optimum, where a smaller tol causes problems. If increasing tol helps, then one should:

   find the local optimum with the higher tol
   reset tol to its previous value 
   restart the program with the first local optimum as the initial value

ILINK or LODSCORE does not allow the theta values to get down to 0.0. Therefore, if one of the locally optimal thetas is reported as close to 0.0, the situation ought to be explored further using LINKMAP or MLINK, which will allow arbitrarily small values of theta.