source: trunk/doc/src/docbook/user/annotations.xml @ 5782

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

References #1590: Documentation cleanup

Restructured documentation to generate shorter filenames.

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