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

Last change on this file since 3372 was 3372, checked in by philippe, 16 years ago
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 29.5 KB
1<?xml version="1.0" encoding="UTF-8"?>
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 3372 2007-05-24 08:45:06Z philippe $
8        Copyright (C) Authors contributing to this file.
10        This file is part of BASE - BioArray Software Environment.
11        Available at
13        BASE is free software; you can redistribute it and/or
14        modify it under the terms of the GNU General Public License
15        as published by the Free Software Foundation; either version 2
16        of the License, or (at your option) any later version.
18        BASE is distributed in the hope that it will be useful,
19        but WITHOUT ANY WARRANTY; without even the implied warranty of
21        GNU General Public License for more details.
23        You should have received a copy of the GNU General Public License
24        along with this program; if not, write to the Free Software
25        Foundation, Inc., 59 Temple Place - Suite 330,
26        Boston, MA  02111-1307, USA.
27    --> 
29<chapter id="annotations">
30    <title>Annotation Types</title>
31    <sect1 id="annotations.introduction">
32        <title>Introduction</title>
33        <para>BASE2 has been engineered to closely map the <ulink
34                url="">MIAME concepts</ulink>. However, since
35            MIAME is focused on microarray processing workflow, information about the description
36            biological samples themselves was left out. BASE2 users are free to annotate
37            Biomaterials (and most BASE2 items) as they wish, from basic free text description to
38            more advanced ontology based terms. To accomodate the annotation needs of users eager
39            with detailed sample annotations and also the needs of very different communities, BASE2
40            provides a mechanism that allows a high level of annotation customization. BASE2 allows
41            to create descriptive elements for both quantitative annotation and qualitative
42            annotation of Biomaterials via the <guilabel>Annotation Type mechanism</guilabel>.
43            Actually, Annotation Types can be used to annotate not only Biomaterials but almost all
44            BASE2 items, from <guilabel>Plates</guilabel> to <guilabel>Protocols</guilabel> and
45                <guilabel>BioAssaysets</guilabel> This chapter details how to manage and use these
46            elements.</para>
47    </sect1>
48    <sect1 id="annotations.manage">
49        <title>Managing Annotation Types</title>
50        <para> </para>
51        <sect2 id="annotations.manage.create_at">
52            <title>Creating Annotation Types</title>
53            <para>Go To <menuchoice>
54                    <guimenu>Administrate</guimenu>
55                    <guimenuitem>Types</guimenuitem>
56                    <guisubmenu>AnnotationTypes</guisubmenu>
57                </menuchoice>
58            </para>
59            <para> Click on <guibutton>New&hellip;</guibutton> and select one of the 8 different
60                types which can be split in 4 main groups</para>
61            <itemizedlist spacing="compact">
62                <listitem>
63                    <para><guilabel>Integer</guilabel>, <guilabel>Long</guilabel>,
64                        <guilabel>Float</guilabel> and <guilabel>Double</guilabel> for Numerical
65                        Annotation Types.</para>
66                </listitem>
68                <listitem>
69                    <para><guilabel>String</guilabel> and <guilabel>text</guilabel> for textual
70                        Annotation Types .</para>
71                </listitem>
73                <listitem>
74                    <para><guilabel>Boolean</guilabel> for declaring Annotation Types that can take
75                        one of 2 possible values.</para>
76                </listitem>
78                <listitem>
79                    <para><guilabel>Boolean</guilabel> for declaring Annotation Type used as
80                        calendar/time stamps.</para>
81                </listitem>
82            </itemizedlist>
83            <note>
84                <para>These distinctions matter essentially to database administrators who need fine
85                    tuning of database settings. Therefore, creation of Annotation Type should be
86                    supervised by system administrators.</para>
87            </note>
88            <para> A <guilabel>Create</guilabel> pop-up window opens. It contains 4 different tabs: </para>
89            <orderedlist numeration="loweralpha" spacing="compact">
90                <listitem>
91                    <para>
92                        <guilabel>Annotation type</guilabel>
93                    </para>
94                    <para> It allows definition of core properties of the newly created annotation
95                        type. This includes specifying: </para>
96                    <itemizedlist spacing="compact">
97                        <listitem>
98                            <para>How the <guilabel>Annotation Type</guilabel> should be
99                            named.</para>
100                        </listitem>
101                        <listitem>
102                            <para>If the <guilabel>Annotation Type</guilabel> should be treated as a
103                                    <guilabel>protocol parameter</guilabel>.</para>
104                        </listitem>
105                        <listitem>
106                            <para>If the <guilabel>Annotation Type</guilabel> should be considered
107                                as <guilabel>MIAME required</guilabel>.</para>
108                        </listitem>
109                        <listitem>
110                            <para>If a <guilabel>default value</guilabel> should be
111                            available.</para>
112                        </listitem>
113                        <listitem>
114                            <para>If more than one option can be selected by setting the
115                                    <guilabel>multiplicity</guilabel> to more than one.</para>
116                        </listitem>
117                        <listitem>
118                            <para>Finally, one can add a short textual description of the
119                                    <guilabel>Annotation Type</guilabel> being created, to clarify
120                                its usage.</para>
121                        </listitem>
122                    </itemizedlist>
123                    <figure id="write_docbook_doc.figures.annotationtype">
124                        <title>The Annotation type tab of the Create Window for a String Annotation
125                            Type</title>
126                        <screenshot>
127                            <mediaobject>
128                                <imageobject>
129                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype.png" format="PNG"/>
130                                </imageobject>
131                            </mediaobject>
132                        </screenshot>
133                    </figure>
134                </listitem>
135                <listitem>
136                    <para>
137                        <guilabel>Options</guilabel>
138                    </para>
139                    <para> The tab allows tuning the interaction options with the Web Graphical User
140                        Interface when using Annotation types: <itemizedlist spacing="compact">
141                            <listitem>
142                                <para>Choosing <guilabel>text box</guilabel> option allows free text
143                                    to be entered.</para>
144                            </listitem>
145                            <listitem>
146                                <para>Choosing the <guilabel>selection list</guilabel> option
147                                    activates the 'value' section. Actual values can be supplied
148                                    using one line for each value (a return entry is used as
149                                    separator).</para>
150                                <para>It enables administrator to declare the list of possible
151                                    values using the "values" box.</para>
152                            </listitem>
153                            <listitem>
154                                <para>Choosing the <guilabel>radio button/checkboxes</guilabel>
155                                    option activates the <guilabel>value</guilabel> section. Actual
156                                    values can be supplied using one line for each value (a return
157                                    entry is used as separator).</para>
158                                <para>When selecting radio-button instead of selection list, this
159                                    will alter the interface in order to allow user to tick button
160                                    instead of selecting from a drop-down list.</para>
161                                <tip>
162                                    <para>In term of usability, drop-down list can be more easily
163                                        navigated especially when the number of possible values is
164                                        large, and because selectionlist and drop-down list allow
165                                        use of arrow and tab for selection.</para>
166                                </tip>
167                            </listitem>
168                            <listitem>
169                                <para>GUI Variations depending on the type of Annotation Types: </para>
170                                <para>Depending on the nature of the annotation type being created
171                                    (e.g. whether it is a boolean, a string or a date), the
172                                        <guilabel>Options</guilabel> tab may display specific
173                                    fields.</para>
174                                <para>When creating an Annotation Type of Type Boolean, the default
175                                    value field is replaced by the true or false radio-button in
176                                    order to allow specification of a value.</para>
177                                <para>Also, when using numerical AnnotationTypes, upper and lower
178                                    limit can be defined.</para>
179                            </listitem>
180                        </itemizedlist>
181                    </para>
182                    <figure id="write_docbook_doc.figures.annotationtype-option">
183                        <title>The Option tab of the Create Window for a String Annotation Type</title>
184                        <screenshot>
185                                    <mediaobject>
186                                        <imageobject>
187                                            <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-option.png" format="PNG"/>
188                                        </imageobject>
189                                    </mediaobject>
190                                </screenshot>
191                    </figure>
192                </listitem>
193                <listitem>
194                    <para>
195                        <guilabel>Item types</guilabel>
196                    </para>
197                    <para> The Item types tab is used to defined which BASE2 entities can be
198                        annotated using the newly creating Annotation Type. Simply use
199                            <guiicon>arrow left|right</guiicon> to moved items between the
200                            <guilabel>disabled for</guilabel> and <guilabel>enabled for</guilabel>
201                        <note>
202                            <para>Experiment item can not be annotated using Annotation Type</para>
203                        </note>
204                    </para>
205                    <figure id="write_docbook_doc.figures.annotationtype-item">
206                        <title>The Item tab of the Create Window for a String Annotation Type</title>
207                        <screenshot>
208                            <mediaobject>
209                                <imageobject>
210                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-item.png" format="PNG"/>
211                                </imageobject>
212                            </mediaobject>
213                        </screenshot>
214                    </figure>
215                </listitem>
216                <listitem>
217                    <para>
218                        <guilabel>Categories</guilabel>
219                    </para>
220                    <para> Annotation Type can be grouped together thanks to the Annotation Category
221                        functionality. This enhances display by avoid overcrowding the list of
222                        annotation types presented to users. It also allows to improve the display of
223                        information. </para>
224                    <figure id="write_docbook_doc.figures.annotationtype-categories">
225                        <title>The categories tab of the Create Window for a String Annotation Type</title>
226                        <screenshot>
227                            <mediaobject>
228                                <imageobject>
229                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-categories.png" format="PNG"/>
230                                </imageobject>
231                            </mediaobject>
232                        </screenshot>
233                    </figure>
234                </listitem>
235            </orderedlist>
237            <para>Click on the <inlinemediaobject>
238                    <imageobject>
239                        <imagedata fileref="figures/save.gif" format="GIF"/>
240                    </imageobject>
241                </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject>
242                    <imageobject>
243                        <imagedata fileref="figures/cancel.gif" format="GIF"/>
244                    </imageobject>
245                </inlinemediaobject> to abort. </para>
247        </sect2>
248        <sect2 id="annotations.manage.update">
249            <title>Updating Annotation Types</title>
250            <para>Using the <keycap>CTRL</keycap>, <keycap>ALT</keycap>, <keycap>SHIFT</keycap> key
251                combination, click on the Annotation Type to be modified from the Annotation Type
252                List View</para>
253            <para>The <guilabel>Edit</guilabel> pop-up window opens, presenting the various tabs
254                presented in the previous section.</para>
255            <note>
256                <para>Everything is editable except the Annotation Type Type itself, which is
257                    immutable and set once and for all upon creation</para>
258            </note>
259        </sect2>
260        <sect2 id="annotations.manage.create_atcategory">
261            <title>Grouping Annotation Type into Categories</title>
262            <para>
263                <guilabel>Annotation Type Categories</guilabel> allow grouping of related Annotation
264                Types, based on users requirements. </para>
265            <para>For creating a new category, go to: </para>
266            <para>
267                <menuchoice>
268                    <guimenu>Administrate</guimenu>
269                    <guimenuitem>Types</guimenuitem>
270                    <guisubmenu>Annotation Type categories</guisubmenu>
271                </menuchoice>
272            </para>
273            <para>Click on <guibutton>New&hellip;</guibutton></para>
274            <para>a pop-up window opens.</para>
275            <para>It contains 2 tabs, one for declaring name and description of the newly created
276                category, the second tab is to provide the list of annotation type to be grouped
277                together under this container.</para>
278            <example id="annotation_types.example.atcategory">
279                <title>A category 'Hematology Descriptors' could be created to group together
280                    Annotation Types such as 'Lymphocyte count' and 'Hematocrite' </title>
281            </example>
282            <example id="annotation_types.example.atcategory-2">
283                <title>A category 'Plasma Clinical Descriptors' could be created to group together
284                    Annotation Types such as 'ALT activity (UI/mL)' and 'LDH activity (UI/mL').
285                </title>
286            </example>
287        </sect2>
289        <sect2 id="annotations.manage.batchupload">
290            <title>Batchloading Annotation Types from file</title>
291            <para>A plugin, CVLoader.jar, has been specially devised with 2 purposes in mind:</para>
292            <orderedlist>
293                <listitem>
294                    <para>To speed-up data Annotation Type declaration and upload in the BASE2
295                        system.</para>
296                </listitem>
297                <listitem>
298                    <para>To enable sharing list of annotation types across BASE2 instances to
299                        ensure consistency in data annotation.</para>
300                </listitem>
301            </orderedlist>
302            <para>In order to achieve this functionality, a file format specification was defined
303                and is detailed now</para>
305            <sect3 id="annotations.manage.batchupload.fileformat">
306                <title>Defining the input file: File format definition</title>
307                <para> To use the CV-loader import plugin, users need to create a tab-delimited file
308                    complying with the following guidelines. Columns names, order, allowed values
309                    and within column separator are important.</para>
310                <itemizedlist spacing="compact">
311                    <listitem>
312                        <para><guilabel>Category Name</guilabel>: free text</para>
313                    </listitem>
314                    <listitem>
315                        <para><guilabel>AnnotationType Name</guilabel>: free text</para>
316                    </listitem>
317                    <listitem>
318                        <para><guilabel>Description</guilabel>: free text</para>
319                    </listitem>
320                    <listitem>
321                        <para><guilabel>ValueType</guilabel>:
322                            {string,text,boolean,data,integer,long,double,float}</para>
323                    </listitem>
324                    <listitem>
325                        <para><guilabel>Required for MIAME</guilabel>: true/false</para>
326                    </listitem>
327                    <listitem>
328                        <para><guilabel>Enumeration</guilabel>: true/false</para>
329                    </listitem>
330                    <listitem>
331                        <para><guilabel>Multiplicity</guilabel>: integer</para>
332                    </listitem>
333                    <listitem>
334                        <para><guilabel>Default value</guilabel>: free text</para>
335                    </listitem>
336                    <listitem>
337                        <para><guilabel>Cv values</guilabel>: semi-colon (;) used as
338                        separator</para>
339                    </listitem>
340                    <listitem>
341                        <para><guilabel>Item types</guilabel>: semi-colon (;) used as separator
342                            {biosource,sample,extract,protocol,arraydesign,array,plate}</para>
343                    </listitem>
344                    <listitem>
345                        <para><guilabel>Parameter</guilabel>: true/false</para>
346                    </listitem>
347                </itemizedlist>
348                <para/>
349            </sect3>
350            <sect3 id="annotations.manage.batchupload.pluginconfig">
351                <title>Configuring the CV loader plugin</title>
352                <para>From the plugin configuration page, Use the <guibutton>Import</guibutton>
353                    button to load the xml configuration file available here. Please refer to <xref
354                        linkend="plugins"/> for more ample explanations about plugin configuration.</para>
355                <note>
356                    <para>By default the plugin creates <guilabel>selection list</guilabel> for all
357                        enumerated values declared in the file. </para>
358                </note>
359                <note>
360                    <para><guilabel>external ID</guilabel> field is not supported in the current
361                        implementation of the plugin. </para>
362                </note>
364            </sect3>
365            <sect3 id="annotations.manage.batchupload.pluginrun">
366                <title>Running the plugin</title>
367                <para>-From the Annotation Type List View page, click on the
368                    <guibutton>Import</guibutton> Button (which shows up only when the import plugin
369                    has been configured).</para>
370                <para>-Supply path to tab delimited file containing the Annotation Type to be
371                    imported. Click <guibutton>Next</guibutton>. </para>
372                <figure id="write_docbook_doc.figures.batchloading-annotationtype-2">
373                    <title>Running the CVloader plugin: specifying the file</title>
374                    <screenshot>
375                          <mediaobject>
376                              <imageobject>
377                                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-2.png" format="PNG"/>
378                              </imageobject>
379                          </mediaobject>
380                      </screenshot>
381                </figure>
382                <para>Define whether or not to update existing Annotation Types and click
383                        <guibutton>Next</guibutton></para>
384                <figure id="write_docbook_doc.figures.batchloading-annotationtype-3">
385                    <title>Running the CVloader plugin in update mode</title>
386                    <screenshot>
387                          <mediaobject>
388                              <imageobject>
389                                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-3.png" format="PNG"/>
390                              </imageobject>
391                          </mediaobject>
392                      </screenshot>
393                </figure>
394                <para> Click <guibutton>Finish</guibutton> to launch the plugin execution. If one
395                    selects the email notification option, a message will be sent upon job
396                    completion detailing success or failure of the import process. </para>
397                <tip>
398                    <para>Once an update has been made using the plugin, it can not be undone but
399                        one can simply update the file and run the plugin again.</para>
400                </tip>
401            </sect3>
402        </sect2>
403    </sect1>
405    <sect1 id="annotations.bestpractices">
406        <title>Annotation Type Best Practices and Tab2mage Export Function functionality</title>
407        <sect2 id="annotations.bestpractices.whattab2mage">
408            <title>What is Tab2mage format ?</title>
409            <para>
410                <ulink url="">Tab2mage format</ulink> is a
411                tab-delimited format veted by <ulink url="">EBI's
412                    ArrayExpress</ulink> repository for submission microarray data.</para>
413            <para>tab2mage format has been chosen by BASE2 to provide an easy way for data
414                deposition to public repository when submitting a manuscript and publishing
415                experimental data.</para>
416            <para>BASE2 can export microarray experiments in tab2mage format thanks to a dedicated
417                export plugin, for more information see <xref
418                    linkend="experiments_analysis.magexport"/></para>
419            <para>However, it is important to understand that for the plugin to work, information
420                recorded in BASE2 should be formatted following a small number of rules. Failing to
421                do so may impair the possibility of exporting to ArrayExpress.</para>
422        </sect2>
423        <sect2 id="annotations.bestpractices.howtab2mage">
424            <title>How tab2mage format specifications affect data annotation in BASE2 ?</title>
425            <para>BASE2 has been engineered to closely map the MIAME concepts and a number of BASE2
426                entities can be mapped directly to tab2mage elements. However, since MIAME is
427                focused on microarray processing workflow, information about the biological sample
428                is down to the user. To accomodate the annotation needs of users, BASE2 provides a
429                mechanism that allows annotation customization to meet user specific requirements.
430                BASE allows to create annotation type for quantitative annotation and qualitative
431                annotation </para>
433            <sect3 id="annotations.bestpractices.howtab2mage.characs">
434                <title>Biomaterial annotation in Tab2mage format</title>
435                <para>Tab2mage specifications only allow "BioSource" items to be annotated with
436                    "BioMaterialCharacteristics".</para>
437                <warning>
438                    <para>All BASE2 Annotation Types used to annotate at the level of "Sample" and
439                        "Extract" items will be lost during the export in tab2mage format in order
440                        to comply with ArrayExpress Tab2mage parser. </para>
441                </warning>
442                <note>
443                    <para> In the context of data exchange between BASE2 instances, the export
444                        function can be altered to allow attachement of Characteristics to items
445                        other than <guilabel>BioSource</guilabel>, therefore avoiding loss of
446                        information. </para>
447                </note>
448                <para/>
449            </sect3>
450            <sect3 id="annotations.bestpractices.howtab2mage.units">
451                <title>Reporting Units in Tab2mage Format</title>
452                <para>To associate Unit to BASE2 Annotation Types and remain compatible with
453                    Tab2mage specifications, users need to adhere to the following convention:</para>
454                <para>annotation_type_name(unit_name) as in "body mass(kg)" or
455                    "concentration(mg/ml)"</para>
456                <warning>
457                    <para>Only one unit can be specified at any one time for any given Annotation
458                        Type. In order to enable tab2mage support, it might be necessary to declare
459                        several related Annotation Type in order to report similar kind of
460                        information but expressed in a different unit. Specifying Age for instance
461                        is a good example on how to deal with such cases: One should create several
462                        related Annotation Types e.g. Age(week), Age(year) or Age(month) as those
463                        variations maybe be necessary when reporting the age of a mouse or the age
464                        of a human volunteer. </para>
465                </warning>
466                <para/>
467            </sect3>
468            <sect3 id="annotations.bestpractices.howtab2mage.parameters">
469                <title>Declaring Protocol Parameters</title>
470                <para>In order to ensure MIAME compliance, Tab2mage specifications cater for
471                    reporting Parameters attached to Protocols and all parameters attached to a
472                    protocol should be declared in the protocol section of a tab2mage file.</para>
473                <para>In BASE2 terms, Tab2mage elements such as 'BioMaterialCharacteristics',
474                    'Parameter' or 'FactorValues' are all AnnotationTypes. But, it is necessary to
475                    flag those Annotations Types meant to be used as Protocol Paramaters as such so
476                    that they can identified by the Tab2mage exporter and handled appropriately.</para>
477                <para>Note that doing so restricts their use to Protocol only.</para>
478                <warning>
479                    <para>It is not possible to use the same AnnotationType Temperature for
480                        reporting a patient body temperature (which is a 'Biomaterial
481                        Characteristic' ) and hybridization temperature (which is a Protocol
482                        Parameter). Hence it will be necessary to declare 2 distinct annotation
483                        types: </para>
484                </warning>
485                <para>-Annotation Type to be used as 'BioSource characteristics': body temperature
486                    (degree_C)</para>
487                <para>-Annotation Type to be used as 'Protocol Parameter': hybridization
488                    temperature(degree_C)</para>
489                <para/>
491            </sect3>
492            <sect3 id="annotations.bestpractices.howtab2mage.expfact">
493                <title>Declaring Experimental Factors </title>
494                <para>It is a MIAME requirement to identify 'Experimental Variables' when submitting
495                    data to ArrayExpress (provided the study is an intervention study). Therefore,
496                    BASE2 users willing to use the tab2mage export function will have to declare
497                    Experimental Factors using the Annotation Types, the inherited annotation
498                    mechanisms and the Experimental Factor Tag available from the
499                        <guilabel>Experiment</guilabel> section. For more information about
500                        <guilabel>inherited annotation</guilabel> please refer to <xref
501                        linkend="annotations.inherited"/> and to the Experiment section <xref
502                        linkend="experiment_analysis"/></para>
503                <para/>
504            </sect3>
505        </sect2>
506    </sect1>
Note: See TracBrowser for help on using the repository browser.