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

Last change on this file since 5706 was 5706, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

User documentation chapter 10 to 15. Added new chapter about "Item subtypes". Removed sections about protocol types, hardware types and software types. Merged "Hardware" and "Software" into a single chapter.

Added some menu separators in the New annotation type menu.

As usual, screen shots have not yet been updated.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 26.6 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 5706 2011-08-23 13:20:30Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
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 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="annotations">
28  <?dbhtml dir="annotations"?>
29  <title>Annotations</title>
30 
31  <sect1 id="annotations.types">
32    <title>Annotation Types</title>
33
34    <helptext external_id="annotationtype.view.properties" 
35      title="Annotation types">
36    <para>
37      BASE has been engineered to closely map the
38      <ulink
39        url="http://www.mged.org/Workgroups/MIAME/miame.html">
40        MIAME concepts</ulink>.
41      However, since MIAME is focused on microarray processing
42      workflow, information about the description biological
43      samples themselves was left out. BASE users are free to
44      annotate biomaterials (and most BASE items) as they wish,
45      from basic free text description to more advanced ontology
46      based terms. To accommodate the annotation needs of users
47      eager with detailed sample annotations and also the needs of
48      very different communities, BASE provides a mechanism that
49      allows a high level of annotation customization. BASE
50      allows to create descriptive elements for both quantitative
51      annotation and qualitative annotation of Biomaterials via
52      the <emphasis>Annotation Type mechanism</emphasis>.
53      Actually, annotation types can be used to annotate not
54      only <emphasis>Biomaterials</emphasis> but almost all BASE items, from
55      <emphasis>Plates</emphasis>
56      to
57      <emphasis>Protocols</emphasis>
58      and
59      <emphasis>Bioassay sets</emphasis>
60    </para>
61
62    <nohelp>
63    <para>
64      Go to
65      <menuchoice>
66        <guimenu>Administrate</guimenu>
67        <guimenuitem>Types</guimenuitem>
68        <guisubmenu>Annotation types</guisubmenu>
69      </menuchoice>
70      to manage your annotation types.
71    </para>
72    </nohelp>
73
74    <para>
75      To create a new annotation type, click on the
76      &gbNew; button. This behaves differently
77      than other buttons found elsewhere and you must select
78      one of the 9 different types which can be split in 4 main groups.
79    </para>
80
81    <itemizedlist>
82    <listitem>
83      <para>
84        <guilabel>Integer</guilabel>,
85        <guilabel>Long</guilabel>,
86        <guilabel>Float</guilabel> and
87        <guilabel>Double</guilabel>
88        for numerical annotation types.
89      </para>
90    </listitem>
91
92    <listitem>
93      <para>
94        <guilabel>String</guilabel> and
95        <guilabel>Text</guilabel> for textual annotation types.
96        The difference is that <guilabel>String</guilabel>:s can
97        have a maximum length of 255 characters and can have an attached
98        list of predefined value. <guilabel>Text</guilabel>
99        annotation types have no practical limit and are always
100        free-text.
101      </para>
102    </listitem>
103
104    <listitem>
105      <para>
106        <guilabel>Boolean</guilabel>
107        for declaring annotation types that can take one
108        <constant>TRUE</constant>/<constant>FALSE</constant>
109        values.
110      </para>
111    </listitem>
112
113    <listitem>
114      <para>
115        <guilabel>Date</guilabel> and <guilabel>Timestamp</guilabel>
116        for declaring annotation types used as
117        calendar/time stamps.
118      </para>
119    </listitem>
120    </itemizedlist>
121
122    <note>
123      <para>
124        These distinctions matter essentially to database
125        administrators who need fine tuning of database
126        settings. Therefore, creation of annotation type
127        should be supervised by system administrators.
128      </para>
129    </note>
130   
131      <seeother>
132        <other external_id="annotationtype.edit">Edit annotation type</other>
133      </seeother>
134    </helptext>
135 
136    <para>
137      The <guilabel>Edit annotation type</guilabel> window is opened in a
138      pop-up. It contains four different tabs.
139    </para>
140 
141    <sect2 id="annotations.types.properties">
142      <title>Properties</title>
143     
144      <figure
145        id="annotations.figures.annotationtype.properties">
146        <title>Annotation type properties</title>
147        <screenshot>
148          <mediaobject>
149            <imageobject>
150              <imagedata
151                fileref="figures/edit_annotationtype.png" format="PNG" />
152            </imageobject>
153          </mediaobject>
154        </screenshot>
155      </figure>
156     
157      <helptext external_id="annotationtype.edit" 
158        title="Edit annotation type">
159       
160        <variablelist>
161        <varlistentry>
162          <term><guilabel>Name</guilabel></term>
163          <listitem>
164            <para>
165            The name of the annotation type.
166            </para>
167          </listitem>
168        </varlistentry>
169        <varlistentry>
170          <term><guilabel>External ID</guilabel></term>
171          <listitem>
172            <para>
173            An ID identifying this annotation type in an external
174            database. This value can be used by tools that
175            need to update annotation types in BASE from external
176            sources. The value does not have to be unique.
177            </para>
178          </listitem>
179        </varlistentry>
180        <varlistentry>
181          <term><guilabel>Multiplicity</guilabel></term>
182          <listitem>
183            <para>
184              The maximum number of values that can be entered
185              for this annotation type. The default is 1. A value
186              of 0, means that any number of values can be used.
187            </para>
188          </listitem>
189        </varlistentry>
190        <varlistentry>
191          <term><guilabel>Default value</guilabel></term>
192          <listitem>
193            <para>
194              A value that can be used as the default when
195              adding values.
196            </para>
197          </listitem>
198        </varlistentry>
199        <varlistentry>
200          <term><guilabel>Required for MIAME</guilabel></term>
201          <listitem>
202            <para>
203              If a value must be specified for this annotation type
204              in order for the experiment to be compliant with MIAME.
205            </para>
206          </listitem>
207        </varlistentry>
208        <varlistentry>
209          <term><guilabel>Protocol parameter</guilabel></term>
210          <listitem>
211            <para>
212              If the annotation type is a protocol parameter. As a protocol
213              parameter an item can only be annotated if a protocol
214              that includes this parameter has been used.
215              <nohelp>See <xref linkend="protocols.parameters" /> 
216              for more information.</nohelp>
217            </para>
218          </listitem>
219        </varlistentry>
220        <varlistentry>
221          <term><guilabel>Description</guilabel></term>
222          <listitem>
223            <para>
224              A short textual description of the
225              to clarify the usage.
226            </para>
227          </listitem>
228        </varlistentry>
229        </variablelist>
230       
231        <seeother>
232          <other external_id="annotationtype.edit.options">Options</other>
233          <other external_id="annotationtype.edit.items">Item types</other>
234          <other external_id="annotationtype.edit.units">Units</other>
235          <other external_id="annotationtype.edit.categories">Categories</other>
236          <other external_id="protocol.edit.parameters">Protocol parameters</other>
237        </seeother>
238      </helptext>
239   
240    </sect2>
241
242    <sect2 id="annotations.types.options">
243      <title>Options</title>
244
245      <figure
246        id="annotations.figures.annotationtype.options">
247        <title>Annotation type options</title>
248        <screenshot>
249          <mediaobject>
250            <imageobject>
251              <imagedata
252                fileref="figures/annotationtype_options.png" format="PNG" />
253            </imageobject>
254          </mediaobject>
255        </screenshot>
256      </figure>
257     
258      <helptext external_id="annotationtype.edit.options" 
259        title="Annotation type options">
260       
261        <para>
262          The available options in this tab depends on the type
263          of annotation type, eg. if is a string, numeric or
264          another type.
265        </para>
266       
267        <variablelist>
268        <varlistentry>
269          <term><guilabel>Interface</guilabel></term>
270          <listitem>
271            <para>
272            Select the type of graphical element to use for
273            entering values for the annotation type. You can select
274            between three different options:
275            <itemizedlist>
276            <listitem>
277              <para>
278              <guilabel>text box</guilabel>: The user must enter the value
279              in a free-text box.
280              </para>
281            </listitem>
282            <listitem>
283              <para>
284              <guilabel>selection list</guilabel>: The user must select
285              values from a list of predefined values.
286              </para>
287            </listitem>
288            <listitem>
289              <para>
290              <guilabel>radiobuttons/checkboxes</guilabel>: The user must
291              select values by marking checkboxes or radiobuttons.
292              </para>
293            </listitem>
294            </itemizedlist>
295           
296            The last two options requires that a list of values are
297            available. Enter possible values in the <guilabel>Values</guilabel>
298            which will be activated automatically.
299            </para>
300            <tip>
301              <para>
302                In term of usability, a drop-down
303                list can be more easily
304                navigated especially when the
305                number of possible values is
306                large, and because selection-list
307                and drop-down list allow use of
308                arrow and tab for selection.
309              </para>
310            </tip>
311          </listitem>
312        </varlistentry>
313       
314        <varlistentry>
315          <term><guilabel>Min/max value</guilabel></term>
316          <listitem>
317            <para>
318              Available for numerical annotation types only.
319              Specifies the minimum and maximum allowed value.
320              If left empty, the bound(s) are undefined and any
321              value is allowed.
322            </para>
323          </listitem>
324        </varlistentry>
325       
326        <varlistentry>
327          <term><guilabel>Max length</guilabel></term>
328          <listitem>
329            <para>
330              The maximum allowed length of a string annotation value.
331              If empty, 255 is the maximum length. If you need longer
332              values than that, use a <emphasis>text</emphasis> 
333              annotation type.
334            </para>
335          </listitem>
336        </varlistentry>
337
338        <varlistentry>
339          <term><guilabel>Input box width/height</guilabel></term>
340          <listitem>
341            <para>
342              A suggested display width and height of the element
343              used for input. These values are ignored in the current
344              implementation.
345            </para>
346          </listitem>
347        </varlistentry>
348
349        <varlistentry>
350          <term><guilabel>Values</guilabel></term>
351          <listitem>
352            <para>
353              A list of predefined values that the user is allowed
354              to select from. This option is only activated if the
355              <guilabel>Interface</guilabel> option is set
356              to <guilabel>selection list</guilabel> or
357              <guilabel>radiobuttons/checkboxes</guilabel>.
358              Actual values can be supplied using one line for each
359              value (a return entry is used as separator).
360            </para>
361          </listitem>
362        </varlistentry>
363
364        </variablelist>
365       
366        <seeother>
367          <other external_id="annotationtype.edit">Properties</other>
368          <other external_id="annotationtype.edit.items">Item types</other>
369          <other external_id="annotationtype.edit.units">Units</other>
370          <other external_id="annotationtype.edit.categories">Categories</other>
371        </seeother>
372      </helptext>
373    </sect2>
374   
375    <sect2 id="annotations.types.items">
376      <title>Item types</title>
377     
378      <figure
379        id="annotations.figures.annotationtype.items">
380        <title>Annotation type items</title>
381        <screenshot>
382          <mediaobject>
383            <imageobject>
384              <imagedata
385                fileref="figures/annotationtype_items.png" format="PNG" />
386            </imageobject>
387          </mediaobject>
388        </screenshot>
389      </figure>
390   
391      <helptext external_id="annotationtype.edit.items" 
392        title="Item types">
393       
394        <para>
395          On this tab you select the item types that you wish to
396          annotate with the annotation type. Simply use
397          left and right buttons to move selection options
398          between the <guilabel>Enabled for</guilabel>
399          and <guilabel>Disabled for</guilabel> lists.
400        </para>
401       
402        <note>
403          <para>
404          If the annotation type has been marked as a
405          <guilabel>Protocol</guilabel> parameter, these settings are
406          ignored, with one exception. If you wish to view parameter
407          values in the list view for a specific item type you must select
408          the item type here. Otherwise the parameter will not be present
409          as a displayable column.
410          </para>
411        </note>
412       
413        <seeother>
414          <other external_id="annotationtype.edit">Properties</other>
415          <other external_id="annotationtype.edit.options">Options</other>
416          <other external_id="annotationtype.edit.units">Units</other>
417          <other external_id="annotationtype.edit.categories">Categories</other>
418        </seeother>
419      </helptext>
420    </sect2>
421 
422    <sect2 id="annotations.types.units">
423      <title>Units</title>
424       
425      <figure
426        id="annotations.figures.annotationtype.units">
427        <title>Annotation type units</title>
428        <screenshot>
429          <mediaobject>
430            <imageobject>
431              <imagedata
432                fileref="figures/annotationtype_units.png" format="PNG" />
433            </imageobject>
434          </mediaobject>
435        </screenshot>
436      </figure>
437 
438      <helptext external_id="annotationtype.edit.units" 
439        title="Units">
440 
441        <para>
442        Numerical annotation types can optionally be given a quantity and unit.
443        </para>
444       
445        <variablelist>
446        <varlistentry>
447          <term><guilabel>Quantity</guilabel></term>
448          <listitem>
449            <para>
450            Select which quantity to use for the annotation type. If you
451            don't want to use units, select the <emphasis>do not use units</emphasis>
452            option.
453            </para>
454            <note>
455              <title>The quantity can't be changed later</title>
456              <para>
457              Once a quantity has been selected and saved for an
458              annotation type, it is not possible to change it to another
459              quantity.
460              </para>
461            </note>
462          </listitem>
463        </varlistentry>
464        <varlistentry>
465          <term><guilabel>Default unit</guilabel></term>
466          <listitem>
467            <para>
468            This list will be populated with units from the selected
469            quantity. You must select one default unit which is the unit
470            that is used if a user leaves out the unit when annotating
471            an item. The selected unit is also the unit that is used internally
472            when storing the values in the database.
473            </para>
474            <warning>
475              <title>Do not change the default unit</title>
476              <para>
477                If you change the default unit for an existing annotation type,
478                all annotation values that exists for it, must be converted to the
479                new unit. This may result in loss of precision due to rounding/truncation
480                errors.
481              </para>
482            </warning>
483          </listitem>
484        </varlistentry>
485       
486        <varlistentry>
487          <term><guilabel>Use units</guilabel></term>
488          <listitem>
489            <para>
490            By default, all units of the selected quantity can be used when
491            annotating items. If you want, you may force the users to use
492            some specific units by moving units into the <emphasis>Use units</emphasis>
493            list. This is recommended since the range of available units is usually
494            quite large. For example, if the weight of something is normally
495            measured in milligrams, it may make sense to leave out kilograms, and
496            only use microgram, milligram and gram.
497            </para>
498          </listitem>
499        </varlistentry>
500       
501        </variablelist>
502       
503        <seeother>
504          <other external_id="annotationtype.edit">Properties</other>
505          <other external_id="annotationtype.edit.options">Options</other>
506          <other external_id="annotationtype.edit.items">Item types</other>
507          <other external_id="annotationtype.edit.categories">Categories</other>
508        </seeother>
509       
510      </helptext>
511    </sect2>
512 
513    <sect2 id="annotations.types.categories">
514      <title>Categories</title>
515   
516      <helptext external_id="annotationtype.edit.categories" 
517        title="Categories">
518       
519        <para>
520          Annotation type can be grouped together by
521          placing them in one or more categories. This
522          enhances display by avoid overcrowding the list
523          of annotation types presented to users. It also
524          allows to improve the display of information.
525        </para>
526       
527        <para>
528          The <guilabel>Categories</guilabel> list displays
529          the currently associated categories. Use the
530          <guibutton>Add categories</guibutton> button
531          to add more categories, or the <guilabel>Remove</guilabel>
532          button to remove the selected categories.
533        </para>
534         
535        <seeother>
536          <other external_id="annotationtype.edit">Properties</other>
537          <other external_id="annotationtype.edit.options">Options</other>
538          <other external_id="annotationtype.edit.items">Item types</other>
539        </seeother>
540      </helptext>
541    </sect2>
542  </sect1>
543 
544  <sect1 id="annotations.categories">
545    <title>Annotation type categories</title>
546   
547    <para>
548      <guilabel>Annotation Type Categories</guilabel>
549      allow grouping of related Annotation Types, based on
550      users requirements.
551    </para>
552   
553    <para>
554      For managing categories go to
555      <menuchoice>
556        <guimenu>Administrate</guimenu>
557        <guimenuitem>Types</guimenuitem>
558          <guisubmenu>Annotation Type categories</guisubmenu>
559        </menuchoice>.
560    </para>
561
562    <example id="annotation_types.example.atcategory">
563      <title>Annotation category examples</title>
564     
565      <para>
566        <itemizedlist>
567        <listitem>
568          <para>
569          A category <userinput>Hematology Descriptors</userinput>
570          could be created to group together annotation types such as
571          <userinput>Lymphocyte count</userinput> and
572          <userinput>Hematocrite</userinput>
573          </para>
574        </listitem>
575       
576        <listitem>
577          <para>
578          A category <userinput>Plasma Clinical Descriptors</userinput>
579          could be created to group together annotation types such as
580          <userinput>ALT activity (UI/mL)</userinput> and
581          <userinput>LDH activity (UI/mL)</userinput>
582          </para>
583        </listitem>
584        </itemizedlist>
585      </para>
586    </example>
587   
588    <tip>
589      <para>
590      If you use the same name for a category as for an item subtype (see <xref linkend="subtypes" />)
591      the annotations in this category will be selected by default when editing an item item
592      by that subtype. This can be useful when you have two or more subtypes of the same
593      main item type and a different set of annotations that should be used on each subtype.
594      For example, <emphasis>Labeled extract</emphasis> and <emphasis>Library</emphasis>
595      are subtypes of <emphasis>Extract</emphasis>, which probably have different annotation
596      types.
597      </para>
598    </tip>
599   
600  </sect1>
601
602  <sect1 id="annotations.annotating">
603    <title>Annotating items</title>
604   
605    <para>
606      Entering annotation values follow the same pattern
607      for all items that can have annotations. They all have
608      a <guilabel>Annotations &amp; parameters</guilabel> tab
609      in their edit view. On this tab you can specify values
610      for all annotation types assigned to the type of item,
611      and all parameters that are attached to the protocol
612      used to create the item. Some items, for example
613      <emphasis>biosources</emphasis> and <emphasis>array designs</emphasis> 
614      cannot have a protocol. In their case the tab is labelled
615      <guilabel>Annotations</guilabel>.
616    </para>
617   
618    <figure
619      id="annotations.figures.annotate">
620      <title>Annotating a sample</title>
621      <screenshot>
622        <mediaobject>
623          <imageobject>
624            <imagedata
625              fileref="figures/annotate.png" format="PNG" />
626          </imageobject>
627        </mediaobject>
628      </screenshot>
629    </figure>
630
631    <helptext external_id="annotations.edit" 
632      title="Annotations &amp; parameters">
633
634      <para>
635        Click on an entry in the list of annotation types to show a
636        form for entering a value for it to the right. Depending
637        on the options set on the annotation type the form may be a simple
638        free text field, a list of checkboxes or radiobuttons, or
639        something else.
640      </para>
641     
642      <para>
643        Annotation types with an <guilabel>X</guilabel> in front
644        of their names already have a value.
645      </para>
646     
647      <para>
648        Annotation types marked with angle brackets
649        <nohelp>
650          (<guiicon>
651            <inlinemediaobject>
652              <imageobject><imagedata fileref="figures/parameter.gif" format="GIF"
653              /></imageobject>
654            </inlinemediaobject>
655          </guiicon>)
656        </nohelp>
657        are protocol parameters.
658      </para>
659     
660      <para>
661        Select an option in the <guilabel>Categories</guilabel> list to filter the
662        annotation types based on the categories
663        they belong to. This list contains all available
664        categories, and three special ones:
665        <itemizedlist>
666        <listitem>
667          <para>
668          <guilabel>all</guilabel>: Display all annotation types
669          </para>
670        </listitem>
671        <listitem>
672          <para>
673          <guilabel>protocol parameters</guilabel>: Display only
674          those annotation types that are parameters to the current
675          protocol.
676          </para>
677        </listitem>
678        <listitem>
679          <para>
680          <guilabel>uncategorized</guilabel>: Display only annotation types
681          that has not been put into a category.
682          </para>
683        </listitem>
684        </itemizedlist>
685      </para>
686     
687      <seeother>
688        <other external_id="annotations.edit.inherited">Inherit annotations</other>
689      </seeother>
690     
691    </helptext>
692   
693    <sect2 id="annotations.inheriting">
694      <title>Inheriting annotations from other items</title>
695     
696      <helptext external_id="annotations.edit.inherited" 
697        title="Inherit annotations">
698        <para>
699          An item may inherit annotations from any of it's parent items.
700          E.g. an extract can inherit annotations from the sample or biosource
701          it was created from. This is an important feature to make the
702          experimental factors work. Annotations that should be used as
703          experimental factors must be inherited to the raw bioassay level.
704          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more
705          information about experimental factors.</nohelp>
706        </para>
707       
708        <nohelp>
709        <figure
710          id="annotations.figures.inherit">
711          <title>Inheriting annotations from a parent item</title>
712          <screenshot>
713            <mediaobject>
714              <imageobject>
715                <imagedata
716                  fileref="figures/inherit_annotations.png" format="PNG" />
717              </imageobject>
718            </mediaobject>
719          </screenshot>
720        </figure>
721        </nohelp>
722   
723        <para>
724          On this screen is a tree-like structure in two levels. The first level
725          lists all parent items which has at least one annotations. The second
726          level lists the annotations and protocol parameters for the item.
727          Selecting an item in the first level will inherit all annotations
728          from that item, including those that you maybe add later.
729          Selecting an annotation or protocol parameter at the second level
730          will inherit only the selected one.
731        </para>
732       
733        <note>
734          <itemizedlist>
735          <listitem>
736            <para>
737            The inheritance is implemented by reference. This means that if
738            you change the value of an annotation the new value is automatically
739            picked up by those inheriting it.
740            </para>
741          </listitem>
742          <listitem>
743            <para>
744            You cannot inherit annotations from an item which does not have
745            annotations.
746            </para>
747          </listitem>
748          <listitem>
749            <para>
750            If you delete an annotation from a parent item, the inheritance will
751            be lost, even if you later add a value again.
752            </para>
753          </listitem>
754          </itemizedlist>
755        </note>
756       
757        <warning>
758          <para>
759          If you rearrange links to parent items after you have
760          specified inheritance, it may happen that you are inheriting
761          annotation from non-parent items. This will be flagged with a warning
762          icon in the list, and must be fixed manually. The item overview
763          tool is an excellent help for locating this kind of problems.
764          <nohelp>See <xref linkend="webclient.itemoverview" />.</nohelp>
765          </para>
766        </warning>
767   
768        <seeother>
769          <other external_id="annotations.edit">Annotations and parameters</other>
770          <other external_id="experiment.edit.factors">Experimental factors</other>
771          <other external_id="item.overview">Item overview tool</other>
772        </seeother>
773     
774      </helptext>     
775     
776    </sect2>
777   
778    <sect2 id="annotations.massimport">
779      <title>Mass annotation import plug-in</title>
780     
781      <para>
782        BASE includes a plug-in for importing annotations to multiple items
783        in one go. The plug-in read annotation values from a simple column-based
784        text file. Usually, a tab is used as the delimiter between columns, but this
785        is configurable.
786        The first row should contain the column headers. One column should contain
787        the name or the external ID of the item. The rest of the columns can each be
788        mapped to an annotation type and contains the annotation values. If a column
789        header exactly match the name of an annotation type, the plug-in will automatically
790        create the mapping, otherwise you must do it manually. You don't have to map
791        all columns if you don't want to.
792      </para>
793     
794      <para>
795        Each column can only contain a single annotation value for each row.
796        If you have annotation types that accept multiple values you can map
797        two or more columns to the same annotation type, or you can add an
798        extra row only giving the name and the extra annotation value.
799        Here is a simple example of a valid file with comma as column separator:
800      </para>
801     
802      <programlisting>
803# 'Time' and 'Age' are integer types
804# 'Subtype' is a string enumeration
805# 'Comment' is a text type that accept multiple values
806Name,Time (hours),Age (years),Subtype,Comment
807Sample #1,0,0,alfa,Very good
808Sample #2,24,0,beta,Not so bad
809Sample #2,,,,Yet another comment
810</programlisting>
811     
812      <para>
813        The plug-in can be used with or without a configuration. The configuration
814        keeps the regular expressions and other settings used to parse the file. If
815        you often import annotations from the same file format, we recommend that
816        you use a configuration. The mapping from file columns to annotation types
817        is not part of the configuration, it must be done each time the plug-in is used.
818      </para>
819     
820      <para>
821        The plug-in can be used from the list view of all annotatable items.
822        Using the plug-in is a three-step wizard:
823      </para>
824     
825      <orderedlist>
826      <listitem>
827        <para>
828        Select a file to import from and the regular expressions and other
829        settings used to parse the file. In this step you also select the column
830        that contains the name or external ID the items. If a configuration is used
831        all settings on this page, except the file to import from, already has values.
832        </para>
833      </listitem>
834     
835      <listitem>
836        <para>
837        The plug-in will start parsing the file until it finds the column headers.
838        You are asked to select an annotation type for each column.
839        </para>
840      </listitem>
841     
842      <listitem>
843        <para>
844        Set error handling options and some other import options.
845        </para>
846      </listitem>
847     
848      </orderedlist>
849     
850    </sect2>
851   
852  </sect1>
853
854</chapter>
Note: See TracBrowser for help on using the repository browser.