Context Navigation

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

Visit:

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

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 3372 2007-05-24 08:45:06Z philippe $
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	<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="http://www.mged.org/Workgroups/MIAME/miame.html">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…</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>
67
68	<listitem>
69	<para><guilabel>String</guilabel> and <guilabel>text</guilabel> for textual
70	Annotation Types .</para>
71	</listitem>
72
73	<listitem>
74	<para><guilabel>Boolean</guilabel> for declaring Annotation Types that can take
75	one of 2 possible values.</para>
76	</listitem>
77
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>
236
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>
246
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…</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>
288
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>
304
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>
363
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>
404
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="http://tab2mage.sourceforge.net/">Tab2mage format</ulink> is a
411	tab-delimited format veted by <ulink url="http://www.ebi.ac.uk/microarray/">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>
432
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/>
490
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>
507
508	</chapter>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: