source: trunk/doc/src/docbook/userdoc/annotations.xml @ 5706

<?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: annotations.xml 5706 2011-08-23 13:20:30Z nicklas $
  
  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Philippe Rocca-Serra, 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="annotations">
  <?dbhtml dir="annotations"?>
  <title>Annotations</title>
  
  <sect1 id="annotations.types">
    <title>Annotation Types</title>

    <helptext external_id="annotationtype.view.properties" 
      title="Annotation types">
    <para>
      BASE has been engineered to closely map the
      <ulink
        url="http://www.mged.org/Workgroups/MIAME/miame.html">
        MIAME concepts</ulink>. 
      However, since MIAME is focused on microarray processing
      workflow, information about the description biological
      samples themselves was left out. BASE users are free to
      annotate biomaterials (and most BASE items) as they wish,
      from basic free text description to more advanced ontology
      based terms. To accommodate the annotation needs of users
      eager with detailed sample annotations and also the needs of
      very different communities, BASE provides a mechanism that
      allows a high level of annotation customization. BASE
      allows to create descriptive elements for both quantitative
      annotation and qualitative annotation of Biomaterials via
      the <emphasis>Annotation Type mechanism</emphasis>.
      Actually, annotation types can be used to annotate not
      only <emphasis>Biomaterials</emphasis> but almost all BASE items, from
      <emphasis>Plates</emphasis>
      to
      <emphasis>Protocols</emphasis>
      and
      <emphasis>Bioassay sets</emphasis>
    </para>

    <nohelp>
    <para>
      Go to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Types</guimenuitem>
        <guisubmenu>Annotation types</guisubmenu>
      </menuchoice>
      to manage your annotation types.
    </para>
    </nohelp>

    <para>
      To create a new annotation type, click on the 
      &gbNew; button. This behaves differently
      than other buttons found elsewhere and you must select
      one of the 9 different types which can be split in 4 main groups.
    </para>

    <itemizedlist>
    <listitem>
      <para>
        <guilabel>Integer</guilabel>,
        <guilabel>Long</guilabel>,
        <guilabel>Float</guilabel> and
        <guilabel>Double</guilabel>
        for numerical annotation types.
      </para>
    </listitem>

    <listitem>
      <para>
        <guilabel>String</guilabel> and
        <guilabel>Text</guilabel> for textual annotation types.
        The difference is that <guilabel>String</guilabel>:s can
        have a maximum length of 255 characters and can have an attached
        list of predefined value. <guilabel>Text</guilabel>
        annotation types have no practical limit and are always 
        free-text.
      </para>
    </listitem>

    <listitem>
      <para>
        <guilabel>Boolean</guilabel>
        for declaring annotation types that can take one
        <constant>TRUE</constant>/<constant>FALSE</constant>
        values.
      </para>
    </listitem>

    <listitem>
      <para>
        <guilabel>Date</guilabel> and <guilabel>Timestamp</guilabel>
        for declaring annotation types used as
        calendar/time stamps.
      </para>
    </listitem>
    </itemizedlist>

    <note>
      <para>
        These distinctions matter essentially to database
        administrators who need fine tuning of database
        settings. Therefore, creation of annotation type
        should be supervised by system administrators.
      </para>
    </note>
    
      <seeother>
        <other external_id="annotationtype.edit">Edit annotation type</other>
      </seeother>
    </helptext>
  
    <para>
      The <guilabel>Edit annotation type</guilabel> window is opened in a
      pop-up. It contains four different tabs.
    </para>
  
    <sect2 id="annotations.types.properties">
      <title>Properties</title>
      
      <figure
        id="annotations.figures.annotationtype.properties">
        <title>Annotation type properties</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata
                fileref="figures/edit_annotationtype.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <helptext external_id="annotationtype.edit" 
        title="Edit annotation type">
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Name</guilabel></term>
          <listitem>
            <para>
            The name of the annotation type.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>External ID</guilabel></term>
          <listitem>
            <para>
            An ID identifying this annotation type in an external
            database. This value can be used by tools that
            need to update annotation types in BASE from external
            sources. The value does not have to be unique.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Multiplicity</guilabel></term>
          <listitem>
            <para>
              The maximum number of values that can be entered 
              for this annotation type. The default is 1. A value
              of 0, means that any number of values can be used.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Default value</guilabel></term>
          <listitem>
            <para>
              A value that can be used as the default when
              adding values. 
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Required for MIAME</guilabel></term>
          <listitem>
            <para>
              If a value must be specified for this annotation type
              in order for the experiment to be compliant with MIAME.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Protocol parameter</guilabel></term>
          <listitem>
            <para>
              If the annotation type is a protocol parameter. As a protocol
              parameter an item can only be annotated if a protocol
              that includes this parameter has been used.
              <nohelp>See <xref linkend="protocols.parameters" /> 
              for more information.</nohelp>
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Description</guilabel></term>
          <listitem>
            <para>
              A short textual description of the
              to clarify the usage.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <seeother>
          <other external_id="annotationtype.edit.options">Options</other>
          <other external_id="annotationtype.edit.items">Item types</other>
          <other external_id="annotationtype.edit.units">Units</other>
          <other external_id="annotationtype.edit.categories">Categories</other>
          <other external_id="protocol.edit.parameters">Protocol parameters</other>
        </seeother>
      </helptext>
    
    </sect2>

    <sect2 id="annotations.types.options">
      <title>Options</title>

      <figure
        id="annotations.figures.annotationtype.options">
        <title>Annotation type options</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata
                fileref="figures/annotationtype_options.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <helptext external_id="annotationtype.edit.options" 
        title="Annotation type options">
        
        <para>
          The available options in this tab depends on the type
          of annotation type, eg. if is a string, numeric or 
          another type.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Interface</guilabel></term>
          <listitem>
            <para>
            Select the type of graphical element to use for
            entering values for the annotation type. You can select
            between three different options:
            <itemizedlist>
            <listitem>
              <para>
              <guilabel>text box</guilabel>: The user must enter the value
              in a free-text box.
              </para>
            </listitem>
            <listitem>
              <para>
              <guilabel>selection list</guilabel>: The user must select
              values from a list of predefined values.
              </para>
            </listitem>
            <listitem>
              <para>
              <guilabel>radiobuttons/checkboxes</guilabel>: The user must 
              select values by marking checkboxes or radiobuttons.
              </para>
            </listitem>
            </itemizedlist>
            
            The last two options requires that a list of values are
            available. Enter possible values in the <guilabel>Values</guilabel>
            which will be activated automatically.
            </para>
            <tip>
              <para>
                In term of usability, a drop-down
                list can be more easily
                navigated especially when the
                number of possible values is
                large, and because selection-list
                and drop-down list allow use of
                arrow and tab for selection.
              </para>
            </tip>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Min/max value</guilabel></term>
          <listitem>
            <para>
              Available for numerical annotation types only.
              Specifies the minimum and maximum allowed value.
              If left empty, the bound(s) are undefined and any
              value is allowed.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Max length</guilabel></term>
          <listitem>
            <para>
              The maximum allowed length of a string annotation value.
              If empty, 255 is the maximum length. If you need longer
              values than that, use a <emphasis>text</emphasis> 
              annotation type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Input box width/height</guilabel></term>
          <listitem>
            <para>
              A suggested display width and height of the element
              used for input. These values are ignored in the current
              implementation.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Values</guilabel></term>
          <listitem>
            <para>
              A list of predefined values that the user is allowed
              to select from. This option is only activated if the
              <guilabel>Interface</guilabel> option is set
              to <guilabel>selection list</guilabel> or 
              <guilabel>radiobuttons/checkboxes</guilabel>.
              Actual values can be supplied using one line for each
              value (a return entry is used as separator).
            </para>
          </listitem>
        </varlistentry>

        </variablelist>
        
        <seeother>
          <other external_id="annotationtype.edit">Properties</other>
          <other external_id="annotationtype.edit.items">Item types</other>
          <other external_id="annotationtype.edit.units">Units</other>
          <other external_id="annotationtype.edit.categories">Categories</other>
        </seeother>
      </helptext>
    </sect2>
    
    <sect2 id="annotations.types.items">
      <title>Item types</title>
      
      <figure
        id="annotations.figures.annotationtype.items">
        <title>Annotation type items</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata
                fileref="figures/annotationtype_items.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    
      <helptext external_id="annotationtype.edit.items" 
        title="Item types">
        
        <para>
          On this tab you select the item types that you wish to
          annotate with the annotation type. Simply use
          left and right buttons to move selection options
          between the <guilabel>Enabled for</guilabel>
          and <guilabel>Disabled for</guilabel> lists.
        </para>
        
        <note>
          <para>
          If the annotation type has been marked as a 
          <guilabel>Protocol</guilabel> parameter, these settings are
          ignored, with one exception. If you wish to view parameter
          values in the list view for a specific item type you must select 
          the item type here. Otherwise the parameter will not be present 
          as a displayable column.
          </para>
        </note>
        
        <seeother>
          <other external_id="annotationtype.edit">Properties</other>
          <other external_id="annotationtype.edit.options">Options</other>
          <other external_id="annotationtype.edit.units">Units</other>
          <other external_id="annotationtype.edit.categories">Categories</other>
        </seeother>
      </helptext>
    </sect2>
  
    <sect2 id="annotations.types.units">
      <title>Units</title>
        
      <figure
        id="annotations.figures.annotationtype.units">
        <title>Annotation type units</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata
                fileref="figures/annotationtype_units.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
  
      <helptext external_id="annotationtype.edit.units" 
        title="Units">
  
        <para>
        Numerical annotation types can optionally be given a quantity and unit.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Quantity</guilabel></term>
          <listitem>
            <para>
            Select which quantity to use for the annotation type. If you
            don't want to use units, select the <emphasis>do not use units</emphasis>
            option.
            </para>
            <note>
              <title>The quantity can't be changed later</title>
              <para>
              Once a quantity has been selected and saved for an
              annotation type, it is not possible to change it to another 
              quantity.
              </para>
            </note>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Default unit</guilabel></term>
          <listitem>
            <para>
            This list will be populated with units from the selected
            quantity. You must select one default unit which is the unit
            that is used if a user leaves out the unit when annotating
            an item. The selected unit is also the unit that is used internally
            when storing the values in the database.
            </para>
            <warning>
              <title>Do not change the default unit</title>
              <para>
                If you change the default unit for an existing annotation type,
                all annotation values that exists for it, must be converted to the
                new unit. This may result in loss of precision due to rounding/truncation 
                errors. 
              </para>
            </warning>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Use units</guilabel></term>
          <listitem>
            <para>
            By default, all units of the selected quantity can be used when
            annotating items. If you want, you may force the users to use 
            some specific units by moving units into the <emphasis>Use units</emphasis>
            list. This is recommended since the range of available units is usually
            quite large. For example, if the weight of something is normally
            measured in milligrams, it may make sense to leave out kilograms, and
            only use microgram, milligram and gram.
            </para>
          </listitem>
        </varlistentry>
        
        </variablelist>
        
        <seeother>
          <other external_id="annotationtype.edit">Properties</other>
          <other external_id="annotationtype.edit.options">Options</other>
          <other external_id="annotationtype.edit.items">Item types</other>
          <other external_id="annotationtype.edit.categories">Categories</other>
        </seeother>
        
      </helptext>
    </sect2>
  
    <sect2 id="annotations.types.categories">
      <title>Categories</title>
    
      <helptext external_id="annotationtype.edit.categories" 
        title="Categories">
        
        <para>
          Annotation type can be grouped together by
          placing them in one or more categories. This
          enhances display by avoid overcrowding the list
          of annotation types presented to users. It also
          allows to improve the display of information.
        </para>
        
        <para>
          The <guilabel>Categories</guilabel> list displays
          the currently associated categories. Use the 
          <guibutton>Add categories</guibutton> button
          to add more categories, or the <guilabel>Remove</guilabel>
          button to remove the selected categories.
        </para>
          
        <seeother>
          <other external_id="annotationtype.edit">Properties</other>
          <other external_id="annotationtype.edit.options">Options</other>
          <other external_id="annotationtype.edit.items">Item types</other>
        </seeother>
      </helptext>
    </sect2>
  </sect1>
  
  <sect1 id="annotations.categories">
    <title>Annotation type categories</title>
    
    <para>
      <guilabel>Annotation Type Categories</guilabel>
      allow grouping of related Annotation Types, based on
      users requirements.
    </para>
    
    <para>
      For managing categories go to 
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Types</guimenuitem>
          <guisubmenu>Annotation Type categories</guisubmenu>
        </menuchoice>.
    </para>

    <example id="annotation_types.example.atcategory">
      <title>Annotation category examples</title>
      
      <para>
        <itemizedlist>
        <listitem>
          <para>
          A category <userinput>Hematology Descriptors</userinput>
          could be created to group together annotation types such as
          <userinput>Lymphocyte count</userinput> and 
          <userinput>Hematocrite</userinput>
          </para>
        </listitem>
        
        <listitem>
          <para>
          A category <userinput>Plasma Clinical Descriptors</userinput>
          could be created to group together annotation types such as
          <userinput>ALT activity (UI/mL)</userinput> and 
          <userinput>LDH activity (UI/mL)</userinput>
          </para>
        </listitem>
        </itemizedlist>
      </para>
    </example>
    
    <tip>
      <para>
      If you use the same name for a category as for an item subtype (see <xref linkend="subtypes" />)
      the annotations in this category will be selected by default when editing an item item
      by that subtype. This can be useful when you have two or more subtypes of the same
      main item type and a different set of annotations that should be used on each subtype.
      For example, <emphasis>Labeled extract</emphasis> and <emphasis>Library</emphasis>
      are subtypes of <emphasis>Extract</emphasis>, which probably have different annotation
      types.
      </para>
    </tip>
    
  </sect1>

  <sect1 id="annotations.annotating">
    <title>Annotating items</title>
    
    <para>
      Entering annotation values follow the same pattern
      for all items that can have annotations. They all have 
      a <guilabel>Annotations &amp; parameters</guilabel> tab
      in their edit view. On this tab you can specify values
      for all annotation types assigned to the type of item,
      and all parameters that are attached to the protocol
      used to create the item. Some items, for example 
      <emphasis>biosources</emphasis> and <emphasis>array designs</emphasis> 
      cannot have a protocol. In their case the tab is labelled
      <guilabel>Annotations</guilabel>.
    </para>
    
    <figure
      id="annotations.figures.annotate">
      <title>Annotating a sample</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata
              fileref="figures/annotate.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <helptext external_id="annotations.edit" 
      title="Annotations &amp; parameters">

      <para>
        Click on an entry in the list of annotation types to show a
        form for entering a value for it to the right. Depending
        on the options set on the annotation type the form may be a simple 
        free text field, a list of checkboxes or radiobuttons, or 
        something else.
      </para>
      
      <para>
        Annotation types with an <guilabel>X</guilabel> in front
        of their names already have a value.
      </para>
      
      <para>
        Annotation types marked with angle brackets
        <nohelp>
          (<guiicon>
            <inlinemediaobject>
              <imageobject><imagedata fileref="figures/parameter.gif" format="GIF"
              /></imageobject>
            </inlinemediaobject>
          </guiicon>)
        </nohelp>
        are protocol parameters.
      </para>
      
      <para>
        Select an option in the <guilabel>Categories</guilabel> list to filter the
        annotation types based on the categories
        they belong to. This list contains all available
        categories, and three special ones:
        <itemizedlist>
        <listitem>
          <para>
          <guilabel>all</guilabel>: Display all annotation types
          </para>
        </listitem>
        <listitem>
          <para>
          <guilabel>protocol parameters</guilabel>: Display only
          those annotation types that are parameters to the current 
          protocol.
          </para>
        </listitem>
        <listitem>
          <para>
          <guilabel>uncategorized</guilabel>: Display only annotation types
          that has not been put into a category.
          </para>
        </listitem>
        </itemizedlist>
      </para>
      
      <seeother>
        <other external_id="annotations.edit.inherited">Inherit annotations</other>
      </seeother>
      
    </helptext>
    
    <sect2 id="annotations.inheriting">
      <title>Inheriting annotations from other items</title>
      
      <helptext external_id="annotations.edit.inherited" 
        title="Inherit annotations">
        <para>
          An item may inherit annotations from any of it's parent items.
          E.g. an extract can inherit annotations from the sample or biosource
          it was created from. This is an important feature to make the
          experimental factors work. Annotations that should be used as 
          experimental factors must be inherited to the raw bioassay level.
          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more 
          information about experimental factors.</nohelp>
        </para>
        
        <nohelp>
        <figure
          id="annotations.figures.inherit">
          <title>Inheriting annotations from a parent item</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata
                  fileref="figures/inherit_annotations.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        </nohelp>
    
        <para>
          On this screen is a tree-like structure in two levels. The first level 
          lists all parent items which has at least one annotations. The second
          level lists the annotations and protocol parameters for the item.
          Selecting an item in the first level will inherit all annotations
          from that item, including those that you maybe add later. 
          Selecting an annotation or protocol parameter at the second level
          will inherit only the selected one.
        </para>
        
        <note>
          <itemizedlist>
          <listitem>
            <para>
            The inheritance is implemented by reference. This means that if
            you change the value of an annotation the new value is automatically
            picked up by those inheriting it.
            </para>
          </listitem>
          <listitem>
            <para>
            You cannot inherit annotations from an item which does not have 
            annotations.
            </para>
          </listitem>
          <listitem>
            <para>
            If you delete an annotation from a parent item, the inheritance will
            be lost, even if you later add a value again.
            </para>
          </listitem>
          </itemizedlist>
        </note>
        
        <warning>
          <para>
          If you rearrange links to parent items after you have 
          specified inheritance, it may happen that you are inheriting
          annotation from non-parent items. This will be flagged with a warning
          icon in the list, and must be fixed manually. The item overview
          tool is an excellent help for locating this kind of problems.
          <nohelp>See <xref linkend="webclient.itemoverview" />.</nohelp>
          </para>
        </warning>
    
        <seeother>
          <other external_id="annotations.edit">Annotations and parameters</other>
          <other external_id="experiment.edit.factors">Experimental factors</other>
          <other external_id="item.overview">Item overview tool</other>
        </seeother>
      
      </helptext>     
      
    </sect2>
    
    <sect2 id="annotations.massimport">
      <title>Mass annotation import plug-in</title>
      
      <para>
        BASE includes a plug-in for importing annotations to multiple items
        in one go. The plug-in read annotation values from a simple column-based
        text file. Usually, a tab is used as the delimiter between columns, but this
        is configurable.
        The first row should contain the column headers. One column should contain
        the name or the external ID of the item. The rest of the columns can each be
        mapped to an annotation type and contains the annotation values. If a column 
        header exactly match the name of an annotation type, the plug-in will automatically 
        create the mapping, otherwise you must do it manually. You don't have to map
        all columns if you don't want to.
      </para>
      
      <para>
        Each column can only contain a single annotation value for each row. 
        If you have annotation types that accept multiple values you can map
        two or more columns to the same annotation type, or you can add an
        extra row only giving the name and the extra annotation value.
        Here is a simple example of a valid file with comma as column separator:
      </para>
      
      <programlisting>
# 'Time' and 'Age' are integer types
# 'Subtype' is a string enumeration
# 'Comment' is a text type that accept multiple values
Name,Time (hours),Age (years),Subtype,Comment
Sample #1,0,0,alfa,Very good
Sample #2,24,0,beta,Not so bad
Sample #2,,,,Yet another comment
</programlisting>
      
      <para>
        The plug-in can be used with or without a configuration. The configuration
        keeps the regular expressions and other settings used to parse the file. If
        you often import annotations from the same file format, we recommend that
        you use a configuration. The mapping from file columns to annotation types 
        is not part of the configuration, it must be done each time the plug-in is used.
      </para>
      
      <para>
        The plug-in can be used from the list view of all annotatable items.
        Using the plug-in is a three-step wizard:
      </para>
      
      <orderedlist>
      <listitem>
        <para>
        Select a file to import from and the regular expressions and other
        settings used to parse the file. In this step you also select the column
        that contains the name or external ID the items. If a configuration is used
        all settings on this page, except the file to import from, already has values.
        </para>
      </listitem>
      
      <listitem>
        <para>
        The plug-in will start parsing the file until it finds the column headers.
        You are asked to select an annotation type for each column.
        </para>
      </listitem>
      
      <listitem>
        <para>
        Set error handling options and some other import options.
        </para>
      </listitem>
      
      </orderedlist>
      
    </sect2>
    
  </sect1>

</chapter>