Troubleshooting FASTLINK/Linkage/Unknown Messages

BioInformatics & Molecular Analysis Section, CIT, NIH

This information is derived from the Linkage Troubleshooting Guide by Dr. Alejando Schaffer, NCBI.

LINKAGE and FASTLINK often produce messages that are difficult to understand. This document briefly summarizes messages from FASTLINK, Linkage and Unknown. Messages are arranged alphabetically. Messages found only in FASTLINK are indicated by [F], incompatibility errors in UNKNOWN are indicated by [U]. See the discussion at the end of this document.

NOTE: The most common error is a white space placement error. By white space error, we mean the insertion of unwanted blank lines or the deletion/insertion of spaces in the input files. If this is case, the error message is often only a clue to the vicinity of the actual error in the data files.

Samples of FASTLINK/Linkage/Unknown Messages
and what they may mean

Data recovered [F]
FASTLINK is recovering from a crash whether you like it or not.
Error detected reading datafile. Illegal value for mutation locus (0)
The mutation locus number is too low. Probably a white space error..
Error detected reading datafile. Illegal value for risk locus (0)
The risk locus number is too low. Probably a white space error.
Error detected reading datafile. Linkage disequilibrium is not allowed with this program
You are trying to allow for linkage disequilibrium and trying to use LODSCORE. Use ILINK instead.
Error detected reading datafile. Mutation locus (5) exceeds nlocus
The locus at which you want to do a mutation model is specified as an index that is higher than the number of loci you specified in the lcp.
Error detected reading datafile. Risk locus (5) exceeds nlocus
The locus at which you want to do a risk analysis is specified as an index that is higher than the number of loci you specified in the lcp script.
Error detected reading iterated locus in datafile. Illegal value (-1)",
The locus number is negative. I have not figured out any plausible circumstances under which this error could occur.
Error detected reading iterated locus in datafile. Value (7) greater than nlocus
You are using ILINK to estimate allele frequencies or something else, and you gave a locus number that is too high.
Error detected reading loci order. Illegal locus number 17 in position 2
Your lcp script wants to use locus 17, but your locus file does not have 17 loci described. This can occur when you mix-up data sets.
Error detected reading loci order. Locus number 17 in position 5 exceeds number of loci
The third line of your locus file has no locus 17 on it, but you asked lcp to use that locus. This probably occurred by using a text editor to add new loci to the locus file and forgetting to update the locus order on line 3.
Error detected reading loci order. Locus number repeated in positions 2 and 3
You probably made a typo in lcp and used the same locus in two different positions of the fixed locus map
Error detected reading locus description. Illegal locus type 7 for locus 6
The first number in the description of each locus in the locus file must be 1,2,3,or 4.
Error detected reading locus description for system 1. Liability classes (100) exceed maxliab.
The maximum number of liability classes at a locus is determined by the constant maxliab, which can be set in unknown.c, commondefs.h, or Makefile.
Error detected reading locus description for system 1. Risk allele (17) exceeds nallele
You are doing a risk assessment and you specified an allele number that is higher than the number of alleles possible for that locus.
Error detected reading locus description for system 2. Illegal number of liability classes (-1),
The number of liability classes that you specified for an affection status locus is too low. This could be a white space error.
Error detected reading locus description for system 2. Illegal risk allele (0)
You are doing a risk assessment and you specified an allele number of 0 or less. Probably a white space error.
Error detected reading locus description for system 2. Number of traits (17) exceeds maxtrait
The maximum number of traits for a quantitative trait locus is determined by the constant maxtrait, which can be set in unknown.c, commondefs.h, or Makefile.
Error detected reading locus description for system 2. Number of traits out of range (-1)
The number of traits is too low. Probably a white space error.
Error detected reading locus description for system 2. Penetrance out of range
You specified a penetrance for a liability class of an affection status locus as a number bigger than 1.0. Probably a white space error.
Error detected reading locus description for system 2. Variance multiplier must be positive
You specified a variance multiplier for a quantitative trait as 0 or less. Almost certainly what happened is that a 0 was read because of a white space error.
Error detected reading locus description for system 3. Variance must be positive
You specified a variance for a quantitative trait as 0 or less. Almost certainly what happened is that a 0 was read because of a white space error.
Error detected reading locus description for system 6. Illegal number of alleles 0
One of your loci is described as having 0 alleles. This is likely a white space error in the locus file causing the wrong string to be interpreted as the number of alleles
Error detected reading locus description for system 6. Illegal number of factors 0
One of your loci is described as having 0 factors. This is likely a white space error in the locus file causing the wrong string to be interpreted as the number of binary factors.
Error detected reading locus description for system 6. Number of factors 17 exceeds maxfact
There is a constant maxfact that is the maximum number of binary factors allowed at a locus of that type. You can change maxfact in unknown.c commondefs.h and Makefile. Important: Set maxfact and maxall to the same value; FASTLINK cannot handle maxfact > 31.
Error detected reading locus description for system 7. Number of alleles 25 exceeds maxall
One of your loci is described as having 25 alleles in the locus file. maxall is a constant limiting the maximum number of alleles at a locus. You can increase maxall to more than 25, by changing unknown.c, commondefs.h, or Makefile.
Important: FASTLINK cannot handle maxall > 31.
Error detected reading pedigree record at pedigree 17. Maximum number of pedigree records exceeded
The maximum number of pedigrees is determined by the constant maxped, which can be changed in commondefs.h unknown.c, and Makefile. You may have truly exceeded maxped or you may have a white space error.
Error detected reading pedigree record 17. Illegal code for sex 8.
The column for gender is the eighth column in pedin.dat and the fifth column in the input to MAKEPED. Error 11 can be caused by entering either the wrong value for the gender or having a white space error that causes the wrong column to be read as gender. Be especially careful to have exactly one carriage return after the entry for each person, and no other carriage returns.
Error detected reading pedigree record 200. Illegal liability class (0).
The liability class is being read as a number that is too low. When you specify a locus as an affection status locus, you may specify different liability classes that get numbered 1,2,3... If you assign an individual a class number in the pedigree file that is lower than the number of liability classes specified, then this error occurs. It is important to remember that affection status loci get 1 column is no liability classes are used and 2 columns if classes are used. Therefore, this error can occur if you specify an affection status locus to have liability classes in the locus file, but forget to specify the class in the pedigree file.
Error detected reading pedigree record 200. Liability class (9) exceeds nclass.
When you specify a locus as an affection status locus, you may specify different liability classes that get numbered 1,2,3... If you assign an individual a class number in the pedigree file that is higher than the number of liability classes specified, then this error occurs. It is important to remember that affection status loci get 1 column is no liability classes are used and 2 columns if classes are used. Therefore, this error can occur if you specify an affection status locus to have liability classes in the locus file, but forget to specify the class in the pedigree file.
Error detected reading pedigree record 300. Allele number 25 exceeds maxall.
A numbered allele cannot have a value larger than the constant maxall. One of your loci is described as having 25 alleles in the locus file. maxall is a constant limiting the maximum number of alleles at a locus. You can increase maxall to more than 25, by changing unknown.c, commondefs.h, or Makefile.
Important: FASTLINK cannot handle maxall > 31.
Error detected reading pedigree record 300. Illegal allele number -1.
You have a negative allele number in your input file. I have not figured out any plausible circumstances under which this error could occur.
Error detected reading pedigree record 300. Illegal binary factor code 2.
Binary factors must be 0 or 1. Usually this error occurs because of a white space problem that causes lsp to look in the wrong columns.
Error detected reading pedigree record 501. Maximum number of individuals exceeded,
The maximum number of people in a a data set is determined by the constant maxped.
ERROR: File empty or inconsistent [U]
One of pedfile.dat and datafile.dat is not there or has the wrong permissions.
ERROR: Incompatibility detected in this family for locus [U]
This is the overall incompatibility message for a pedigree. Here "family" means "pedigree". Note that locus 2 here is post-lsp locus numbering. so it means the second locus in your analysis.
Error opening ipedfile.dat and pedfile.dat. [F]
Something is wrong in your lcp script or your usage of it
Error opening pedfile.dat in UNKNOWN [U]
pedfile.dat is not there or you do not have permission to read it. This error could arise if you are doing multiple runs in the same directory simultaneously (this is a no-no for both LINKAGE and FASTLINK) or your directory permissions are not set up properly.
foundped() found 0 pedigrees - UNKNOWN [U]
Something is seriously wrong with pedfile.dat. It's hard to imagine what could cause this, but the message is in there for safety.
Illegal instruction (on Suns) [F]
maxhap is probably too big causing you to blow out the stack in segdown or segup
Illegal interference parameter 17 Lack of interference assumed
The second number after the last locus description in the locus file indicates whether you want interference (1) or mapping (2). No interference (the common case) is 0.
Illegal locus number 0 in lod score list
The locus number is too high instead of too low.
Illegal sex difference parameter 1 Parameter must be 0 with sex-linked data
You are using X-chromosome data and you specified that male theta should be different from female theta in datain.dat. This number is the first number after the last locus description in the locus file. This warning may be harmless.
Illegal sex difference parameter 3 Parameter should be 0, 1, or 2
The first number after the last locus description in the locus file indicates whether you want male theta and female theta to be different Codes are:
This is probably a white space error
Locus 17 in lod score list exceeds nlocus 5
You get this one if you use LODSCORE because the lcp script format for lodscore is different. The third line of your locus file has no locus 17 on it, but you asked lcp to use that locus. This probably occurred by using a text editor to add new loci to the locus file and forgetting to update the locus order on line 3.
Non-standard affection status 6 interpreted as normal in pedigree record 200
The affection status of a person can be 0,1, or 2. You probably have a white space error. This warning should not be ignored.
NOTE: attempting to continue previous (unfinished) run [F]
FASTLINK thinks you want to recover from a crash
Number of iterated parameters greater then maxn.
The number of parameters that you can simultaneously estimate in ILINK is determined by the constant maxn, which can be increased in ildefs.h or Makefile. You have exceeded maxn in the way your datafile.dat is set up. Could be caused by a white space error.
Number of loci 17 exceeds the constant maxlocus
maxlocus is the maximum number of loci that can be used simultaneously in a run. You can increase maxlocus by changing commondefs.h or Makefile.
Number of loci read. Less than minimum of 1
The first number in locus file (datain.dat) or datafile.dat is mangled; you probably erred in using preplink to prepare the locus file.
One incompatibility involves the family in which person 9 is a child [U]
Essentially the same as the previous error message, except that there are two ways of flagging errors depending on how the pedigree is traversed.
One incompatibility involves the family in which person 17 is a parent [U]
You have a violation of Mendelian rules of inheritance in the current pedigree. This message will be printed before the message for the whole pedigree. Here "family" means "nuclear family", including parents and children. The first nuclear family that is pinpointed definitely has an error (Note that the individuals are counted starting at 1 with each pedigree, so 17 means the 17th person listed in pedfile.dat for the current pedigree. Note that if 17 is involved in multiple marriages, each of these should be checked.
Press to continue [U]
Recent versions of UNKNOWN ask for an interactive response when errors occur. This was introduced by Terwilliger and Ott. Press if you want incompatibilities checked for the remaining pedigrees in your data set. Otherwise, kill the program.
Problem with malloc, probably not enough space [F]
You are out of memory, get more swap space.
Reduce max_vectors_considered to 9999 [U]
You have a looped pedigree, probably with multiple loops. UNKNOWN is running out of memory keeping track of all the possible loop breaker vectors. If you reduce the constant max_vectors_considered you trade space for time. The genotype inference for loops becomes less precise, but takes less space.
The next pedigree appears to have an unbroken loop [F]
You failed to use properly the loops program as part of makeped See Chapter 7 of Terwilliger and Ott
The next pedigree appears to have an unbroken loop [U]
The program is getting into an infinite loop probably because you have not broken a loop properly. The LINKAGE preprocessor program MAKEPED can be used to break loops before running UNKNOWN.
The program will exit politely to allow you to correct the problem [F]
I am sparing you a core dump
WARNING: You are doing an autosomal run but have AUTOSOMAL_RUN set to 0 [F]
Change AUTOSOMAL_RUN to 1 in moddefs.h
You must increase the constant maxloop [U]
In FASTLINK 3.0P, maxloop is defined in both unknown.c and commondefs.h. In bothe files, the value must be at least as large as the number of loops in each pedigree. In previous versions of FASTLINK, maxloop appeared only in commondefs.h. Edit unknown.c and commondefs.h to increase maxloop.
You probably need to run the slower version of this program [F]
FASTLINK can be configure to use more memory "fast version" or less memory "slow version". You are using the fast version and have run out of memory. Recompile to get the slow version instead, with make installslow.
Your pedigree has more loops than allowed by the constant maxloop [F]
You must increase maxloop in commondefs.h. Starting with FASTLINK 3.0P maxloop will occur also in unknown.c You are *strongly encouraged* to read loops.ps.

Discussion of FASTLINK 2.3/3.0 and Unknown
Changes in Error Detection

One of the main purposes of UNKNOWN is to detect violations of Mendelian rules of inheritance. In LINKAGE and FASTLINK, through version 2.2, error detection was done only for loopless pedigrees and the program would report only the erroneous pedigree/locus pair.

In FASTLINK 2.3P, the loopless error checking was improved so that the program now pinpoints the nuclear family which contains the error. It is not possible for the program to determine automatically whether it is a parent or a child (or both) whose genotype must be changed.

Sometimes, the program will pinpoint multiple nuclear families that are in error in the same pedigree. In this situation, only the first nuclear family is sure to be wrong; the others may be propagated consequences of the first error detected. It may not be possible to determine whether they are separate errors or not without correcting the first error. If you want to see the first error only, change the default value of the constant ONE_ERROR_ONLY to 1.

In FASTLINK 3.0P, UNKNOWN now detects incompatibility errors in looped pedigrees. However, it reports only the pedigree/locus pair. If you wish to have the nuclear families pinpointed, then artificially remove all the loops by replacing every number that is 2 or higher in column 9 of the pedigree file with a 0. Then re-run UNKNOWN. Do not throw away your original pedigree file, since you will want to fix the genotype errors there and use that file for the actual computations.