Changeset 3395


Ignore:
Timestamp:
May 28, 2007, 2:22:58 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #534. Major reorganisation. Swapped screen shots.

Location:
trunk/doc/src/docbook
Files:
3 added
6 deleted
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/userdoc/annotations.xml

    r3394 r3395  
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    44    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    5     <!--
    6         $Id$
    7        
    8         Copyright (C) Authors contributing to this file.
    9        
    10         This file is part of BASE - BioArray Software Environment.
    11         Available at http://base.thep.lu.se/
    12        
    13         BASE is free software; you can redistribute it and/or
    14         modify it under the terms of the GNU General Public License
    15         as published by the Free Software Foundation; either version 2
    16         of the License, or (at your option) any later version.
    17        
    18         BASE is distributed in the hope that it will be useful,
    19         but WITHOUT ANY WARRANTY; without even the implied warranty of
    20         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    21         GNU General Public License for more details.
    22        
    23         You should have received a copy of the GNU General Public License
    24         along with this program; if not, write to the Free Software
    25         Foundation, Inc., 59 Temple Place - Suite 330,
    26         Boston, MA  02111-1307, USA.
    27     -->
     5<!--
     6  $Id$
     7 
     8  Copyright (C) Authors contributing to this file.
     9 
     10  This file is part of BASE - BioArray Software Environment.
     11  Available at http://base.thep.lu.se/
     12 
     13  BASE is free software; you can redistribute it and/or
     14  modify it under the terms of the GNU General Public License
     15  as published by the Free Software Foundation; either version 2
     16  of the License, or (at your option) any later version.
     17 
     18  BASE is distributed in the hope that it will be useful,
     19  but WITHOUT ANY WARRANTY; without even the implied warranty of
     20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     21  GNU General Public License for more details.
     22 
     23  You should have received a copy of the GNU General Public License
     24  along with this program; if not, write to the Free Software
     25  Foundation, Inc., 59 Temple Place - Suite 330,
     26  Boston, MA  02111-1307, USA.
     27-->
    2828
    2929<chapter id="annotations">
    3030  <?dbhtml dir="annotations"?>
    31     <title>Annotation Types</title>
    32     <sect1 id="annotations.introduction">
    33         <title>Introduction</title>
    34         <para>BASE2 has been engineered to closely map the <ulink
    35                 url="http://www.mged.org/Workgroups/MIAME/miame.html">MIAME concepts</ulink>. However, since
    36             MIAME is focused on microarray processing workflow, information about the description
    37             biological samples themselves was left out. BASE2 users are free to annotate
    38             Biomaterials (and most BASE2 items) as they wish, from basic free text description to
    39             more advanced ontology based terms. To accomodate the annotation needs of users eager
    40             with detailed sample annotations and also the needs of very different communities, BASE2
    41             provides a mechanism that allows a high level of annotation customization. BASE2 allows
    42             to create descriptive elements for both quantitative annotation and qualitative
    43             annotation of Biomaterials via the <guilabel>Annotation Type mechanism</guilabel>.
    44             Actually, Annotation Types can be used to annotate not only Biomaterials but almost all
    45             BASE2 items, from <guilabel>Plates</guilabel> to <guilabel>Protocols</guilabel> and
    46                 <guilabel>BioAssaysets</guilabel> This chapter details how to manage and use these
    47             elements.</para>
    48     </sect1>
    49     <sect1 id="annotations.manage">
    50         <title>Managing Annotation Types</title>
    51         <para> </para>
    52         <sect2 id="annotations.manage.create_at">
    53             <title>Creating Annotation Types</title>
    54             <para>Go To <menuchoice>
    55                     <guimenu>Administrate</guimenu>
    56                     <guimenuitem>Types</guimenuitem>
    57                     <guisubmenu>AnnotationTypes</guisubmenu>
    58                 </menuchoice>
    59             </para>
    60             <para> Click on &gbNew; and select one of the 8 different
    61                 types which can be split in 4 main groups</para>
    62             <itemizedlist spacing="compact">
    63                 <listitem>
    64                     <para><guilabel>Integer</guilabel>, <guilabel>Long</guilabel>,
    65                         <guilabel>Float</guilabel> and <guilabel>Double</guilabel> for Numerical
    66                         Annotation Types.</para>
    67                 </listitem>
    68 
    69                 <listitem>
    70                     <para><guilabel>String</guilabel> and <guilabel>text</guilabel> for textual
    71                         Annotation Types .</para>
    72                 </listitem>
    73 
    74                 <listitem>
    75                     <para><guilabel>Boolean</guilabel> for declaring Annotation Types that can take
    76                         one of 2 possible values.</para>
    77                 </listitem>
    78 
    79                 <listitem>
    80                     <para><guilabel>Boolean</guilabel> for declaring Annotation Type used as
    81                         calendar/time stamps.</para>
    82                 </listitem>
    83             </itemizedlist>
    84             <note>
    85                 <para>These distinctions matter essentially to database administrators who need fine
    86                     tuning of database settings. Therefore, creation of Annotation Type should be
    87                     supervised by system administrators.</para>
    88             </note>
    89             <para> A <guilabel>Create</guilabel> pop-up window opens. It contains 4 different tabs: </para>
    90             <orderedlist numeration="loweralpha" spacing="compact">
    91                 <listitem>
    92                     <para>
    93                         <guilabel>Annotation type</guilabel>
    94                     </para>
    95                     <para> It allows definition of core properties of the newly created annotation
    96                         type. This includes specifying: </para>
    97                     <itemizedlist spacing="compact">
    98                         <listitem>
    99                             <para>How the <guilabel>Annotation Type</guilabel> should be
    100                             named.</para>
    101                         </listitem>
    102                         <listitem>
    103                             <para>If the <guilabel>Annotation Type</guilabel> should be treated as a
    104                                     <guilabel>protocol parameter</guilabel>.</para>
    105                         </listitem>
    106                         <listitem>
    107                             <para>If the <guilabel>Annotation Type</guilabel> should be considered
    108                                 as <guilabel>MIAME required</guilabel>.</para>
    109                         </listitem>
    110                         <listitem>
    111                             <para>If a <guilabel>default value</guilabel> should be
    112                             available.</para>
    113                         </listitem>
    114                         <listitem>
    115                             <para>If more than one option can be selected by setting the
    116                                     <guilabel>multiplicity</guilabel> to more than one.</para>
    117                         </listitem>
    118                         <listitem>
    119                             <para>Finally, one can add a short textual description of the
    120                                     <guilabel>Annotation Type</guilabel> being created, to clarify
    121                                 its usage.</para>
    122                         </listitem>
    123                     </itemizedlist>
    124                     <figure id="write_docbook_doc.figures.annotationtype">
    125                         <title>The Annotation type tab of the Create Window for a String Annotation
    126                             Type</title>
    127                         <screenshot>
    128                             <mediaobject>
    129                                 <imageobject>
    130                                     <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype.png" format="PNG"/>
    131                                 </imageobject>
    132                             </mediaobject>
    133                         </screenshot>
    134                     </figure>
    135                 </listitem>
    136                 <listitem>
    137                     <para>
    138                         <guilabel>Options</guilabel>
    139                     </para>
    140                     <para> The tab allows tuning the interaction options with the Web Graphical User
    141                         Interface when using Annotation types: <itemizedlist spacing="compact">
    142                             <listitem>
    143                                 <para>Choosing <guilabel>text box</guilabel> option allows free text
    144                                     to be entered.</para>
    145                             </listitem>
    146                             <listitem>
    147                                 <para>Choosing the <guilabel>selection list</guilabel> option
    148                                     activates the 'value' section. Actual values can be supplied
    149                                     using one line for each value (a return entry is used as
    150                                     separator).</para>
    151                                 <para>It enables administrator to declare the list of possible
    152                                     values using the "values" box.</para>
    153                             </listitem>
    154                             <listitem>
    155                                 <para>Choosing the <guilabel>radio button/checkboxes</guilabel>
    156                                     option activates the <guilabel>value</guilabel> section. Actual
    157                                     values can be supplied using one line for each value (a return
    158                                     entry is used as separator).</para>
    159                                 <para>When selecting radio-button instead of selection list, this
    160                                     will alter the interface in order to allow user to tick button
    161                                     instead of selecting from a drop-down list.</para>
    162                                 <tip>
    163                                     <para>In term of usability, drop-down list can be more easily
    164                                         navigated especially when the number of possible values is
    165                                         large, and because selectionlist and drop-down list allow
    166                                         use of arrow and tab for selection.</para>
    167                                 </tip>
    168                             </listitem>
    169                             <listitem>
    170                                 <para>GUI Variations depending on the type of Annotation Types: </para>
    171                                 <para>Depending on the nature of the annotation type being created
    172                                     (e.g. whether it is a boolean, a string or a date), the
    173                                         <guilabel>Options</guilabel> tab may display specific
    174                                     fields.</para>
    175                                 <para>When creating an Annotation Type of Type Boolean, the default
    176                                     value field is replaced by the true or false radio-button in
    177                                     order to allow specification of a value.</para>
    178                                 <para>Also, when using numerical AnnotationTypes, upper and lower
    179                                     limit can be defined.</para>
    180                             </listitem>
    181                         </itemizedlist>
    182                     </para>
    183                     <figure id="write_docbook_doc.figures.annotationtype-option">
    184                         <title>The Option tab of the Create Window for a String Annotation Type</title>
    185                         <screenshot>
    186                                     <mediaobject>
    187                                         <imageobject>
    188                                             <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-option.png" format="PNG"/>
    189                                         </imageobject>
    190                                     </mediaobject>
    191                                 </screenshot>
    192                     </figure>
    193                 </listitem>
    194                 <listitem>
    195                     <para>
    196                         <guilabel>Item types</guilabel>
    197                     </para>
    198                     <para> The Item types tab is used to defined which BASE2 entities can be
    199                         annotated using the newly creating Annotation Type. Simply use
    200                             <guiicon>arrow left|right</guiicon> to moved items between the
    201                             <guilabel>disabled for</guilabel> and <guilabel>enabled for</guilabel>
    202                         <note>
    203                             <para>Experiment item can not be annotated using Annotation Type</para>
    204                         </note>
    205                     </para>
    206                     <figure id="write_docbook_doc.figures.annotationtype-item">
    207                         <title>The Item tab of the Create Window for a String Annotation Type</title>
    208                         <screenshot>
    209                             <mediaobject>
    210                                 <imageobject>
    211                                     <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-item.png" format="PNG"/>
    212                                 </imageobject>
    213                             </mediaobject>
    214                         </screenshot>
    215                     </figure>
    216                 </listitem>
    217                 <listitem>
    218                     <para>
    219                         <guilabel>Categories</guilabel>
    220                     </para>
    221                     <para> Annotation Type can be grouped together thanks to the Annotation Category
    222                         functionality. This enhances display by avoid overcrowding the list of
    223                         annotation types presented to users. It also allows to improve the display of
    224                         information. </para>
    225                     <figure id="write_docbook_doc.figures.annotationtype-categories">
    226                         <title>The categories tab of the Create Window for a String Annotation Type</title>
    227                         <screenshot>
    228                             <mediaobject>
    229                                 <imageobject>
    230                                     <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-categories.png" format="PNG"/>
    231                                 </imageobject>
    232                             </mediaobject>
    233                         </screenshot>
    234                     </figure>
    235                 </listitem>
    236             </orderedlist>
    237 
    238             <para>Click on the <inlinemediaobject>
    239                     <imageobject>
    240                         <imagedata fileref="figures/save.gif" format="GIF"/>
    241                     </imageobject>
    242                 </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject>
    243                     <imageobject>
    244                         <imagedata fileref="figures/cancel.gif" format="GIF"/>
    245                     </imageobject>
    246                 </inlinemediaobject> to abort. </para>
    247 
    248         </sect2>
    249         <sect2 id="annotations.manage.update">
    250             <title>Updating Annotation Types</title>
    251             <para>Using the <keycap>CTRL</keycap>, <keycap>ALT</keycap>, <keycap>SHIFT</keycap> key
    252                 combination, click on the Annotation Type to be modified from the Annotation Type
    253                 List View</para>
    254             <para>The <guilabel>Edit</guilabel> pop-up window opens, presenting the various tabs
    255                 presented in the previous section.</para>
    256             <note>
    257                 <para>Everything is editable except the Annotation Type Type itself, which is
    258                     immutable and set once and for all upon creation</para>
    259             </note>
    260         </sect2>
    261         <sect2 id="annotations.manage.create_atcategory">
    262             <title>Grouping Annotation Type into Categories</title>
    263             <para>
    264                 <guilabel>Annotation Type Categories</guilabel> allow grouping of related Annotation
    265                 Types, based on users requirements. </para>
    266             <para>For creating a new category, go to: </para>
    267             <para>
    268                 <menuchoice>
    269                     <guimenu>Administrate</guimenu>
    270                     <guimenuitem>Types</guimenuitem>
    271                     <guisubmenu>Annotation Type categories</guisubmenu>
    272                 </menuchoice>
    273             </para>
    274             <para>Click on &gbNew;</para>
    275             <para>a pop-up window opens.</para>
    276             <para>It contains 2 tabs, one for declaring name and description of the newly created
    277                 category, the second tab is to provide the list of annotation type to be grouped
    278                 together under this container.</para>
    279             <example id="annotation_types.example.atcategory">
    280                 <title>A category 'Hematology Descriptors' could be created to group together
    281                     Annotation Types such as 'Lymphocyte count' and 'Hematocrite' </title>
    282             </example>
    283             <example id="annotation_types.example.atcategory-2">
    284                 <title>A category 'Plasma Clinical Descriptors' could be created to group together
    285                     Annotation Types such as 'ALT activity (UI/mL)' and 'LDH activity (UI/mL').
    286                 </title>
    287             </example>
    288         </sect2>
    289 
    290         <sect2 id="annotations.manage.batchupload">
    291             <title>Batchloading Annotation Types from file</title>
    292             <para>A plugin, CVLoader.jar, has been specially devised with 2 purposes in mind:</para>
    293             <orderedlist>
    294                 <listitem>
    295                     <para>To speed-up data Annotation Type declaration and upload in the BASE2
    296                         system.</para>
    297                 </listitem>
    298                 <listitem>
    299                     <para>To enable sharing list of annotation types across BASE2 instances to
    300                         ensure consistency in data annotation.</para>
    301                 </listitem>
    302             </orderedlist>
    303             <para>In order to achieve this functionality, a file format specification was defined
    304                 and is detailed now</para>
    305 
    306             <sect3 id="annotations.manage.batchupload.fileformat">
    307                 <title>Defining the input file: File format definition</title>
    308                 <para> To use the CV-loader import plugin, users need to create a tab-delimited file
    309                     complying with the following guidelines. Columns names, order, allowed values
    310                     and within column separator are important.</para>
    311                 <itemizedlist spacing="compact">
    312                     <listitem>
    313                         <para><guilabel>Category Name</guilabel>: free text</para>
    314                     </listitem>
    315                     <listitem>
    316                         <para><guilabel>AnnotationType Name</guilabel>: free text</para>
    317                     </listitem>
    318                     <listitem>
    319                         <para><guilabel>Description</guilabel>: free text</para>
    320                     </listitem>
    321                     <listitem>
    322                         <para><guilabel>ValueType</guilabel>:
    323                             {string,text,boolean,data,integer,long,double,float}</para>
    324                     </listitem>
    325                     <listitem>
    326                         <para><guilabel>Required for MIAME</guilabel>: true/false</para>
    327                     </listitem>
    328                     <listitem>
    329                         <para><guilabel>Enumeration</guilabel>: true/false</para>
    330                     </listitem>
    331                     <listitem>
    332                         <para><guilabel>Multiplicity</guilabel>: integer</para>
    333                     </listitem>
    334                     <listitem>
    335                         <para><guilabel>Default value</guilabel>: free text</para>
    336                     </listitem>
    337                     <listitem>
    338                         <para><guilabel>Cv values</guilabel>: semi-colon (;) used as
    339                         separator</para>
    340                     </listitem>
    341                     <listitem>
    342                         <para><guilabel>Item types</guilabel>: semi-colon (;) used as separator
    343                             {biosource,sample,extract,protocol,arraydesign,array,plate}</para>
    344                     </listitem>
    345                     <listitem>
    346                         <para><guilabel>Parameter</guilabel>: true/false</para>
    347                     </listitem>
    348                 </itemizedlist>
    349                 <para/>
    350             </sect3>
    351             <sect3 id="annotations.manage.batchupload.pluginconfig">
    352                 <title>Configuring the CV loader plugin</title>
    353                 <para>From the plugin configuration page, Use the &gbImport;
    354                     button to load the xml configuration file available here. Please refer to <xref
    355                         linkend="plugins"/> for more ample explanations about plugin configuration.</para>
    356                 <note>
    357                     <para>By default the plugin creates <guilabel>selection list</guilabel> for all
    358                         enumerated values declared in the file. </para>
    359                 </note>
    360                 <note>
    361                     <para><guilabel>external ID</guilabel> field is not supported in the current
    362                         implementation of the plugin. </para>
    363                 </note>
    364 
    365             </sect3>
    366             <sect3 id="annotations.manage.batchupload.pluginrun">
    367                 <title>Running the plugin</title>
    368                 <para>-From the Annotation Type List View page, click on the
    369                     &gbImport; Button (which shows up only when the import plugin
    370                     has been configured).</para>
    371                 <para>-Supply path to tab delimited file containing the Annotation Type to be
    372                     imported. Click &gbNext;. </para>
    373                 <figure id="write_docbook_doc.figures.batchloading-annotationtype-2">
    374                     <title>Running the CVloader plugin: specifying the file</title>
    375                     <screenshot>
    376                           <mediaobject>
    377                               <imageobject>
    378                                   <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-2.png" format="PNG"/>
    379                               </imageobject>
    380                           </mediaobject>
    381                       </screenshot>
    382                 </figure>
    383                 <para>Define whether or not to update existing Annotation Types and click
    384                         &gbNext;</para>
    385                 <figure id="write_docbook_doc.figures.batchloading-annotationtype-3">
    386                     <title>Running the CVloader plugin in update mode</title>
    387                     <screenshot>
    388                           <mediaobject>
    389                               <imageobject>
    390                                   <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-3.png" format="PNG"/>
    391                               </imageobject>
    392                           </mediaobject>
    393                       </screenshot>
    394                 </figure>
    395                 <para> Click &gbFinish; to launch the plugin execution. If one
    396                     selects the email notification option, a message will be sent upon job
    397                     completion detailing success or failure of the import process. </para>
    398                 <tip>
    399                     <para>Once an update has been made using the plugin, it can not be undone but
    400                         one can simply update the file and run the plugin again.</para>
    401                 </tip>
    402             </sect3>
    403         </sect2>
    404     </sect1>
    405 
    406     <sect1 id="annotations.bestpractices">
    407         <title>Best Practices and Tab2Mage Export functionality</title>
    408        
    409         See <xref linkend="experiments_analysis.magexport" />.
    410        
    411     </sect1>
     31  <title>Annotations</title>
     32 
     33  <sect1 id="annotations.types">
     34    <title>Annotation Types</title>
     35
     36    <helptext id="annotationtype.view.properties"
     37      title="Annotation types">
     38    <para>
     39      BASE2 has been engineered to closely map the
     40      <ulink
     41        url="http://www.mged.org/Workgroups/MIAME/miame.html">
     42        MIAME concepts</ulink>.
     43      However, since MIAME is focused on microarray processing
     44      workflow, information about the description biological
     45      samples themselves was left out. BASE2 users are free to
     46      annotate biomaterials (and most BASE2 items) as they wish,
     47      from basic free text description to more advanced ontology
     48      based terms. To accomodate the annotation needs of users
     49      eager with detailed sample annotations and also the needs of
     50      very different communities, BASE2 provides a mechanism that
     51      allows a high level of annotation customization. BASE2
     52      allows to create descriptive elements for both quantitative
     53      annotation and qualitative annotation of Biomaterials via
     54      the <emphasis>Annotation Type mechanism</emphasis>.
     55      Actually, annotation types can be used to annotate not
     56      only <emphasis>Biomaterials</emphasis> but almost all BASE2 items, from
     57      <emphasis>Plates</emphasis>
     58      to
     59      <emphasis>Protocols</emphasis>
     60      and
     61      <emphasis>BioAssaysets</emphasis>
     62    </para>
     63
     64    <nohelp>
     65    <para>
     66      Go to
     67      <menuchoice>
     68        <guimenu>Administrate</guimenu>
     69        <guimenuitem>Types</guimenuitem>
     70        <guisubmenu>Annotation types</guisubmenu>
     71      </menuchoice>
     72      to manage your annotation types.
     73    </para>
     74    </nohelp>
     75
     76    <para>
     77      To create a new annotation type, click on the
     78      &gbNew; button. This behaves differently
     79      than other buttons found elsewhere and you must select
     80      one of the 8 different types which can be split in 4 main groups.
     81    </para>
     82
     83    <itemizedlist>
     84    <listitem>
     85      <para>
     86        <guilabel>Integer</guilabel>,
     87        <guilabel>Long</guilabel>,
     88        <guilabel>Float</guilabel> and
     89        <guilabel>Double</guilabel>
     90        for numerical annotation types.
     91      </para>
     92    </listitem>
     93
     94    <listitem>
     95      <para>
     96        <guilabel>String</guilabel> and
     97        <guilabel>Text</guilabel> for textual annotation types.
     98        The difference is that <guilabel>String</guilabel>:s can
     99        have a maximum length of 255 characters and can have an attached
     100        list of predefined value. <guilabel>Text</guilabel>
     101        annotation types have no practival limit and are always
     102        free-text.
     103      </para>
     104    </listitem>
     105
     106    <listitem>
     107      <para>
     108        <guilabel>Boolean</guilabel>
     109        for declaring annotation types that can take one
     110        <constant>TRUE</constant>/<constant>FALSE</constant>
     111        values.
     112      </para>
     113    </listitem>
     114
     115    <listitem>
     116      <para>
     117        <guilabel>Date</guilabel>
     118        for declaring annotation types used as
     119        calendar/time stamps.
     120      </para>
     121    </listitem>
     122    </itemizedlist>
     123
     124    <note>
     125      <para>
     126        These distinctions matter essentially to database
     127        administrators who need fine tuning of database
     128        settings. Therefore, creation of annotation type
     129        should be supervised by system administrators.
     130      </para>
     131    </note>
     132   
     133      <seeother>
     134        <other external_id="annotationtype.edit">Edit annotation type</other>
     135      </seeother>
     136    </helptext>
     137 
     138    <para>
     139      The <guilabel>Edit annotation type</guilabel> window is opened in a
     140      popup. It contains four different tabs.
     141    </para>
     142 
     143    <sect2 id="annotations.types.properties">
     144      <title>Properties</title>
     145     
     146      <figure
     147        id="annotations.figures.annotationtype.properties">
     148        <title>Annotation type properties</title>
     149        <screenshot>
     150          <mediaobject>
     151            <imageobject>
     152              <imagedata
     153                fileref="figures/edit_annotationtype.png" format="PNG" />
     154            </imageobject>
     155          </mediaobject>
     156        </screenshot>
     157      </figure>
     158     
     159      <helptext external_id="annotationtype.edit"
     160        title="Edit annotation type">
     161       
     162        <variablelist>
     163        <varlistentry>
     164          <term><guilabel>Name</guilabel></term>
     165          <listitem>
     166            <para>
     167            The name of the annotation type.
     168            <nohelp>
     169            See <xref linkend="experiments_analysis.magexport" />
     170            if you are going to use this annotation type when
     171            exporting Tab2Mage files.
     172            </nohelp>
     173            </para>
     174          </listitem>
     175        </varlistentry>
     176        <varlistentry>
     177          <term><guilabel>External ID</guilabel></term>
     178          <listitem>
     179            <para>
     180            An ID identifying this annotation type in an external
     181            database. This value can be used by tools that
     182            need to update annotation types in BASE from external
     183            sources. The value doesn't have to be unique.
     184            </para>
     185          </listitem>
     186        </varlistentry>
     187        <varlistentry>
     188          <term><guilabel>Multiplicity</guilabel></term>
     189          <listitem>
     190            <para>
     191              The maximum number of values that can be entered
     192              for this annotation type. The default is 1. A value
     193              of 0, means that any number of values can be used.
     194            </para>
     195          </listitem>
     196        </varlistentry>
     197        <varlistentry>
     198          <term><guilabel>Default value</guilabel></term>
     199          <listitem>
     200            <para>
     201              A value that can be used as the default when
     202              adding values.
     203            </para>
     204          </listitem>
     205        </varlistentry>
     206        <varlistentry>
     207          <term><guilabel>Required for MIAME</guilabel></term>
     208          <listitem>
     209            <para>
     210              If a value must be specified for this annotation type
     211              in order for the experiment to be compliant with MIAME.
     212            </para>
     213          </listitem>
     214        </varlistentry>
     215        <varlistentry>
     216          <term><guilabel>Protocol parameter</guilabel></term>
     217          <listitem>
     218            <para>
     219              If the annotation type is a protocol parameter. As a protocol
     220              parameter an item can only be annotated if a protocol
     221              that includes this parameter has been used.
     222              <nohelp>See <xref linkend="protocols.parameters" />
     223              for more information.</nohelp>
     224            </para>
     225          </listitem>
     226        </varlistentry>
     227        <varlistentry>
     228          <term><guilabel>Description</guilabel></term>
     229          <listitem>
     230            <para>
     231              A short textual description of the
     232              to clarify the usage.
     233            </para>
     234          </listitem>
     235        </varlistentry>
     236        </variablelist>
     237       
     238        <seeother>
     239          <other external_id="annotationtype.edit.options">Options</other>
     240          <other external_id="annotationtype.edit.items">Item types</other>
     241          <other external_id="annotationtype.edit.categories">Categories</other>
     242          <other external_id="protocol.edit.parameters">Protocol parameters</other>
     243        </seeother>
     244      </helptext>
     245   
     246    </sect2>
     247
     248    <sect2 id="annotations.types.options">
     249      <title>Options</title>
     250
     251      <figure
     252        id="annotations.figures.annotationtype.options">
     253        <title>Annotation type options</title>
     254        <screenshot>
     255          <mediaobject>
     256            <imageobject>
     257              <imagedata
     258                fileref="figures/annotationtype_options.png" format="PNG" />
     259            </imageobject>
     260          </mediaobject>
     261        </screenshot>
     262      </figure>
     263     
     264      <helptext external_id="annotationtype.edit.options"
     265        title="Annotation type options">
     266       
     267        <para>
     268          The available options in this tab depends on the type
     269          of annotation type, eg. if is a string, numeric or
     270          another type.
     271        </para>
     272       
     273        <variablelist>
     274        <varlistentry>
     275          <term><guilabel>Interface</guilabel></term>
     276          <listitem>
     277            <para>
     278            Select the type of graphical element to use for
     279            entering values for the annotation type. You can select
     280            between three different options:
     281            <itemizedlist>
     282            <listitem>
     283              <para>
     284              <guilabel>text box</guilabel>: The user must enter the value
     285              in a free-text box.
     286              </para>
     287            </listitem>
     288            <listitem>
     289              <para>
     290              <guilabel>selection list</guilabel>: The user must select
     291              values from a list of predefined values.
     292              </para>
     293            </listitem>
     294            <listitem>
     295              <para>
     296              <guilabel>radiobuttons/checkboxes</guilabel>: The user must
     297              select values by marking checkboxes or radiobuttons.
     298              </para>
     299            </listitem>
     300            </itemizedlist>
     301           
     302            The last two options requires that a list of values are
     303            available. Enter possible values in the <guilabel>Values</guilabel>
     304            which will be activated automatically.
     305            </para>
     306            <tip>
     307              <para>
     308                In term of usability, a drop-down
     309                list can be more easily
     310                navigated especially when the
     311                number of possible values is
     312                large, and because selectionlist
     313                and drop-down list allow use of
     314                arrow and tab for selection.
     315              </para>
     316            </tip>
     317          </listitem>
     318        </varlistentry>
     319       
     320        <varlistentry>
     321          <term><guilabel>Min/max value</guilabel></term>
     322          <listitem>
     323            <para>
     324              Available for numerical annotation types only.
     325              Specifies the minimum and maximum allowed value.
     326              If left empty, the bound(s) are undefined and any
     327              value is allowed.
     328            </para>
     329          </listitem>
     330        </varlistentry>
     331
     332        <varlistentry>
     333          <term><guilabel>Min/max value</guilabel></term>
     334          <listitem>
     335            <para>
     336              Available for numerical annotation types only.
     337              Specifies the minimum and maximum allowed value.
     338              If left empty, the bound(s) are undefined and any
     339              value is allowed.
     340            </para>
     341          </listitem>
     342        </varlistentry>
     343       
     344        <varlistentry>
     345          <term><guilabel>Max length</guilabel></term>
     346          <listitem>
     347            <para>
     348              The maximum allowed length of a string annotation value.
     349              If empty, 255 is the maximum length. If you need longer
     350              values than that, use a <emphasis>text</emphasis>
     351              annotation type.
     352            </para>
     353          </listitem>
     354        </varlistentry>
     355
     356        <varlistentry>
     357          <term><guilabel>Input box width/height</guilabel></term>
     358          <listitem>
     359            <para>
     360              A suggested display width and height of the element
     361              used for input. These values are ignored in the current
     362              implementation.
     363            </para>
     364          </listitem>
     365        </varlistentry>
     366
     367        <varlistentry>
     368          <term><guilabel>Values</guilabel></term>
     369          <listitem>
     370            <para>
     371              A list of predefined values that the user is allowed
     372              to select from. This option is only activated if the
     373              <guilabel>Interface</guilabel> option is set
     374              to <guilabel>selection list</guilabel> or
     375              <guilabel>radiobuttons/checkboxes</guilabel>.
     376              Actual values can be supplied using one line for each
     377              value (a return entry is used as separator).
     378            </para>
     379          </listitem>
     380        </varlistentry>
     381
     382        </variablelist>
     383       
     384        <seeother>
     385          <other external_id="annotationtype.edit">Properties</other>
     386          <other external_id="annotationtype.edit.items">Item types</other>
     387          <other external_id="annotationtype.edit.categories">Categories</other>
     388        </seeother>
     389      </helptext>
     390    </sect2>
     391   
     392    <sect2 id="annotations.types.items">
     393      <title>Item types</title>
     394     
     395      <figure
     396        id="annotations.figures.annotationtype.items">
     397        <title>Annotation type items</title>
     398        <screenshot>
     399          <mediaobject>
     400            <imageobject>
     401              <imagedata
     402                fileref="figures/annotationtype_items.png" format="PNG" />
     403            </imageobject>
     404          </mediaobject>
     405        </screenshot>
     406      </figure>
     407   
     408      <helptext external_id="annotationtype.edit.items"
     409        title="Item types">
     410       
     411        <para>
     412          On this tab you select the item types that you wish to
     413          annotate with the annotation type. Simply use
     414          left and right buttons to move selection options
     415          between the <guilabel>Enabled for</guilabel>
     416          and <guilabel>Disabled for</guilabel> lists.
     417        </para>
     418       
     419        <note>
     420          <para>
     421          If the annotation type has been marked as a
     422          <guilabel>Protocol</guilabel> parameter, these settings are
     423          ignored, with one exception. If you wish to view parameter
     424          values in the list view for a specific item type you must select
     425          the item type here. Otherwise the parameter will not be present
     426          as a displayable column.
     427          </para>
     428        </note>
     429       
     430        <seeother>
     431          <other external_id="annotationtype.edit">Properties</other>
     432          <other external_id="annotationtype.edit.options">Options</other>
     433          <other external_id="annotationtype.edit.categories">Categories</other>
     434        </seeother>
     435      </helptext>
     436    </sect2>
     437 
     438    <sect2 id="annotations.types.categories">
     439      <title>Categories</title>
     440   
     441      <helptext external_id="annotationtype.edit.categories"
     442        title="Categories">
     443       
     444        <para>
     445          Annotation type can be grouped together by
     446          placing them in one or more categories. This
     447          enhances display by avoid overcrowding the list
     448          of annotation types presented to users. It also
     449          allows to improve the display of information.
     450        </para>
     451       
     452        <para>
     453          The <guilabel>Categories</guilabel> list displays
     454          the currently associated categories. Use the
     455          <guibutton>Add categories</guibutton> button
     456          to add more categories, or the <guilabel>Remove</guilabel>
     457          button to remove the selected categories.
     458        </para>
     459         
     460        <seeother>
     461          <other external_id="annotationtype.edit">Properties</other>
     462          <other external_id="annotationtype.edit.options">Options</other>
     463          <other external_id="annotationtype.edit.items">Item types</other>
     464        </seeother>
     465      </helptext>
     466    </sect2>
     467  </sect1>
     468 
     469  <sect1 id="annotations.categories">
     470    <title>Annotation type categories</title>
     471   
     472    <para>
     473      <guilabel>Annotation Type Categories</guilabel>
     474      allow grouping of related Annotation Types, based on
     475      users requirements.
     476    </para>
     477   
     478    <para>
     479      For managing categories go to
     480      <menuchoice>
     481        <guimenu>Administrate</guimenu>
     482        <guimenuitem>Types</guimenuitem>
     483          <guisubmenu>Annotation Type categories</guisubmenu>
     484        </menuchoice>.
     485    </para>
     486
     487    <example id="annotation_types.example.atcategory">
     488      <title>Annotation category examples</title>
     489     
     490      <para>
     491        <itemizedlist>
     492        <listitem>
     493          <para>
     494          A category <userinput>Hematology Descriptors</userinput>
     495          could be created to group together annotation types such as
     496          <userinput>Lymphocyte count</userinput> and
     497          <userinput>Hematocrite</userinput>
     498          </para>
     499        </listitem>
     500       
     501        <listitem>
     502          <para>
     503          A category <userinput>Plasma Clinical Descriptors</userinput>
     504          could be created to group together annotation types such as
     505          <userinput>ALT activity (UI/mL)</userinput> and
     506          <userinput>LDH activity (UI/mL)</userinput>
     507          </para>
     508        </listitem>
     509        </itemizedlist>
     510      </para>
     511    </example>
     512  </sect1>
     513
     514  <sect1 id="annotations.bestpractices">
     515    <title>Best Practices and Tab2Mage Export functionality</title>
     516    <para>
     517    See <xref linkend="experiments_analysis.magexport" />.
     518    </para>
     519  </sect1>
    412520
    413521</chapter>
Note: See TracChangeset for help on using the changeset viewer.