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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: rawbioassays.xml 3523 2007-06-20 12:32:41Z nicklas $

  Copyright (C) Authors contributing to this file.

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<sect1 id="experiments_analysis.rawbioassay">
  <title>Raw bioassays</title>
  <para>
    A <guilabel>Raw bioassay</guilabel> is the representation
    of the result of analysing one or more images from a 
    <guilabel>Scan</guilabel>. This typically generates a 
    raw data file with lots of measurements for the spots
    on the hybridization.
  </para>
  
  <para>
    Creating a new raw bioassay is a two-step process:
  </para>
  
  <orderedlist>
    <listitem>
      <para>
        Create a new raw bioassay item with the
        <guilabel>New</guilabel> button in the 
        list view.
      </para>
    </listitem>
    <listitem>
      <para>
        Upload the file with the raw data and import it
        to the raw bioassay. See <xref linkend="import_export_data.import" />.
      </para>
    </listitem>
  </orderedlist>
  
  <note>
    <title>Supported file formats</title>
    BASE has built-in support for most file formats where the data comes
    in a tab-separated (or similar) form. Data from one hybridization
    must be in a single file. Support for other file formats
    mat be added through plug-ins.
  </note>
  
  <sect2 id="experiments_analysis.rawbioassay.properties">
    <title>Raw bioassay properties</title>
    
    <para>
      A raw bioassay has the following properties:
    </para>

    <helptext external_id="rawbioassay.edit" title="Edit raw bioassay">
    
    <variablelist>
      <varlistentry>
        <term><guilabel>Name</guilabel></term>
        <listitem>
          <para>
            The name of the raw bioassay.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Raw data type</guilabel></term>
        <listitem>
          <para>
            The type of raw data. This cannot be
            changed after raw data has been
            imported. <nohelp>See
            <xref linkend="experiments_analysis.rawdatatypes" />.</nohelp>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Array design</guilabel></term>
        <listitem>
          <para>
            The array design used on the array slide (optional).
            If an array design is specified
            the import will verify that the raw data has
            the same reporter on the same position. This
            prevents mistakes but also speed up analysis
            since some optimzations can be used when assigning 
            positions in bioassay sets.
            The array design can be changed after raw data has been 
            imported, but this triggers a new validation. If the raw data
            is stored in the database, the position, coordinates and reporter of all features
            on the new array design must exactly match the position,
            coordinates and reporter of the raw data. For Affymetrix data, the
            CEL file is validated against the CDF file of the new array design.
            If the validation fails, the array design is not changed.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>CEL file</guilabel></term>
        <listitem>
          <para>
            Only used for Affymetrix data. 
            <nohelp>See
            <xref linkend="experiments_analysis.affymetrix" />
            </nohelp>
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Scan</guilabel></term>
        <listitem>
          <para>
            The scan this raw bioassay is related to (optional).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Software</guilabel></term>
        <listitem>
          <para>
            The software used to analyse the image or images (optional).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Protocol</guilabel></term>
        <listitem>
          <para>
            The protocol used when analysing the image(s) (optional). 
            Software parameters may be registered as part of
            the protocol.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Description</guilabel></term>
        <listitem>
          <para>
            A description of the raw bioassay (optional).
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    
    <seeother>
      <other external_id="annotations.edit">Annotations</other>
      <other external_id="annotations.edit.inerited">Inherit annotations</other>
    </seeother>
    </helptext> 
        
    <para>
      A raw bioassay can have annotations. Read more about this in
      <xref linkend="annotations"/>.
    </para>
    
  </sect2>
  
  <sect2 id="experiments_analysis.rawbioassay.rawdata">
    <title>Import raw data</title>
    <para>
      Raw data must be imported after you have created the raw 
      bioassay item. The import is handled by plug-ins. To start
      the import click on the <guibutton>Import&hellip;</guibutton>
      button on the single-item view for the raw bioassay.
      If this button does not appear it may be because no file
      format has been specified for the raw data type used by the
      raw bioassay or that the logged in user does not have permission
      to use the import plug-in or file format.
      See <xref linkend="import_export_data.import" /> for more 
      information.
    </para>
    
    <note>
      <title>Affymetrix data</title>
      Affymterix data is handled differently and is not
      imported into the database. See <xref linkend="experiments_analysis.affymetrix" />.
    </note>
    
  </sect2>

  <sect2 id="experiments_analysis.rawdatatypes">
    <title>Raw data types</title>
    <para>TODO</para>
    
    <sect3 id="experiments_analysis.affymetrix">
      <title>Affymetrix data</title>
      <para>TODO</para>
    </sect3>
    
  </sect2>

  <sect2 id="experiments_analysis.spotimages">
    <title>Spot images</title>
    <para>
      If you have uploaded the image or images from the scan
      you may create spot images. Spot images allows you to 
      view the image of each spot separately in the analysis.
      For this to work the raw data must contain the X and Y
      coordinates of each spot.
    </para>
    
    <para>
      After raw data has been imported into the database
      you will find that a <guibutton>Create spot images&hellip;</guibutton>
      button appears in the toolbar on the single-item view
      for the raw bioassay. Click on this button to open
      a window that allows you to specify parameters for the
      spot image extraction.
    </para>
    
    <figure id="experiments_analysis.figures.spotimage">
      <title>Create spot images</title>
      <screenshot>
        <mediaobject>
          <imageobject><imagedata 
            fileref="figures/create_spot_images.png" format="PNG"
            /></imageobject>
        </mediaobject>
      </screenshot>
    </figure>
    
    <helptext external_id="rawbioassay.edit.spotimages" 
      title="Create spot images">
      
    <variablelist>
      <varlistentry>
        <term><guilabel>X/Y scale and offset</guilabel></term>
        <listitem>
          <para>
            For the spot image creation process to be able
            to find the spots, the X and Y coordinates from 
            the raw data must be converted into image pixel 
            values. The formula used is:
            <code>pixelX = (rawX - offsetX) / scaleX</code>
          </para>
          
          <important>
            It is important that you get these values correct,
            or the spot image creation process may fail or generate
            incorrect spot images.
          </important>
          
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guilabel>Spot size</guilabel></term>
        <listitem>
          <para>
            The spot size is given in pixels and is the width and
            hight around each spot that is large enough to contain
            the spot without having too much empty space or 
            neighbouring spots around it.
          </para>
      
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guilabel>Gamma correction</guilabel></term>
        <listitem>
          <para>
            Gamma correction is needed to make the images
            look good on computer displays. A value between
            1.8 and 2.2 is usually best.
            See <ulink url="http://en.wikipedia.org/wiki/Gamma_correction"
              >http://en.wikipedia.org/wiki/Gamma_correction</ulink>
            for more information.
          </para>
      
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guilabel>Quality</guilabel></term>
        <listitem>
          <para>
            The quality setting to use when saving the generated
            spot images as JPEG images. A value between 0 = poor
            and 1 = good can be used.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guilabel>Red, green and blue image files</guilabel></term>
        <listitem>
          <para>
            You must select which scanned image files to use for the
            red, green and blue component of the generated spot images.
            Use the <guibutton>Select&hellip;</guibutton> buttons
            to select existing images or upload new ones.
            The original image files must be 8- or
            16-bit grey scale images. Some scanners, for
            example Genepix, can create TIFF files with more than
            one image in each file. BASE supports this and uses 
            the images in the order they appear in the TIFF file.
          </para>
          
          <note>
            Avoid TIFF images which also contains previews
            of the full image. BASE may use the wrong image 
            with an error as the result. If you have multi-image
            TIFF files these must only contain the full images.
          </note>
          
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Save as</guilabel></term>
        <listitem>
          <para>
            Specify the path and filename where the generated spot
            images should be saved. The process will create
            a single zip file containing all the images.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guilabel>Overwrite existing file</guilabel></term>
        <listitem>
          <para>
            If a file with the same name already exists you
            must mark this checkbox to overwrite it.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    
    <para>
      Click on the <guibutton>Create</guibutton> button
      to add the spot image creation job to the job queue,
      or on &gbCancel; to abort.
    </para>
    
    </helptext>
  </sect2>
</sect1>