source: branches/3.6-stable/doc/src/docbook/user/annotations.xml @ 6975

<?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 6975 2015-10-08 06:11:11Z 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" filename="index.html" ?>
  
  <title>Annotations</title>
  
  <sect1 id="annotations.types">
    <?dbhtml filename="types.html" ?>
    <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 several 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 and is not
            used by BASE.
            </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>Disable change log</guilabel></term>
          <listitem>
            <para>
              If this option is checked, change history logging does not include the
              actual old/new annotation values. Note that the log will still contain 
              an entry that the annotation was modified. It is recomended that this
              option is enabled for annotations containing sensitive data since
              access permissions to the change history are different.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Disable inheritance</guilabel></term>
          <listitem>
            <para>
              If this option is checked, annotations of this type are not allowed to be
              inherited to other items. <nohelp>See <xref linkend="annotations.inheriting" /> 
              for more information about inheritance.</nohelp> It is recomended that this
              option is enabled for annotations containing sensitive data since
              access permissions to inherited information may be different.
            </para>
            <warning>
              <title>Existing inherited annotations are removed</title>
              <para>
                Be careful when enabling this option for an annotation type
                if there are existing items that already inherit this annotation
                type from their parents. The existing inheritance is automatically
                dropped, and it will not be re-created if resetting this option
                again.
              </para>
            </warning>
            
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Description</guilabel></term>
          <listitem>
            <para>
              A short textual description 
              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 parameter</guilabel>, 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>
    
      <figure
        id="annotations.figures.annotationtype.categories">
        <title>Annotation type categories</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata
                fileref="figures/annotationtype_categories.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      
      <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>
        
        <tip>
          <title>Create categories with the same name as item subtypes</title>
          <para>
            If you, for example, have defined multiple subtypes of extracts
            (see <xref linkend="subtypes" />),
            it usually so that some annotation types are only intended for
            one subtype while some other annotation types are only intended
            for the other subtype. If you create categories with the same name
            as the item subtypes, BASE will automatically select the corresponding
            category when annotating an extract with a subtype. This makes the interface
            cleaner and easier to use since irrelevant annotation types are hidden.
            Note that it is possible for annotations to be part of more than one
            category so it is also possible to define annotation types that are
            intended for all types of extracts by including them in both categories.
          </para>
        </tip>
        
        <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.annotating">
    <?dbhtml filename="annotating.html" ?>
    <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>
        All possible annotation types are listed under the 
        <guilabel>Primary annotations</guilabel> section. Click
        on an entry in the list to display a form for entering
        a value for the annotation. 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.png" format="PNG"
              /></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.inherit">Inherit annotations</other>
      </seeother>
      
    </helptext>
    
    <sect2 id="annotations.inheriting">
      <title>Inheriting annotations from other items</title>
      
      <helptext external_id="annotations.inherit" 
        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 root raw bioassay level.
          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more 
          information about experimental factors.</nohelp> Click on the
          <guibutton>Inherit&hellip;</guibutton> button to open a dialog for inheriting
          annotations.
        </para>
        
        <para>
          Annotations can either be inherited by reference (the default) or as a cloned value. Inheriting
          by reference means that if you change the value of the source annotation the new value is automatically
          picked up by all items inheriting it. A cloned annotation is a copy
          of the original annotation and it is not automatically updated if the original
          annotation is modified.
        </para>
        
        <para>
          Inherited and cloned annotations are listed under the <guilabel>Inherited &amp; cloned</guilabel> 
          section. Inherited annotations are marked with <guiicon><inlinemediaobject><imageobject><imagedata 
            fileref="figures/inherited.png" format="PNG"
            /></imageobject></inlinemediaobject></guiicon> and are always a references back to the original
          value. Cloned annotations are marked with a double <guilabel>xx</guilabel>. Cloned annotations
          that are out-of-sync with their source annotations are marked with <guiicon><inlinemediaobject><imageobject><imagedata 
            fileref="figures/cloned-outofsync.png" format="PNG"
            /></imageobject></inlinemediaobject></guiicon>.
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Inherit...</guilabel>
            </term>
            <listitem>
              <para>Opens the <guilabel>Inherit annotations</guilabel> dialog (see below).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Delete</guilabel>
            </term>
            <listitem>
              <para>
                Will remove values from the checked primary annotations and delete
                links to inherited and cloned annotations.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Sync, Clone, Unclone</guilabel>
            </term>
            <listitem>
              <para>
                Convert between INHERITED and CLONED annotation and synchronizes
                cloned annotations with their source annotation in case the values
                have changed.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        
        <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>
          In this dialog there is a tree-like structure in two levels to the left.
          The first level 
          lists all parent items which has at least one annotation. 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. Selecting an annotation or protocol parameter at 
          the second level will inherit only the selected one.
        </para>
        
        <para>
          The filter field on the top of the dialog is a simple search filter to
          make it easier to find a specific annotation. In large projects, the
          parent tree may contain lots of items having hundreds of different
          annotations. Use the filter to find annotations containing the 
          same text. The search is case-insensitive and will match anywhere
          on the name of the annotation type, but not values. The filter only 
          affects what is displayed. Changes that have been made to hidden items 
          are still saved.
        </para>
        
        <para>
          Use the <guibutton>Inherit</guibutton> button to inherit the selected
          annotations by reference, and the <guibutton>Clone</guibutton> button
          to clone the values of the selected annotations.
        </para>
        
        <note>
          <itemizedlist>
          <listitem>
            <para>
            Already inherited or cloned annotations are not shown in the dialog.
            </para>
          </listitem>
          <listitem>
            <para>
            Annotations that are inherited by reference can easily be converted to
            cloned annotations. Select the annotation in the list and click on the
            <guilabel>clone</guilabel> link.
            <nohelp>
            <figure>
              <title>Convert to a cloned annotation</title>
              <screenshot>
                <mediaobject>
                  <imageobject>
                    <imagedata
                      fileref="figures/clone_annotation.png" format="PNG" />
                  </imageobject>
                </mediaobject>
              </screenshot>
            </figure>
            </nohelp>
            </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="annotations.batch_inherit">Batch inherit annotations</other>
          <other external_id="item.overview">Item overview tool</other>
        </seeother>
      
      </helptext>     
      
    </sect2>
    
    <sect2 id="annotations.batch-inherit">
      <title>Batch inherit annotations</title>
      
      <helptext external_id="annotations.batch_inherit" 
        title="Batch inherit annotations">
        <para>
          Manually inheriting annotations on a per-item basis will quickly become a time-consuming
          and boring task as the project gets larger. Typically, there is a given set of annotations
          that should be inherited from different levels in the parent chain. This is possible
          with the batch inherit feature. Open this dialog by selecting at least one item in the
          list-view and then use the <guibutton>Inherit annotations&hellip;</guibutton> button
          in the toolbar.
        </para>
        
        <nohelp>
        <figure
          id="annotations.figures.batch_inherit">
          <title>Batch inherit annotations</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata
                  fileref="figures/batch_inherit_annotations.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        </nohelp>
        
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Select annotation types</guilabel></term>
          <listitem>
            <para>
              Use this button to select one or more annotation types that you want to inherit.
              Once the selection has been made, the selected annotation types will be added to
              the table in the dialog as shown on the screen shot.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Action</guilabel></term>
          <listitem>
            <para>
              For each annotation type you can select if you want to
              <guilabel>inherit</guilabel> or <guilabel>clone</guilabel> new annotations, 
              <guilabel>remove</guilabel> existing inherited annotations or 
              <guilabel>resync</guilabel> existing cloned annotation. It is possible to use different
              actions for different annotation types.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Parent item type</guilabel></term>
          <listitem>
            <para>
              In this list you can select if you want to inherit from
              any type of parent or only from a specific type. This is
              useful if the same annotation is present on multiple parent
              levels. If the annotation type has been added to a category,
              BASE will automatically try to guess the parent type (=the 
              parent type that has the same name as the category). This
              option is disabled when removing annotations.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Options</guilabel></term>
          <listitem>
            <para>
              You may specify if existing inherited annotations should be
              replaced and if duplicate inheritance should be allowed or not.
              The default is to replace existing annotations and not allow
              duplicates. 
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <para>
          Click on <guibutton>Ok</guibutton> to finish. The work is performed as a background job
          on the server. The progress can be followed in the dialog. It may take a while to
          complete if several items was selected since BASE will need to look up all parents
          and determine if they have any annotations that match the critera that was set up.
        </para>
      </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>