Changeset 3372 for trunk/doc/src/docbook/userdoc/annotations.xml
- Timestamp:
- May 24, 2007, 10:45:06 AM (16 years ago)
- File:
-
- 1 edited
-
trunk/doc/src/docbook/userdoc/annotations.xml (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/userdoc/annotations.xml
r3246 r3372 2 2 <!DOCTYPE chapter PUBLIC 3 3 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 4 5 <!--6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 --> 4 "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"> 5 <!-- 6 $Id$ 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 28 29 29 <chapter id="annotations"> 30 <?dbhtml dir="annotations"?> 31 <title>Annotations</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 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 36 508 </chapter>
Note: See TracChangeset
for help on using the changeset viewer.
