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

Last change on this file since 3400 was 3400, checked in by Nicklas Nordborg, 14 years ago

Fixes #534.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 20.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: annotations.xml 3400 2007-05-29 06:47:04Z nicklas $
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-->
28
29<chapter id="annotations">
30  <?dbhtml dir="annotations"?>
31  <title>Annotations</title>
32 
33  <sect1 id="annotations.types">
34    <title>Annotation Types</title>
35
36    <helptext external_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>
520 
521  <sect1 id="annotations.annotating">
522    <title>Annotating items</title>
523   
524    <para>
525      Entering annotation values follow the same pattern
526      for all items that can have annotations. They all have
527      a <guilabel>Annotations &amp; parameters</guilabel> tab
528      in their edit view. On this tab you can specify values
529      for all annotation types assigned to the type of item,
530      and all parameters that are attached to the protocol
531      used to create the item. Some items, for example
532      <emphasis>biosources</emphasis> and <emphasis>array designs</emphasis> 
533      can't have a protocol. In their case the tab is labelled
534      <guilabel>Annotations</guilabel>.
535    </para>
536   
537    <figure
538      id="annotations.figures.annotate">
539      <title>Annotating a sample</title>
540      <screenshot>
541        <mediaobject>
542          <imageobject>
543            <imagedata
544              fileref="figures/annotate.png" format="PNG" />
545          </imageobject>
546        </mediaobject>
547      </screenshot>
548    </figure>
549
550    <helptext external_id="annotations.edit" 
551      title="Annotations &amp; parameters">
552
553      <para>
554        Click on an entry in the list of annotation types to show a
555        form for entering a value for it to the right. Depending
556        on the options set on the annotation type the form may be a simple
557        free text field, a list of checkboxes or radiobuttons, or
558        something else.
559      </para>
560     
561      <para>
562        Annotation types with an <guilabel>X</guilabel> in front
563        of their names already have a value.
564      </para>
565     
566      <para>
567        Annotation types marked with angle brackets
568        <nohelp>
569        (<inlinemediaobject>
570          <imageobject><imagedata fileref="figures/parameter.gif" format="GIF"
571          /></imageobject>
572        </inlinemediaobject>)</nohelp>
573        are protocol parameters.
574      </para>
575     
576      <para>
577        Select an option in the <guilabel>Categories</guilabel> list to filter the
578        annotation types based on the categories
579        they belong to. This list contains all available
580        categories, and three special ones:
581        <itemizedlist>
582        <listitem>
583          <para>
584          <guilabel>all</guilabel>: Display all annotatation types
585          </para>
586        </listitem>
587        <listitem>
588          <para>
589          <guilabel>protocol parameters</guilabel>: Display only
590          those annotation types that are parameters to the current
591          protocol.
592          </para>
593        </listitem>
594        <listitem>
595          <para>
596          <guilabel>uncategorized</guilabel>: Display only annotation types
597          that hasn't been put into a category.
598          </para>
599        </listitem>
600        </itemizedlist>
601      </para>
602     
603      <seeother>
604        <other external_id="annotations.edit.inherited">Inherit annotations</other>
605      </seeother>
606     
607    </helptext>
608   
609    <sect2 id="annotations.inheriting">
610      <title>Inheriting annotations from other items</title>
611     
612      <helptext external_id="annotations.edit.inherited" 
613        title="Inherit annotations">
614        <para>
615          An item may inherit annotations from any of it's parent items.
616          E.g. an extract can inherit annotations from the sample or biosource
617          it was created from. This is an important feature to make the
618          experimental factors work. Annotations that should be used as
619          experimental factors must be inherited to the raw bioassay level.
620          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more
621          information about experimental factors.</nohelp>
622        </para>
623       
624        <nohelp>
625        <figure
626          id="annotations.figures.inherit">
627          <title>Inheriting annotations from a parent item</title>
628          <screenshot>
629            <mediaobject>
630              <imageobject>
631                <imagedata
632                  fileref="figures/inherit_annotations.png" format="PNG" />
633              </imageobject>
634            </mediaobject>
635          </screenshot>
636        </figure>
637        </nohelp>
638   
639        <para>
640          On this screen is a tree-like structure in two levels. The first level
641          lists all parent items which has at least one annotations. The second
642          level lists the annotations and protocol parameters for the item.
643          Selecting an item in the first level will inherit all annotations
644          from that item, including those that you maybe add later.
645          Selecting an annotation or protocol parameter at the second level
646          will inherit only the selected one.
647        </para>
648       
649        <note>
650          <itemizedlist>
651          <listitem>
652            <para>
653            The inheritance is implemented by reference. This means that if
654            you change the value of an annotation the new value is automatically
655            picked up by those inheriting it.
656            </para>
657          </listitem>
658          <listitem>
659            <para>
660            You can't inherit annotations from an item which doesn't have
661            annotations.
662            </para>
663          </listitem>
664          <listitem>
665            <para>
666            If you delete an annotation from a parent item, the inheritance will
667            be lost, even if you later add a value again.
668            </para>
669          </listitem>
670          </itemizedlist>
671        </note>
672       
673        <warning>
674          <para>
675          If you rearrange links to parent items after you have
676          specified inheritance, it may happen that you are inheriting
677          annotation from non-parent items. This will be flagged with a warning
678          icon in the list, and must be fixed manually. The experiment validation
679          tool is an excellent help for locating this kind of problems.
680          <nohelp>See <xref linkend="experiments_analysis.experiment.overview" />.</nohelp>
681          </para>
682        </warning>
683   
684        <seeother>
685          <other external_id="annotations.edit">Annotations and parameters</other>
686          <other external_id="experiment.edit.factors">Experimental factors</other>
687          <other external_id="experiment.overview">Experiment validation tool</other>
688        </seeother>
689     
690      </helptext>     
691     
692    </sect2>
693   
694  </sect1>
695
696</chapter>
Note: See TracBrowser for help on using the repository browser.