source: trunk/doc/src/docbook/userdoc/experiments_analysis.xml @ 3308

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: experiments_analysis.xml 3308 2007-05-08 12:34:07Z 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.
-->

<chapter id="experiments_analysis">
  <?dbhtml dir="analysis"?>
  <title>Experiments and analysis</title>
    
    <sect1 id="experiments_analysis.scans">
      <title>Scans and images</title>
      <para>TODO</para>
    </sect1>

    <sect1 id="experiments_analysis.rawbioassay">
      <title>Raw bioassays</title>
      <para>TODO</para>
    
      <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>TODO</para>
      </sect2>
      
    </sect1>
    
    <sect1 id="experiments_analysis.experiments">
      <title>Experiments</title>
      <para>TODO</para>
      
      <sect2 id="experiments_analysis.experimentoverview">
        <title>Experiment overview</title>
        
        <para>
          With the <guilabel>Experiment overview</guilabel> 
          function you can get an overview of all hybridizations,
          extracts, samples, annotations, etc. used in an 
          experiment. The overview includes a lot of checks
          that validates your experimental setup for missing
          or possibly incorrect information.
        </para>
        
        <para>
          You can access the overview of an experiment by navigating
          to the single-item view of the experiment you are interested in.
          Then, switch to the <guilabel>Overview</guilabel> tab that
          is present on that page. Here is an example of what is displayed:
        </para>
        
        <figure id="experiments_analysis.figures.experimentoverview">
          <title>The experiment overview</title>
          <screenshot>
            <mediaobject>
              <imageobject><imagedata 
                fileref="figures/experiment_overview.png" format="PNG"
                /></imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="experiment.overview " 
          title="Experiment overview">
        <para>
          The page is divided into three sections:
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
            To the left is a tree displaying all items
            in the experiment and how they are linked to
            each other.
            </para>
          </listitem>
          
          <listitem>
            <para>
            The lower right shows a list of warnings and error
            messages that was found when validating the experiment.
            <nohelp>
            In the example you can see that we have failed to
            specify a value for the <guilabel>Temperature</guilabel>
            protocol parameter for one of the samples.
            </nohelp>
            </para>
          </listitem>
            
          <listitem>
            <para>
              The upper right shows information about the
              currently selected item in the tree. This part also
              contains more information errors or warnings for this
              item. It may also present you with one or more suggestions
              about how to fix the problem and with a link that
              takes you to the most probable location where you can fix
              the error or warning.
            </para>
            
            <note>
              <title>No links?</title>
              If you don't have permission to change things no links
              will be shown.
            </note>
            
          </listitem>
            
        </itemizedlist>
        
        <seeother>
          <other external_id="experiment.overview.validationoptions"
            >Validation options</other>
          <other external_id="experiment.overview.fixfailures"
            >How to fix validation failures</other>
        </seeother>
        
        </helptext>
        
        <sect3 id="experiments_analysis.validationoptions">
          <title>Validation options</title>
          <para>
            Click on the <guibutton>Validation options</guibutton>
            button in the toolbar to open the <guilabel>Validation
            options</guilabel> dialog.
          </para>
          
          <figure id="experiments_analysis.figures.validationoptions">
            <title>Validation options</title>
            <screenshot>
              <mediaobject>
                <imageobject><imagedata 
                  fileref="figures/validation_options.png" format="PNG"
                  /></imageobject>
              </mediaobject>
            </screenshot>
          </figure>         
          
          <helptext external_id="experiment.overview.validationoptions" 
            title="Validation options">
            <para>
              The validation procedure is highly 
              configurable and you can select what you want to
              ignore, or something should be displayed as an error
              or warning.
            </para>
            
            <variablelist>
              <varlistentry>
                <term><guilabel>Presets</guilabel></term>
                <listitem>
                  <para>
                  The list contains predefined and
                  user defined validation options.
                  Use the <guibutton>Save as&hellip;</guibutton>
                  button to save the current options as a user defined
                  preset. The <guibutton>Remove&hellip;</guibutton>
                  button is used to remove the currently selected
                  preset. Predefined presets can't be deleted.
                  </para>
                </listitem>
              </varlistentry>
              
              <varlistentry>
                <term><guilabel>Project defaults</guilabel></term>
                <listitem>
                  <para>
                  The options in this section are used to check
                  if your experiment uses the same values as set
                  by the project default values of the currently active
                  project<nohelp>
                  (see <xref linkend="project_permission.projects" />)</nohelp>. 
                  If no project is active or if the active project doesn't
                  have default values these options are ignored.
                  </para>
                </listitem>
                
              </varlistentry>
              
              <varlistentry>
                <term><guilabel>Missing items</guilabel></term>
                <listitem>
                  <para>
                  The options in this section are used to check if
                  you have specified values for optional items. 
                  For example, there is an option that warns you if 
                  you havn't specified a protocol.
                  </para>
                </listitem>
              </varlistentry>
              
              <varlistentry>
                <term><guilabel>Annotations</guilabel></term>
                <listitem>
                  <para>
                  The options in this section are used to check 
                  problems related to annotations. The most
                  important ones are listed here:
                  </para>
                  
                  <itemizedlist>
                  <listitem>
                    <simpara>
                    <emphasis>Missing MIAME annotation value</emphasis>:
                    Checks that you have specified values
                    for all annotations marked as 
                    <guilabel>Required for MIAME</guilabel>.
                    </simpara>
                  </listitem>
                  
                  <listitem>
                    <simpara>
                    <emphasis>Missing factor value</emphasis>:
                    Checks that you have specified values for
                    all annotations used as experimental factors in
                    the experiment.
                    </simpara>
                  </listitem>
                  
                  <listitem>
                    <simpara>
                    <emphasis>Missing parameter value</emphasis>:
                    Checks that you have specified values
                    for all protocol parameters.
                    </simpara>
                  </listitem>

                  <listitem>
                    <simpara>
                    <emphasis>Annotation is protocol parameter</emphasis>:
                    Checks if an item has been annotated with a 
                    an annotation that is actually a protocol parameter.
                    </simpara>
                  </listitem>

                  <listitem>
                    <simpara>
                    <emphasis>Annotation has invalid value</emphasis>:
                    Checks if annotation values are correct with 
                    respect to the rules given by the annotation type.
                    This might include numeric values that are outside 
                    the valid range, or values not in the list
                    of allows values for an enumerated annotation type.
                    </simpara>
                  </listitem>

                  <listitem>
                    <simpara>
                    <emphasis>Inheriting annotation from non-parent</emphasis>:
                    Checks if inherited annotations really comes from a
                    parent item. This might happen if you rearrange 
                    parent-child relationship because you found that
                    they were incorrectly linked.
                    </simpara>
                  </listitem>
                  </itemizedlist>
                  
                
                </listitem>
              </varlistentry>
              
              <varlistentry>
                <term><guilabel>Denied access</guilabel></term>
                <listitem>
                  <para>
                  The options in this section are used to
                  check if you don't have access (read permission)
                  to an item in the experiment hierarchy. If this 
                  happens the validation can't proceed in that branch.
                  This might mask other validation problems.
                  </para>
                </listitem>
              </varlistentry>
              
              <varlistentry>
                <term><guilabel>Other</guilabel></term>
                <listitem>
                  <para>
                  This section collects options that doesn't fit
                  into any of the other sections. The most
                  important options are:
                  </para>
                  
                  <itemizedlist>
                    <listitem>
                      <simpara>
                      <emphasis>Array deign mismatch</emphasis>:
                      Checks if the array design specified for
                      a raw bioassay is the same array design
                      specified for the hybridization.
                      </simpara>
                    </listitem>
                    
                    <listitem>
                      <simpara>
                      <emphasis>Multiple array designs</emphasis>:
                      Checks if all raw bioassays use the
                      same array design or not.
                      </simpara>
                    </listitem>
                  
                    <listitem>
                      <simpara>
                      <emphasis>Incorrect number of labled extracts</emphasis>:
                      Checks if the number of labeled extracts
                      match the number of channels for the experiment.
                      </simpara>
                    </listitem>

                    <listitem>
                      <simpara>
                      <emphasis>Non-unique name</emphasis>:
                      Checks if two items of the same type
                      have the same name. A unique name if important
                      when exporting data in Tab2Mage format.
                      </simpara>
                    </listitem>

                    <listitem>
                      <simpara>
                      <emphasis>Circular reference to pooled item</emphasis>:
                      If you have used pooling, checks that no 
                      circular references have been created.
                      </simpara>
                    </listitem>
                  
                  </itemizedlist>
                  
                </listitem>
              </varlistentry>
              
            </variablelist>
            
            <para>
              Click on the <guibutton>Save</guibutton> button
              to use the current settings. The display will
              automatically refresh itself.
            </para>
            
          </helptext>
          
          <helptext external_id="experiment.overview.validationoptions.savepreset" 
            title="Save preset" webonly="1">
            
            <para>
            Saves all validation options as a preset. 
            </para>
            
            <variablelist>
              <varlistentry>
                <term><guilabel>Name</guilabel></term>
                <listitem>
                  <para>
                    The name of the preset. The name must be unique
                    and if a preset with the same name already exists
                    you will be asked if you want to overwrite it or not.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
            
            <para>
              Click on the <guibutton>Save</guibutton> button
              to save the preset or <guibutton>Cancel</guibutton>
              to abort.
            </para>
          </helptext>
          
        </sect3>
        
        <sect3 id="experiments_analysis.fixfailures">
          <title>Fixing validation failures</title>
          <helptext external_id="experiment.overview.fixfailures" 
            title="How to fix validation failures">
            
            <para>
            The experiment overview includes a function that allows
            you to quickly fix most of the problems found during the 
            validation. The easiest way to use the function is:
            </para>
            
            <orderedlist>
              <listitem>
                <simpara>
                Click on an error or warning in the list of failures in 
                the lower right
                pane. The tree in the left pane and the item overview in the
                top right pane will automatically be updated to show the
                exact location of the faulty item.
                </simpara>
              </listitem>
              <listitem>
                <simpara>
                The upper right pane should contain a list labeled
                <guilabel>Failure details</guilabel> with more information
                about each failure and also one or more suggestions for fixing
                the problem. For example, a failure due to a missing item
                should suggest that you add or select an item.
                </simpara>
              </listitem>
              
              <listitem>
                <simpara>
                The suggestions should also have links that takes
                you to an edit view where you can do the changes.
                </simpara>
              </listitem>
              
              <listitem>
                <simpara>
                After saving the changes you must click on the
                <guibutton>Revalidate</guibutton> button to update
                interface. If you want, you can fix more than one 
                failure before clicking on the button.
                </simpara>
              </listitem>
                
            </orderedlist>
          
          </helptext>
        </sect3>
        
      </sect2>
      
      <sect2 id="experiments_analysis.magexport">
        <title>Tab2Mage export</title>
        <para>TODO</para>
      </sect2>
      
      
    </sect1>
    
    <sect1 id="experiments_analysis.analysis">
      <title>Analysing data within BASE</title>
      <para>TODO</para>
      
      <sect2 id="experiments_analysis.bioassaysets">
        <title>Transformations and bioassay sets</title>
        <para>TODO</para>
      
        <sect3 id="experiments_analysis.rootbioassayset">
          <title>The root bioassay set</title>
          <para>TODO</para>
        </sect3>
        
        <sect3 id="experiments_analysis.overviewplots">
          <title>Overview plots</title>
          <para>TODO</para>
        </sect3>
        
      </sect2>
      
      <sect2 id="experiments_analysis.filtering">
        <title>Filtering data</title>
        <para>TODO</para>
        
        <sect3 id="experiments_analysis.formulas">
          <title>Formulas</title>
          <para>TODO</para>
          
        </sect3>
      </sect2>
      
      <sect2 id="experiments_analysis.normalization">
        <title>Normalizing data</title>
        <para>TODO</para>
        
      </sect2>
      
      <sect2 id="experiments_analysis.plugins">
        <title>Other analysis plugins</title>
        <para>TODO</para>
        
      </sect2>
      
      
      <sect2 id="experiments_analysis.plotter">
        <title>Plot tool</title>
        <para>TODO</para>
        
        <sect3 id="experiments_analysis.scatterplot">
          <title>Scatter plots</title>
          <para>TODO</para>
        </sect3>
        
        <sect3 id="experiments_analysis.histogramplot">
          <title>Histogram plots</title>
          <para>TODO</para>
        </sect3>
        
        <sect3 id="experiments_analysis.filterplot">
          <title>Filtering plots</title>
          <para>TODO</para>
        </sect3>
        
        <sect3 id="experiments_analysis.saveplot">
          <title>Save plots</title>
          <para>TODO</para>
        </sect3>
        
      </sect2>
      
      <sect2 id="experiments_analysis.explorer">
        <title>Experiment explorer</title>
        <para>TODO</para>
        
        <sect3 id="experiments_analysis.explorer.reporterview">
          <title>Reporter view</title>
          <para>TODO</para>
        </sect3>
        
        <sect3 id="experiments_analysis.explorer.reportersearch">
          <title>Reporter search</title>
          <para>TODO</para>
        </sect3>
        
      </sect2>
      
    </sect1>
    
    <sect1 id="experiments_analysis.mev">
      <title>Analysing data with Multiexperiment Viewer (MeV)</title>
      <para>TODO</para>
    </sect1>
    

</chapter>