doc/src/docbook/user/rawbioassays.xml

Code
Comments
Other
Rev Date Author Line
3487 13 Jun 07 peter 1 <?xml version="1.0" encoding="UTF-8"?>
3487 13 Jun 07 peter 2 <!DOCTYPE sect1 PUBLIC 
3487 13 Jun 07 peter 3     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
3487 13 Jun 07 peter 4     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
3487 13 Jun 07 peter 5 <!--
3487 13 Jun 07 peter 6   $Id$
3487 13 Jun 07 peter 7
3675 16 Aug 07 jari 8   Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
3487 13 Jun 07 peter 9
3487 13 Jun 07 peter 10   This file is part of BASE - BioArray Software Environment.
3487 13 Jun 07 peter 11   Available at http://base.thep.lu.se/
3487 13 Jun 07 peter 12
3487 13 Jun 07 peter 13   BASE is free software; you can redistribute it and/or
3487 13 Jun 07 peter 14   modify it under the terms of the GNU General Public License
4477 05 Sep 08 jari 15   as published by the Free Software Foundation; either version 3
3487 13 Jun 07 peter 16   of the License, or (at your option) any later version.
3487 13 Jun 07 peter 17
3487 13 Jun 07 peter 18   BASE is distributed in the hope that it will be useful,
3487 13 Jun 07 peter 19   but WITHOUT ANY WARRANTY; without even the implied warranty of
3487 13 Jun 07 peter 20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
3487 13 Jun 07 peter 21   GNU General Public License for more details.
3487 13 Jun 07 peter 22
3487 13 Jun 07 peter 23   You should have received a copy of the GNU General Public License
4509 11 Sep 08 jari 24   along with BASE. If not, see <http://www.gnu.org/licenses/>.
3487 13 Jun 07 peter 25 -->
3487 13 Jun 07 peter 26
3487 13 Jun 07 peter 27 <sect1 id="experiments_analysis.rawbioassay">
5783 05 Oct 11 nicklas 28   <?dbhtml filename="rawbioassays.html" ?>
3487 13 Jun 07 peter 29   <title>Raw bioassays</title>
3318 10 May 07 nicklas 30   <para>
3318 10 May 07 nicklas 31     A <guilabel>Raw bioassay</guilabel> is the representation
5783 05 Oct 11 nicklas 32     of the result of analyzing data from the physical bioassay
5783 05 Oct 11 nicklas 33     down to the point where we have a file or a set of files
5783 05 Oct 11 nicklas 34     containing measurements per feature (eg. spot, gene, etc.)
5783 05 Oct 11 nicklas 35     for a single sample or extract. Further analysis is usually
5783 05 Oct 11 nicklas 36     needed before we can say something about individual features
5783 05 Oct 11 nicklas 37     or samples and how they relate to each other. This
5783 05 Oct 11 nicklas 38     kind of analisys is done in <guilabel>Experiments</guilabel>.
5783 05 Oct 11 nicklas 39     See <xref linkend="experiments_analysis.experiments" />.
3318 10 May 07 nicklas 40   </para>
3318 10 May 07 nicklas 41   
3318 10 May 07 nicklas 42   <para>
5783 05 Oct 11 nicklas 43     The term <guilabel>Raw bioassay</guilabel> is bit misleading since the
5783 05 Oct 11 nicklas 44     real "raw data" is actually the images from a microarray scan or the
5783 05 Oct 11 nicklas 45     output from a sequencer. For historical reasons we have chosen to keep
5783 05 Oct 11 nicklas 46     the term raw bioassay since this represents the first possibility for
5783 05 Oct 11 nicklas 47     a transition between file-base data and database-stored data. Typically, 
5783 05 Oct 11 nicklas 48     all pre-rawbioassay analysis is done outside of BASE, and although
5783 05 Oct 11 nicklas 49     we now have the possibility to track this in detail, it will
5783 05 Oct 11 nicklas 50     probably remain so for some time in the future. See
5783 05 Oct 11 nicklas 51     <xref linkend="experiments_analysis.derivedbioassays" />.
5783 05 Oct 11 nicklas 52   
3318 10 May 07 nicklas 53   </para>
3318 10 May 07 nicklas 54   
5783 05 Oct 11 nicklas 55   <sect2 id="experiments_analysis.rawbioassay.create">
5783 05 Oct 11 nicklas 56     <title>Create raw bioassays</title>
5783 05 Oct 11 nicklas 57     <para>
5783 05 Oct 11 nicklas 58       Creating a new raw bioassay is a two- or three-step process:
5783 05 Oct 11 nicklas 59     </para>
3318 10 May 07 nicklas 60   
5783 05 Oct 11 nicklas 61     <orderedlist>
5783 05 Oct 11 nicklas 62       <listitem>
5783 05 Oct 11 nicklas 63         <para>
5783 05 Oct 11 nicklas 64           Create a new raw bioassay item with the &gbNew; button in the raw bioassays list view.
5783 05 Oct 11 nicklas 65           It is also possible to create raw bioassays from the derived bioassays
5783 05 Oct 11 nicklas 66           list- and single view- page.
5783 05 Oct 11 nicklas 67         </para>
5783 05 Oct 11 nicklas 68       </listitem>
5783 05 Oct 11 nicklas 69       <listitem>
5783 05 Oct 11 nicklas 70         <para>
5783 05 Oct 11 nicklas 71         Upload the file(s) with the raw data and attach them to the
5783 05 Oct 11 nicklas 72         raw bioassay.
5783 05 Oct 11 nicklas 73         </para>
5783 05 Oct 11 nicklas 74       </listitem>
5783 05 Oct 11 nicklas 75       <listitem>
5783 05 Oct 11 nicklas 76         <para>
5783 05 Oct 11 nicklas 77           The used platform may require that data is imported to the database.
5783 05 Oct 11 nicklas 78           See <xref linkend="import_data" />. If the platform is a
5783 05 Oct 11 nicklas 79           file-only platform, this step can be skipped.
5783 05 Oct 11 nicklas 80         </para>
5783 05 Oct 11 nicklas 81       </listitem>
5783 05 Oct 11 nicklas 82     </orderedlist>
3318 10 May 07 nicklas 83   
5783 05 Oct 11 nicklas 84     <note>
5783 05 Oct 11 nicklas 85       <title>Supported file formats</title>
5783 05 Oct 11 nicklas 86       BASE has built-in support for most file formats where the data comes
5783 05 Oct 11 nicklas 87       in a tab-separated (or similar) form. Data for one raw bioassay
5783 05 Oct 11 nicklas 88       must be in a single file. Support for other file formats
5783 05 Oct 11 nicklas 89       may be added through plug-ins.
5783 05 Oct 11 nicklas 90     </note>
5783 05 Oct 11 nicklas 91   </sect2>
5783 05 Oct 11 nicklas 92   
3318 10 May 07 nicklas 93   <sect2 id="experiments_analysis.rawbioassay.properties">
3318 10 May 07 nicklas 94     <title>Raw bioassay properties</title>
3318 10 May 07 nicklas 95     
3872 23 Oct 07 nicklas 96     <figure
3872 23 Oct 07 nicklas 97       id="experiments_analysis.figures.rawbioassay.edit">
3872 23 Oct 07 nicklas 98       <title>Raw bioassay properties</title>
3872 23 Oct 07 nicklas 99       <screenshot>
3872 23 Oct 07 nicklas 100         <mediaobject>
3872 23 Oct 07 nicklas 101           <imageobject>
3872 23 Oct 07 nicklas 102             <imagedata
3872 23 Oct 07 nicklas 103               fileref="figures/rawbioassay_edit.png" format="PNG" />
3872 23 Oct 07 nicklas 104           </imageobject>
3872 23 Oct 07 nicklas 105         </mediaobject>
3872 23 Oct 07 nicklas 106       </screenshot>
3872 23 Oct 07 nicklas 107     </figure>  
3318 10 May 07 nicklas 108
3318 10 May 07 nicklas 109     <helptext external_id="rawbioassay.edit" title="Edit raw bioassay">
3318 10 May 07 nicklas 110     
3318 10 May 07 nicklas 111     <variablelist>
3318 10 May 07 nicklas 112       <varlistentry>
3318 10 May 07 nicklas 113         <term><guilabel>Name</guilabel></term>
3318 10 May 07 nicklas 114         <listitem>
3318 10 May 07 nicklas 115           <para>
3318 10 May 07 nicklas 116             The name of the raw bioassay.
3318 10 May 07 nicklas 117           </para>
3318 10 May 07 nicklas 118         </listitem>
3318 10 May 07 nicklas 119       </varlistentry>
3318 10 May 07 nicklas 120       <varlistentry>
3872 23 Oct 07 nicklas 121         <term>
3872 23 Oct 07 nicklas 122           <guilabel>Platform</guilabel>
3872 23 Oct 07 nicklas 123         </term>
3872 23 Oct 07 nicklas 124         <listitem>
3872 23 Oct 07 nicklas 125           <para>
3872 23 Oct 07 nicklas 126             Select the platform / variant used for the
3872 23 Oct 07 nicklas 127             raw bioassay. The selected options affects which
3872 23 Oct 07 nicklas 128             files that can be selected on the <guilabel>Data files</guilabel>
3872 23 Oct 07 nicklas 129             tab. If the platform supports importing data to the database
3872 23 Oct 07 nicklas 130             you must also select a <guilabel>Raw data type</guilabel>.
3872 23 Oct 07 nicklas 131           </para>
3872 23 Oct 07 nicklas 132         </listitem>
3872 23 Oct 07 nicklas 133       </varlistentry>
3872 23 Oct 07 nicklas 134       <varlistentry>
3318 10 May 07 nicklas 135         <term><guilabel>Raw data type</guilabel></term>
3318 10 May 07 nicklas 136         <listitem>
3318 10 May 07 nicklas 137           <para>
3872 23 Oct 07 nicklas 138             The type of raw data. This option is disabled for file-only
3872 23 Oct 07 nicklas 139             platforms and for platforms that are locked to a specific
3872 23 Oct 07 nicklas 140             raw data type. This cannot be changed after raw data has been
3318 10 May 07 nicklas 141             imported. <nohelp>See
3318 10 May 07 nicklas 142             <xref linkend="experiments_analysis.rawdatatypes" />.</nohelp>
3318 10 May 07 nicklas 143           </para>
3318 10 May 07 nicklas 144         </listitem>
3318 10 May 07 nicklas 145       </varlistentry>
3318 10 May 07 nicklas 146       <varlistentry>
5783 05 Oct 11 nicklas 147         <term><guilabel>Parent bioassay</guilabel></term>
5783 05 Oct 11 nicklas 148         <listitem>
5783 05 Oct 11 nicklas 149           <para>
5783 05 Oct 11 nicklas 150             The derived bioassay that is the parent of this
5783 05 Oct 11 nicklas 151             raw bioassay.
5783 05 Oct 11 nicklas 152           </para>
5783 05 Oct 11 nicklas 153         </listitem>
5783 05 Oct 11 nicklas 154       </varlistentry>
5783 05 Oct 11 nicklas 155       <varlistentry>
5783 05 Oct 11 nicklas 156         <term><guilabel>Parent extract</guilabel></term>
5783 05 Oct 11 nicklas 157         <listitem>
5783 05 Oct 11 nicklas 158           <para>
5783 05 Oct 11 nicklas 159             The extract which this raw bioassay has measured. This is normally selected
5783 05 Oct 11 nicklas 160             among the extracts that are linked with the physical bioassay that this
5783 05 Oct 11 nicklas 161             raw bioassay is coming from. Selecting the correct extract is important if the
5783 05 Oct 11 nicklas 162             physical bioassay contains more than one extract, since otherwise it may affect
5783 05 Oct 11 nicklas 163             how annotations are inherited and used in downstream analysis.
5783 05 Oct 11 nicklas 164           </para>
5783 05 Oct 11 nicklas 165         </listitem>
5783 05 Oct 11 nicklas 166       </varlistentry>
5783 05 Oct 11 nicklas 167       <varlistentry>
3318 10 May 07 nicklas 168         <term><guilabel>Array design</guilabel></term>
3318 10 May 07 nicklas 169         <listitem>
3318 10 May 07 nicklas 170           <para>
3318 10 May 07 nicklas 171             The array design used on the array slide (optional).
3318 10 May 07 nicklas 172             If an array design is specified
3318 10 May 07 nicklas 173             the import will verify that the raw data has
3318 10 May 07 nicklas 174             the same reporter on the same position. This
3318 10 May 07 nicklas 175             prevents mistakes but also speed up analysis
3940 08 Nov 07 martin 176             since some optimizations can be used when assigning 
3323 10 May 07 nicklas 177             positions in bioassay sets.
3523 20 Jun 07 nicklas 178             The array design can be changed after raw data has been 
3523 20 Jun 07 nicklas 179             imported, but this triggers a new validation. If the raw data
4093 18 Jan 08 enell 180             is stored in the database, the features on the new array design must 
4093 18 Jan 08 enell 181             match the the raw data. The verification can use three different methods:
4093 18 Jan 08 enell 182           </para>
4093 18 Jan 08 enell 183           
4093 18 Jan 08 enell 184           <itemizedlist>
4093 18 Jan 08 enell 185           <listitem>
4093 18 Jan 08 enell 186             <para>
4093 18 Jan 08 enell 187             Coordinates: Verify block, meta-grid, row and column coordinates.
4093 18 Jan 08 enell 188             </para>
4093 18 Jan 08 enell 189           </listitem>
4093 18 Jan 08 enell 190           <listitem>
4093 18 Jan 08 enell 191             <para>Position: Verify the position number.</para>
4093 18 Jan 08 enell 192           </listitem>
4093 18 Jan 08 enell 193           <listitem>
4093 18 Jan 08 enell 194             <para>
4093 18 Jan 08 enell 195             Feature ID: Verify the feature ID. This option can only be used
4093 18 Jan 08 enell 196             if the raw bioassay is currently connected to an array design that
4093 18 Jan 08 enell 197             has feature ID values already.
4093 18 Jan 08 enell 198             </para>
4093 18 Jan 08 enell 199           </listitem>
4093 18 Jan 08 enell 200           </itemizedlist>
4093 18 Jan 08 enell 201           <para>
4093 18 Jan 08 enell 202             In all three cases it is also verified that the reporter of the raw
4093 18 Jan 08 enell 203             data matches the reporter of the features.
4093 18 Jan 08 enell 204           </para>
4093 18 Jan 08 enell 205
4093 18 Jan 08 enell 206           <para>
4093 18 Jan 08 enell 207             For Affymetrix data, the
3523 20 Jun 07 nicklas 208             CEL file is validated against the CDF file of the new array design.
3523 20 Jun 07 nicklas 209             If the validation fails, the array design is not changed.
3318 10 May 07 nicklas 210           </para>
3318 10 May 07 nicklas 211         </listitem>
3318 10 May 07 nicklas 212       </varlistentry>
3318 10 May 07 nicklas 213       <varlistentry>
3318 10 May 07 nicklas 214         <term><guilabel>Software</guilabel></term>
3318 10 May 07 nicklas 215         <listitem>
3318 10 May 07 nicklas 216           <para>
5783 05 Oct 11 nicklas 217             The software used to generate the raw data (optional).
3318 10 May 07 nicklas 218           </para>
3318 10 May 07 nicklas 219         </listitem>
3318 10 May 07 nicklas 220       </varlistentry>
3318 10 May 07 nicklas 221       <varlistentry>
3318 10 May 07 nicklas 222         <term><guilabel>Protocol</guilabel></term>
3318 10 May 07 nicklas 223         <listitem>
3318 10 May 07 nicklas 224           <para>
5783 05 Oct 11 nicklas 225             The protocol used when generating the raw data (optional). 
3318 10 May 07 nicklas 226             Software parameters may be registered as part of
3318 10 May 07 nicklas 227             the protocol.
3318 10 May 07 nicklas 228           </para>
3318 10 May 07 nicklas 229         </listitem>
3318 10 May 07 nicklas 230       </varlistentry>
3318 10 May 07 nicklas 231       <varlistentry>
3318 10 May 07 nicklas 232         <term><guilabel>Description</guilabel></term>
3318 10 May 07 nicklas 233         <listitem>
3318 10 May 07 nicklas 234           <para>
3318 10 May 07 nicklas 235             A description of the raw bioassay (optional).
3318 10 May 07 nicklas 236           </para>
3318 10 May 07 nicklas 237         </listitem>
3318 10 May 07 nicklas 238       </varlistentry>
3318 10 May 07 nicklas 239     </variablelist>
3318 10 May 07 nicklas 240     
3318 10 May 07 nicklas 241     <seeother>
3872 23 Oct 07 nicklas 242       <other external_id="datafiles.edit">Data files</other>
3318 10 May 07 nicklas 243       <other external_id="annotations.edit">Annotations</other>
3318 10 May 07 nicklas 244       <other external_id="annotations.edit.inerited">Inherit annotations</other>
3318 10 May 07 nicklas 245     </seeother>
3318 10 May 07 nicklas 246     </helptext>  
5800 12 Oct 11 nicklas 247     
5800 12 Oct 11 nicklas 248     
5800 12 Oct 11 nicklas 249     <para>
5800 12 Oct 11 nicklas 250       The <guilabel>Data files</guilabel> tab allows BASE users to select
5800 12 Oct 11 nicklas 251       files that contains data for the raw bioassay. 
5800 12 Oct 11 nicklas 252       Read more about this in <xref linkend="platforms.selectfiles" />.
5800 12 Oct 11 nicklas 253     </para>
5800 12 Oct 11 nicklas 254   
5800 12 Oct 11 nicklas 255     <para>
5800 12 Oct 11 nicklas 256       The <guilabel>Annotations</guilabel> tab allows BASE users to use 
5800 12 Oct 11 nicklas 257       annotation types to refine bioassay description. More about annotating items 
5800 12 Oct 11 nicklas 258       can be read in <xref linkend="annotations.annotating" />
5800 12 Oct 11 nicklas 259     </para>
3318 10 May 07 nicklas 260         
5800 12 Oct 11 nicklas 261     <para>
5800 12 Oct 11 nicklas 262       This <guilabel>Inherited annotations</guilabel> tab contains a list of those annotations
5800 12 Oct 11 nicklas 263       that are inherited from the bioassay's parents. Information about working with inherited 
5800 12 Oct 11 nicklas 264       annotations can be found in <xref linkend="annotations.inheriting" />.
5800 12 Oct 11 nicklas 265     </para>
3318 10 May 07 nicklas 266     
3318 10 May 07 nicklas 267   </sect2>
3487 13 Jun 07 peter 268   
3318 10 May 07 nicklas 269   <sect2 id="experiments_analysis.rawbioassay.rawdata">
3318 10 May 07 nicklas 270     <title>Import raw data</title>
3318 10 May 07 nicklas 271     <para>
3872 23 Oct 07 nicklas 272       Depending on the platform, raw data may have to be imported after 
3872 23 Oct 07 nicklas 273       you have created the raw bioassay item. This section doesn't apply
3872 23 Oct 07 nicklas 274       to file-only platforms. The import is handled by plug-ins. To start
3318 10 May 07 nicklas 275       the import click on the <guibutton>Import&hellip;</guibutton>
3318 10 May 07 nicklas 276       button on the single-item view for the raw bioassay.
3487 13 Jun 07 peter 277       If this button does not appear it may be because no file
3318 10 May 07 nicklas 278       format has been specified for the raw data type used by the
3487 13 Jun 07 peter 279       raw bioassay or that the logged in user does not have permission
3318 10 May 07 nicklas 280       to use the import plug-in or file format.
4432 01 Sep 08 jari 281       See <xref linkend="import_data" /> for more 
3318 10 May 07 nicklas 282       information.
3318 10 May 07 nicklas 283     </para>
3318 10 May 07 nicklas 284     
3318 10 May 07 nicklas 285     <note>
3872 23 Oct 07 nicklas 286       <title>File-only platforms</title>
3872 23 Oct 07 nicklas 287       File-only platforms, such as Affymetrix, is handled differently and data is not
5783 05 Oct 11 nicklas 288       imported into the database.
3318 10 May 07 nicklas 289     </note>
3318 10 May 07 nicklas 290     
3318 10 May 07 nicklas 291   </sect2>
3487 13 Jun 07 peter 292
3487 13 Jun 07 peter 293   <sect2 id="experiments_analysis.rawdatatypes">
3487 13 Jun 07 peter 294     <title>Raw data types</title>
3487 13 Jun 07 peter 295     
3872 23 Oct 07 nicklas 296     <para>
3872 23 Oct 07 nicklas 297       A raw data type defines the types of measured values that can be stored
5783 05 Oct 11 nicklas 298       for individual features in the database. Usually this includes some
3872 23 Oct 07 nicklas 299       kind of foreground and background intensity values. The number and meaning
5783 05 Oct 11 nicklas 300       of the values usually depends on the hardware and software used to analyze 
5783 05 Oct 11 nicklas 301       the data from the experiment. Many tools provide mean and median values,
3872 23 Oct 07 nicklas 302       standard deviations, quality control information, etc. Since there are so
3872 23 Oct 07 nicklas 303       many existing tools with many different data file formats BASE uses a 
3872 23 Oct 07 nicklas 304       separate database table for each raw data type to store data. The raw data
3872 23 Oct 07 nicklas 305       tables have been optimized for the type of raw data they can hold and only
3872 23 Oct 07 nicklas 306       has the columns that are needed to store the data. BASE ships with a large
3872 23 Oct 07 nicklas 307       number of pre-defined raw data types. An administrator may also define
3872 23 Oct 07 nicklas 308       additional raw data type. See <xref linkend="appendix.rawdatatypes" /> 
3872 23 Oct 07 nicklas 309       for more information.
3872 23 Oct 07 nicklas 310     </para>
3872 23 Oct 07 nicklas 311     
3872 23 Oct 07 nicklas 312     <sect3 id="experiments_analysis.fileonly">
3872 23 Oct 07 nicklas 313       <title>File-only platforms</title>
3872 23 Oct 07 nicklas 314       <para>
5783 05 Oct 11 nicklas 315         In some cases it doesn't make sense to import any data into the
5783 05 Oct 11 nicklas 316         database. The main reason is that performance will suffer as the
5783 05 Oct 11 nicklas 317         number of entries in the database gets higher. A typical Genepix file 
5783 05 Oct 11 nicklas 318         contains ~55K spots while an Affymetrix file may have millions. 
3872 23 Oct 07 nicklas 319       </para>
3872 23 Oct 07 nicklas 320       <para>
3872 23 Oct 07 nicklas 321         The drawback of keeping the data in files is that none of the generic
3872 23 Oct 07 nicklas 322         tools in BASE can read it. Special plug-ins must be developed for each
3872 23 Oct 07 nicklas 323         type of data file that can be used to analyze and visualize the data.
3872 23 Oct 07 nicklas 324         For the Affymetrix platform there are implementations of the RMAExpress
3872 23 Oct 07 nicklas 325         and Plier normalizations available on the BASE plug-ins web site. 
3872 23 Oct 07 nicklas 326         BASE also ships with built-in plug-ins for extracting metadata from 
3872 23 Oct 07 nicklas 327         Affymetrix CEL and CDF files (ie. headers, number of spots, etc).
3872 23 Oct 07 nicklas 328       </para>
3872 23 Oct 07 nicklas 329       <para>
3872 23 Oct 07 nicklas 330         Users of other file-only platforms should check the BASE plug-ins
3872 23 Oct 07 nicklas 331         website for plug-ins related to their platform. If they can't
3872 23 Oct 07 nicklas 332         find any we recommend that they try to find other users of the same 
3872 23 Oct 07 nicklas 333         platform and try to cooperate in developing the required tools and
3872 23 Oct 07 nicklas 334         plug-ins.
3872 23 Oct 07 nicklas 335       </para>
3487 13 Jun 07 peter 336     </sect3>
3487 13 Jun 07 peter 337     
3487 13 Jun 07 peter 338   </sect2>
3487 13 Jun 07 peter 339
3487 13 Jun 07 peter 340 </sect1>
3487 13 Jun 07 peter 341