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

Last change on this file since 3392 was 3392, checked in by Nicklas Nordborg, 15 years ago

References #534 and #546. Moved info about Tab2Mage to Experiments and analysis chapter.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 22.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5    <!--
6        $Id: annotations.xml 3392 2007-05-28 09:21:31Z nicklas $
7       
8        Copyright (C) Authors contributing to this file.
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 2
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 this program; if not, write to the Free Software
25        Foundation, Inc., 59 Temple Place - Suite 330,
26        Boston, MA  02111-1307, USA.
27    --> 
28
29<chapter id="annotations">
30  <?dbhtml dir="annotations"?>
31    <title>Annotation Types</title>
32    <sect1 id="annotations.introduction">
33        <title>Introduction</title>
34        <para>BASE2 has been engineered to closely map the <ulink
35                url="http://www.mged.org/Workgroups/MIAME/miame.html">MIAME concepts</ulink>. However, since
36            MIAME is focused on microarray processing workflow, information about the description
37            biological samples themselves was left out. BASE2 users are free to annotate
38            Biomaterials (and most BASE2 items) as they wish, from basic free text description to
39            more advanced ontology based terms. To accomodate the annotation needs of users eager
40            with detailed sample annotations and also the needs of very different communities, BASE2
41            provides a mechanism that allows a high level of annotation customization. BASE2 allows
42            to create descriptive elements for both quantitative annotation and qualitative
43            annotation of Biomaterials via the <guilabel>Annotation Type mechanism</guilabel>.
44            Actually, Annotation Types can be used to annotate not only Biomaterials but almost all
45            BASE2 items, from <guilabel>Plates</guilabel> to <guilabel>Protocols</guilabel> and
46                <guilabel>BioAssaysets</guilabel> This chapter details how to manage and use these
47            elements.</para>
48    </sect1>
49    <sect1 id="annotations.manage">
50        <title>Managing Annotation Types</title>
51        <para> </para>
52        <sect2 id="annotations.manage.create_at">
53            <title>Creating Annotation Types</title>
54            <para>Go To <menuchoice>
55                    <guimenu>Administrate</guimenu>
56                    <guimenuitem>Types</guimenuitem>
57                    <guisubmenu>AnnotationTypes</guisubmenu>
58                </menuchoice>
59            </para>
60            <para> Click on <guibutton>New&hellip;</guibutton> and select one of the 8 different
61                types which can be split in 4 main groups</para>
62            <itemizedlist spacing="compact">
63                <listitem>
64                    <para><guilabel>Integer</guilabel>, <guilabel>Long</guilabel>,
65                        <guilabel>Float</guilabel> and <guilabel>Double</guilabel> for Numerical
66                        Annotation Types.</para>
67                </listitem>
68
69                <listitem>
70                    <para><guilabel>String</guilabel> and <guilabel>text</guilabel> for textual
71                        Annotation Types .</para>
72                </listitem>
73
74                <listitem>
75                    <para><guilabel>Boolean</guilabel> for declaring Annotation Types that can take
76                        one of 2 possible values.</para>
77                </listitem>
78
79                <listitem>
80                    <para><guilabel>Boolean</guilabel> for declaring Annotation Type used as
81                        calendar/time stamps.</para>
82                </listitem>
83            </itemizedlist>
84            <note>
85                <para>These distinctions matter essentially to database administrators who need fine
86                    tuning of database settings. Therefore, creation of Annotation Type should be
87                    supervised by system administrators.</para>
88            </note>
89            <para> A <guilabel>Create</guilabel> pop-up window opens. It contains 4 different tabs: </para>
90            <orderedlist numeration="loweralpha" spacing="compact">
91                <listitem>
92                    <para>
93                        <guilabel>Annotation type</guilabel>
94                    </para>
95                    <para> It allows definition of core properties of the newly created annotation
96                        type. This includes specifying: </para>
97                    <itemizedlist spacing="compact">
98                        <listitem>
99                            <para>How the <guilabel>Annotation Type</guilabel> should be
100                            named.</para>
101                        </listitem>
102                        <listitem>
103                            <para>If the <guilabel>Annotation Type</guilabel> should be treated as a
104                                    <guilabel>protocol parameter</guilabel>.</para>
105                        </listitem>
106                        <listitem>
107                            <para>If the <guilabel>Annotation Type</guilabel> should be considered
108                                as <guilabel>MIAME required</guilabel>.</para>
109                        </listitem>
110                        <listitem>
111                            <para>If a <guilabel>default value</guilabel> should be
112                            available.</para>
113                        </listitem>
114                        <listitem>
115                            <para>If more than one option can be selected by setting the
116                                    <guilabel>multiplicity</guilabel> to more than one.</para>
117                        </listitem>
118                        <listitem>
119                            <para>Finally, one can add a short textual description of the
120                                    <guilabel>Annotation Type</guilabel> being created, to clarify
121                                its usage.</para>
122                        </listitem>
123                    </itemizedlist>
124                    <figure id="write_docbook_doc.figures.annotationtype">
125                        <title>The Annotation type tab of the Create Window for a String Annotation
126                            Type</title>
127                        <screenshot>
128                            <mediaobject>
129                                <imageobject>
130                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype.png" format="PNG"/>
131                                </imageobject>
132                            </mediaobject>
133                        </screenshot>
134                    </figure>
135                </listitem>
136                <listitem>
137                    <para>
138                        <guilabel>Options</guilabel>
139                    </para>
140                    <para> The tab allows tuning the interaction options with the Web Graphical User
141                        Interface when using Annotation types: <itemizedlist spacing="compact">
142                            <listitem>
143                                <para>Choosing <guilabel>text box</guilabel> option allows free text
144                                    to be entered.</para>
145                            </listitem>
146                            <listitem>
147                                <para>Choosing the <guilabel>selection list</guilabel> option
148                                    activates the 'value' section. Actual values can be supplied
149                                    using one line for each value (a return entry is used as
150                                    separator).</para>
151                                <para>It enables administrator to declare the list of possible
152                                    values using the "values" box.</para>
153                            </listitem>
154                            <listitem>
155                                <para>Choosing the <guilabel>radio button/checkboxes</guilabel>
156                                    option activates the <guilabel>value</guilabel> section. Actual
157                                    values can be supplied using one line for each value (a return
158                                    entry is used as separator).</para>
159                                <para>When selecting radio-button instead of selection list, this
160                                    will alter the interface in order to allow user to tick button
161                                    instead of selecting from a drop-down list.</para>
162                                <tip>
163                                    <para>In term of usability, drop-down list can be more easily
164                                        navigated especially when the number of possible values is
165                                        large, and because selectionlist and drop-down list allow
166                                        use of arrow and tab for selection.</para>
167                                </tip>
168                            </listitem>
169                            <listitem>
170                                <para>GUI Variations depending on the type of Annotation Types: </para>
171                                <para>Depending on the nature of the annotation type being created
172                                    (e.g. whether it is a boolean, a string or a date), the
173                                        <guilabel>Options</guilabel> tab may display specific
174                                    fields.</para>
175                                <para>When creating an Annotation Type of Type Boolean, the default
176                                    value field is replaced by the true or false radio-button in
177                                    order to allow specification of a value.</para>
178                                <para>Also, when using numerical AnnotationTypes, upper and lower
179                                    limit can be defined.</para>
180                            </listitem>
181                        </itemizedlist>
182                    </para>
183                    <figure id="write_docbook_doc.figures.annotationtype-option">
184                        <title>The Option tab of the Create Window for a String Annotation Type</title>
185                        <screenshot>
186                                    <mediaobject>
187                                        <imageobject>
188                                            <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-option.png" format="PNG"/>
189                                        </imageobject>
190                                    </mediaobject>
191                                </screenshot>
192                    </figure>
193                </listitem>
194                <listitem>
195                    <para>
196                        <guilabel>Item types</guilabel>
197                    </para>
198                    <para> The Item types tab is used to defined which BASE2 entities can be
199                        annotated using the newly creating Annotation Type. Simply use
200                            <guiicon>arrow left|right</guiicon> to moved items between the
201                            <guilabel>disabled for</guilabel> and <guilabel>enabled for</guilabel>
202                        <note>
203                            <para>Experiment item can not be annotated using Annotation Type</para>
204                        </note>
205                    </para>
206                    <figure id="write_docbook_doc.figures.annotationtype-item">
207                        <title>The Item tab of the Create Window for a String Annotation Type</title>
208                        <screenshot>
209                            <mediaobject>
210                                <imageobject>
211                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-item.png" format="PNG"/>
212                                </imageobject>
213                            </mediaobject>
214                        </screenshot>
215                    </figure>
216                </listitem>
217                <listitem>
218                    <para>
219                        <guilabel>Categories</guilabel>
220                    </para>
221                    <para> Annotation Type can be grouped together thanks to the Annotation Category
222                        functionality. This enhances display by avoid overcrowding the list of
223                        annotation types presented to users. It also allows to improve the display of
224                        information. </para>
225                    <figure id="write_docbook_doc.figures.annotationtype-categories">
226                        <title>The categories tab of the Create Window for a String Annotation Type</title>
227                        <screenshot>
228                            <mediaobject>
229                                <imageobject>
230                                    <imagedata contentwidth="7cm" width="7cm" fileref="figures/annotationtype-categories.png" format="PNG"/>
231                                </imageobject>
232                            </mediaobject>
233                        </screenshot>
234                    </figure>
235                </listitem>
236            </orderedlist>
237
238            <para>Click on the <inlinemediaobject>
239                    <imageobject>
240                        <imagedata fileref="figures/save.gif" format="GIF"/>
241                    </imageobject>
242                </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject>
243                    <imageobject>
244                        <imagedata fileref="figures/cancel.gif" format="GIF"/>
245                    </imageobject>
246                </inlinemediaobject> to abort. </para>
247
248        </sect2>
249        <sect2 id="annotations.manage.update">
250            <title>Updating Annotation Types</title>
251            <para>Using the <keycap>CTRL</keycap>, <keycap>ALT</keycap>, <keycap>SHIFT</keycap> key
252                combination, click on the Annotation Type to be modified from the Annotation Type
253                List View</para>
254            <para>The <guilabel>Edit</guilabel> pop-up window opens, presenting the various tabs
255                presented in the previous section.</para>
256            <note>
257                <para>Everything is editable except the Annotation Type Type itself, which is
258                    immutable and set once and for all upon creation</para>
259            </note>
260        </sect2>
261        <sect2 id="annotations.manage.create_atcategory">
262            <title>Grouping Annotation Type into Categories</title>
263            <para>
264                <guilabel>Annotation Type Categories</guilabel> allow grouping of related Annotation
265                Types, based on users requirements. </para>
266            <para>For creating a new category, go to: </para>
267            <para>
268                <menuchoice>
269                    <guimenu>Administrate</guimenu>
270                    <guimenuitem>Types</guimenuitem>
271                    <guisubmenu>Annotation Type categories</guisubmenu>
272                </menuchoice>
273            </para>
274            <para>Click on <guibutton>New&hellip;</guibutton></para>
275            <para>a pop-up window opens.</para>
276            <para>It contains 2 tabs, one for declaring name and description of the newly created
277                category, the second tab is to provide the list of annotation type to be grouped
278                together under this container.</para>
279            <example id="annotation_types.example.atcategory">
280                <title>A category 'Hematology Descriptors' could be created to group together
281                    Annotation Types such as 'Lymphocyte count' and 'Hematocrite' </title>
282            </example>
283            <example id="annotation_types.example.atcategory-2">
284                <title>A category 'Plasma Clinical Descriptors' could be created to group together
285                    Annotation Types such as 'ALT activity (UI/mL)' and 'LDH activity (UI/mL').
286                </title>
287            </example>
288        </sect2>
289
290        <sect2 id="annotations.manage.batchupload">
291            <title>Batchloading Annotation Types from file</title>
292            <para>A plugin, CVLoader.jar, has been specially devised with 2 purposes in mind:</para>
293            <orderedlist>
294                <listitem>
295                    <para>To speed-up data Annotation Type declaration and upload in the BASE2
296                        system.</para>
297                </listitem>
298                <listitem>
299                    <para>To enable sharing list of annotation types across BASE2 instances to
300                        ensure consistency in data annotation.</para>
301                </listitem>
302            </orderedlist>
303            <para>In order to achieve this functionality, a file format specification was defined
304                and is detailed now</para>
305
306            <sect3 id="annotations.manage.batchupload.fileformat">
307                <title>Defining the input file: File format definition</title>
308                <para> To use the CV-loader import plugin, users need to create a tab-delimited file
309                    complying with the following guidelines. Columns names, order, allowed values
310                    and within column separator are important.</para>
311                <itemizedlist spacing="compact">
312                    <listitem>
313                        <para><guilabel>Category Name</guilabel>: free text</para>
314                    </listitem>
315                    <listitem>
316                        <para><guilabel>AnnotationType Name</guilabel>: free text</para>
317                    </listitem>
318                    <listitem>
319                        <para><guilabel>Description</guilabel>: free text</para>
320                    </listitem>
321                    <listitem>
322                        <para><guilabel>ValueType</guilabel>:
323                            {string,text,boolean,data,integer,long,double,float}</para>
324                    </listitem>
325                    <listitem>
326                        <para><guilabel>Required for MIAME</guilabel>: true/false</para>
327                    </listitem>
328                    <listitem>
329                        <para><guilabel>Enumeration</guilabel>: true/false</para>
330                    </listitem>
331                    <listitem>
332                        <para><guilabel>Multiplicity</guilabel>: integer</para>
333                    </listitem>
334                    <listitem>
335                        <para><guilabel>Default value</guilabel>: free text</para>
336                    </listitem>
337                    <listitem>
338                        <para><guilabel>Cv values</guilabel>: semi-colon (;) used as
339                        separator</para>
340                    </listitem>
341                    <listitem>
342                        <para><guilabel>Item types</guilabel>: semi-colon (;) used as separator
343                            {biosource,sample,extract,protocol,arraydesign,array,plate}</para>
344                    </listitem>
345                    <listitem>
346                        <para><guilabel>Parameter</guilabel>: true/false</para>
347                    </listitem>
348                </itemizedlist>
349                <para/>
350            </sect3>
351            <sect3 id="annotations.manage.batchupload.pluginconfig">
352                <title>Configuring the CV loader plugin</title>
353                <para>From the plugin configuration page, Use the <guibutton>Import</guibutton>
354                    button to load the xml configuration file available here. Please refer to <xref
355                        linkend="plugins"/> for more ample explanations about plugin configuration.</para>
356                <note>
357                    <para>By default the plugin creates <guilabel>selection list</guilabel> for all
358                        enumerated values declared in the file. </para>
359                </note>
360                <note>
361                    <para><guilabel>external ID</guilabel> field is not supported in the current
362                        implementation of the plugin. </para>
363                </note>
364
365            </sect3>
366            <sect3 id="annotations.manage.batchupload.pluginrun">
367                <title>Running the plugin</title>
368                <para>-From the Annotation Type List View page, click on the
369                    <guibutton>Import</guibutton> Button (which shows up only when the import plugin
370                    has been configured).</para>
371                <para>-Supply path to tab delimited file containing the Annotation Type to be
372                    imported. Click <guibutton>Next</guibutton>. </para>
373                <figure id="write_docbook_doc.figures.batchloading-annotationtype-2">
374                    <title>Running the CVloader plugin: specifying the file</title>
375                    <screenshot>
376                          <mediaobject>
377                              <imageobject>
378                                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-2.png" format="PNG"/>
379                              </imageobject>
380                          </mediaobject>
381                      </screenshot>
382                </figure>
383                <para>Define whether or not to update existing Annotation Types and click
384                        <guibutton>Next</guibutton></para>
385                <figure id="write_docbook_doc.figures.batchloading-annotationtype-3">
386                    <title>Running the CVloader plugin in update mode</title>
387                    <screenshot>
388                          <mediaobject>
389                              <imageobject>
390                                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/batchloading-annotationtype-3.png" format="PNG"/>
391                              </imageobject>
392                          </mediaobject>
393                      </screenshot>
394                </figure>
395                <para> Click <guibutton>Finish</guibutton> to launch the plugin execution. If one
396                    selects the email notification option, a message will be sent upon job
397                    completion detailing success or failure of the import process. </para>
398                <tip>
399                    <para>Once an update has been made using the plugin, it can not be undone but
400                        one can simply update the file and run the plugin again.</para>
401                </tip>
402            </sect3>
403        </sect2>
404    </sect1>
405
406    <sect1 id="annotations.bestpractices">
407        <title>Best Practices and Tab2Mage Export functionality</title>
408       
409        See <xref linkend="experiments_analysis.magexport" />.
410       
411    </sect1>
412
413</chapter>
Note: See TracBrowser for help on using the repository browser.