plugins/base2/net.sf.basedb.illumina/trunk/README

Code
Comments
Other
Rev Date Author Line
546 18 Jan 08 nicklas 1 ----------------------------------------------------------------------
570 06 Feb 08 martin 2 {{{
1166 28 Sep 09 jari 3 Copyright (C) 2008 Nicklas Nordborg
1166 28 Sep 09 jari 4 Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
570 06 Feb 08 martin 5
570 06 Feb 08 martin 6 This file is part of Illumina plug-in package for BASE.
570 06 Feb 08 martin 7 Available at http://baseplugins.thep.lu.se/
570 06 Feb 08 martin 8 BASE main site: http://base.thep.lu.se/
570 06 Feb 08 martin 9
570 06 Feb 08 martin 10 This is free software; you can redistribute it and/or
570 06 Feb 08 martin 11 modify it under the terms of the GNU General Public License
940 27 Jan 09 martin 12 as published by the Free Software Foundation; either version 3
570 06 Feb 08 martin 13 of the License, or (at your option) any later version.
570 06 Feb 08 martin 14
570 06 Feb 08 martin 15 The software is distributed in the hope that it will be useful,
570 06 Feb 08 martin 16 but WITHOUT ANY WARRANTY; without even the implied warranty of
570 06 Feb 08 martin 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
570 06 Feb 08 martin 18 GNU General Public License for more details.
570 06 Feb 08 martin 19
570 06 Feb 08 martin 20 You should have received a copy of the GNU General Public License
941 27 Jan 09 martin 21 along with BASE. If not, see <http://www.gnu.org/licenses/>.
570 06 Feb 08 martin 22 }}}
546 18 Jan 08 nicklas 23 ----------------------------------------------------------------------
546 18 Jan 08 nicklas 24
570 06 Feb 08 martin 25 == Requirements ==
546 18 Jan 08 nicklas 26
2286 13 Mar 14 nicklas 27  1. BASE 3.3 or later.
627 13 Mar 08 nicklas 28  
627 13 Mar 08 nicklas 29 For expression experiments:
627 13 Mar 08 nicklas 30  
570 06 Feb 08 martin 31  2. Illumina Bead Summary (IBS) files. The IBS files contain quantified probe intensities.
1032 07 Apr 09 nicklas 32  3. Illumina Sentrix Array binary manifest (BGX) file. The BGX files contain probe annotations.
570 06 Feb 08 martin 33  
627 13 Mar 08 nicklas 34 For SNP experiments:
627 13 Mar 08 nicklas 35
627 13 Mar 08 nicklas 36  2. Illumina SNP manifest files
627 13 Mar 08 nicklas 37  3. Illumina SNP raw data files
627 13 Mar 08 nicklas 38
570 06 Feb 08 martin 39 Tested using Illumina BeadArray Reader (Version: 1.7.0.44) and BeadScan 
570 06 Feb 08 martin 40 (Version: 3.5.31.17122)  ## This is what we use in Lund.
546 18 Jan 08 nicklas 41
570 06 Feb 08 martin 42 == Introduction ==
546 18 Jan 08 nicklas 43
627 13 Mar 08 nicklas 44 This README file contains general information about the plug-in package and
627 13 Mar 08 nicklas 45 specific information about expression data. See the README_SNP file specific
627 13 Mar 08 nicklas 46 information about SNP data.
627 13 Mar 08 nicklas 47
570 06 Feb 08 martin 48 The Illumina BeadArray Reader is a scanner that can read arrays including Illumina 
1032 07 Apr 09 nicklas 49 Sentrix BeadChips and Sentrix Array Matrices (SAMs). Operation of the BeadArray 
1166 28 Sep 09 jari 50 Reader and image acquisition from Sentrix arrays is handled by the Illumina BeadScan 
570 06 Feb 08 martin 51 software.
546 18 Jan 08 nicklas 52
570 06 Feb 08 martin 53 The data output from a BeadArray Reader scanner by default consists of files 
570 06 Feb 08 martin 54 including image data (IDAT) files that can be read by data analysis software such 
570 06 Feb 08 martin 55 as the Illumina BeadStudio software. 
546 18 Jan 08 nicklas 56
1032 07 Apr 09 nicklas 57 The Illumina plug-ins package for BASE reads Illumina Sentrix Array data from 
570 06 Feb 08 martin 58 Illumina Bead Summary (IBS) files. The IBS files are not by default outputted by 
570 06 Feb 08 martin 59 the BeadArray Reader and the scanner must be configured to do so. Once the 
570 06 Feb 08 martin 60 BeadArray Reader is configured it will output IBS files in addition to any default 
570 06 Feb 08 martin 61 output files. To configure a BeadArray Reader to output IBS files, users are asked 
570 06 Feb 08 martin 62 to contact their local Illumina Field Application Scientist.
570 06 Feb 08 martin 63
1032 07 Apr 09 nicklas 64 The IBS files are text files that contain bead-type level data for scanned Sentrix 
570 06 Feb 08 martin 65 arrays. The file format is explained in detail in the section Illumina Bead Summary 
570 06 Feb 08 martin 66 files.
570 06 Feb 08 martin 67
570 06 Feb 08 martin 68 == Illumina Bead Summary (IBS) files ==
570 06 Feb 08 martin 69
1032 07 Apr 09 nicklas 70 The IBS files contain bead-type level data for scanned Sentrix arrays. 
570 06 Feb 08 martin 71 The IBS files are simple comma separated text files with file extension .csv. 
570 06 Feb 08 martin 72 The IBS files are outputted by the BeadArray Reader in the same directory as any 
570 06 Feb 08 martin 73 additional data files from a scan. Note that IBS files are not outputted by a 
570 06 Feb 08 martin 74 BeadArray Reader with default settings. Contact a local Illumina Field Application 
570 06 Feb 08 martin 75 Scientist to configure the scanner to output IBS files.
570 06 Feb 08 martin 76
570 06 Feb 08 martin 77 IBS files are composed of four comma separated columns. See below for an example 
570 06 Feb 08 martin 78 IBS file including header and 3 rows of data.
570 06 Feb 08 martin 79 {{{
580 11 Feb 08 nicklas 80 Illumicode,N,Mean GRN,Dev GRN
580 11 Feb 08 nicklas 81 10008,26,222,47
580 11 Feb 08 nicklas 82 10010,16,57,11
580 11 Feb 08 nicklas 83 10014,16,56,13
570 06 Feb 08 martin 84 }}}
580 11 Feb 08 nicklas 85
570 06 Feb 08 martin 86 The column content in an IBS file is described below.
570 06 Feb 08 martin 87  - ''' Illumicode ''': A code corresponding to the Array_Address_Id in the 
1166 28 Sep 09 jari 88  Illumina Sentrix Array binary manifest (BGX) file. Note that the Illumicode 
1032 07 Apr 09 nicklas 89  is a string (or integer) of varying length. The Array_Address_Id is a string with 
1166 28 Sep 09 jari 90  a fixed length of 10 characters that consists of an Illumicode padded with zeros.
570 06 Feb 08 martin 91  - ''' N ''': The total number of beads used to calculate Mean GRN and Dev GRN.
570 06 Feb 08 martin 92  - ''' Mean GRN ''': The mean intensity.
570 06 Feb 08 martin 93  - ''' Dev GRN ''': Standard deviation of the mean intensity. 
570 06 Feb 08 martin 94
1166 28 Sep 09 jari 95 IBS files may contain some rows with Illumicode that are not represented in the 
1093 27 May 09 martin 96 BGX files. 
1093 27 May 09 martin 97 Our interpretation is that some probes that used to be annotated with a gene has 
1093 27 May 09 martin 98 later been considered poor by Illumina (as we have only observed an increase 
1166 28 Sep 09 jari 99 in the number of unmatched probes for later BGX revisions). To avoid that the 
1093 27 May 09 martin 100 raw data importer fails cause of some probes, listed in the IBS-file, couldn't 
1093 27 May 09 martin 101 be found in BASE - you have to set plug-in parameter 'Probe not found=skip', 
1093 27 May 09 martin 102 when importing data from an IBS-file into BASE.
1093 27 May 09 martin 103
580 11 Feb 08 nicklas 104 A new raw data type has been defined in illumina-raw-data-types.xml
580 11 Feb 08 nicklas 105 to hold this kind of data. The name of the raw data type is
580 11 Feb 08 nicklas 106 '''Illumina Bead Summary (IBS)''' and the unique ID is '''illumina_bead_summary'''
580 11 Feb 08 nicklas 107
580 11 Feb 08 nicklas 108
1032 07 Apr 09 nicklas 109 == Illumina Sentrix Array binary manifest (BGX) files ==
570 06 Feb 08 martin 110
1032 07 Apr 09 nicklas 111 In addition to IDAT files, BeadStudio requires Illumina Sentrix Array binary 
570 06 Feb 08 martin 112 manifest (BGX) files that contain information about the probes on a specific 
1032 07 Apr 09 nicklas 113 Illumina Sentrix Array, including gene symbol, probe sequence, and so on. 
570 06 Feb 08 martin 114 In BASE, the BGX files are used to create array designs that describe the probe 
1032 07 Apr 09 nicklas 115 content of a specific Illumina Sentrix Array.
570 06 Feb 08 martin 116
570 06 Feb 08 martin 117 BGX files are tab separated text files composed of 3 sections named Heading, 
570 06 Feb 08 martin 118 Probes, and Controls respectively. The first section is the Heading section. 
1166 28 Sep 09 jari 119 It is preceded by a row containing the text [Heading]. In the Heading section 
570 06 Feb 08 martin 120 some information is presented including the number of Probes and Controls 
570 06 Feb 08 martin 121 described in the BGX file. See below for an example of the Heading section.
570 06 Feb 08 martin 122 {{{
580 11 Feb 08 nicklas 123 [Heading]
580 11 Feb 08 nicklas 124 Date  1/3/2007
580 11 Feb 08 nicklas 125 ContentVersion  1.0
580 11 Feb 08 nicklas 126 FormatVersion  1.0.0
580 11 Feb 08 nicklas 127 Number of Probes  48701
580 11 Feb 08 nicklas 128 Number of Controls  1426
570 06 Feb 08 martin 129 }}}
1166 28 Sep 09 jari 130 Following the Heading section is the Probes section which is preceded by a row 
570 06 Feb 08 martin 131 containing the text [Probes]. The first row of the Probes section, i.e., the row 
570 06 Feb 08 martin 132 after [Probes] contain the header for the Probes section. Following the Probes 
1166 28 Sep 09 jari 133 section is the Controls section which is preceded by a row containing the text 
570 06 Feb 08 martin 134 [Controls]. The first row of the Controls section, i.e., the row after [Controls] 
570 06 Feb 08 martin 135 contain the header for the Controls section. Note that the header row for the 
570 06 Feb 08 martin 136 Controls section is completely different that the header row for the Probes section. 
570 06 Feb 08 martin 137 See below for an example of Probes header and Controls header and how information 
570 06 Feb 08 martin 138 in the BGX file is mapped to BASE.
570 06 Feb 08 martin 139
570 06 Feb 08 martin 140 == Mapping reporter/control annotations from BGX files to BASE ==
570 06 Feb 08 martin 141
580 11 Feb 08 nicklas 142 The table below shows how the [Probes] section in the BGX file are mapped to 
580 11 Feb 08 nicklas 143 reporter annotations in BASE. Annotations in <brackets> are new annotations
580 11 Feb 08 nicklas 144 defined in the illumina-extended-properties.xml file. BGX columns marked
580 11 Feb 08 nicklas 145 with - are not mapped to BASE.
570 06 Feb 08 martin 146
580 11 Feb 08 nicklas 147 || '''BGX column'''      || '''BASE reporter annotation''' || '''Example value'''       ||
580 11 Feb 08 nicklas 148 || Species               || Species                        || Homo sapiens              ||
580 11 Feb 08 nicklas 149 || Source                || <Source>                       || RefSeq                    ||
580 11 Feb 08 nicklas 150 || Search_Key            || <Search_Key>                   || ILMN_5998                 ||
580 11 Feb 08 nicklas 151 || Transcript            || -                              || ILMN_5998                 ||
580 11 Feb 08 nicklas 152 || ILMN_Gene             || <ILMN_Gene>                    || BRCA1                     ||
580 11 Feb 08 nicklas 153 || Source_Reference_ID   || <Source_Reference_ID>          || NM_007301.2               ||
580 11 Feb 08 nicklas 154 || RefSeq_ID             || RefSeq                         || NM_007301.2               ||
580 11 Feb 08 nicklas 155 || Unigene_ID            || Cluster ID                     ||                           ||
580 11 Feb 08 nicklas 156 || Entrez_Gene_ID        || LocusLink                      || 672                       ||
580 11 Feb 08 nicklas 157 || GI                    || -                              || 63252878                  ||
580 11 Feb 08 nicklas 158 || Accession             || Accession                      || NM_007301.2               ||
580 11 Feb 08 nicklas 159 || Symbol                || Gene symbol                    || BRCA1                     ||
580 11 Feb 08 nicklas 160 || Protein_Product       || -                              || NP_009232.1               ||
580 11 Feb 08 nicklas 161 || Probe_Id              || External ID                    || ILMN_1738027              ||
580 11 Feb 08 nicklas 162 || Array_Address_Id      || Feature ID *                   || 0003120095                ||
580 11 Feb 08 nicklas 163 || Probe_Type            || <Isoform_Type>                 || A                         ||
580 11 Feb 08 nicklas 164 || Probe_Start           || -                              || 6438                      ||
580 11 Feb 08 nicklas 165 || Probe_Sequence        || Sequence                       || ATCCAGGACTGTTTATAGCTGTTGGAAGGACTAGGTCTTCCCTAGCCCCC ||
580 11 Feb 08 nicklas 166 || Chromosome            || Chromosome                     || 17                        ||
580 11 Feb 08 nicklas 167 || Probe_Chr_Orientation || <Probe_Chr_Orientation>        ||                           ||
580 11 Feb 08 nicklas 168 || Probe_Coordinates     || <Probe_Coordinates>            || 38449935-38449984         ||
580 11 Feb 08 nicklas 169 || Definition            || Description                    || Homo sapiens breast cancer 1, early onset (BRCA1), transcript variant BRCA1-delta15-17, mRNA.                          ||
580 11 Feb 08 nicklas 170 || Ontology_Component    || GO cell location               || ubiquitin ligase complex [goid 151] [pmid 14976165] [evidence NAS]; ...  ||
580 11 Feb 08 nicklas 171 || Ontology_Process      || GO biological process          || protein ubiquitination [goid 16567] [pmid 15905410] [evidence NAS]; ... ||
580 11 Feb 08 nicklas 172 || Ontology_Function     || GO molecular function          || metal ion binding [goid 46872] [evidence IEA]; ... ||
580 11 Feb 08 nicklas 173 || Synonyms              || <Synonyms>                     || IRIS; PSCP; BRCAI; BRCC1; RNF53 ||
570 06 Feb 08 martin 174
580 11 Feb 08 nicklas 175 The table below shows how the [Controls] section in the BGX file are mapped to 
580 11 Feb 08 nicklas 176 reporter annotations in BASE. Annotations in <brackets> are new annotations
580 11 Feb 08 nicklas 177 defined in the illumina-extended-properties.xml file. BGX columns marked
580 11 Feb 08 nicklas 178 with - are not mapped to BASE.
570 06 Feb 08 martin 179
580 11 Feb 08 nicklas 180 || '''BGX column'''       || '''BASE reporter annotation''' || '''Example value ''' ||
580 11 Feb 08 nicklas 181 || Probe_Id               || External ID                    || ILMN_943471          ||
580 11 Feb 08 nicklas 182 || Array_Address_Id       || Feature ID *                   || 0004780609           ||
580 11 Feb 08 nicklas 183 || Reporter_Group_Name    || <Control_Group_Name>           || housekeeping         ||
580 11 Feb 08 nicklas 184 || Reporter_Group_id      || <Control_Group_Id>             || housekeeping         ||
580 11 Feb 08 nicklas 185 || Reporter_Composite_map || <Control_Composite_map>        || GI_34304116-S        ||
580 11 Feb 08 nicklas 186 || Probe_Sequence         || Sequence                       || CGTGAAGACCCTGACTGGTAAGACCATCACTCTCGAAGTGGAGCCGAGTG ||
570 06 Feb 08 martin 187
580 11 Feb 08 nicklas 188 * The Feature ID is not a reporter annotation. It is used only to 
580 11 Feb 08 nicklas 189 identify the probe on an array design.
580 11 Feb 08 nicklas 190
580 11 Feb 08 nicklas 191 The column mappings for the [Probes] section can be changed by modifying 
580 11 Feb 08 nicklas 192 the existing import configuration or creating a new configuration. The
580 11 Feb 08 nicklas 193 column mappings for [Controls] section can't be changed.
580 11 Feb 08 nicklas 194
580 11 Feb 08 nicklas 195 == Getting started ==
580 11 Feb 08 nicklas 196
1166 28 Sep 09 jari 197  1. Install this package as described by the instructions in the
1166 28 Sep 09 jari 198     INSTALL file.
1166 28 Sep 09 jari 199  2. Optionally, if not already done, disable use of the 'Illumina' raw
1166 28 Sep 09 jari 200     data type provided by a standard BASE installation; Simply remove,
1166 28 Sep 09 jari 201     or comment out, the `<raw-data-type>` entry for `id='illumina'` in
1166 28 Sep 09 jari 202     configuration file
1166 28 Sep 09 jari 203     `/path/to/base/WEB-INF/classes/raw-data-types.xml` and restart the
1166 28 Sep 09 jari 204     BASE server. If a user already used the 'Illumina' raw data type,
1166 28 Sep 09 jari 205     BASE will display an error message in the GUI. Either restore the
1166 28 Sep 09 jari 206     use of 'Illumina' raw data type or remove the data using
1166 28 Sep 09 jari 207     'Illumina' raw data type.
1166 28 Sep 09 jari 208  3. Import reporter annotations. You will need one or more BGX files for this. 
583 12 Feb 08 nicklas 209     BGX files can be downloaded from http://www.switchtoi.com/annotationfiles.ilmn.
580 11 Feb 08 nicklas 210      * Upload the BGX file(s) to BASE.
580 11 Feb 08 nicklas 211      * Go to the View -> Reporters menu.
580 11 Feb 08 nicklas 212      * Click on the Import button.
580 11 Feb 08 nicklas 213      * Use the auto-detect function or select the Illumina BGX reporter importer plug-in.
580 11 Feb 08 nicklas 214      * Select the BGX file.
580 11 Feb 08 nicklas 215      * Finish the job registration and wait for the plug-in to complete.
580 11 Feb 08 nicklas 216      * Repeat this one time for each BGX file.
1166 28 Sep 09 jari 217  4. Create array designs. You will need one array design for each BGX file.
580 11 Feb 08 nicklas 218      * Go to the Array LIMS -> Array designs menu.
580 11 Feb 08 nicklas 219      * Click on the New button.
580 11 Feb 08 nicklas 220      * Choose the Illumina/Expression 1 or the Illumina/Expression 2 platform. The difference
580 11 Feb 08 nicklas 221        is that the Expression 2 has two IBS files for each raw data set, but Expression 1
580 11 Feb 08 nicklas 222        only has one.
580 11 Feb 08 nicklas 223      * We recommend that you give the array design the same name as the BGX file.
580 11 Feb 08 nicklas 224      * Switch to the Data files tab and select the BGX file.
580 11 Feb 08 nicklas 225      * Click on Save.
580 11 Feb 08 nicklas 226      * Click on the newly created array design.
580 11 Feb 08 nicklas 227      * Click on the Import button and select the Illumina BGX feature importer plug-in.
580 11 Feb 08 nicklas 228      * Click on Next and select the Duplicate feature=skip option.
580 11 Feb 08 nicklas 229      * Finish the job registration and wait for the plug-in to complete.
580 11 Feb 08 nicklas 230      * Repeat this for each BGX file.
1166 28 Sep 09 jari 231  5. Import raw data. You will need one or two IBS files.
580 11 Feb 08 nicklas 232      * Upload the IBS file(s) to BASE.
580 11 Feb 08 nicklas 233      * Go to the View -> Raw bioassays menu.
580 11 Feb 08 nicklas 234      * Click on the New button.
580 11 Feb 08 nicklas 235      * Select the Illumina/Expression 1 or the Illumina/Expression 2 platform. The difference
580 11 Feb 08 nicklas 236        is that the Expression 2 has two IBS files for each raw data set, but Expression 1
580 11 Feb 08 nicklas 237        only has one.
580 11 Feb 08 nicklas 238      * Select one of the array designs created in step 3.
580 11 Feb 08 nicklas 239      * Switch to the Data files tab and select the IBS file(s).
580 11 Feb 08 nicklas 240      * Click on Save.
580 11 Feb 08 nicklas 241      * Click on the newly created raw bioassay.
580 11 Feb 08 nicklas 242      * Click on the Import button and select the Illumina Bead Summary Importer
580 11 Feb 08 nicklas 243      * Finish the job registration and wait for the plug-in to complete.
580 11 Feb 08 nicklas 244      * Repeat this for each set of raw data files.
1166 28 Sep 09 jari 245  6. Add your raw data sets to an experiment.
580 11 Feb 08 nicklas 246  
1196 05 Mar 10 jari 247 Tip! Steps 1-4 only needs to be done a single time for a BASE
1196 05 Mar 10 jari 248 installation. If more than one user is going to use the Illumina
1196 05 Mar 10 jari 249 package we recommend that the array designs created in step 4 are
1196 05 Mar 10 jari 250 shared to the appropriate users, for example, the Everyone group.
580 11 Feb 08 nicklas 251
1196 05 Mar 10 jari 252 Tip! The data import step in (5) above can be done for an entire
1196 05 Mar 10 jari 253 experiment at a time.

Generated on Tue Nov 21 03:43:28 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)