source: trunk/doc/src/docbook/userdoc/biomaterials.xml @ 5708

<?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: biomaterials.xml 5708 2011-08-25 12:48:46Z nicklas $
  
  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
  Copyright (C) 2008, 2009 Jari Häkkinen, Martin Svensson
  
  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 3
  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 BASE. If not, see <http://www.gnu.org/licenses/>.
-->
<chapter id="biomaterials">
  <?dbhtml dir="biomaterials"?>
  <title>Biomaterial</title>
  <sect1 id="biomaterial.introduction">
    <title>Introduction</title>
    <para>
      The generic term biomaterial refers to any biological material used in an experiment.
      Biomaterial is divided in three main components, <emphasis>biosources</emphasis>, <emphasis>samples</emphasis>
      and <emphasis>extracts</emphasis>. The biomaterials can then be subclassified further by 
      the use of subtypes (see <xref linkend="subtypes"/>). BASE has, for example, defined two extracts subtypes: 
      <emphasis>Labeled extract</emphasis> (used in microarray experiments)
      and <emphasis>Library</emphasis> (used in sequencing experiments).    
      The order used in presenting those entities is not innocuous as it represents the
      sequence of transformation a source material undergoes until it is in a state compatible
      for further exeperimental processing. This progression is actually
      mimicked in the BASE
      <guimenu>Biomaterial LIMS</guimenu>
      menu again to insist on this natural progression.
    </para>
    <itemizedlist>
      <listitem>
        <simpara>
          Biosources correspond to the native biological entity used in an experiment
          prior to any treatment.
        </simpara>
      </listitem>
      <listitem>
        <simpara>
          Samples are central to BASE to describe the sample processing. So samples can
          be created from other samples if user want to track sample processing event in a
          finely granular fashion.
        </simpara>
      </listitem>
      <listitem>
        <simpara>
          Extracts correspond to nucleic acid material extracted from a tissue sample or a
          cell culture sample.
        </simpara>
      </listitem>
    </itemizedlist>
    <para>
      BASE allows users to create any of the these entities fairly freely, however it is
      expected that users will follow the natural path of the laboratory workflow.
    </para>
    <tip>
      <para>
        It is highly recommended that you have read
        <xref linkend="webclient.items" />
        before continuing with this chapter.
      </para>
    </tip>
  </sect1>
  
  <sect1 id="biomaterials.biosources">
    <title>Biosources</title>


    <para>
      Biosources correspond to the native biological entity used in an experiment prior to any treatment. 
      Biosources can be added to BASE by most users and are managed from <menuchoice>
        <guimenu>Biomaterial LIMS</guimenu>
        <guimenuitem>Biosources</guimenuitem>
      </menuchoice>. 
      Use the &gbNew; button to create a new biosource. This brings up the dialog below.
    </para>

      <figure id="biomaterials.figures.biosource-tab-1">
        <title>Biosource properties</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 
                fileref="figures/biosource-tab-1.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      <helptext external_id="biosource.edit" title="Biosource properties">

        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>
                This is the only mandatory field. BASE by default assigns
                <replaceable>New biosource</replaceable>
                as name but it is advised to provide unique sensible names.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Type</guilabel>
            </term>
            <listitem>
              <para>
              The subtype of the biosource. The list
              may evolve depending on additions by the server
              administrator. Selecting the proper subtype
              is recommended and enables BASE to automatically guess 
              the most likely subtype when creating child biomaterial.
              <nohelp>
              See <xref linkend="subtypes" /> for more information.
              </nohelp>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>External ID</guilabel>
            </term>
            <listitem>
              <para>
                An external reference identifiers (e.g. a patient identification
                code) can be supplied using this field.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>A free text description can be supplied using this field.</para>
            </listitem>
          </varlistentry>
        </variablelist>
        <seeother>
          <other external_id="annotations.edit">Annotations</other>
        </seeother>
      </helptext>

      <para>
        The <guilabel>Annotations</guilabel> tab allows BASE users to use 
        annotation types to refine biosource description. More about annotating items 
        can be read in <xref linkend="annotations.annotating" />
      </para>

  </sect1>
  <sect1 id="biomaterial.samples">
    <title>Samples</title>
    <para>
      Samples result from processing events applied to biosource material or other samples
      before they are turned into an extract. In other words, samples can be created from
      biosource items or from one or more sample items. When a sample is created from several
      other samples, a pooling event is performed.
    </para>
    <para>
      For every step of transformation from biosource to sample, it is possible to provide
      information about the protocol used to perform this task. It is not enforced in BASE
      but it should serve as guidance when devising the granularity of the sample processing
      task. Also, it is good practice to provide protocol information to ensure MIAME
      compliance.
    </para>
    <para>
      Use
      <menuchoice>
        <guimenu>Biomaterial LIMS</guimenu>
        <guimenuitem>Samples</guimenuitem>
      </menuchoice>
      to get to the list of samples.
    </para>
    
    <sect2 id="biomaterial.samples.create">
      <title>Create sample</title>
    
      <para>
        Beside the common way, using the &gbNew; button, a sample can be created in one of
        the following ways:
      </para>
        <variablelist>
          <varlistentry>
            <term>from either biosource list- or single view- page.</term>
            <listitem>
              <para>
                No matter how complex the sample processing phase is, at least one
                sample has to be anchored to a biosource. Therefore, a natural way
                to create an sample is to click on
                <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/add.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon>
                in the <guilabel>Samples</guilabel> column of the biosource list view. There is also a
                corresponding button,
                <guibutton>New sample&hellip;</guibutton>
                in the toolbar when viewing a single biosource.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>from the sample list page</term>
            <listitem>
              <para>
                Child samples can be created from a single parent by clicking on the 
                <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/add.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon> icon in the <guilabel>Child samples</guilabel> column.
                Pooled samples can be created by first selecting the parents
                from the list of samples and then click the <guibutton>Pool&hellip;</guibutton>
                button in the toolbar.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
    </sect2>
      
    <sect2 id="biomaterial.samples.properties">
      <title>Sample properties</title>
        <figure id="biomaterials.figures.biosample-tab-1">
          <title>Sample properties</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/biosample-tab-1.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        <helptext external_id="sample.edit" title="Edit sample">
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>
                  The sample's name (required). BASE by default assigns names to
                  samples (by suffixing
                  <replaceable>s#</replaceable>
                  when creating a sample from an existing biosource or
                  <replaceable>New Sample</replaceable>
                  otherwise) but it is possible to edit at will.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Type</guilabel>
              </term>
              <listitem>
                <para>
                The subtype of the sample. The list
                may evolve depending on additions by the server
                administrator. Selecting the proper subtype
                is recommended and enables BASE to automatically guess 
                the most likely subtype when creating child biomaterial.
                <nohelp>
                See <xref linkend="subtypes" /> for more information.
                </nohelp>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>External ID</guilabel>
              </term>
              <listitem>
                <para>
                  An identification used to identify the sample outside BASE.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Original quantity</guilabel>
              </term>
              <listitem>
                <para>
                  This is meant to report information about the actual mass of
                  sample created.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Created</guilabel>
              </term>
              <listitem>
                <para>
                  A date when the sample was created. The information can be
                  important when running quality controls on data and account for
                  potential confounding factor (e.g. day effect).
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Registered</guilabel>
              </term>
              <listitem>
                <para>The date at which the sample was entered in BASE.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Protocol</guilabel>
              </term>
              <listitem>
                <para>The protocol used to produce this sample.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Bioplate</guilabel>
              </term>
              <listitem>
                <para>The bioplate where this sample is located.</para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Biowell</guilabel>
              </term>
              <listitem>
                <para>
                  Biowell that holds this sample.
                  <guilabel>Bioplate</guilabel> has to be defined before
                  biowell can be selected.
                </para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Description</guilabel>
              </term>
              <listitem>
                <para>
                  A text field to report any information that not can be captured
                  otherwise.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          
          <seeother>
            <other external_id="sample.parents">Parents</other>
            <other external_id="annotations.edit">Annotations &amp; parameters</other>
            <other external_id="annotations.edit.inherited">Inherited annotations</other>
          </seeother>
        </helptext>
    </sect2>
    
    <sect2 id="biomaterial.samples.parents">
      <title>Sample parents</title>
        <figure id="biomaterials.figures.biosample-tab-2">
          <title>Sample parents</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/biosample-tab-2.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="sample.parents" title="Sample's parents">
          <para>
            This is meant to keep track of the sample origin. BASE
            distinguishes between two cases which are controlled by the
            <guilabel>Parent type</guilabel>
            radio-button in the edit pop-up window.
          </para>
          <itemizedlist>
            <listitem>
              <para>
                If the parent is a biosource the radio-button is set to
                <guilabel>Biosource</guilabel>. Only a single biosource
                can be used as the parent. This option is automatically
                selected if the user selects a biosource with the 
                <guibutton>Select biosource</guibutton> button.
              </para>
            </listitem>
            <listitem>
              <para>
                When the parent is one or several other samples the radio-button is
                set to <guilabel>Sample</guilabel>. This option is automatically
                selected if the user add samples with the <guibutton>Add samples</guibutton> button.            
                For each parent sample, it is
                possible to specify the amount used in µg. This will automatically
                update the <guilabel>remaining quantity</guilabel> of the parent.
              </para>
            </listitem>
          </itemizedlist>
          
          <seeother>
            <other external_id="sample.edit">Sample properties</other>
            <other external_id="annotations.edit">Annotations &amp; parameters</other>
            <other external_id="annotations.edit.inherited">Inherited annotations</other>
          </seeother>
        </helptext>
    </sect2>
    <para>
      The <guilabel>Annotations</guilabel> tab allows BASE users to use 
      annotation types to refine sample description. More about annotating items 
      can be read in <xref linkend="annotations.annotating" />
    </para>
        
    <para>
      This <guilabel>Inherited annotations</guilabel> tab contains a list of those annotations
      that are inherited from the sample's parents. Information about working with inherited 
      annotations can be found in <xref linkend="annotations.inheriting" />.
    </para>
  </sect1>

  <sect1 id="biomaterials.extracts">
    <title>Extracts</title>
    <para>
      Extract items should be used to describe the events that transform a sample material
      into an extract material. An extract can be created from one sample item or from one or
      more extract items. When an extract is created from several other extracts, a pooling
      event is performed.
    </para>
    <para>
      During the transformation from samples to extracts, it is possible to provide
      information about the protocol used to perform this task. It is not enforced in BASE
      but it should serve as guidance when devising the granularity of the sample processing
      task. Also, it is good practice to provide protocol information.
    </para>
    <para>
      Use
      <menuchoice>
        <guimenu>Biomaterial LIMS</guimenu>
        <guimenuitem>Extracts</guimenuitem>
      </menuchoice>
      to get to the list of extracts.
    </para>
    <sect2 id="biomaterials.extracts.create">
      <title>Create extract</title>
      <para>
        Beside the common way, using the &gbNew; button, an extract can be created in one of
        the following ways:
        <variablelist>
          <varlistentry>
            <term>from either sample list- or single view- page.</term>
            <listitem>
              <para>
                No matter how complex the extract processing phase is, at least one
                extract has to be anchored to a sample. Therefore, a natural way to
                create an extract is to click on
                <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/add.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon>
                in the <guilabel>Child extracts</guilabel> column for the sample that should be a parent of the
                extract.  There is also a corresponding button,
                <guibutton>New child extract&hellip;</guibutton>
                in the toolbar when viewing a single sample.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>from the extract list page</term>
            <listitem>
              <para>
                Child extracts can be created from a single parent by clicking on the 
                <guiicon>
                  <inlinemediaobject>
                    <imageobject>
                      <imagedata fileref="figures/add.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
                </guiicon> icon in the <guilabel>Child extracts</guilabel> column.
                Pooled extract can be created by first selecting the parents
                from the list of extracts and then press
                <guibutton>Pool&hellip;</guibutton>
                in the toolbar. The selected extracts will be put into the parent
                property.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>
    <sect2 id="biomaterials.extracts.properties">
      <title>Extract properties</title>
      
        <figure id="biomaterials.figures.extract-tab-1">
          <title>Extract properties</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/extract-tab-1.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        <helptext external_id="extract.edit" title="Edit extract">
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>
                  A mandatory field for providing the extract name. BASE by
                  default assigns names to extract (by suffixing
                  <replaceable>e#</replaceable>
                  when creating an extract from an existing sample or
                  <replaceable>New extract</replaceable>
                  otherwise) but it is possible to edit it at will.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Type</guilabel>
              </term>
              <listitem>
                <para>
                The subtype of the extract. The list
                may evolve depending on additions by the server
                administrator. Selecting the proper subtype
                is recommended and enables BASE to automatically guess 
                the most likely subtype when creating child biomaterial and
                bioassays.
                <nohelp>
                See <xref linkend="subtypes" /> for more information.
                </nohelp>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Tag</guilabel>
              </term>
              <listitem>
                <para>
                  If the extract has been marked with a tag, select it here. Note
                  that the subtype of the extract usually limits what kind of tag
                  that can be used. For example, a <emphasis>labeled extract</emphasis>
                  should be tagged with a <emphasis>label</emphasis>.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>External ID</guilabel>
              </term>
              <listitem>
                <para>The extracts identification outside BASE</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Original quantity</guilabel>
              </term>
              <listitem>
                <para>
                  Holds information about the original mass of the created
                  extract.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Created</guilabel>
              </term>
              <listitem>
                <para>
                  The date when the extract was created. The information can be
                  important when running quality controls on data and account for
                  potential confounding factor (e.g. day effect)
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Registered</guilabel>
              </term>
              <listitem>
                <para>
                  This is automatically populated with a date at which the sample
                  was entered in BASE system.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Protocol</guilabel>
              </term>
              <listitem>
                <para>
                  The extraction protocol that was used to produce the extract.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Bioplate</guilabel>
              </term>
              <listitem>
                <para>The bioplate where this extract is located.</para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Biowell</guilabel>
              </term>
              <listitem>
                <para>
                  Biowell that holds this extract.
                  <guilabel>Bioplate</guilabel> has to be defined before
                  biowell can be selected.
                </para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Description</guilabel>
              </term>
              <listitem>
                <para>
                  A text field to report any information that not can be captured
                  otherwise.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <seeother>
            <other external_id="extract.edit.parents">Parents</other>
            <other external_id="annotations.edit">Annotations &amp; parameters</other>
            <other external_id="annotations.edit.inherited">Inherited annotations</other>
          </seeother>
        </helptext>
  </sect2>
  
  <sect2 id="biomaterials.extracts.parents">
    <title>Extract parents</title>
        <figure id="biomaterials.figures.extract-tab-2">
          <title>Extract parents</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/extract-tab-2.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        <helptext external_id="extract.parents" title="Extract's parents">
          <para>
            This is meant to keep track of the extract origin. BASE
            distinguishes between two cases which are controlled by the
            <guilabel>Parent type</guilabel>
            radio-button in the edit pop-up window.
          </para>
          <itemizedlist>
            <listitem>
              <para>
                If the parent is a sample the radio-button is set to
                <guilabel>Sample</guilabel>. Only a single sample
                can be used as the parent. This option is automatically
                selected if the user selects a sample with the 
                <guibutton>Select sample</guibutton> button.
              </para>
            </listitem>
            <listitem>
              <para>
                When the parent is one or several other extracts the radio-button is
                set to <guilabel>Extract</guilabel>. This option is automatically
                selected if the user add extracts with the <guibutton>Add extracts</guibutton> button.            
              </para>
            </listitem>
          </itemizedlist>
          
          <para>
            For each parent item, it is
            possible to specify the amount used in micrograms. This will automatically
            update the <guilabel>remaining quantity</guilabel> of the parent.
          </para>
          
          <seeother>
            <other external_id="extract.edit">Extract properties</other>
            <other external_id="annotations.edit">Annotations &amp; parameters</other>
            <other external_id="annotations.edit.inherited">Inherited annotations</other>
          </seeother>
        </helptext>

    <para>
      The <guilabel>Annotations</guilabel> tab allows BASE users to use 
      annotation types to refine extract description. More about annotating items 
      can be read in <xref linkend="annotations.annotating" />
    </para>
        
    <para>
      This <guilabel>Inherited annotations</guilabel> tab contains a list of those annotations
      that are inherited from the extract's parents. Information about working with inherited 
      annotations can be found in <xref linkend="annotations.inheriting" />.
    </para>


  </sect2>


  </sect1>

  <sect1 id="biomaterials.tags">
    <title>Tags</title>
    <para>
      Before attempting to create tagged extracts, users should make sure that the
      appropriate tag object is present in BASE. To browse the list of tags, go to
      <menuchoice>
        <guimenu>Biomaterial LIMS</guimenu>
        <guimenuitem>Tags</guimenuitem>
      </menuchoice>
    </para>

    <figure id="biomaterials.figures.tags">
      <title>Tag properties</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata 
              fileref="figures/edit_tag.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <helptext external_id="tag.edit" title="Edit tag">
      <para>
        The tag item is very simple and does not need much explanation. There are only
        a few properties for a tag.
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>The name of the tag (required).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Type</guilabel>
            </term>
            <listitem>
              <para>
              The subtype of the tag. The list
              may evolve depending on additions by the server
              administrator. Selecting the proper subtype
              is important and enables BASE to automatically guess 
              the most likely tag when creating tagged extracts (eg.
              a <emphasis>Label</emphasis> for a <emphasis>Labeled extract</emphasis> 
              or a <emphasis>Barcode</emphasis> for a <emphasis>Library</emphasis>).
              <nohelp>
              See <xref linkend="subtypes" /> for more information.
              </nohelp>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>
                An explaining text or other information associated with the
                tag.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </helptext>

  </sect1>

  
  <sect1 id="biomaterials.bioplates">
    <title>Bioplates</title>
    <para>
      With bioplates it is possible to organize biomaterial such as samples and extracts
      into wells. Each plate has a number of wells that is defined by the plate geometry. 
    </para>
    <para>
      Use
      <menuchoice>
        <guimenu>Biomaterial LIMS</guimenu>
        <guimenuitem>Bioplates</guimenuitem>
      </menuchoice>
      to get to the list of bioplates.    
    </para>
    <sect2 id="biomaterials.bioplate.properties">
      <title>Bioplate properties</title>      

      <figure id="biomaterials.figures.bioplate-tab-1">
        <title>Bioplate properties</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 
                fileref="figures/bioplate-tab-1.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>

      <helptext external_id="bioplate.edit" title="Edit bioplate">
        <para>
          <variablelist>
            <varlistentry>
              <term><guilabel>Name</guilabel></term>
              <listitem>
                <para>
                  The bioplate name. The name does not have to be unique but it is
                  recommended to keep it unique. BASE by default assigns 
                  <replaceable>New bioplate</replaceable> as name. 
                  This field is mandatory. 
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><guilabel>Bioplate type</guilabel></term>
              <listitem>
                <para>
                  The type of the bioplate may be a generic storage plate that
                  can store any type of biomaterial or a locked plate that
                  can only store a single type of biomaterial. This field
                  is mandatory and can only be set for new bioplates.
                  <nohelp>See <xref linkend="biomaterials.bioplatetypes" /> for more
                  information.</nohelp>
                </para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term><guilabel>Plate geometry</guilabel></term>
              <listitem>
                <para>
                  Information about the plate design defining the
                  number of  rows and columns on the bioplate. 
                  This field is mandatory and can only be set for new bioplates.
                </para>
              </listitem>             
            </varlistentry>
            <varlistentry>
              <term><guilabel>Freezer</guilabel></term>
              <listitem>
                <para>The freezer where the bioplate is stored. Optional.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><guilabel>Barcode</guilabel></term>
              <listitem>
                <para>
                  Barcode of the bioplate.
                  Optional.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><guilabel>Description</guilabel></term>
              <listitem>
                <para>
                  Other useful information about the bioplate. Optional.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>
        
        <seeother>
          <other external_id="annotations.edit">Annotations</other>
        </seeother>
      </helptext>
      
    <para>
      The <guilabel>Annotations</guilabel> tab allows BASE users to use 
      annotation types to refine bioplate description. More about annotating items 
      can be read in <xref linkend="annotations.annotating" />
    </para>

    </sect2>
    <sect2 id="biomaterials.bioplate.biowells">
      <title>Biowells</title>
      <para>
        Biowells existence are managed through the bioplate they
        belong to. Creating a bioplate will automatically create the
        biowells (as given by the selected geometry) on the plate. 
        The wells are initially empty. To add biomaterial to the plate
        go to the single-item view page for the bioplate. This page
        includes an overview of the layout of the plate. Clicking
        on an empty well will open a popup dialog that allows you
        to select a biomaterial. The same dialog can also be accessed from
        the <guilabel>Wells</guilabel> tab. Assigning a biomaterial to a 
        biowell can also be done when editing a sample or extract.
      </para>
      
      <figure id="biomaterials.figures.biowell">
        <title>Biowell properties</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 
                fileref="figures/biowell.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>

        <helptext external_id="biowell.edit" title="Edit biowell">
          <para>
            <variablelist>
              <varlistentry>
                <term><guilabel>Bioplate</guilabel></term>
                <listitem>
                  <para>
                    Shows which bioplate the biowell is located on. 
                    This property is read-only.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>              
                <term><guilabel>Well location</guilabel></term>
                <listitem>
                  <para>
                    The biowell location on the bioplate in row+column format. 
                    This property is read-only.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>Biomaterial type</guilabel></term>
                <listitem>
                  <para>
                    The type of biomaterial stored in this biowell. This 
                    property must be selected before before a 
                    biomaterial can be selected. On some plates this
                    is locked due to settings in the bioplate's type.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>              
                <term><guilabel>Biomaterial</guilabel></term>
                <listitem>
                  <para>
                    Name of the biomaterial in this biowell. Before changing
                    this you must select the appropriate <guilabel>Biomaterial type</guilabel>.
                    A biomaterial can only be placed in a single well. If the selected
                    biomaterial is already placed in another location it will be moved.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
        </helptext> 
    </sect2>
    
    <sect2 id="biomaterials.bioplatetypes">
      <title>Bioplate types</title>
      
      <helptext external_id="bioplatetype.view.properties" title="Bioplate types">
      <para>
        Bioplate types are used to subclassify bioplates and may put restrictions on them.
        BASE ships with a few pre-defined bioplate types. The <emphasis>Storage plate</emphasis> type
        is a generic plate type that can be used for all types of biomaterial and doesn't
        have any other restrictions on it. The reaction plate types are locked to a single
        type of biomaterial and have a restriction that biomaterial can never be moved out from
        a well once it has been placed there.
      </para>
      </helptext>
      
      <figure id="biomaterials.figures.bioplatetype">
        <title>Bioplate type properties</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 
                fileref="figures/edit_bioplatetype.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
          <helptext external_id="bioplatetype.edit" title="Edit bioplate type">
          <para>
            <variablelist>
              <varlistentry>
                <term><guilabel>Name</guilabel></term>
                <listitem>
                  <para>
                    The name of the bioplate type.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>              
                <term><guilabel>Biomaterial type</guilabel></term>
                <listitem>
                  <para>
                    Select if bioplates using this type should be locked to
                    specific biomaterial type or not. This property can only
                    be set for new bioplate types.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term><guilabel>Well lock mode</guilabel></term>
                <listitem>
                  <para>
                    This option controls the wells on bioplates using this type.
                    There are four options:
                    <itemizedlist>
                      <listitem>
                        <para><guilabel>Unlocked</guilabel>:
                          The wells are unlocked and biomaterial can be added
                          and removed freely any number of times.
                        </para>
                      </listitem>
                      <listitem>
                        <para><guilabel>Locked after add+clear</guilabel>:
                          A biomaterial can be placed once in the well and
                          then moved to another bioplate. After that the well
                          becomes locked and it is not possible to add a
                          different biomaterial to it.
                        </para>
                      </listitem>
                      <listitem>
                        <para><guilabel>Locked after add</guilabel>:
                          The wells are locked as soon as biomaterial is
                          added to them. The biomaterial can't be moved to another
                          place or be replaced with other biomaterial.
                        </para>
                      </listitem>
                      <listitem>
                        <para><guilabel>Locked at plate creation</guilabel>:
                          The wells are locked as soon as the bioplate has been
                          saved to the database. This lock mode is primarily intended
                          to be used when plug-ins are creating and populating the
                          bioplate as a single event.
                        </para>
                      </listitem>
                    </itemizedlist>
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>              
                <term><guilabel>Description</guilabel></term>
                <listitem>
                  <para>
                    Other useful information about the bioplate type. Optional.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
        </helptext> 
    </sect2>
    
    <sect2 id="biomaterials.bioplateevents">
      <title>Bioplate events</title>
    
      <para>
        TODO
      </para>
    
    </sect2>
    
  </sect1>
  
  <sect1 id="biomaterials.lists">
    <title>Biomaterial lists</title>
    
    <para>
      TODO
    </para>
  
  </sect1>

  <sect1 id="biomaterials.bioassays">
    <title>Physical bioassays</title>
    <para>
      A physical bioassay represents the application of one or more extracts
      to an experimental setup designed to measure quantities that we are 
      interested in. For example, a <emphasis>Hybridization</emphasis> event corresponds 
      to the application of one or more <emphasis>Labeled extracts</emphasis>
      materials to a microarray slide under conditions detailed in hybridization protocols.
      Use
      <menuchoice>
        <guimenu>View</guimenu>
        <guimenuitem>Physical bioassays</guimenuitem>
      </menuchoice>
      to get to the bioassays.
    </para>
    
    <sect2 id="biomaterials.bioassays.create">
      <title>Create physical bioassays</title>
      <para>
        In BASE, there are two possible routes to create a physical bioassay except the
        common way with the &gbNew; button at the list page.
      </para>
      <variablelist>
        <varlistentry>
          <term>from the extract list view page</term>
          <listitem>
            <para>
              Select at least one extract, to create a bioassay from, by
              ticking the selection boxes before the name field.
              Click on the <guibutton>New physical bioassay&hellip;</guibutton>
              in the toolbar.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>from the extract single-item page</term>
          <listitem>
            <para>
              When viewing an extract in single-item view, click on the
              <guibutton>New physical bioassay&hellip;</guibutton>
              button in the toolbar.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    
    <sect2 id="biomaterials.bioassays.properties">
      <title>Bioassay properties</title>

  
        <figure id="biomaterials.figures.bioassays-tab-1">
          <title>Physical bioassay properties</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/physicalbioassay-tab-1.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure> 
        
        <helptext external_id="physicalbioassay.edit" title="Edit physical bioassay">
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>
                The bioassay's name (required). It is recommended that the default
                name is replaced with something that is unique.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Type</guilabel>
            </term>
            <listitem>
              <para>
              The subtype of the bioassay. The list
              may evolve depending on additions by the server
              administrator. Selecting the proper subtype
              is recommended and enables BASE to automatically guess 
              the most likely subtype when assignint source biomaterials
              and when creating derived bioassays.
              <nohelp>
              See <xref linkend="subtypes" /> for more information.
              </nohelp>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Size</guilabel>
            </term>
            <listitem>
              <para>
                The size of the bioassay is the number of independent
                positions on the bioassay. Depending on the 
                characteristics of the bioassay, multiple biomaterials
                may share the same position, but are then usually
                required to have different tags. Two biomaterials 
                in different positions can use the same tag.
                The default value is 1, but some platforms, for example
                Illumina BeadArrays, has slides with 6 or 8 positions. 
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Created</guilabel>
            </term>
            <listitem>
              <para>
                A date should be provided. The information can be important when
                running quality controls on data and account for potential
                confounding factor (e.g. to account for a day effect).
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Registered</guilabel>
            </term>
            <listitem>
              <para>
                This field is automatically populated with a date at which the
                hybridization was entered in BASE system.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Protocol</guilabel>
            </term>
            <listitem>
              <para>
                The protocol that was used to create the bioassay.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Hardware</guilabel>
            </term>
            <listitem>
              <para>
                Information about the machine (if any) that was used when creating
                the bioassay.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Array slide</guilabel>
            </term>
            <listitem>
              <para>The array slide that was used for the bioassay.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>
                A free text field to report any information that can not be captured
                otherwise.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <seeother>
          <other external_id="physicalbioassay.extracts">Extracts</other>
          <other external_id="annotations.edit">Annotations &amp; parameters</other>
          <other external_id="annotations.edit.inherited">Inherited annotations</other>
        </seeother>
        </helptext>
      </sect2>
      
      <sect2 id="biomaterials.bioassays.extracts">
        <title>Parent extracts</title>
        
        <figure id="biomaterials.figures.bioassay-tab-2">
          <title>Parent extracts</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata 
                  fileref="figures/physicalbioassay-tab-2.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="physicalbioassay.extracts" title="Extracts">
        <para>
          This important tab allows users to select the extracts used by the
          bioassay, and specify the amount of material used, expressed in microgram.
        </para>
        <para>
          Use the <guibutton>Add extracts</guibutton> button to add
          items and the <guibutton>Remove</guibutton> button to remove items.
          Select one or several extracts in the list and write the used 
          mass and position number in the fields below the list.
        </para>
        
        <seeother>
          <other external_id="physicalbioassay.edit">Edit physical bioassay</other>
          <other external_id="annotations.edit">Annotations &amp; parameters</other>
          <other external_id="annotations.edit.inherited">Inherited annotations</other>
        </seeother>
        </helptext>
        
      </sect2>
      
      
    <para>
      The <guilabel>Annotations</guilabel> tab allows BASE users to use 
      annotation types to refine bioassay description. More about annotating items 
      can be read in <xref linkend="annotations.annotating" />
    </para>
        
    <para>
      This <guilabel>Inherited annotations</guilabel> tab contains a list of those annotations
      that are inherited from the bioassay's parents. Information about working with inherited 
      annotations can be found in <xref linkend="annotations.inheriting" />.
    </para>
      
  </sect1>
</chapter>