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

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

References #1590: Documentation cleanup

FAQ section and removed information related to the Tab2Mage exporter.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 26.3 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 5682 2011-08-02 07:09:56Z 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>BioAssaysets</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 8 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>Min/max value</guilabel></term>
328          <listitem>
329            <para>
330              Available for numerical annotation types only.
331              Specifies the minimum and maximum allowed value.
332              If left empty, the bound(s) are undefined and any
333              value is allowed.
334            </para>
335          </listitem>
336        </varlistentry>
337       
338        <varlistentry>
339          <term><guilabel>Max length</guilabel></term>
340          <listitem>
341            <para>
342              The maximum allowed length of a string annotation value.
343              If empty, 255 is the maximum length. If you need longer
344              values than that, use a <emphasis>text</emphasis> 
345              annotation type.
346            </para>
347          </listitem>
348        </varlistentry>
349
350        <varlistentry>
351          <term><guilabel>Input box width/height</guilabel></term>
352          <listitem>
353            <para>
354              A suggested display width and height of the element
355              used for input. These values are ignored in the current
356              implementation.
357            </para>
358          </listitem>
359        </varlistentry>
360
361        <varlistentry>
362          <term><guilabel>Values</guilabel></term>
363          <listitem>
364            <para>
365              A list of predefined values that the user is allowed
366              to select from. This option is only activated if the
367              <guilabel>Interface</guilabel> option is set
368              to <guilabel>selection list</guilabel> or
369              <guilabel>radiobuttons/checkboxes</guilabel>.
370              Actual values can be supplied using one line for each
371              value (a return entry is used as separator).
372            </para>
373          </listitem>
374        </varlistentry>
375
376        </variablelist>
377       
378        <seeother>
379          <other external_id="annotationtype.edit">Properties</other>
380          <other external_id="annotationtype.edit.items">Item types</other>
381          <other external_id="annotationtype.edit.units">Units</other>
382          <other external_id="annotationtype.edit.categories">Categories</other>
383        </seeother>
384      </helptext>
385    </sect2>
386   
387    <sect2 id="annotations.types.items">
388      <title>Item types</title>
389     
390      <figure
391        id="annotations.figures.annotationtype.items">
392        <title>Annotation type items</title>
393        <screenshot>
394          <mediaobject>
395            <imageobject>
396              <imagedata
397                fileref="figures/annotationtype_items.png" format="PNG" />
398            </imageobject>
399          </mediaobject>
400        </screenshot>
401      </figure>
402   
403      <helptext external_id="annotationtype.edit.items" 
404        title="Item types">
405       
406        <para>
407          On this tab you select the item types that you wish to
408          annotate with the annotation type. Simply use
409          left and right buttons to move selection options
410          between the <guilabel>Enabled for</guilabel>
411          and <guilabel>Disabled for</guilabel> lists.
412        </para>
413       
414        <note>
415          <para>
416          If the annotation type has been marked as a
417          <guilabel>Protocol</guilabel> parameter, these settings are
418          ignored, with one exception. If you wish to view parameter
419          values in the list view for a specific item type you must select
420          the item type here. Otherwise the parameter will not be present
421          as a displayable column.
422          </para>
423        </note>
424       
425        <seeother>
426          <other external_id="annotationtype.edit">Properties</other>
427          <other external_id="annotationtype.edit.options">Options</other>
428          <other external_id="annotationtype.edit.units">Units</other>
429          <other external_id="annotationtype.edit.categories">Categories</other>
430        </seeother>
431      </helptext>
432    </sect2>
433 
434    <sect2 id="annotations.types.units">
435      <title>Units</title>
436       
437      <figure
438        id="annotations.figures.annotationtype.units">
439        <title>Annotation type units</title>
440        <screenshot>
441          <mediaobject>
442            <imageobject>
443              <imagedata
444                fileref="figures/annotationtype_units.png" format="PNG" />
445            </imageobject>
446          </mediaobject>
447        </screenshot>
448      </figure>
449 
450      <helptext external_id="annotationtype.edit.units" 
451        title="Units">
452 
453        <para>
454        Numerical annotation types can optionally be given a quantity and unit.
455        </para>
456       
457        <variablelist>
458        <varlistentry>
459          <term><guilabel>Quantity</guilabel></term>
460          <listitem>
461            <para>
462            Select which quantity to use for the annotation type. If you
463            don't want to use units, select the <emphasis>do not use units</emphasis>
464            option.
465            </para>
466            <note>
467              <title>The quantity can't be changed later</title>
468              <para>
469              Once a quantity has been selected and saved for an
470              annotation type, it is not possible to change it to another
471              quantity.
472              </para>
473            </note>
474          </listitem>
475        </varlistentry>
476        <varlistentry>
477          <term><guilabel>Default unit</guilabel></term>
478          <listitem>
479            <para>
480            This list will be populated with units from the selected
481            quantity. You must select one default unit which is the unit
482            that is used if a user leaves out the unit when annotating
483            an item. The selected unit is also the unit that is used internally
484            when storing the values in the database.
485            </para>
486            <warning>
487              <title>Do not change the default unit</title>
488              <para>
489                If you change the default unit for an existing annotation type,
490                all annotation values that exists for it, must be converted to the
491                new unit. This may result in loss of precision due to rounding/truncation
492                errors.
493              </para>
494            </warning>
495          </listitem>
496        </varlistentry>
497       
498        <varlistentry>
499          <term><guilabel>Use units</guilabel></term>
500          <listitem>
501            <para>
502            By default, all units of the selected quantity can be used when
503            annotating items. If you want, you may force the users to use
504            some specific units by moving units into the <emphasis>Use units</emphasis>
505            list. This is recommended since the range of available units is usually
506            quite large. For example, if the weight of something is normally
507            measured in milligrams, it may make sense to leave out kilograms, and
508            only use microgram, milligram and gram.
509            </para>
510          </listitem>
511        </varlistentry>
512       
513        </variablelist>
514       
515        <seeother>
516          <other external_id="annotationtype.edit">Properties</other>
517          <other external_id="annotationtype.edit.options">Options</other>
518          <other external_id="annotationtype.edit.items">Item types</other>
519          <other external_id="annotationtype.edit.categories">Categories</other>
520        </seeother>
521       
522      </helptext>
523    </sect2>
524 
525    <sect2 id="annotations.types.categories">
526      <title>Categories</title>
527   
528      <helptext external_id="annotationtype.edit.categories" 
529        title="Categories">
530       
531        <para>
532          Annotation type can be grouped together by
533          placing them in one or more categories. This
534          enhances display by avoid overcrowding the list
535          of annotation types presented to users. It also
536          allows to improve the display of information.
537        </para>
538       
539        <para>
540          The <guilabel>Categories</guilabel> list displays
541          the currently associated categories. Use the
542          <guibutton>Add categories</guibutton> button
543          to add more categories, or the <guilabel>Remove</guilabel>
544          button to remove the selected categories.
545        </para>
546         
547        <seeother>
548          <other external_id="annotationtype.edit">Properties</other>
549          <other external_id="annotationtype.edit.options">Options</other>
550          <other external_id="annotationtype.edit.items">Item types</other>
551        </seeother>
552      </helptext>
553    </sect2>
554  </sect1>
555 
556  <sect1 id="annotations.categories">
557    <title>Annotation type categories</title>
558   
559    <para>
560      <guilabel>Annotation Type Categories</guilabel>
561      allow grouping of related Annotation Types, based on
562      users requirements.
563    </para>
564   
565    <para>
566      For managing categories go to
567      <menuchoice>
568        <guimenu>Administrate</guimenu>
569        <guimenuitem>Types</guimenuitem>
570          <guisubmenu>Annotation Type categories</guisubmenu>
571        </menuchoice>.
572    </para>
573
574    <example id="annotation_types.example.atcategory">
575      <title>Annotation category examples</title>
576     
577      <para>
578        <itemizedlist>
579        <listitem>
580          <para>
581          A category <userinput>Hematology Descriptors</userinput>
582          could be created to group together annotation types such as
583          <userinput>Lymphocyte count</userinput> and
584          <userinput>Hematocrite</userinput>
585          </para>
586        </listitem>
587       
588        <listitem>
589          <para>
590          A category <userinput>Plasma Clinical Descriptors</userinput>
591          could be created to group together annotation types such as
592          <userinput>ALT activity (UI/mL)</userinput> and
593          <userinput>LDH activity (UI/mL)</userinput>
594          </para>
595        </listitem>
596        </itemizedlist>
597      </para>
598    </example>
599  </sect1>
600
601  <sect1 id="annotations.annotating">
602    <title>Annotating items</title>
603   
604    <para>
605      Entering annotation values follow the same pattern
606      for all items that can have annotations. They all have
607      a <guilabel>Annotations &amp; parameters</guilabel> tab
608      in their edit view. On this tab you can specify values
609      for all annotation types assigned to the type of item,
610      and all parameters that are attached to the protocol
611      used to create the item. Some items, for example
612      <emphasis>biosources</emphasis> and <emphasis>array designs</emphasis> 
613      cannot have a protocol. In their case the tab is labelled
614      <guilabel>Annotations</guilabel>.
615    </para>
616   
617    <figure
618      id="annotations.figures.annotate">
619      <title>Annotating a sample</title>
620      <screenshot>
621        <mediaobject>
622          <imageobject>
623            <imagedata
624              fileref="figures/annotate.png" format="PNG" />
625          </imageobject>
626        </mediaobject>
627      </screenshot>
628    </figure>
629
630    <helptext external_id="annotations.edit" 
631      title="Annotations &amp; parameters">
632
633      <para>
634        Click on an entry in the list of annotation types to show a
635        form for entering a value for it to the right. Depending
636        on the options set on the annotation type the form may be a simple
637        free text field, a list of checkboxes or radiobuttons, or
638        something else.
639      </para>
640     
641      <para>
642        Annotation types with an <guilabel>X</guilabel> in front
643        of their names already have a value.
644      </para>
645     
646      <para>
647        Annotation types marked with angle brackets
648        <nohelp>
649          (<guiicon>
650            <inlinemediaobject>
651              <imageobject><imagedata fileref="figures/parameter.gif" format="GIF"
652              /></imageobject>
653            </inlinemediaobject>
654          </guiicon>)
655        </nohelp>
656        are protocol parameters.
657      </para>
658     
659      <para>
660        Select an option in the <guilabel>Categories</guilabel> list to filter the
661        annotation types based on the categories
662        they belong to. This list contains all available
663        categories, and three special ones:
664        <itemizedlist>
665        <listitem>
666          <para>
667          <guilabel>all</guilabel>: Display all annotation types
668          </para>
669        </listitem>
670        <listitem>
671          <para>
672          <guilabel>protocol parameters</guilabel>: Display only
673          those annotation types that are parameters to the current
674          protocol.
675          </para>
676        </listitem>
677        <listitem>
678          <para>
679          <guilabel>uncategorized</guilabel>: Display only annotation types
680          that has not been put into a category.
681          </para>
682        </listitem>
683        </itemizedlist>
684      </para>
685     
686      <seeother>
687        <other external_id="annotations.edit.inherited">Inherit annotations</other>
688      </seeother>
689     
690    </helptext>
691   
692    <sect2 id="annotations.inheriting">
693      <title>Inheriting annotations from other items</title>
694     
695      <helptext external_id="annotations.edit.inherited" 
696        title="Inherit annotations">
697        <para>
698          An item may inherit annotations from any of it's parent items.
699          E.g. an extract can inherit annotations from the sample or biosource
700          it was created from. This is an important feature to make the
701          experimental factors work. Annotations that should be used as
702          experimental factors must be inherited to the raw bioassay level.
703          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more
704          information about experimental factors.</nohelp>
705        </para>
706       
707        <nohelp>
708        <figure
709          id="annotations.figures.inherit">
710          <title>Inheriting annotations from a parent item</title>
711          <screenshot>
712            <mediaobject>
713              <imageobject>
714                <imagedata
715                  fileref="figures/inherit_annotations.png" format="PNG" />
716              </imageobject>
717            </mediaobject>
718          </screenshot>
719        </figure>
720        </nohelp>
721   
722        <para>
723          On this screen is a tree-like structure in two levels. The first level
724          lists all parent items which has at least one annotations. The second
725          level lists the annotations and protocol parameters for the item.
726          Selecting an item in the first level will inherit all annotations
727          from that item, including those that you maybe add later.
728          Selecting an annotation or protocol parameter at the second level
729          will inherit only the selected one.
730        </para>
731       
732        <note>
733          <itemizedlist>
734          <listitem>
735            <para>
736            The inheritance is implemented by reference. This means that if
737            you change the value of an annotation the new value is automatically
738            picked up by those inheriting it.
739            </para>
740          </listitem>
741          <listitem>
742            <para>
743            You cannot inherit annotations from an item which does not have
744            annotations.
745            </para>
746          </listitem>
747          <listitem>
748            <para>
749            If you delete an annotation from a parent item, the inheritance will
750            be lost, even if you later add a value again.
751            </para>
752          </listitem>
753          </itemizedlist>
754        </note>
755       
756        <warning>
757          <para>
758          If you rearrange links to parent items after you have
759          specified inheritance, it may happen that you are inheriting
760          annotation from non-parent items. This will be flagged with a warning
761          icon in the list, and must be fixed manually. The item overview
762          tool is an excellent help for locating this kind of problems.
763          <nohelp>See <xref linkend="webclient.itemoverview" />.</nohelp>
764          </para>
765        </warning>
766   
767        <seeother>
768          <other external_id="annotations.edit">Annotations and parameters</other>
769          <other external_id="experiment.edit.factors">Experimental factors</other>
770          <other external_id="item.overview">Item overview tool</other>
771        </seeother>
772     
773      </helptext>     
774     
775    </sect2>
776   
777    <sect2 id="annotations.massimport">
778      <title>Mass annotation import plug-in</title>
779     
780      <para>
781        BASE includes a plug-in for importing annotations to multiple items
782        in one go. The plug-in read annotation values from a simple column-based
783        text file. Usually, a tab is used as the delimiter between columns.
784        The first row should contain the column headers. One column should contain
785        the name or the external ID of the item. The rest of the columns can each be
786        mapped to an annotation type and contains the annotation values. If a column
787        header exactly match the name of an annotation type, the plug-in will automatically
788        create the mapping, otherwise you must do it manually. You don't have to map
789        all columns if you don't want to.
790      </para>
791     
792      <para>
793        Each column can only contain a single annotation value for each row.
794        If you have annotation types that accept multiple values you can map
795        two or more columns to the same annotation type, or you can add an
796        extra row only giving the name and the extra annotation value.
797        Here is a simple example of a valid file with comma as column separator:
798      </para>
799     
800      <programlisting>
801# 'Time' and 'Age' are integer types
802# 'Subtype' is a string enumeration
803# 'Comment' is a text type that accept multiple values
804Name,Time (hours),Age (years),Subtype,Comment
805Sample #1,0,0,alfa,Very good
806Sample #2,24,0,beta,Not so bad
807Sample #2,,,,Yet another comment
808</programlisting>
809     
810      <para>
811        The plug-in can be used with or without a configuration. The configuration
812        keeps the regular expressions and other settings used to parse the file. If
813        you often import annotations from the same file format, we recommend that
814        you use a configuration. The mapping from file columns to annotation types
815        is not part of the configuration, it must be done each time the plug-in is used.
816      </para>
817     
818      <para>
819        The plug-in can be used from the list view of all annotatable items.
820        Using the plug-in is a three-step wizard:
821      </para>
822     
823      <orderedlist>
824      <listitem>
825        <para>
826        Select a file to import from and the regular expressions and other
827        settings used to parse the file. In this step you also select the column
828        that contains the name or external ID the items. If a configuration is used
829        all settings on this page, except the file to import from, already has values.
830        </para>
831      </listitem>
832     
833      <listitem>
834        <para>
835        The plug-in will start parsing the file until it finds the column headers.
836        You are asked to select an annotation type for each column.
837        </para>
838      </listitem>
839     
840      <listitem>
841        <para>
842        Set error handling options and some other import options.
843        </para>
844      </listitem>
845     
846      </orderedlist>
847     
848    </sect2>
849   
850  </sect1>
851
852</chapter>
Note: See TracBrowser for help on using the repository browser.