source: trunk/doc/src/docbook/userdoc/rawbioassays.xml @ 4568

Last change on this file since 4568 was 4568, checked in by Martin Svensson, 13 years ago

Fixes #1105 Automatically set "array design" on raw bioassay that has link via scan->hyb->...->array design

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 15.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: rawbioassays.xml 4568 2008-10-07 13:54:47Z martin $
7
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<sect1 id="experiments_analysis.rawbioassay">
28  <title>Raw bioassays</title>
29  <para>
30    A <guilabel>Raw bioassay</guilabel> is the representation
31    of the result of analysing one or more images from a
32    <guilabel>Scan</guilabel>. This typically generates a
33    raw data file with lots of measurements for the spots
34    on the hybridization.
35  </para>
36 
37  <para>
38    Creating a new raw bioassay is a two- or three-step process:
39  </para>
40 
41  <orderedlist>
42    <listitem>
43      <para>
44        Create a new raw bioassay item with the
45        <guilabel>New</guilabel> button in the
46        list view.
47      </para>
48    </listitem>
49    <listitem>
50      <para>
51      Upload the file(s) with the raw data and attach it/them to the
52      raw bioassay.
53      </para>
54    </listitem>
55    <listitem>
56      <para>
57        The used platform may require that data is imported to the database.
58        See <xref linkend="import_data" />. If the platform is a
59        file-only platform, this step can be skipped.
60      </para>
61    </listitem>
62  </orderedlist>
63 
64  <note>
65    <title>Supported file formats</title>
66    BASE has built-in support for most file formats where the data comes
67    in a tab-separated (or similar) form. Data from one hybridization
68    must be in a single file. Support for other file formats
69    may be added through plug-ins.
70  </note>
71 
72  <sect2 id="experiments_analysis.rawbioassay.properties">
73    <title>Raw bioassay properties</title>
74   
75    <figure
76      id="experiments_analysis.figures.rawbioassay.edit">
77      <title>Raw bioassay properties</title>
78      <screenshot>
79        <mediaobject>
80          <imageobject>
81            <imagedata
82              fileref="figures/rawbioassay_edit.png" format="PNG" />
83          </imageobject>
84        </mediaobject>
85      </screenshot>
86    </figure> 
87
88    <helptext external_id="rawbioassay.edit" title="Edit raw bioassay">
89   
90    <variablelist>
91      <varlistentry>
92        <term><guilabel>Name</guilabel></term>
93        <listitem>
94          <para>
95            The name of the raw bioassay.
96          </para>
97        </listitem>
98      </varlistentry>
99      <varlistentry>
100        <term>
101          <guilabel>Array index</guilabel>
102        </term>
103        <listitem>
104          <para>
105            The index of the sub-array on the hybridization this
106            raw bioassay's data is linked with. The default value
107            is 1. With some platforms, for example Illumina, which has
108            slides with 6 or 8 arrays the value should be changed to
109            reflect the correct sub-array. This information is important
110            to link the raw bioassay with the correct biomaterial
111            entries.
112          </para>
113        </listitem>
114      </varlistentry>
115      <varlistentry>
116        <term>
117          <guilabel>Platform</guilabel>
118        </term>
119        <listitem>
120          <para>
121            Select the platform / variant used for the
122            raw bioassay. The selected options affects which
123            files that can be selected on the <guilabel>Data files</guilabel>
124            tab. If the platform supports importing data to the database
125            you must also select a <guilabel>Raw data type</guilabel>.
126          </para>
127        </listitem>
128      </varlistentry>
129      <varlistentry>
130        <term><guilabel>Raw data type</guilabel></term>
131        <listitem>
132          <para>
133            The type of raw data. This option is disabled for file-only
134            platforms and for platforms that are locked to a specific
135            raw data type. This cannot be changed after raw data has been
136            imported. <nohelp>See
137            <xref linkend="experiments_analysis.rawdatatypes" />.</nohelp>
138          </para>
139        </listitem>
140      </varlistentry>
141      <varlistentry>
142        <term><guilabel>Array design</guilabel></term>
143        <listitem>
144          <para>
145            The array design used on the array slide (optional).
146            If an array design is specified
147            the import will verify that the raw data has
148            the same reporter on the same position. This
149            prevents mistakes but also speed up analysis
150            since some optimizations can be used when assigning
151            positions in bioassay sets.
152            The array design can be changed after raw data has been
153            imported, but this triggers a new validation. If the raw data
154            is stored in the database, the features on the new array design must
155            match the the raw data. The verification can use three different methods:
156          </para>
157         
158          <itemizedlist>
159          <listitem>
160            <para>
161            Coordinates: Verify block, meta-grid, row and column coordinates.
162            </para>
163          </listitem>
164          <listitem>
165            <para>Position: Verify the position number.</para>
166          </listitem>
167          <listitem>
168            <para>
169            Feature ID: Verify the feature ID. This option can only be used
170            if the raw bioassay is currently connected to an array design that
171            has feature ID values already.
172            </para>
173          </listitem>
174          </itemizedlist>
175          <para>
176            In all three cases it is also verified that the reporter of the raw
177            data matches the reporter of the features.
178          </para>
179
180          <para>
181            For Affymetrix data, the
182            CEL file is validated against the CDF file of the new array design.
183            If the validation fails, the array design is not changed.
184          </para>
185        </listitem>
186      </varlistentry>
187      <varlistentry>
188        <term><guilabel>Scan</guilabel></term>
189        <listitem>
190          <para>
191            The scan this raw bioassay is related to (optional). Changing this property will
192            also update the value in <guilabel>Array design</guilabel>, but only if the
193            selected scan is connected to an array design and the current user has permission
194            to view it.
195          </para>
196        </listitem>
197      </varlistentry>
198      <varlistentry>
199        <term><guilabel>Software</guilabel></term>
200        <listitem>
201          <para>
202            The software used to analyse the image or images (optional).
203          </para>
204        </listitem>
205      </varlistentry>
206      <varlistentry>
207        <term><guilabel>Protocol</guilabel></term>
208        <listitem>
209          <para>
210            The protocol used when analysing the image(s) (optional).
211            Software parameters may be registered as part of
212            the protocol.
213          </para>
214        </listitem>
215      </varlistentry>
216      <varlistentry>
217        <term><guilabel>Description</guilabel></term>
218        <listitem>
219          <para>
220            A description of the raw bioassay (optional).
221          </para>
222        </listitem>
223      </varlistentry>
224    </variablelist>
225   
226    <seeother>
227      <other external_id="datafiles.edit">Data files</other>
228      <other external_id="annotations.edit">Annotations</other>
229      <other external_id="annotations.edit.inerited">Inherit annotations</other>
230    </seeother>
231    </helptext> 
232       
233    <para>
234      A raw bioassay can have annotations. Read more about this in
235      <xref linkend="annotations"/>.
236    </para>
237   
238  </sect2>
239 
240  <sect2 id="experiments_analysis.rawbioassay.rawdata">
241    <title>Import raw data</title>
242    <para>
243      Depending on the platform, raw data may have to be imported after
244      you have created the raw bioassay item. This section doesn't apply
245      to file-only platforms. The import is handled by plug-ins. To start
246      the import click on the <guibutton>Import&hellip;</guibutton>
247      button on the single-item view for the raw bioassay.
248      If this button does not appear it may be because no file
249      format has been specified for the raw data type used by the
250      raw bioassay or that the logged in user does not have permission
251      to use the import plug-in or file format.
252      See <xref linkend="import_data" /> for more
253      information.
254    </para>
255   
256    <note>
257      <title>File-only platforms</title>
258      File-only platforms, such as Affymetrix, is handled differently and data is not
259      imported into the database. See <xref linkend="experiments_analysis.fileonly" />.
260    </note>
261   
262  </sect2>
263
264  <sect2 id="experiments_analysis.rawdatatypes">
265    <title>Raw data types</title>
266   
267    <para>
268      A raw data type defines the types of measured values that can be stored
269      for individual spots in the database. Usually this includes some
270      kind of foreground and background intensity values. The number and meaning
271      of the values usually depends on the scanner and software used to analyse
272      the images from a hybridization. Many tools provide mean and median values,
273      standard deviations, quality control information, etc. Since there are so
274      many existing tools with many different data file formats BASE uses a
275      separate database table for each raw data type to store data. The raw data
276      tables have been optimized for the type of raw data they can hold and only
277      has the columns that are needed to store the data. BASE ships with a large
278      number of pre-defined raw data types. An administrator may also define
279      additional raw data type. See <xref linkend="appendix.rawdatatypes" /> 
280      for more information.
281    </para>
282   
283    <sect3 id="experiments_analysis.fileonly">
284      <title>File-only platforms</title>
285      <para>
286        BASE 2.5 introduced a generic way to keep the data in files instead
287        of having to import it to the database. In older BASE versions this
288        ability was limited to the Affymetrix platform. The reason for
289        keeping the data in files is that the number of spots tend to grow,
290        which may result in bad performance if the database should be used.
291        A typical Genepix file contains ~55K spots while an Affymetrix file may
292        have millions.
293      </para>
294      <para>
295        The drawback of keeping the data in files is that none of the generic
296        tools in BASE can read it. Special plug-ins must be developed for each
297        type of data file that can be used to analyze and visualize the data.
298        For the Affymetrix platform there are implementations of the RMAExpress
299        and Plier normalizations available on the BASE plug-ins web site.
300        BASE also ships with built-in plug-ins for extracting metadata from
301        Affymetrix CEL and CDF files (ie. headers, number of spots, etc).
302      </para>
303      <para>
304        Users of other file-only platforms should check the BASE plug-ins
305        website for plug-ins related to their platform. If they can't
306        find any we recommend that they try to find other users of the same
307        platform and try to cooperate in developing the required tools and
308        plug-ins.
309      </para>
310    </sect3>
311   
312  </sect2>
313
314  <sect2 id="experiments_analysis.spotimages">
315    <title>Spot images</title>
316    <para>
317      If you have uploaded the image or images from the scan
318      you may create spot images. Spot images allows you to
319      view the image of each spot separately in the analysis.
320      For this to work the raw data must contain the X and Y
321      coordinates of each spot.
322    </para>
323   
324    <para>
325      After raw data has been imported into the database
326      you will find that a <guibutton>Create spot images&hellip;</guibutton>
327      button appears in the toolbar on the single-item view
328      for the raw bioassay. Click on this button to open
329      a window that allows you to specify parameters for the
330      spot image extraction.
331    </para>
332   
333    <figure id="experiments_analysis.figures.spotimage">
334      <title>Create spot images</title>
335      <screenshot>
336        <mediaobject>
337          <imageobject><imagedata 
338            fileref="figures/create_spot_images.png" format="PNG"
339            /></imageobject>
340        </mediaobject>
341      </screenshot>
342    </figure>
343   
344    <helptext external_id="rawbioassay.edit.spotimages" 
345      title="Create spot images">
346     
347    <variablelist>
348      <varlistentry>
349        <term><guilabel>X/Y scale and offset</guilabel></term>
350        <listitem>
351          <para>
352            For the spot image creation process to be able
353            to find the spots, the X and Y coordinates from
354            the raw data must be converted into image pixel
355            values. The formula used is:
356            <code>pixelX = (rawX - offsetX) / scaleX</code>
357          </para>
358         
359          <important>
360            It is important that you get these values correct,
361            or the spot image creation process may fail or generate
362            incorrect spot images.
363          </important>
364         
365        </listitem>
366      </varlistentry>
367     
368      <varlistentry>
369        <term><guilabel>Spot size</guilabel></term>
370        <listitem>
371          <para>
372            The spot size is given in pixels and is the width and
373            hight around each spot that is large enough to contain
374            the spot without having too much empty space or
375            neighbouring spots around it.
376          </para>
377     
378        </listitem>
379      </varlistentry>
380     
381      <varlistentry>
382        <term><guilabel>Gamma correction</guilabel></term>
383        <listitem>
384          <para>
385            Gamma correction is needed to make the images
386            look good on computer displays. A value between
387            1.8 and 2.2 is usually best.
388            See <ulink url="http://en.wikipedia.org/wiki/Gamma_correction"
389              >http://en.wikipedia.org/wiki/Gamma_correction</ulink>
390            for more information.
391          </para>
392     
393        </listitem>
394      </varlistentry>
395     
396      <varlistentry>
397        <term><guilabel>Quality</guilabel></term>
398        <listitem>
399          <para>
400            The quality setting to use when saving the generated
401            spot images as JPEG images. A value between 0 = poor
402            and 1 = good can be used.
403          </para>
404        </listitem>
405      </varlistentry>
406     
407      <varlistentry>
408        <term><guilabel>Red, green and blue image files</guilabel></term>
409        <listitem>
410          <para>
411            You must select which scanned image files to use for the
412            red, green and blue component of the generated spot images.
413            Use the <guibutton>Select&hellip;</guibutton> buttons
414            to select existing images or upload new ones.
415            The original image files must be 8- or
416            16-bit grey scale images. Some scanners, for
417            example Genepix, can create TIFF files with more than
418            one image in each file. BASE supports this and uses
419            the images in the order they appear in the TIFF file.
420          </para>
421         
422          <note>
423            Avoid TIFF images which also contains previews
424            of the full image. BASE may use the wrong image
425            with an error as the result. If you have multi-image
426            TIFF files these must only contain the full images.
427          </note>
428         
429        </listitem>
430      </varlistentry>
431      <varlistentry>
432        <term><guilabel>Save as</guilabel></term>
433        <listitem>
434          <para>
435            Specify the path and filename where the generated spot
436            images should be saved. The process will create
437            a single zip file containing all the images.
438          </para>
439        </listitem>
440      </varlistentry>
441     
442      <varlistentry>
443        <term><guilabel>Overwrite existing file</guilabel></term>
444        <listitem>
445          <para>
446            If a file with the same name already exists you
447            must mark this checkbox to overwrite it.
448          </para>
449        </listitem>
450      </varlistentry>
451    </variablelist>
452   
453    <para>
454      Click on the <guibutton>Create</guibutton> button
455      to add the spot image creation job to the job queue,
456      or on &gbCancel; to abort.
457    </para>
458   
459    </helptext>
460  </sect2>
461</sect1>
462   
Note: See TracBrowser for help on using the repository browser.