source: branches/3.6-stable/doc/src/docbook/user/annotations.xml @ 6975

Last change on this file since 6975 was 6975, checked in by Nicklas Nordborg, 6 years ago

References #1941: Store experimental factor values as part experiments

Added 'Clone' button in the 'Inherit annotations' dialog to make it possible to clone annotations in a single step without having to re-select and clone in a second step.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 34.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 6975 2015-10-08 06:11:11Z 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 several 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 and is not
179            used by BASE.
180            </para>
181          </listitem>
182        </varlistentry>
183        <varlistentry>
184          <term><guilabel>Multiplicity</guilabel></term>
185          <listitem>
186            <para>
187              The maximum number of values that can be entered
188              for this annotation type. The default is 1. A value
189              of 0, means that any number of values can be used.
190            </para>
191          </listitem>
192        </varlistentry>
193        <varlistentry>
194          <term><guilabel>Default value</guilabel></term>
195          <listitem>
196            <para>
197              A value that can be used as the default when
198              adding values.
199            </para>
200          </listitem>
201        </varlistentry>
202        <varlistentry>
203          <term><guilabel>Required for MIAME</guilabel></term>
204          <listitem>
205            <para>
206              If a value must be specified for this annotation type
207              in order for the experiment to be compliant with MIAME.
208            </para>
209          </listitem>
210        </varlistentry>
211        <varlistentry>
212          <term><guilabel>Protocol parameter</guilabel></term>
213          <listitem>
214            <para>
215              If the annotation type is a protocol parameter. As a protocol
216              parameter an item can only be annotated if a protocol
217              that includes this parameter has been used.
218              <nohelp>See <xref linkend="protocols.parameters" /> 
219              for more information.</nohelp>
220            </para>
221          </listitem>
222        </varlistentry>
223        <varlistentry>
224          <term><guilabel>Disable change log</guilabel></term>
225          <listitem>
226            <para>
227              If this option is checked, change history logging does not include the
228              actual old/new annotation values. Note that the log will still contain
229              an entry that the annotation was modified. It is recomended that this
230              option is enabled for annotations containing sensitive data since
231              access permissions to the change history are different.
232            </para>
233          </listitem>
234        </varlistentry>
235        <varlistentry>
236          <term><guilabel>Disable inheritance</guilabel></term>
237          <listitem>
238            <para>
239              If this option is checked, annotations of this type are not allowed to be
240              inherited to other items. <nohelp>See <xref linkend="annotations.inheriting" /> 
241              for more information about inheritance.</nohelp> It is recomended that this
242              option is enabled for annotations containing sensitive data since
243              access permissions to inherited information may be different.
244            </para>
245            <warning>
246              <title>Existing inherited annotations are removed</title>
247              <para>
248                Be careful when enabling this option for an annotation type
249                if there are existing items that already inherit this annotation
250                type from their parents. The existing inheritance is automatically
251                dropped, and it will not be re-created if resetting this option
252                again.
253              </para>
254            </warning>
255           
256          </listitem>
257        </varlistentry>
258        <varlistentry>
259          <term><guilabel>Description</guilabel></term>
260          <listitem>
261            <para>
262              A short textual description
263              to clarify the usage.
264            </para>
265          </listitem>
266        </varlistentry>
267        </variablelist>
268       
269        <seeother>
270          <other external_id="annotationtype.edit.options">Options</other>
271          <other external_id="annotationtype.edit.items">Item types</other>
272          <other external_id="annotationtype.edit.units">Units</other>
273          <other external_id="annotationtype.edit.categories">Categories</other>
274          <other external_id="protocol.edit.parameters">Protocol parameters</other>
275        </seeother>
276      </helptext>
277   
278    </sect2>
279
280    <sect2 id="annotations.types.options">
281      <title>Options</title>
282
283      <figure
284        id="annotations.figures.annotationtype.options">
285        <title>Annotation type options</title>
286        <screenshot>
287          <mediaobject>
288            <imageobject>
289              <imagedata
290                fileref="figures/annotationtype_options.png" format="PNG" />
291            </imageobject>
292          </mediaobject>
293        </screenshot>
294      </figure>
295     
296      <helptext external_id="annotationtype.edit.options" 
297        title="Annotation type options">
298       
299        <para>
300          The available options in this tab depends on the type
301          of annotation type, eg. if is a string, numeric or
302          another type.
303        </para>
304       
305        <variablelist>
306        <varlistentry>
307          <term><guilabel>Interface</guilabel></term>
308          <listitem>
309            <para>
310            Select the type of graphical element to use for
311            entering values for the annotation type. You can select
312            between three different options:
313            <itemizedlist>
314            <listitem>
315              <para>
316              <guilabel>text box</guilabel>: The user must enter the value
317              in a free-text box.
318              </para>
319            </listitem>
320            <listitem>
321              <para>
322              <guilabel>selection list</guilabel>: The user must select
323              values from a list of predefined values.
324              </para>
325            </listitem>
326            <listitem>
327              <para>
328              <guilabel>radiobuttons/checkboxes</guilabel>: The user must
329              select values by marking checkboxes or radiobuttons.
330              </para>
331            </listitem>
332            </itemizedlist>
333           
334            The last two options requires that a list of values are
335            available. Enter possible values in the <guilabel>Values</guilabel>
336            which will be activated automatically.
337            </para>
338            <tip>
339              <para>
340                In term of usability, a drop-down
341                list can be more easily
342                navigated especially when the
343                number of possible values is
344                large, and because selection-list
345                and drop-down list allow use of
346                arrow and tab for selection.
347              </para>
348            </tip>
349          </listitem>
350        </varlistentry>
351       
352        <varlistentry>
353          <term><guilabel>Min/max value</guilabel></term>
354          <listitem>
355            <para>
356              Available for numerical annotation types only.
357              Specifies the minimum and maximum allowed value.
358              If left empty, the bound(s) are undefined and any
359              value is allowed.
360            </para>
361          </listitem>
362        </varlistentry>
363       
364        <varlistentry>
365          <term><guilabel>Max length</guilabel></term>
366          <listitem>
367            <para>
368              The maximum allowed length of a string annotation value.
369              If empty, 255 is the maximum length. If you need longer
370              values than that, use a <emphasis>text</emphasis> 
371              annotation type.
372            </para>
373          </listitem>
374        </varlistentry>
375
376        <varlistentry>
377          <term><guilabel>Input box width/height</guilabel></term>
378          <listitem>
379            <para>
380              A suggested display width and height of the element
381              used for input. These values are ignored in the current
382              implementation.
383            </para>
384          </listitem>
385        </varlistentry>
386
387        <varlistentry>
388          <term><guilabel>Values</guilabel></term>
389          <listitem>
390            <para>
391              A list of predefined values that the user is allowed
392              to select from. This option is only activated if the
393              <guilabel>Interface</guilabel> option is set
394              to <guilabel>selection list</guilabel> or
395              <guilabel>radiobuttons/checkboxes</guilabel>.
396              Actual values can be supplied using one line for each
397              value (a return entry is used as separator).
398            </para>
399          </listitem>
400        </varlistentry>
401
402        </variablelist>
403       
404        <seeother>
405          <other external_id="annotationtype.edit">Properties</other>
406          <other external_id="annotationtype.edit.items">Item types</other>
407          <other external_id="annotationtype.edit.units">Units</other>
408          <other external_id="annotationtype.edit.categories">Categories</other>
409        </seeother>
410      </helptext>
411    </sect2>
412   
413    <sect2 id="annotations.types.items">
414      <title>Item types</title>
415     
416      <figure
417        id="annotations.figures.annotationtype.items">
418        <title>Annotation type items</title>
419        <screenshot>
420          <mediaobject>
421            <imageobject>
422              <imagedata
423                fileref="figures/annotationtype_items.png" format="PNG" />
424            </imageobject>
425          </mediaobject>
426        </screenshot>
427      </figure>
428   
429      <helptext external_id="annotationtype.edit.items" 
430        title="Item types">
431       
432        <para>
433          On this tab you select the item types that you wish to
434          annotate with the annotation type. Simply use
435          left and right buttons to move selection options
436          between the <guilabel>Enabled for</guilabel>
437          and <guilabel>Disabled for</guilabel> lists.
438        </para>
439       
440        <note>
441          <para>
442          If the annotation type has been marked as a
443          <guilabel>Protocol parameter</guilabel>, these settings are
444          ignored, with one exception. If you wish to view parameter
445          values in the list view for a specific item type you must select
446          the item type here. Otherwise the parameter will not be present
447          as a displayable column.
448          </para>
449        </note>
450       
451        <seeother>
452          <other external_id="annotationtype.edit">Properties</other>
453          <other external_id="annotationtype.edit.options">Options</other>
454          <other external_id="annotationtype.edit.units">Units</other>
455          <other external_id="annotationtype.edit.categories">Categories</other>
456        </seeother>
457      </helptext>
458    </sect2>
459 
460    <sect2 id="annotations.types.units">
461      <title>Units</title>
462       
463      <figure
464        id="annotations.figures.annotationtype.units">
465        <title>Annotation type units</title>
466        <screenshot>
467          <mediaobject>
468            <imageobject>
469              <imagedata
470                fileref="figures/annotationtype_units.png" format="PNG" />
471            </imageobject>
472          </mediaobject>
473        </screenshot>
474      </figure>
475 
476      <helptext external_id="annotationtype.edit.units" 
477        title="Units">
478 
479        <para>
480        Numerical annotation types can optionally be given a quantity and unit.
481        </para>
482       
483        <variablelist>
484        <varlistentry>
485          <term><guilabel>Quantity</guilabel></term>
486          <listitem>
487            <para>
488            Select which quantity to use for the annotation type. If you
489            don't want to use units, select the <emphasis>do not use units</emphasis>
490            option.
491            </para>
492            <note>
493              <title>The quantity can't be changed later</title>
494              <para>
495              Once a quantity has been selected and saved for an
496              annotation type, it is not possible to change it to another
497              quantity.
498              </para>
499            </note>
500          </listitem>
501        </varlistentry>
502        <varlistentry>
503          <term><guilabel>Default unit</guilabel></term>
504          <listitem>
505            <para>
506            This list will be populated with units from the selected
507            quantity. You must select one default unit which is the unit
508            that is used if a user leaves out the unit when annotating
509            an item. The selected unit is also the unit that is used internally
510            when storing the values in the database.
511            </para>
512            <warning>
513              <title>Do not change the default unit</title>
514              <para>
515                If you change the default unit for an existing annotation type,
516                all annotation values that exists for it, must be converted to the
517                new unit. This may result in loss of precision due to rounding/truncation
518                errors.
519              </para>
520            </warning>
521          </listitem>
522        </varlistentry>
523       
524        <varlistentry>
525          <term><guilabel>Use units</guilabel></term>
526          <listitem>
527            <para>
528            By default, all units of the selected quantity can be used when
529            annotating items. If you want, you may force the users to use
530            some specific units by moving units into the <emphasis>Use units</emphasis>
531            list. This is recommended since the range of available units is usually
532            quite large. For example, if the weight of something is normally
533            measured in milligrams, it may make sense to leave out kilograms, and
534            only use microgram, milligram and gram.
535            </para>
536          </listitem>
537        </varlistentry>
538       
539        </variablelist>
540       
541        <seeother>
542          <other external_id="annotationtype.edit">Properties</other>
543          <other external_id="annotationtype.edit.options">Options</other>
544          <other external_id="annotationtype.edit.items">Item types</other>
545          <other external_id="annotationtype.edit.categories">Categories</other>
546        </seeother>
547       
548      </helptext>
549    </sect2>
550 
551    <sect2 id="annotations.types.categories">
552      <title>Categories</title>
553   
554      <figure
555        id="annotations.figures.annotationtype.categories">
556        <title>Annotation type categories</title>
557        <screenshot>
558          <mediaobject>
559            <imageobject>
560              <imagedata
561                fileref="figures/annotationtype_categories.png" format="PNG" />
562            </imageobject>
563          </mediaobject>
564        </screenshot>
565      </figure>
566     
567      <helptext external_id="annotationtype.edit.categories" 
568        title="Categories">
569       
570        <para>
571          Annotation type can be grouped together by
572          placing them in one or more categories. This
573          enhances display by avoid overcrowding the list
574          of annotation types presented to users. It also
575          allows to improve the display of information.
576        </para>
577       
578        <para>
579          The <guilabel>Categories</guilabel> list displays
580          the currently associated categories. Use the
581          <guibutton>Add categories</guibutton> button
582          to add more categories, or the <guilabel>Remove</guilabel>
583          button to remove the selected categories.
584        </para>
585       
586        <tip>
587          <title>Create categories with the same name as item subtypes</title>
588          <para>
589            If you, for example, have defined multiple subtypes of extracts
590            (see <xref linkend="subtypes" />),
591            it usually so that some annotation types are only intended for
592            one subtype while some other annotation types are only intended
593            for the other subtype. If you create categories with the same name
594            as the item subtypes, BASE will automatically select the corresponding
595            category when annotating an extract with a subtype. This makes the interface
596            cleaner and easier to use since irrelevant annotation types are hidden.
597            Note that it is possible for annotations to be part of more than one
598            category so it is also possible to define annotation types that are
599            intended for all types of extracts by including them in both categories.
600          </para>
601        </tip>
602       
603        <seeother>
604          <other external_id="annotationtype.edit">Properties</other>
605          <other external_id="annotationtype.edit.options">Options</other>
606          <other external_id="annotationtype.edit.items">Item types</other>
607        </seeother>
608      </helptext>
609    </sect2>
610  </sect1>
611 
612  <sect1 id="annotations.annotating">
613    <?dbhtml filename="annotating.html" ?>
614    <title>Annotating items</title>
615   
616    <para>
617      Entering annotation values follow the same pattern
618      for all items that can have annotations. They all have
619      a <guilabel>Annotations &amp; parameters</guilabel> tab
620      in their edit view. On this tab you can specify values
621      for all annotation types assigned to the type of item,
622      and all parameters that are attached to the protocol
623      used to create the item. Some items, for example
624      <emphasis>biosources</emphasis> and <emphasis>array designs</emphasis> 
625      cannot have a protocol. In their case the tab is labelled
626      <guilabel>Annotations</guilabel>.
627    </para>
628   
629    <figure
630      id="annotations.figures.annotate">
631      <title>Annotating a sample</title>
632      <screenshot>
633        <mediaobject>
634          <imageobject>
635            <imagedata
636              fileref="figures/annotate.png" format="PNG" />
637          </imageobject>
638        </mediaobject>
639      </screenshot>
640    </figure>
641
642    <helptext external_id="annotations.edit" 
643      title="Annotations &amp; parameters">
644
645      <para>
646        All possible annotation types are listed under the
647        <guilabel>Primary annotations</guilabel> section. Click
648        on an entry in the list to display a form for entering
649        a value for the annotation. Depending
650        on the options set on the annotation type the form may be a simple
651        free text field, a list of checkboxes or radiobuttons, or
652        something else.
653      </para>
654     
655      <para>
656        Annotation types with an <guilabel>x</guilabel> in front
657        of their names already have a value.
658      </para>
659     
660      <para>
661        Annotation types marked with angle brackets
662        <nohelp>
663          (<guiicon><inlinemediaobject><imageobject><imagedata fileref="figures/parameter.png" format="PNG"
664              /></imageobject></inlinemediaobject></guiicon>)
665        </nohelp>
666        are protocol parameters.
667      </para>
668     
669      <para>
670        Select an option in the <guilabel>Categories</guilabel> list to filter the
671        annotation types based on the categories
672        they belong to. This list contains all available
673        categories, and three special ones:
674        <itemizedlist>
675        <listitem>
676          <para>
677          <guilabel>all</guilabel>: Display all annotation types
678          </para>
679        </listitem>
680        <listitem>
681          <para>
682          <guilabel>protocol parameters</guilabel>: Display only
683          those annotation types that are parameters to the current
684          protocol.
685          </para>
686        </listitem>
687        <listitem>
688          <para>
689          <guilabel>uncategorized</guilabel>: Display only annotation types
690          that has not been put into a category.
691          </para>
692        </listitem>
693        </itemizedlist>
694      </para>
695     
696     
697      <seeother>
698        <other external_id="annotations.inherit">Inherit annotations</other>
699      </seeother>
700     
701    </helptext>
702   
703    <sect2 id="annotations.inheriting">
704      <title>Inheriting annotations from other items</title>
705     
706      <helptext external_id="annotations.inherit" 
707        title="Inherit annotations">
708        <para>
709          An item may inherit annotations from any of it's parent items.
710          E.g. an extract can inherit annotations from the sample or biosource
711          it was created from. This is an important feature to make the
712          experimental factors work. Annotations that should be used as
713          experimental factors must be inherited to the root raw bioassay level.
714          <nohelp>See <xref linkend="experiments_analysis.experiment.factors" /> for more
715          information about experimental factors.</nohelp> Click on the
716          <guibutton>Inherit&hellip;</guibutton> button to open a dialog for inheriting
717          annotations.
718        </para>
719       
720        <para>
721          Annotations can either be inherited by reference (the default) or as a cloned value. Inheriting
722          by reference means that if you change the value of the source annotation the new value is automatically
723          picked up by all items inheriting it. A cloned annotation is a copy
724          of the original annotation and it is not automatically updated if the original
725          annotation is modified.
726        </para>
727       
728        <para>
729          Inherited and cloned annotations are listed under the <guilabel>Inherited &amp; cloned</guilabel> 
730          section. Inherited annotations are marked with <guiicon><inlinemediaobject><imageobject><imagedata 
731            fileref="figures/inherited.png" format="PNG"
732            /></imageobject></inlinemediaobject></guiicon> and are always a references back to the original
733          value. Cloned annotations are marked with a double <guilabel>xx</guilabel>. Cloned annotations
734          that are out-of-sync with their source annotations are marked with <guiicon><inlinemediaobject><imageobject><imagedata 
735            fileref="figures/cloned-outofsync.png" format="PNG"
736            /></imageobject></inlinemediaobject></guiicon>.
737        </para>
738       
739        <variablelist>
740          <varlistentry>
741            <term>
742              <guilabel>Inherit...</guilabel>
743            </term>
744            <listitem>
745              <para>Opens the <guilabel>Inherit annotations</guilabel> dialog (see below).</para>
746            </listitem>
747          </varlistentry>
748          <varlistentry>
749            <term>
750              <guilabel>Delete</guilabel>
751            </term>
752            <listitem>
753              <para>
754                Will remove values from the checked primary annotations and delete
755                links to inherited and cloned annotations.
756              </para>
757            </listitem>
758          </varlistentry>
759          <varlistentry>
760            <term>
761              <guilabel>Sync, Clone, Unclone</guilabel>
762            </term>
763            <listitem>
764              <para>
765                Convert between INHERITED and CLONED annotation and synchronizes
766                cloned annotations with their source annotation in case the values
767                have changed.
768              </para>
769            </listitem>
770          </varlistentry>
771        </variablelist>
772       
773        <nohelp>
774        <figure
775          id="annotations.figures.inherit">
776          <title>Inheriting annotations from a parent item</title>
777          <screenshot>
778            <mediaobject>
779              <imageobject>
780                <imagedata
781                  fileref="figures/inherit_annotations.png" format="PNG" />
782              </imageobject>
783            </mediaobject>
784          </screenshot>
785        </figure>
786        </nohelp>
787   
788        <para>
789          In this dialog there is a tree-like structure in two levels to the left.
790          The first level
791          lists all parent items which has at least one annotation. The second
792          level lists the annotations and protocol parameters for the item.
793          Selecting an item in the first level will inherit all annotations
794          from that item. Selecting an annotation or protocol parameter at
795          the second level will inherit only the selected one.
796        </para>
797       
798        <para>
799          The filter field on the top of the dialog is a simple search filter to
800          make it easier to find a specific annotation. In large projects, the
801          parent tree may contain lots of items having hundreds of different
802          annotations. Use the filter to find annotations containing the
803          same text. The search is case-insensitive and will match anywhere
804          on the name of the annotation type, but not values. The filter only
805          affects what is displayed. Changes that have been made to hidden items
806          are still saved.
807        </para>
808       
809        <para>
810          Use the <guibutton>Inherit</guibutton> button to inherit the selected
811          annotations by reference, and the <guibutton>Clone</guibutton> button
812          to clone the values of the selected annotations.
813        </para>
814       
815        <note>
816          <itemizedlist>
817          <listitem>
818            <para>
819            Already inherited or cloned annotations are not shown in the dialog.
820            </para>
821          </listitem>
822          <listitem>
823            <para>
824            Annotations that are inherited by reference can easily be converted to
825            cloned annotations. Select the annotation in the list and click on the
826            <guilabel>clone</guilabel> link.
827            <nohelp>
828            <figure>
829              <title>Convert to a cloned annotation</title>
830              <screenshot>
831                <mediaobject>
832                  <imageobject>
833                    <imagedata
834                      fileref="figures/clone_annotation.png" format="PNG" />
835                  </imageobject>
836                </mediaobject>
837              </screenshot>
838            </figure>
839            </nohelp>
840            </para>
841          </listitem>
842          <listitem>
843            <para>
844            If you delete an annotation from a parent item, the inheritance will
845            be lost, even if you later add a value again.
846            </para>
847          </listitem>
848          </itemizedlist>
849        </note>
850       
851        <warning>
852          <para>
853          If you rearrange links to parent items after you have
854          specified inheritance, it may happen that you are inheriting
855          annotation from non-parent items. This will be flagged with a warning
856          icon in the list, and must be fixed manually. The item overview
857          tool is an excellent help for locating this kind of problems.
858          <nohelp>See <xref linkend="webclient.itemoverview" />.</nohelp>
859          </para>
860        </warning>
861   
862        <seeother>
863          <other external_id="annotations.edit">Annotations and parameters</other>
864          <other external_id="experiment.edit.factors">Experimental factors</other>
865          <other external_id="annotations.batch_inherit">Batch inherit annotations</other>
866          <other external_id="item.overview">Item overview tool</other>
867        </seeother>
868     
869      </helptext>     
870     
871    </sect2>
872   
873    <sect2 id="annotations.batch-inherit">
874      <title>Batch inherit annotations</title>
875     
876      <helptext external_id="annotations.batch_inherit" 
877        title="Batch inherit annotations">
878        <para>
879          Manually inheriting annotations on a per-item basis will quickly become a time-consuming
880          and boring task as the project gets larger. Typically, there is a given set of annotations
881          that should be inherited from different levels in the parent chain. This is possible
882          with the batch inherit feature. Open this dialog by selecting at least one item in the
883          list-view and then use the <guibutton>Inherit annotations&hellip;</guibutton> button
884          in the toolbar.
885        </para>
886       
887        <nohelp>
888        <figure
889          id="annotations.figures.batch_inherit">
890          <title>Batch inherit annotations</title>
891          <screenshot>
892            <mediaobject>
893              <imageobject>
894                <imagedata
895                  fileref="figures/batch_inherit_annotations.png" format="PNG" />
896              </imageobject>
897            </mediaobject>
898          </screenshot>
899        </figure>
900        </nohelp>
901       
902       
903        <variablelist>
904        <varlistentry>
905          <term><guilabel>Select annotation types</guilabel></term>
906          <listitem>
907            <para>
908              Use this button to select one or more annotation types that you want to inherit.
909              Once the selection has been made, the selected annotation types will be added to
910              the table in the dialog as shown on the screen shot.
911            </para>
912          </listitem>
913        </varlistentry>
914        <varlistentry>
915          <term><guilabel>Action</guilabel></term>
916          <listitem>
917            <para>
918              For each annotation type you can select if you want to
919              <guilabel>inherit</guilabel> or <guilabel>clone</guilabel> new annotations,
920              <guilabel>remove</guilabel> existing inherited annotations or
921              <guilabel>resync</guilabel> existing cloned annotation. It is possible to use different
922              actions for different annotation types.
923            </para>
924          </listitem>
925        </varlistentry>
926        <varlistentry>
927          <term><guilabel>Parent item type</guilabel></term>
928          <listitem>
929            <para>
930              In this list you can select if you want to inherit from
931              any type of parent or only from a specific type. This is
932              useful if the same annotation is present on multiple parent
933              levels. If the annotation type has been added to a category,
934              BASE will automatically try to guess the parent type (=the
935              parent type that has the same name as the category). This
936              option is disabled when removing annotations.
937            </para>
938          </listitem>
939        </varlistentry>
940        <varlistentry>
941          <term><guilabel>Options</guilabel></term>
942          <listitem>
943            <para>
944              You may specify if existing inherited annotations should be
945              replaced and if duplicate inheritance should be allowed or not.
946              The default is to replace existing annotations and not allow
947              duplicates.
948            </para>
949          </listitem>
950        </varlistentry>
951        </variablelist>
952       
953        <para>
954          Click on <guibutton>Ok</guibutton> to finish. The work is performed as a background job
955          on the server. The progress can be followed in the dialog. It may take a while to
956          complete if several items was selected since BASE will need to look up all parents
957          and determine if they have any annotations that match the critera that was set up.
958        </para>
959      </helptext>
960     
961    </sect2>
962   
963    <sect2 id="annotations.massimport">
964      <title>Mass annotation import plug-in</title>
965     
966      <para>
967        BASE includes a plug-in for importing annotations to multiple items
968        in one go. The plug-in read annotation values from a simple column-based
969        text file. Usually, a tab is used as the delimiter between columns, but this
970        is configurable.
971        The first row should contain the column headers. One column should contain
972        the name or the external ID of the item. The rest of the columns can each be
973        mapped to an annotation type and contains the annotation values. If a column
974        header exactly match the name of an annotation type, the plug-in will automatically
975        create the mapping, otherwise you must do it manually. You don't have to map
976        all columns if you don't want to.
977      </para>
978     
979      <para>
980        Each column can only contain a single annotation value for each row.
981        If you have annotation types that accept multiple values you can map
982        two or more columns to the same annotation type, or you can add an
983        extra row only giving the name and the extra annotation value.
984        Here is a simple example of a valid file with comma as column separator:
985      </para>
986     
987      <programlisting>
988# 'Time' and 'Age' are integer types
989# 'Subtype' is a string enumeration
990# 'Comment' is a text type that accept multiple values
991Name,Time (hours),Age (years),Subtype,Comment
992Sample #1,0,0,alfa,Very good
993Sample #2,24,0,beta,Not so bad
994Sample #2,,,,Yet another comment
995</programlisting>
996     
997      <para>
998        The plug-in can be used with or without a configuration. The configuration
999        keeps the regular expressions and other settings used to parse the file. If
1000        you often import annotations from the same file format, we recommend that
1001        you use a configuration. The mapping from file columns to annotation types
1002        is not part of the configuration, it must be done each time the plug-in is used.
1003      </para>
1004     
1005      <para>
1006        The plug-in can be used from the list view of all annotatable items.
1007        Using the plug-in is a three-step wizard:
1008      </para>
1009     
1010      <orderedlist>
1011      <listitem>
1012        <para>
1013        Select a file to import from and the regular expressions and other
1014        settings used to parse the file. In this step you also select the column
1015        that contains the name or external ID the items. If a configuration is used
1016        all settings on this page, except the file to import from, already has values.
1017        </para>
1018      </listitem>
1019     
1020      <listitem>
1021        <para>
1022        The plug-in will start parsing the file until it finds the column headers.
1023        You are asked to select an annotation type for each column.
1024        </para>
1025      </listitem>
1026     
1027      <listitem>
1028        <para>
1029        Set error handling options and some other import options.
1030        </para>
1031      </listitem>
1032     
1033      </orderedlist>
1034     
1035    </sect2>
1036   
1037  </sect1>
1038
1039</chapter>
Note: See TracBrowser for help on using the repository browser.