How to check and fix Illuminus for the Chrom X bug Go to Outmoded Bonsai Project page for downloads
The history of the project is largely documented in the news archive and mailing list archive.
Jump back to the Main Outmoded Bonsai Introduction.
Support This Project

About that Illuminus X Chromosome bug

2011 August update: Added info about version 2d

Added in 2010 March: A year from the uncovering of the bug, there is still no official bug-fix update. Meanwhile, Illumina has released the GenTrain 2 clustering algorithm with GeonomeStudio 2009.2 in December 2009. More description in description of the GenTrain Genotypes. It is interesting to compare the reaction of Amgen staff to FlowJo data corruption about having somewhat serious bugs - they took the bug-fix patch and incoporated it at the earliest convenience (within about a week).

BeadStudio/GenomeStudio's start-up message since at least 2007 contains a paragraph "Due to the precise clustering of the Infinium Assay, Illumina recommends a GenCall score cutoff of 0.15 for all Infinium products ... Be sure to adjust the GenCall score cutoff in BeadStudio from the default 0.25 to 0.15 when you are analyzing data from Infinium products.". The Illuminus paper mentioned the comparison was done with a cut-off of 0.20 (a higher cut-off gives lower call-rates) - running BeadStudio in a way against Illumina's explicit advice gives less than optimal results. Is that intentional or an over-sight?

Because of a prior agreement not to redistribute the source code of Chiamo, readers are referred to the Wellcome Trust Centre Illuminus page, the the LSHTM Illuminus page or the direct link illuminus.tar.gz in Oxford, illuminus.tar.gz in LSHTM for downloading Illuminus. This page will only contain information on how to identify different versions of illuminus, and also how to patch the source code to fix the X chromosome bug. The detail of the bug is first showed in this set of slides and more details in this set of cluster plots. You may need to revert the 1:1:1 mixture change with illuminus_v2_111_mixture.diff and apply the correct HWE calculation with Illuminus_v3_sex_HWE_correction.patch.

A 1:1:1 mixture is equivalent to fixing MAF to 0.5 and also fixing the male/female ratio to 1:2. While the male/female ratio is better than the autosome model (=all female, no male) for which the bug was originally discovered for, fixing MAF to 0.5 is likely to make the numerical instability of the EM algorithm worse. These problems are covered in more details in the documents mentioned above. A 1:1:1 mixture is in many ways worse than the original bug.

The procedure is shown below; also with details about all the available versions of Illuminus I know of, and how to identify them; and, if there is one which is not listed here, how to apply the corection HWE change to some other versions of Illuminus, or check yours had the change included.

Different versions of Illuminus

Here are the file size, first known available dates, and the md5sum (a cryptographical signature of the file content - it is the same regardless of the date stamp or file renaming). The md5 checksum of a file can be calculated with the md5sum utlity on linux systems. On solaris the equivalent utility is md5 .

md5sum Available since version (supposedly) file size (byte)
93f2d5f67f8930e7aaf488c671a5bfe8 21th Dec 2007 1 2371317
7a1bfcb9df6f488e4957fb2034e75ea5 23th Oct 2008 2 1663452
5d6314c08f3b5a647e3ab190190086b0 3rd April 2009 2 2647468
cdee8ade8dd6c775391365fa1502e878 21st April 2009 2 1743964
d112b6de4c55d26e5be218d051896206 1st June 2010 2 1745396

I'll refer to the 4 different version 2's as 2a, 2b, 2c, 2d. Version 2a and 2b are the same as far as the chrom X treatment is concerned; version 2c and 2d change to use a 1:1:1 mixture. This document will not cover how to fix version 1, which is left as an exercise for those who want to do it.

Procedure

  1. Unpack the source code, and change into the directory:

  2. tar -zxpvf illuminus.tar.gz
    cd Illuminus/
  3. Revert the 1:1:1 mixture change (if it is version 2c), note the -R flag. patch takes a --dry-run option for just "trying out" also, before one actually makes the change.
  4. patch -p1 -R < illuminus_v2_111_mixture.diff 
  5. Apply the HWE correction:
  6. patch -p1 < Illuminus_v3_sex_HWE_correction.patch

The anatomy of a patch, and how to read it

Patches or diffs are typically generated by diff -u or diff -c, and is human-readable. It can have some descriptive text at the beginning (which is ignored by patch), the precise command used to generate it, the full path of the file before and after (the -p1 option for patch is taken to remove the first 1 part in the full path). The below applied with patch -p1 says to find illuminus.h in the current directory.

It says, the source file from line 883 onwards for 10 lines is changed to the output file from line 883 onwards for 20 lines like this: 3 lines are the same, remove 3 lines (the minus sign at the beginning of line), keep one line, add 13 lines (the plus sign at the beginning of the line), and keep 3 lines.

A patch typically includes 3 lines before and after a change which make it easier to identify the location, in case the line number does not quite match (due to changes occuring elsewhere meanwhile). It can also have multiple stances detailing changes to different sections of a file, and even detailing changes to different files. So with this understanding it is possible to apply a change forward and backward by hand. ( Note the change below is to be applied in reverse!)

diff -ru Illuminus.v2b/illuminus.h Illuminus/illuminus.h
--- Illuminus.v2b/illuminus.h 2008-10-23 14:39:22.000000000 +0100
+++ Illuminus/illuminus.h 2009-04-21 17:37:29.000000000 +0100
@@ -883,10 +883,20 @@
}

totp = pa + pb;
- lambda[0] = pa * pa / totp / totp;
- lambda[1] = 2 * pa * pb / totp / totp;
- lambda[2] = pb * pb / totp / totp;

+ if(chrX)
+ {
+ lambda[0] = 1.0;
+ lambda[1] = 1.0;
+ lambda[2] = 1.0;
+ }
+ else
+ {
+ lambda[0] = pa * pa / totp / totp;
+ lambda[1] = 2 * pa * pb / totp / totp;
+ lambda[2] = pb * pb / totp / totp;
+ }
+
maf = pa / totp;

}


Hin-Tak Leung, last updated 2011-08-10

Get Outmoded Bonsai at SourceForge.net. Fast, secure and Free Open Source software downloads Get Outmoded Bonsai at SourceForge.net. Fast, secure and Free Open Source software downloads Support This Project