Changeset 3372
- Timestamp:
- May 24, 2007, 10:45:06 AM (16 years ago)
- Location:
- trunk/doc/src/docbook/userdoc
- Files:
-
- 1 added
- 7 edited
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> -
trunk/doc/src/docbook/userdoc/biomaterials.xml
r3246 r3372 3 3 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 4 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 29 <chapter id="biomaterials"> 30 <?dbhtml dir="biomaterials"?> 31 <title>Biomaterials</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 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 <chapter id="biomaterial"> 29 <title>Biomaterials</title> 30 <sect1 id="biomaterial.introduction"> 31 <title>Introduction</title> 32 <para> The generic term Biomaterial refers to any biological material used in an Experiment. 33 Biomaterials are subdivided in 4 components, BioSource, Sample, Extract and Labeled Extract. The 34 order use in presenting those entities is not inocuous as it represents the sequence of 35 transformation a source material undergoes until it is in a state compatible with the realization 36 of a microarray Hybridization. This progression is actually mimicked in the BASE2 View menu again 37 to insist on this natural progression. </para> 38 <para>BioSources correspond to the native biological entity used in an experiment prior to any 39 treatment. </para> 40 <para>Samples are central to BASE2 to describe the sample processing. So Samples can be created 41 from other Samples if user want to track sample processing event in a finely granular fashion.</para> 42 <para>Extracts correspond to nucleic acid material extracted from a tissue sample or a cell 43 culture sample.</para> 44 <para>LabeledExtracts correspond to nucleic acid materials which have undergone a marking 45 procedure using a fluorescent or radioactive compound for detection in a microarray assay.</para> 46 <para>BASE2 allows users to create any of the these entities fairly freely, however it is expected 47 that users will follow the natural path of the laboratory workflow.</para> 48 </sect1> 49 <sect1 id="biosource.manage"> 50 <title>Managing BioSources</title> 51 52 <sect2 id="biosource.manage.create"> 53 <title>Creating BioSources</title> 54 <para>Go to <menuchoice> 55 <guimenu>View</guimenu> 56 <guimenuitem>BioSources</guimenuitem> 57 </menuchoice> , Click on <guibutton>New…</guibutton> button </para> 58 <para> A 'Create' pop-up window opens, it contains 2 tabs: <guilabel>Biosource</guilabel> and 59 <guilabel>Annotations</guilabel>. </para> 60 <itemizedlist> 61 <listitem> 62 <para> 63 <guilabel>BioSource</guilabel> 64 </para> 65 <para> This tab allows users to enter essential information about a BioSource.</para> 66 <variablelist> 67 <varlistentry> 68 <term> 69 <guilabel>Name</guilabel> 70 </term> 71 <listitem> 72 <para> This is only mandatory field. BASE2 by default assigns 'New Biosource' as name but it 73 is advised to provide unique sensible names, as this may impact exporting in tab2mage 74 format.</para> 75 <para>For more information about tab2mage format and export, please refer to section <xref 76 linkend="experiments_analysis.magexport"/> and section <xref 77 linkend="annotations.bestpractices"/></para> 78 </listitem> 79 </varlistentry> 80 <varlistentry> 81 <term> 82 <guilabel>Description</guilabel> 83 </term> 84 <listitem> 85 <para> A free text description can be supplied using this field.</para> 86 </listitem> 87 </varlistentry> 88 <varlistentry> 89 <term> 90 <guilabel>External id</guilabel> 91 </term> 92 <listitem> 93 <para> An external reference identifiers (e.g. a patient identification code) can be 94 supplied using this field.</para> 95 </listitem> 96 </varlistentry> 97 </variablelist> 98 99 <figure id="write_docbook_doc.figures.biosource-tab-1"> 100 <title>The Biosource tab in the Biosource Create Window</title> 101 <screenshot> 102 <mediaobject> 103 <imageobject> 104 <imagedata contentwidth="10cm" width="10cm" fileref="figures/biosource-tab-1.png" format="PNG"/> 105 </imageobject> 106 </mediaobject> 107 </screenshot> 108 </figure> 109 </listitem> 110 <listitem> 111 <para> 112 <guilabel>Annotations</guilabel> 113 </para> 114 <para> This tab allows BASE2 users to use Annotation Types to refine BioSource description.</para> 115 <para>A list of Annotation Type will be displayed only if owned by or shared to the user.</para> 116 <important> 117 <para> In order to use this feature, Annotation Type must be declared and made available. To 118 learn more about Annotation Types, please refer to <xref linkend="annotations"/> 119 </para> 120 </important> 121 <para> Annotation Types can be filtered based on their grouping properties using the 122 <guilabel>categories</guilabel> select-list feature. For more information about Annotation 123 Type Categories, refer to section <xref linkend="annotations.manage.create_atcategory"/>. </para> 124 <figure id="write_docbook_doc.figures.biosource-tab-2"> 125 <title>The Annotation tab from the Biosource Create Window</title> 126 <screenshot> 127 <mediaobject> 128 <imageobject> 129 <imagedata contentwidth="10cm" width="10cm" fileref="figures/biosource-tab-2.png" format="PNG"/> 130 </imageobject> 131 </mediaobject> 132 </screenshot> 133 </figure> 134 <para>To provide a value to a specific Annotation Type, click on it.</para> 135 <para> Upon selection, the windows is updated to present a drop-down list, an entry box or a 136 radio-button check box, depending on the type of the Annotation Type.</para> 137 <para>Once a value has been supplied, an <inlinemediaobject> 138 <imageobject> 139 <imagedata fileref="figures/annotated.gif" format="GIF"/> 140 </imageobject> 141 </inlinemediaobject> symbol appear in front of the annotation type.</para> 142 <para>The actual type of the Annotation Type will be reminded between bracket, for instance 143 appearing in the interface as <guilabel>(float)</guilabel> or <guilabel>(string)</guilabel>.</para> 144 <para>A validation will be applied upon data entry to match the requirements, i.e. check for 145 integer,boolean, string... values are provided.</para> 146 <figure id="write_docbook_doc.figures.biosource-tab-3"> 147 <title>Providing Annotation Type values from the Biosource Create Window</title> 148 <screenshot> 149 <mediaobject> 150 <imageobject> 151 <imagedata contentwidth="10cm" width="10cm" fileref="figures/biosource-tab-3.png" format="PNG"/> 152 </imageobject> 153 </mediaobject> 154 </screenshot> 155 </figure> 156 </listitem> 157 </itemizedlist> 158 <para>Click on the <inlinemediaobject> 159 <imageobject> 160 <imagedata fileref="figures/save.gif" format="GIF"/> 161 </imageobject> 162 </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject> 163 <imageobject> 164 <imagedata fileref="figures/cancel.gif" format="GIF"/> 165 </imageobject> 166 </inlinemediaobject> button to abort. </para> 167 </sect2> 168 <sect2 id="biosource.manage.detail_view"> 169 <title>Viewing/Editing BioSources</title> 170 <para>From the BioSource List View, clicking on the BioSource <guilabel>Name</guilabel> opens a 171 detailed view for that Biosource, showing a summary of all information available in BASE2 about 172 that particular entity.</para> 173 <para> The default behavior opens the detailed view on the <guilabel>Properties</guilabel> tab, 174 which shows a summary information and displays the list of Samples derived from a BioSource, if 175 any.</para> 176 <figure id="write_docbook_doc.figures.biosource-itemview-prop"> 177 <title>BioSource Item View, properties tab</title> 178 <screenshot> 179 <mediaobject> 180 <imageobject> 181 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosource-itemview-prop.png" format="PNG"/> 182 </imageobject> 183 </mediaobject> 184 </screenshot> 185 </figure> 186 <para>By clicking on the <guilabel>Annotations</guilabel> tab, users can display the list of 187 Annotation Types used to annotate a Biosource. </para> 188 <figure id="write_docbook_doc.figures.biosource-itemview-annot"> 189 <title>BioSource Item View, annotations tab</title> 190 <screenshot> 191 <mediaobject> 192 <imageobject> 193 <imagedata contentwidth="13cm" width="13cm" fileref="figures/biosource-itemview-annot.png" format="PNG"/> 194 </imageobject> 195 </mediaobject> 196 </screenshot> 197 </figure> 198 <para>Clicking the <inlinemediaobject> 199 <imageobject> 200 <imagedata fileref="figures/edit.gif" format="GIF"/> 201 </imageobject> 202 </inlinemediaobject><guiicon> edit icon</guiicon> in the <interface>value</interface> for any of 203 the annotations (e.g. 'antibiotic' in our example), opens an Annotate window (which is a 204 BioSource Edit window set on the annotation tab) and highlights the selected Annotation Type, 205 prompting for data entry.</para> 206 <figure id="write_docbook_doc.figures.biosource-itemview-annot-edit"> 207 <title>BioSource annotations edit</title> 208 <screenshot> 209 <mediaobject> 210 <imageobject> 211 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosource-itemview-annot-edit.png" format="PNG"/> 212 </imageobject> 213 </mediaobject> 214 </screenshot> 215 </figure> 216 <para> The relevant Annotation Type is highlighted and a list of possible values is displayed. </para> 217 <para>Again, all Annotation types marked with a <inlinemediaobject> 218 <imageobject> 219 <imagedata fileref="figures/annotated.gif" format="GIF"/> 220 </imageobject> 221 </inlinemediaobject> symbol have been used to provided information.</para> 222 <para>Click on the <inlinemediaobject> 223 <imageobject> 224 <imagedata fileref="figures/save.gif" format="GIF"/> 225 </imageobject> 226 </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject> 227 <imageobject> 228 <imagedata fileref="figures/cancel.gif" format="GIF"/> 229 </imageobject> 230 </inlinemediaobject> button to abort. </para> 231 </sect2> 232 <sect2 id="biosource.manage.delete_restore"> 233 <title>Deleting/Restoring BioSources</title> 234 <para>As for other items in BASE2, BioSources can be removed. For a generic overview on how to 235 delete and restore items, refer to section <xref linkend="webclient.items.delete"/> 236 </para> 237 <para> To delete, do the following</para> 238 <itemizedlist> 239 <listitem> 240 <para> Select one or more BioSources and click <guibutton>Delete</guibutton> button in the menu 241 bar. </para> 242 <para> All the selected BioSources have been marked as deleted and are no longer available from 243 the interface. </para> 244 <para> From the <guilabel>view/preset…</guilabel> select box, ticking the 245 <guilabel>Removed</guilabel> option allows to display those of the BioSources earmarked for 246 deletion. They will be shown with a symbol <inlinemediaobject> 247 <imageobject> 248 <imagedata fileref="figures/deleted.gif" format="GIF"/> 249 </imageobject> 250 </inlinemediaobject> in front of them. </para> 251 </listitem> 252 <listitem> 253 <para> Alternately, navigating to the BioSource Item View, hitting the 254 <guibutton>Delete</guibutton> will perform the task.</para> 255 <para> As shown in the next picture, the BioSource is then marked with the <inlinemediaobject> 256 <imageobject> 257 <imagedata fileref="figures/deleted.gif" format="GIF"/> 258 </imageobject> 259 </inlinemediaobject><guilabel>This item has been flagged for deletion</guilabel> label.</para> 260 <figure id="write_docbook_doc.figures.biosource-delete"> 261 <title>Deleting BioSource from the Item View</title> 262 <screenshot> 263 <mediaobject> 264 <imageobject> 265 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosource-delete.png" format="PNG"/> 266 </imageobject> 267 </mediaobject> 268 </screenshot> 269 </figure> 270 </listitem> 271 <listitem> 272 <para>Deletion errors can be easily recovered. Select the item to recover from the List View 273 (be sure to check the <guilabel>Removed</guilabel> option in the View/preset.. filter) and hit 274 the <guibutton>Restore</guibutton> to performed the task. </para> 275 </listitem> 276 </itemizedlist> 277 <important> 278 <para>To really delete an item from the database you must use the trashcan. Items deleted from 279 the Trashcan can not be recovered. To learn more about the trashcan function, please refer to 280 <xref linkend="trashcan"/> 281 </para> 282 </important> 283 </sect2> 284 </sect1> 285 <sect1 id="sample.manage"> 286 <title>Managing Samples</title> 287 <para>Samples result from processing events applied to <guilabel>BioSource</guilabel> material or 288 other <guilabel>Samples</guilabel> before they are turned into an <guilabel>Extract</guilabel>.</para> 289 <para>In other words, Samples can be created from BioSource items or from one or more Sample 290 items.</para> 291 <para>When a Sample is created from several other Samples, a 'pooling' event is performed. A 292 specific section details how to create pools, refer to <xref 293 linkend="sample.manage.createsample.pool"/></para> 294 <para>For every step of transformation from BioSource to Sample, it is possible to provide 295 information about the protocol used to perform this task. It is not enforced in BASE2 but it 296 should serve as guidance when devising the granularity of the sample processing task. Also, it is 297 good practice to provide protocol information to ensure MIAME compliance.</para> 298 <sect2 id="sample.manage.createsamplefrombiosource"> 299 <title>Creating Samples</title> 300 <orderedlist> 301 <listitem> 302 <para>Creating Samples from the BioSource page</para> 303 <para>No matter how complex the sample processing phase is, at least one Sample has to be 304 anchored to a BioSource.</para> 305 <para>Therefore, a natural way to create a Sample is to click on the <inlinemediaobject> 306 <imageobject> 307 <imagedata fileref="figures/add.gif" format="GIF"/> 308 </imageobject> 309 </inlinemediaobject> 310 <guibutton>Create new Sample</guibutton> from the Sample column of the BioSource list view.</para> 311 <figure id="write_docbook_doc.figures.biosource-create-sample"> 312 <title>Creating a Sample from the BioSource list view</title> 313 <screenshot> 314 <mediaobject> 315 <imageobject> 316 <imagedata contentwidth="13cm" width="13cm" fileref="figures/biosource-create-sample.png" format="PNG"/> 317 </imageobject> 318 </mediaobject> 319 </screenshot> 320 </figure> 321 </listitem> 322 <listitem> 323 <para>Creating Samples from the Sample List view page</para> 324 <para> This is the alternative for creating Sample from the BioSource. To do so, go to <menuchoice> 325 <guimenu>View</guimenu> 326 <guimenuitem>BioSamples</guimenuitem> 327 </menuchoice> , Click on <guibutton>New…</guibutton> button </para> 328 <para> A 'Create' pop-up window opens, it contains 4 tabs: <guilabel>Sample</guilabel>, 329 <guilabel>Parents</guilabel>, <guilabel> Annotations & parameters</guilabel> and 330 <guilabel>Inherited Annotations</guilabel>. </para> 331 <itemizedlist> 332 <listitem> 333 <para>The Sample Tab </para> 334 <para>This tab contains 1 mandatory field for providing the Sample <guilabel>Name</guilabel>. 335 BASE2 by default assigns names to Samples (by suffixing 's#' when creating a Sample from an 336 existing Biosource or 'New Sample' otherwise) but it is possible to edit at will.</para> 337 <para>There are 5 optional fields to provide more detailed information</para> 338 <itemizedlist> 339 <listitem> 340 <para><guilabel>External ID</guilabel>: for instance to report a barcode attached to a 341 Sample</para> 342 </listitem> 343 <listitem> 344 <para><guilabel>Original Quantity (ug)</guilabel>: this is meant to report information 345 about the actual mass of biomaterial created</para> 346 </listitem> 347 <listitem> 348 <para><guilabel>Created</guilabel>: a date should be provided. The information can be 349 important when running quality controls on data and account for potential confounding 350 factor (e.g. day effect)</para> 351 </listitem> 352 <listitem> 353 <para><guilabel>Protocol</guilabel>: this a controled field. A select-list displays 354 protocols whose type is <guilabel>sampling</guilabel> and which are shared to or owned by 355 the logged-in user. </para> 356 <important> 357 <para>It is not mandatory to supply protocol in BASE2 Reporting protocols is a MIAME 358 requirement</para> 359 </important> 360 </listitem> 361 <listitem> 362 <para><guilabel>Description</guilabel>: a free text field to report any information that 363 not can be captured otherwise</para> 364 </listitem> 365 </itemizedlist> 366 <para>Finally, a 7th field, <guilabel>Registered</guilabel> is automatically populated with a 367 date at which the Sample was entered in BASE2 system.</para> 368 <figure id="write_docbook_doc.figures.biosample-tab-1"> 369 <title>Sample tab</title> 370 <screenshot> 371 <mediaobject> 372 <imageobject> 373 <imagedata contentwidth="10cm" width="10cm" fileref="figures/biosample-tab-1.png" format="PNG"/> 374 </imageobject> 375 </mediaobject> 376 </screenshot> 377 </figure> 378 </listitem> 379 <listitem> 380 <para>The Parents Tab </para> 381 <para>This important tab does what it says on the tin: It is meant to keep track of the 382 Sample origin. BASE2 distinguished between 2 cases which are controled by the 383 <guibutton>pooled</guibutton> radio-button</para> 384 <orderedlist> 385 <listitem> 386 <para>The Parent is a BioSource</para> 387 <para> The <guibutton>Pooled</guibutton> radio-button is set to <guilabel>No</guilabel></para> 388 <para> The BioSource select button is active and allows users to point to one and only one 389 BioSource from which the Sample originates from.</para> 390 <figure id="write_docbook_doc.figures.biosample-tab-2-select-biosource"> 391 <title>Parent tab and interaction when pooled button is set to No</title> 392 <screenshot> 393 <mediaobject> 394 <imageobject> 395 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-2-select-biosource.png" format="PNG"/> 396 </imageobject> 397 </mediaobject> 398 </screenshot> 399 </figure> 400 </listitem> 401 <listitem> 402 <para>The Parent is another Sample</para> 403 <para> The <guibutton>Pooled</guibutton> radio-button has to be set to 404 <guilabel>Yes</guilabel></para> 405 <para>Upon selection, the BioSource select button is deactivated and the Samples box and 406 button are activated.</para> 407 <para>This allows users to specify one or more Samples to be selected from the Sample List 408 View page. </para> 409 <figure id="write_docbook_doc.figures.biosample-tab-2-select-sample"> 410 <title>Parent tab and interaction when pooled button is set to Yes</title> 411 <screenshot> 412 <mediaobject> 413 <imageobject> 414 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-2-select-sample.png" format="PNG"/> 415 </imageobject> 416 </mediaobject> 417 </screenshot> 418 </figure> 419 </listitem> 420 </orderedlist> 421 </listitem> 422 <listitem> 423 <para>Annotations & parameters </para> 424 <para>As seen in the BioSource section, this tab allows users to further supply information 425 about the Sample provided they have defined or shared annotation types to annotate Sample 426 items.</para> 427 <para>The display of Annotation Type can be filtered based on the Annotation Type Category 428 they belong to. </para> 429 <important> 430 <para> In order to use this feature, Annotation Type must be declared and made available. To 431 learn more about Annotation Types, please refer to <xref linkend="annotations"/> 432 </para> 433 </important> 434 <para>To provide a value for a given annotation type, simply click on it an use the input 435 field or select a value from the drop-down lists or radio buttons.</para> 436 <figure id="write_docbook_doc.figures.biosample-tab-3"> 437 <title>Annotations & parameters</title> 438 <screenshot> 439 <mediaobject> 440 <imageobject> 441 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-3.png" format="PNG"/> 442 </imageobject> 443 </mediaobject> 444 </screenshot> 445 </figure> 446 </listitem> 447 <listitem> 448 <para>Inherited Annotations case1 </para> 449 <para>The next picture shows </para> 450 <figure id="write_docbook_doc.figures.biosample-tab-4"> 451 <title>Inherited Annotations</title> 452 <screenshot> 453 <mediaobject> 454 <imageobject> 455 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-4.png" format="PNG"/> 456 </imageobject> 457 </mediaobject> 458 </screenshot> 459 </figure> 460 <para>Inherited Annotations case2</para> 461 <figure id="write_docbook_doc.figures.biosample-tab-4bis"> 462 <title>Inherited Annotations</title> 463 <screenshot> 464 <mediaobject> 465 <imageobject> 466 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-4bis.png" format="PNG"/> 467 </imageobject> 468 </mediaobject> 469 </screenshot> 470 </figure> 471 </listitem> 472 </itemizedlist> 473 </listitem> 474 </orderedlist> 475 </sect2> 476 <sect2 id="sample.manage.createsample.pool"> 477 <title>Creating Pooled Samples</title> 478 <para>It is common practice when biological material is scarce to pool Samples from equivalent 479 sources. BASE2 provides mechanisms to report on such practice.</para> 480 <para>This section details how.</para> 481 <para>There are 2 ways to create Pooled Samples in BASE2</para> 482 <orderedlist> 483 <listitem> 484 <para>Using the Pooled radio button option from the Sample Create page, and this has been shown 485 already </para> 486 </listitem> 487 <listitem> 488 <para>Using the Pool button in the Menu bar</para> 489 <para>The Sample List View page menu bar contains an additionnal button the usage of which is 490 detailed now.</para> 491 <para>The <guibutton>Pool…</guibutton> button <inlinemediaobject> 492 <imageobject> 493 <imagedata fileref="figures/new_pooled.gif" format="GIF"/> 494 </imageobject> 495 </inlinemediaobject> allows users to create Pooled Samples by selecting the list of Samples 496 used to produce that new Sample.</para> 497 <para> Users simply need to tick the select-boxes in front of each relevant Sample and click 498 the <inlinemediaobject> 499 <imageobject> 500 <imagedata fileref="figures/new_pooled.gif" format="GIF"/> 501 </imageobject> 502 </inlinemediaobject> button. </para> 503 <para>This provides an easy and simple way to create Pooled Samples. The result of such process 504 is the creation of a New Sample, which Parent Samples are listing and preset in the Parent tab</para> 505 <figure id="write_docbook_doc.figures.biosample-tab-2-pool-sample"> 506 <title>Pooling of Samples</title> 507 <screenshot> 508 <mediaobject> 509 <imageobject> 510 <imagedata contentwidth="12cm" width="12cm" fileref="figures/biosample-tab-2-pool-sample.png" format="PNG"/> 511 </imageobject> 512 </mediaobject> 513 </screenshot> 514 </figure> 515 </listitem> 516 </orderedlist> 517 </sect2> 518 <sect2 id="sample.manage.delete"> 519 <title>Deleting/Restoring Samples</title> 520 <para>As for other items in BASE2, Samples can be removed. For a generic overview on how to 521 delete and restore items, refer to section <xref linkend="webclient.items.delete"/></para> 522 <para>To delete, do the following</para> 523 <itemizedlist> 524 <listitem> 525 <para> Select one or more Samples and click <guibutton>Delete</guibutton> button in the menu 526 bar. </para> 527 <para> All the selected Samples have been marked as deleted and are no longer available from 528 the interface. </para> 529 <para> From the <guilabel>view/preset…</guilabel> select box, ticking the 530 <guilabel>Removed</guilabel> option allows to display those Samples earmarked for deletion. 531 They will be shown with a symbol <guiicon>D</guiicon> in front of them. </para> 532 </listitem> 533 <listitem> 534 <para> Alternately, navigating to the Sample Item View, one can hit the 535 <guibutton>Delete</guibutton> to performed the task. As showen in the next picture, the Sample 536 is then flagged with the <guiicon>This item has been flagged for deletion</guiicon> 537 </para> 538 <figure id="write_docbook_doc.figures.sample-delete"> 539 <title>Deleting Samples from the Item View</title> 540 <screenshot> 541 <mediaobject> 542 <imageobject> 543 <imagedata contentwidth="12cm" width="12cm" fileref="figures/sample-delete.png" format="PNG"/> 544 </imageobject> 545 </mediaobject> 546 </screenshot> 547 </figure> 548 </listitem> 549 <listitem> 550 <para>Deletion errors can be easily recovered. Select the item to recover from the List View 551 (be sure to check the <guilabel>removed</guilabel> option in the View/preset.. filter) and hit 552 the <guibutton>Restore</guibutton> to performed the task. </para> 553 </listitem> 554 </itemizedlist> 555 <important> 556 <para>To really delete an item from the database you must use the trashcan. Items deleted from 557 the Trashcan can not be recovered. To learn more about the trashcan function, please refer to 558 <xref linkend="trashcan"/> 559 </para> 560 </important> 561 </sect2> 562 </sect1> 563 564 <sect1 id="extract.manage"> 565 <title>Managing Extracts</title> 566 <para>Extract items should be used to describe the events that transform a Sample material in an 567 Extract material.</para> 568 <para>Extracts can be created from Sample items or from one or more Extract items.</para> 569 <para>When an Extract is created from several other Extracts, a Pooling event is performed. A 570 specific section details how to create pooled Extracts</para> 571 <para>During the transformation from Samples to Extracts, it is possible to provide information 572 about the protocol used to perform this task.</para> 573 <para>It is not enforced in BASE2 but it should serve as guidance when devising the granularity of 574 the sample processing task. Also, it is good practice to provide protocol information.</para> 575 <sect2 id="extract.manage.createextractfromsample"> 576 <title>Creating Extracts</title> 577 <orderedlist> 578 <listitem> 579 <para>Creating Extracts from the Sample page</para> 580 <para>Following the laboratory workflow, a natural way to create a new Extract is to click on 581 the <guibutton>New extract</guibutton> from the Extract column of the Sample List View.</para> 582 <figure id="write_docbook_doc.figures.sample-create-extract"> 583 <title>Creating an Extract from the Sample list view</title> 584 <screenshot> 585 <mediaobject> 586 <imageobject> 587 <imagedata contentwidth="12cm" width="12cm" fileref="figures/sample-create-extract.png" format="PNG"/> 588 </imageobject> 589 </mediaobject> 590 </screenshot> 591 </figure> 592 </listitem> 593 <listitem> 594 <para>Creating Extracts from the Sample List view page</para> 595 <para> Alternately, Extracts can be created directly ysing the Extract create page. To do so, 596 go to <menuchoice> 597 <guimenu>View</guimenu> 598 <guimenuitem>Extracts</guimenuitem> 599 </menuchoice> , Click on <guibutton>New…</guibutton> button </para> 600 <para> A 'Create' pop-up window opens, it contains 4 tabs: <guilabel>Extract</guilabel>, 601 <guilabel>Parents</guilabel>, <guilabel> Annotations & parameters</guilabel> and 602 <guilabel>Inherited Annotations</guilabel>. </para> 603 <itemizedlist> 604 <listitem> 605 <para>The Extract Tab </para> 606 <para>This tab contains 1 mandatory field for providing the extract name. </para> 607 <para>BASE2 by default assigns names to Extract (by suffixing 'e#' when creating an Extract 608 from an existing Sample or 'New Extract' otherwise) but it is possible to edit it at will</para> 609 <para>There 5 optional fields to provide more detailed information</para> 610 <itemizedlist> 611 <listitem> 612 <para><guilabel>External ID</guilabel>: for instance to report a barcode attached to an 613 extract</para> 614 </listitem> 615 <listitem> 616 <para><guilabel>Original Quantity (ug)</guilabel>: this is meant to report information 617 about the actual mass of biomaterial created</para> 618 </listitem> 619 <listitem> 620 <para><guilabel>Created</guilabel>: a date should be provided. The information can be 621 important when running quality controls on data and account for potential confounding 622 factor (e.g. day effect)</para> 623 </listitem> 624 <listitem> 625 <para><guilabel>Protocol</guilabel>: this a controled field. A select-list displays 626 protocol whose type is '<guilabel>extraction</guilabel>' and which are shared to or owned 627 by the logged-in user. Reporting Protocol should be viewed as a MIAME requirement</para> 628 </listitem> 629 <listitem> 630 <para><guilabel>Description</guilabel>: a free text field to report any information that 631 not can be captured otherwise</para> 632 </listitem> 633 </itemizedlist> 634 <para>Finally, a 7th field <guilabel>Registered</guilabel> is automatically populated with a 635 date at which the sample was entered in BASE2 system.</para> 636 <figure id="write_docbook_doc.figures.extract-tab-1"> 637 <title>Extract tab</title> 638 <screenshot> 639 <mediaobject> 640 <imageobject> 641 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-1.png" format="PNG"/> 642 </imageobject> 643 </mediaobject> 644 </screenshot> 645 </figure> 646 </listitem> 647 <listitem> 648 <para>The Parents Tab </para> 649 <para>This important tab allows users to select the Extract origin. BASE2 distinguished 650 between 2 cases which are controled by the <guibutton>'pooled'</guibutton> radio-button</para> 651 <orderedlist> 652 <listitem> 653 <para>The Parent is a Sample</para> 654 <para> The <guibutton>pooled</guibutton> radio-button is set to <guilabel>No</guilabel></para> 655 <para> The Sample select button is active and allows users to point to one and only one 656 Sample from which the sample originates from.</para> 657 <figure id="write_docbook_doc.figures.extract-tab-2-select-sample"> 658 <title>Parent tab and interaction when pooled button is set to No</title> 659 <screenshot> 660 <mediaobject> 661 <imageobject> 662 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-2-select-sample.png" format="PNG"/> 663 </imageobject> 664 </mediaobject> 665 </screenshot> 666 </figure> 667 </listitem> 668 <listitem> 669 <para>The Parent is another Extract</para> 670 <para> The <guibutton>pooled</guibutton> radio-button has to be set to 671 <guilabel>Yes</guilabel></para> 672 <para>Upon selection, the Samples select button is deactivated and the Extracts box and 673 button are activated.</para> 674 <para>This allows users to specify one or more extracts to be selected from the Extract 675 list View page.</para> 676 <figure id="write_docbook_doc.figures.extract-tab-2-select-extract"> 677 <title>Parent tab and interaction when pooled button is set to Yes</title> 678 <screenshot> 679 <mediaobject> 680 <imageobject> 681 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-2-select-extract.png" format="PNG"/> 682 </imageobject> 683 </mediaobject> 684 </screenshot> 685 </figure> 686 </listitem> 687 </orderedlist> 688 </listitem> 689 <listitem> 690 <para>Annotations & parameters </para> 691 <para>As seen in the BioSource and Sample sections, this tab allows users to supply further 692 information about the Extract, provided they have defined Annotation Types to annotation 693 Extract items or have such elements shared to them.</para> 694 <para>The display of Annotation Type can be filtered based on the Annotation Type Category 695 they belong to.</para> 696 <important> 697 <para> In order to use this feature, Annotation Type must be declared and made available. To 698 learn more about Annotation Types, please refer to <xref linkend="annotations"/> 699 </para> 700 </important> 701 <para>To provide a value for a given annotation type, simply click on it an use the input 702 field or select a value from the drop-down lists or radio buttons.</para> 703 <figure id="write_docbook_doc.figures.extract-tab-3"> 704 <title>Annotations & parameters</title> 705 <screenshot> 706 <mediaobject> 707 <imageobject> 708 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-3.png" format="PNG"/> 709 </imageobject> 710 </mediaobject> 711 </screenshot> 712 </figure> 713 </listitem> 714 <listitem> 715 <para>Inherited Annotations case1 </para> 716 <para>The next picture shows </para> 717 <figure id="write_docbook_doc.figures.extract-tab-4"> 718 <title>Inherited Annotations</title> 719 <screenshot> 720 <mediaobject> 721 <imageobject> 722 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-4.png" format="PNG"/> 723 </imageobject> 724 </mediaobject> 725 </screenshot> 726 </figure> 727 </listitem> 728 </itemizedlist> 729 </listitem> 730 </orderedlist> 731 </sect2> 732 <sect2 id="extract.manage.createextractpool"> 733 <title>Creating Pooled Extracts</title> 734 <para>It is common practice when biological material is scarce to pool extracts from equivalent 735 sources. BASE2 provides mechanisms to report on such practice. This section details how.</para> 736 <para>There are 2 ways to create pooled samples in BASE2:</para> 737 <orderedlist> 738 <listitem> 739 <para>Using the Pooled radio button option from the Extract Create page, and this has been 740 shown already.</para> 741 </listitem> 742 <listitem> 743 <para>Using the Pool button in the Menu bar</para> 744 <para>The Sample List View page menu bar contains an addition <guibutton>Pool…</guibutton> 745 <inlinemediaobject> 746 <imageobject> 747 <imagedata fileref="figures/new_pooled.gif" format="GIF"/> 748 </imageobject> 749 </inlinemediaobject> button, the usage of which is detailed now.</para> 750 <para>The <guibutton>Pool…</guibutton> 751 <inlinemediaobject> 752 <imageobject> 753 <imagedata fileref="figures/new_pooled.gif" format="GIF"/> 754 </imageobject> 755 </inlinemediaobject> button allows users to create Pooled Extracts by selecting the list of 756 Extracts used to derived a new Extract. Users simply to tick to boxes in front of each 757 relevant Extract and click the <guibutton>Pool...</guibutton></para> 758 <para>This provides an easy and simple way to create pooled Extracts. The result of such 759 process is the creation of a New Extract, in which, when navigating to the Parent tab, shows 760 that all the Extracts involved are already set and listed in the Extract box of the tab.</para> 761 <figure id="write_docbook_doc.figures.biosample-tab-2-pool-extract"> 762 <title>Pooling of Extracts</title> 763 <screenshot> 764 <mediaobject> 765 <imageobject> 766 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-tab-2-pool-extract.png" format="PNG"/> 767 </imageobject> 768 </mediaobject> 769 </screenshot> 770 </figure> 771 </listitem> 772 </orderedlist> 773 </sect2> 774 <sect2 id="extract.manage.delete"> 775 <title>Deleting/Restoring Extracts</title> 776 <para>As for other items in BASE2, Extracts can be removed. For a generic overview on how to 777 delete and restore items, refer to section <xref linkend="webclient.items.delete"/> 778 </para> 779 <para>To delete, do the following</para> 780 <itemizedlist> 781 <listitem> 782 <para> Select one or more Extract and click <guibutton>Delete</guibutton> button in the menu 783 bar.</para> 784 <para> All the selected Extracts have been marked as deleted and are no longer available from 785 the interface.</para> 786 <para> Only by selecting from the <guilabel>view/preset…</guilabel> select box the 787 <guilabel>Removed</guilabel> option, one can see those of the Extracts earmarked for 788 deletion. They will be shown with a symbol in front of them.</para> 789 </listitem> 790 <listitem> 791 <para> Alternately, navigating to the Extract Item View, one can hit the 792 <guibutton>Delete</guibutton> to performed the task.</para> 793 <para> As shown in the next picture, the Extract is then marked with the <guilabel>This item 794 has been flagged for deletion</guilabel> 795 </para> 796 <figure id="write_docbook_doc.figures.extract-delete"> 797 <title>Deleting Extracts from the Item View</title> 798 <screenshot> 799 <mediaobject> 800 <imageobject> 801 <imagedata contentwidth="12cm" width="12cm" fileref="figures/extract-delete.png" format="PNG"/> 802 </imageobject> 803 </mediaobject> 804 </screenshot> 805 </figure> 806 </listitem> 807 <listitem> 808 <para>Deletion errors at this stage can be easily recovered. Select the item to recover from 809 the List View (be sure to check the <guilabel>removed</guilabel> option in the View/preset.. 810 filter) and hit the <guibutton>Restore</guibutton> to performed the task. </para> 811 </listitem> 812 </itemizedlist> 813 <important> 814 <para>To really delete an item from the database you must use the trashcan. Items deleted from 815 the Trashcan can not be recovered. To learn more about the trashcan function, please refer to 816 <xref linkend="trashcan"/> 817 </para> 818 </important> 819 </sect2> 820 </sect1> 821 822 823 824 <sect1 id="label"> 825 <title>Managing Labels</title> 826 827 <sect2 id="label.browse"> 828 <title>Browsing Labels</title> 829 <para>Before attempting to create Labeled Extracts, users should make sure that the appropriate 830 Label object is present in BASE2</para> 831 <para>To browse the list of Labels, go to <menuchoice> 832 <guimenu>View</guimenu> 833 <guimenuitem>Labels</guimenuitem> 834 </menuchoice> It is wise to select the clear filter option or select the <guilabel>shared to 835 me</guilabel> option from the view/preset select box in order to view all different dyes.</para> 836 <para>Clicking on any of item opens an item view page</para> 837 <figure id="write_docbook_doc.figures.label-itemview"> 838 <title>The Label Item View Page</title> 839 <screenshot> 840 <mediaobject> 841 <imageobject> 842 <imagedata contentwidth="12cm" width="12cm" fileref="figures/label-itemview.png" format="PNG"/> 843 </imageobject> 844 </mediaobject> 845 </screenshot> 846 </figure> 847 <para>Note the <guibutton>New labeled extract</guibutton> button available from this page. For 848 more detailed about creating Labeled extracts, see <xref linkend="labeledextract.manage"/></para> 849 850 </sect2> 851 <sect2 id="label.create"> 852 <title>Creating Labels</title> 853 <para> Click on <guibutton>New…</guibutton> button, a pop-up window opens. Fill in 854 Name and description if required. Label item are very simple object and do not bear association 855 to Annotation Type. </para> 856 </sect2> 857 </sect1> 858 <sect1 id="labeledextract.manage"> 859 <title>Managing Labeled Extracts</title> 860 <para>Labeled Extract items should be used to describe the event that transformed a Extract 861 material in a Labeled Extract material.</para> 862 <para>Labeled extracts can be created from Extract items or from one or more Labeled extract 863 items.</para> 864 <para>When a Labeled Extract is created from several other Labeled Extracts, a Pooling event is 865 performed. A specific section details how to create pooled Labeled Extracts</para> 866 <para>During the transformation from Extracts to Labeled Extracts, it is possible to provide 867 information about the protocol used to perform this task.</para> 868 <para>It is not enforced in BASE2 but it should serve as guidance when devising the granularity of 869 the extract processing task. Also, it is good practice to provide protocol information.</para> 870 <sect2 id="labeledextract.manage.createlabeledextractfromextract"> 871 <title>Creating Labeled Extracts</title> 872 <orderedlist> 873 <listitem> 874 <para>Creating Labeled Extracts from the Extract page</para> 875 <para>Following the laboratory workflow, a natural way to create a Labeled Extract is to click 876 on the <guibutton>New labeled extract</guibutton> from the Labeled Extract column of the 877 Extract List View.</para> 878 <figure id="write_docbook_doc.figures.sample-create-labeledextract"> 879 <title>Creating a Labeled Extract from the Extract List View</title> 880 <screenshot> 881 <mediaobject> 882 <imageobject> 883 <imagedata contentwidth="12cm" width="12cm" fileref="figures/sample-create-labeledextract.png" format="PNG"/> 884 </imageobject> 885 </mediaobject> 886 </screenshot> 887 </figure> 888 </listitem> 889 <listitem> 890 <para>Creating Labeled Extracts from the Extract Item View page</para> 891 <para> Alternately, Labeled Extracts can be created directly using the Labeled Extract create 892 page. To do so, go to <menuchoice> 893 <guimenu>View</guimenu> 894 <guimenuitem>Labeled Extracts</guimenuitem> 895 </menuchoice> , Click on <guibutton>New…</guibutton> button </para> 896 <para> A 'Create' pop-up window opens, it contains 4 tabs: <guilabel>Labeled 897 Extract</guilabel>, <guilabel>Parents</guilabel>, <guilabel> Annotations & 898 parameters</guilabel> and <guilabel>Inherited Annotations</guilabel>. </para> 899 <itemizedlist> 900 <listitem> 901 <para>The Labeled Extract Tab </para> 902 <para>This tab contains 2 mandatory fields, one for providing the Labeled Extract 903 <guilabel>Name</guilabel>, the other one <guilabel>Label</guilabel> to specify which dye or 904 marker was used in the labeling reaction.</para> 905 <para> BASE2 by default assigns names to Labeled Extract(by suffixing 'lbe#' when creating a 906 Labeled Extract from an existing Extract or 'New labeled extract' otherwise) but it is 907 possible to edit it at will</para> 908 <para>There 5 optional fields to provide more detailed information</para> 909 <itemizedlist> 910 <listitem> 911 <para><guilabel>External ID</guilabel>: for instance to report a barcode attached to an 912 extract</para> 913 </listitem> 914 <listitem> 915 <para><guilabel>Original Quantity (ug)</guilabel>: this is meant to report information 916 about the actual mass of biomaterial created</para> 917 </listitem> 918 <listitem> 919 <para><guilabel>Created</guilabel>: a date should be provided. The information can be 920 important when running quality controls on data and account for potential confounding 921 factor (e.g. day effect)</para> 922 </listitem> 923 <listitem> 924 <para><guilabel>Protocol</guilabel>: this a controled field. A select-list displays 925 protocol whose type is '<guilabel>labeling</guilabel>' and which are shared to or owned by 926 the logged-in user. Reporting Protocol should be viewed as a MIAME requirement</para> 927 </listitem> 928 <listitem> 929 <para><guilabel>Description</guilabel>: a free text field to report any information that 930 can not be captured otherwise</para> 931 </listitem> 932 </itemizedlist> 933 <para>Finally, a 7th field <guilabel>Created</guilabel> is automatically populated with a 934 date at which the Labeled Extract was actually entered in BASE2 system.</para> 935 <figure id="write_docbook_doc.figures.labeledextract-tab-1"> 936 <title>Labeled Extract tab</title> 937 <screenshot> 938 <mediaobject> 939 <imageobject> 940 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-1.png" format="PNG"/> 941 </imageobject> 942 </mediaobject> 943 </screenshot> 944 </figure> 945 </listitem> 946 <listitem> 947 <para>The Parents Tab </para> 948 <para>This important tab allows users to select the Labeled Extract origin. BASE2 949 distinguished between 2 cases which are controled by the <guibutton>'pooled'</guibutton> 950 radio-button</para> 951 <orderedlist> 952 <listitem> 953 <para>The Parent is an Extract</para> 954 <para> The <guibutton>pooled</guibutton> radio-button is set to <guilabel>No</guilabel></para> 955 <para> The Extract select button is active and allows users to point to one and only one 956 Extract from which the Labeled Extract originates from.</para> 957 <figure id="write_docbook_doc.figures.labeledextract-tab-2-select-extract"> 958 <title>Parent tab and interaction when pooled button is set to No</title> 959 <screenshot> 960 <mediaobject> 961 <imageobject> 962 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-2-select-extract.png" format="PNG"/> 963 </imageobject> 964 </mediaobject> 965 </screenshot> 966 </figure> 967 </listitem> 968 <listitem> 969 <para>The Parent is another Labeled Extract</para> 970 <para> The <guibutton>pooled</guibutton> radio-button has to be set to 971 <guilabel>Yes</guilabel></para> 972 <para>Upon selection, the Extract select button is deactivated and the Labeled Extracts box 973 and button are activated. </para> 974 <para>This allows users to specify one or more extracts to be selected from the Labeled 975 Extract list View page. </para> 976 <figure id="write_docbook_doc.figures.labeledextract-tab-2-select-labeledextract"> 977 <title>Parent tab and interaction when pooled button is set to Yes</title> 978 <screenshot> 979 <mediaobject> 980 <imageobject> 981 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-2-select-labeledextract.png" format="PNG"/> 982 </imageobject> 983 </mediaobject> 984 </screenshot> 985 </figure> 986 </listitem> 987 </orderedlist> 988 </listitem> 989 <listitem> 990 <para>Annotations & parameters </para> 991 <para>As seen in the BioSource and Sample sections, this tab allows users to further supply 992 information about the labeled extract provided they have defined annotation types to 993 annotate Labeled Extract items or have such elements shared to them.</para> 994 <para>The display of Annotation Types can be filtered based on the Annotation Type Categories 995 they belong to.</para> 996 <important> 997 <para> In order to use this feature, Annotation Type must be declared and made available. To 998 learn more about Annotation Types, please refer to <xref linkend="annotations"/> 999 </para> 1000 </important> 1001 <para>To provide a value for a given annotation type, simply click on it an use the input 1002 field or select a value from the drop-down lists or radio buttons.</para> 1003 <figure id="write_docbook_doc.figures.labeledextract-tab-3"> 1004 <title>Annotations & parameters</title> 1005 <screenshot> 1006 <mediaobject> 1007 <imageobject> 1008 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-3.png" format="PNG"/> 1009 </imageobject> 1010 </mediaobject> 1011 </screenshot> 1012 </figure> 1013 </listitem> 1014 <listitem> 1015 <para>Inherited Annotations case1 </para> 1016 <para>The next picture shows </para> 1017 <figure id="write_docbook_doc.figures.labeledextract-tab-4"> 1018 <title>Inherited Annotations</title> 1019 <screenshot> 1020 <mediaobject> 1021 <imageobject> 1022 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-4.png" format="PNG"/> 1023 </imageobject> 1024 </mediaobject> 1025 </screenshot> 1026 </figure> 1027 </listitem> 1028 </itemizedlist> 1029 </listitem> 1030 </orderedlist> 1031 </sect2> 1032 <sect2 id="labeledextract.manage.createelabeledxtract.pool"> 1033 <title>Creating Pooled Labeled Extracts</title> 1034 <para>It is common practice when biological material is scarce to pool extracts from equivalent 1035 sources. BASE2 provides mechanisms to report on such practice.</para> 1036 <para>This section details how.</para> 1037 <para>There are 2 ways to create pooled Labeled Extracts in BASE2</para> 1038 <orderedlist> 1039 <listitem> 1040 <para>Using the Pooled radio button option from the Labeled Extract Create page, and this has 1041 been shown already </para> 1042 </listitem> 1043 <listitem> 1044 <para>Using the Pool button in the Menu bar</para> 1045 <para>The Labeled Extracts List View page menu bar contains an addition 1046 <guibutton>Pool…</guibutton> button, the usage of which is detailed now.</para> 1047 <para>The <guibutton>Pool…</guibutton> button <inlinemediaobject> 1048 <imageobject> 1049 <imagedata fileref="figures/new_pooled.gif" format="GIF"/> 1050 </imageobject> 1051 </inlinemediaobject> allows users to create Pooled Labeled Extracts by selecting the list of 1052 Labeled Extracts used to derived a new Labeled Extract. Users simply have to tick to boxes in 1053 front of each relevant Labeled Extract and click the <guibutton>Pool...</guibutton></para> 1054 <para>This provides an easy and simple way to create pooled Labeled Extracts. The result of 1055 such process is the creation of a New Labeled Extract, in which, when navigating to the Parent 1056 tab, shows that all the Labeled Extracts involved are already set and listed in the Labeled 1057 Extract box of the tab.</para> 1058 <figure id="write_docbook_doc.figures.labeledextract-tab-2-pool-labeledextract"> 1059 <title>Pooling of Labeled Extracts:</title> 1060 <screenshot> 1061 <mediaobject> 1062 <imageobject> 1063 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-tab-2-pool-labeledextract.png" format="PNG"/> 1064 </imageobject> 1065 </mediaobject> 1066 </screenshot> 1067 </figure> 1068 </listitem> 1069 </orderedlist> 1070 </sect2> 1071 <sect2 id="labeledextract.manage.delete"> 1072 <title>Deleting/Restoring Labeled Extracts</title> 1073 <para>As for other items in BASE2, Labeled Extracts can be deleted. For a generic overview on how 1074 to delete and restore items, refer to section <xref linkend="webclient.items.delete"/></para> 1075 <para>To delete, do the following</para> 1076 <itemizedlist> 1077 <listitem> 1078 <para> Select one or more Labeled Extract and click <guibutton>Delete</guibutton> button in the 1079 menu bar. </para> 1080 <para> All the selected Labeled Extracts have been marked as deleted and are no longer 1081 available from the interface. </para> 1082 <para> Only by selecting from the <guilabel>view/preset…</guilabel> select box the 1083 <guilabel>Removed</guilabel> option, one can see those of the Labeled Extracts earmarked for 1084 deletion. They will be shown with a symbol in front of them. </para> 1085 </listitem> 1086 <listitem> 1087 <para> Alternately, navigating to the Labeled Extract Item View, one can hit the 1088 <guibutton>Delete</guibutton> to performed the task. As showed in the next picture, the 1089 Labeled Extract is then marked with the <inlinemediaobject> 1090 <imageobject> 1091 <imagedata fileref="figures/deleted.gif" format="GIF"/> 1092 </imageobject> 1093 </inlinemediaobject> 1094 <guiicon>This item has been flagged for deletion</guiicon> 1095 </para> 1096 <figure id="write_docbook_doc.figures.labeledextract-delete"> 1097 <title>Deleting Labeled Extracts from the Item View</title> 1098 <screenshot> 1099 <mediaobject> 1100 <imageobject> 1101 <imagedata contentwidth="12cm" width="12cm" fileref="figures/labeledextract-delete.png" format="PNG"/> 1102 </imageobject> 1103 </mediaobject> 1104 </screenshot> 1105 </figure> 1106 </listitem> 1107 <listitem> 1108 <para>Deletion errors at this stage can be easily recovered. Select the item to recover from 1109 the List View (be sure to check the <guilabel>Removed</guilabel> option in the View/preset.. 1110 filter) and hit the <guibutton>Restore</guibutton> to performed the task. </para> 1111 </listitem> 1112 </itemizedlist> 1113 <important> 1114 <para>To really delete an item from the database you must use the trashcan. Items deleted from 1115 the Trashcan can not be recovered. To learn more about the trashcan function, please refer to 1116 <xref linkend="trashcan"/> 1117 </para> 1118 </important> 1119 </sect2> 1120 </sect1> 1121 <sect1 id="hybridization.manage"> 1122 <title>Managing Hybridizations</title> 1123 <para> An hybridization event corresponds to the application of one or more labeled extracts 1124 materials to a microarray slide under conditions detailed in hybridization protocols. </para> 1125 <para>In BASE2, there are 3 possible routes to create an hybridization object.</para> 1126 <sect2 id="hybridization.manage.create"> 1127 <title>Creating Hybridizations</title> 1128 <orderedlist> 1129 <listitem> 1130 <para>Creating Hybridization from the Labeled Extract List View page</para> 1131 <para>Select at least one Labeled Extract by ticking to selection boxes before the name field.</para> 1132 <para>Click on the <guibutton>New hybridzation (to be changed)</guibutton> from the menu bar of 1133 Labeled Extract list view.</para> 1134 <figure id="write_docbook_doc.figures.hyb-create-labeledlistview"> 1135 <title>Creating a Hybridization from the Labeled Extract List View</title> 1136 <screenshot> 1137 <mediaobject> 1138 <imageobject> 1139 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hyb-create-labeledlistview.png" format="PNG"/> 1140 </imageobject> 1141 </mediaobject> 1142 </screenshot> 1143 </figure> 1144 </listitem> 1145 <listitem> 1146 <para>Creating Hybridization from the Labeled Extract Item View page</para> 1147 <para>After having selected a Labeled Extract and displayed it in the Item View, Click on the 1148 <guibutton>New hybridization</guibutton> button from the Menu bar of the Labeled Extract Item 1149 View.</para> 1150 <figure id="write_docbook_doc.figures.hyb-create-labeleditemview"> 1151 <title>Creating a Hybridization from the Labeled Extract Item View</title> 1152 <screenshot> 1153 <mediaobject> 1154 <imageobject> 1155 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hyb-create-labeleditemview.png" format="PNG"/> 1156 </imageobject> 1157 </mediaobject> 1158 </screenshot> 1159 </figure> 1160 </listitem> 1161 <listitem> 1162 <para>Creating Hybridizations from the Hybridization List View page</para> 1163 <para> Hybridizations can be created directly using the Hybridization create page. To do so, go 1164 to <menuchoice> 1165 <guimenu>View</guimenu> 1166 <guimenuitem>Hybridizations</guimenuitem> 1167 </menuchoice> , Click on <guibutton>New…</guibutton> 1168 </para> 1169 <figure id="write_docbook_doc.figures.hyb-create"> 1170 <title>Creating Hybridizations from the Hybridization List View</title> 1171 <screenshot> 1172 <mediaobject> 1173 <imageobject> 1174 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hyb-create.png" format="PNG"/> 1175 </imageobject> 1176 </mediaobject> 1177 </screenshot> 1178 </figure> 1179 <para> Irrespective of the methods chosen to create the Hybridization item, A 'Create' pop-up 1180 window will open. It contains 4 distinct tabs: <guilabel>Hybridization</guilabel>, 1181 <guilabel>Parents</guilabel>, <guilabel> Annotations & parameters</guilabel> and 1182 <guilabel>Inherited Annotations</guilabel>. </para> 1183 <itemizedlist> 1184 <listitem> 1185 <para>The Hybridization Tab </para> 1186 1187 <variablelist> 1188 <varlistentry> 1189 <term> 1190 <interface>Name</interface> 1191 </term> 1192 <listitem> 1193 <para> New Hybridization is BASE2 default name but it is strongly advise to provide a 1194 meaningful and unique name as it matters for tab2mage export to function properly. </para> 1195 <para>There are 5 optional fields to provide more detailed information</para> 1196 1197 </listitem> 1198 </varlistentry> 1199 1200 <varlistentry> 1201 <term> 1202 <guilabel>Created</guilabel> 1203 </term> 1204 <listitem> 1205 <para>A date should be provided. The information can be important when running quality 1206 controls on data and account for potential confounding factor (e.g. to account for a day 1207 effect)</para> 1208 </listitem> 1209 </varlistentry> 1210 1211 <varlistentry> 1212 <term> 1213 <guilabel>Protocol</guilabel> 1214 </term> 1215 <listitem> 1216 <para>This is a controled field. A select-list displays protocol whose type is 1217 '<guilabel>hybridization</guilabel>' and which are shared to or owned by the logged-in 1218 user.</para> 1219 <important> 1220 <para> Reporting Protocols should be viewed as a MIAME requirement </para> 1221 </important> 1222 </listitem> 1223 </varlistentry> 1224 1225 <varlistentry> 1226 <term> 1227 <guilabel>Hardware</guilabel> 1228 </term> 1229 <listitem> 1230 <para>This is a controled field. A select-list displays Hardware whose type is 1231 '<guilabel>Hybridization station</guilabel>' and which are shared to or owned by the 1232 logged-in user.</para> 1233 </listitem> 1234 </varlistentry> 1235 1236 <varlistentry> 1237 <term> 1238 <guilabel>Array Slide</guilabel> 1239 </term> 1240 <listitem> 1241 <para>This is meant to specify the actual microarray slide.</para> 1242 <note> 1243 <para>Ideally, The Array Slides should have been created but for those users with 1244 permission to do, Array Slides could be generated at that point.</para> 1245 </note> 1246 </listitem> 1247 </varlistentry> 1248 1249 <varlistentry> 1250 <term> 1251 <guilabel>Description</guilabel> 1252 </term> 1253 <listitem> 1254 <para>A free text field to report any information that can not be captured 1255 otherwise</para> 1256 </listitem> 1257 </varlistentry> 1258 1259 <varlistentry> 1260 <term> 1261 <guilabel>Registered</guilabel> 1262 </term> 1263 <listitem> 1264 <para>This 7th field is automatically populated with a date at which the sample was 1265 entered in BASE2 system.</para> 1266 </listitem> 1267 </varlistentry> 1268 </variablelist> 1269 1270 <figure id="write_docbook_doc.figures.hybridization-tab-1"> 1271 <title>Hybridization tab</title> 1272 <screenshot> 1273 <mediaobject> 1274 <imageobject> 1275 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hybridization-tab-1.png" format="PNG"/> 1276 </imageobject> 1277 </mediaobject> 1278 </screenshot> 1279 </figure> 1280 </listitem> 1281 <listitem> 1282 <para>The Labeled Extract Tab </para> 1283 <para>This important tab allows users to select the Labeled Extracts applied to an Array 1284 Slide, and specify the amount of material used, expressed in microgram.</para> 1285 <figure id="write_docbook_doc.figures.hybridization-tab-2"> 1286 <title>Labeled Extract tab</title> 1287 <screenshot> 1288 <mediaobject> 1289 <imageobject> 1290 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hybridization-tab-2.png" format="PNG"/> 1291 </imageobject> 1292 </mediaobject> 1293 </screenshot> 1294 </figure> 1295 </listitem> 1296 <listitem> 1297 <para>Annotations & parameters </para> 1298 <para>As seen in the BioSource and Sample sections, this tab allows users to supply further 1299 information about the hybridization provided annotation types have been defined or shared to 1300 annotate Hybridization items. The display of Annotation Types can be filtered based on the 1301 Annotation Type Category they belong to.</para> 1302 <important> 1303 <para> In order to use this feature, Annotation Type must be declared and made available. To 1304 learn more about Annotation Types, please refer to <xref linkend="annotations"/> 1305 </para> 1306 </important> 1307 <para>To provide a value for a given annotation type, simply click on it and use the input 1308 field or select a value from the drop-down lists or radio buttons.</para> 1309 <para>A caption also reminds users if Annotation Types are parameters <inlinemediaobject> 1310 <imageobject> 1311 <imagedata fileref="figures/parameter.gif" format="GIF"/> 1312 </imageobject> 1313 </inlinemediaobject>and if annotation values have already been supplied, marked by the <inlinemediaobject> 1314 <imageobject> 1315 <imagedata fileref="figures/annotated.gif" format="GIF"/> 1316 </imageobject> 1317 </inlinemediaobject> logo.</para> 1318 <figure id="write_docbook_doc.figures.hybridization-tab-3"> 1319 <title>Annotations & parameters</title> 1320 <screenshot> 1321 <mediaobject> 1322 <imageobject> 1323 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hybridization-tab-3.png" format="PNG"/> 1324 </imageobject> 1325 </mediaobject> 1326 </screenshot> 1327 </figure> 1328 </listitem> 1329 <listitem> 1330 <para>Inherited Annotations </para> 1331 <para>The next screenshot shows a typical view of the functionality.</para> 1332 <figure id="write_docbook_doc.figures.hybridization-tab-4"> 1333 <title>Inherited Annotations</title> 1334 <screenshot> 1335 <mediaobject> 1336 <imageobject> 1337 <imagedata contentwidth="12cm" width="12cm" fileref="figures/hybridization-tab-4.png" format="PNG"/> 1338 </imageobject> 1339 </mediaobject> 1340 </screenshot> 1341 </figure> 1342 <para> Note the tags used to distinguish between Annotation Types which are parameters noted <inlinemediaobject> 1343 <imageobject> 1344 <imagedata fileref="figures/parameter.gif" format="GIF"/> 1345 </imageobject> 1346 </inlinemediaobject> and those which are Biomaterial Characteristics,noted <inlinemediaobject> 1347 <imageobject> 1348 <imagedata fileref="figures/annotation.gif" format="GIF"/> 1349 </imageobject> 1350 </inlinemediaobject></para> 1351 </listitem> 1352 </itemizedlist> 1353 </listitem> 1354 </orderedlist> 1355 </sect2> 1356 <sect2 id="hybridization.manage.viewedit"> 1357 <title>Viewing/Editing Hybridizations</title> 1358 <para>As for other items in BASE2, Hybridizations can be edited. To do so, do the following</para> 1359 <itemizedlist> 1360 <listitem> 1361 <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or 1362 <keycap>SHIFT</keycap> keys while clicking on the name of an Hybridization Item, which is a 1363 live link. </para> 1364 </listitem> 1365 <listitem> 1366 <para> Alternately, navigating to the Hybridization Item View, one can hit the 1367 <guibutton>Edit</guibutton> to performed the task.</para> 1368 </listitem> 1369 1370 <listitem> 1371 <para>The Hybridization item View summarizes key information such as the list of 1372 <guilabel>Labeled Extracts</guilabel>, and the list of associated <guilabel>Scans</guilabel>. 1373 Both are available as hyperlinks to allow quick and easy navigation.</para> 1374 <figure id="write_docbook_doc.figures.hybridization-itemview"> 1375 <title>Hardware Item View</title> 1376 <screenshot> 1377 <mediaobject> 1378 <imageobject> 1379 <imagedata contentwidth="10cm" width="10cm" fileref="figures/hybridization-itemview.png" format="PNG"/> 1380 </imageobject> 1381 </mediaobject> 1382 </screenshot> 1383 </figure> 1384 </listitem> 1385 </itemizedlist> 1386 1387 </sect2> 1388 1389 <sect2 id="hybridization.manage.delete"> 1390 <title>Deleting/Restoring Hybridizations</title> 1391 <para>As for other items in BASE2, Hybridizations can be deleted. For a generic overview on how 1392 to delete and restore items, refer to section <xref linkend="webclient.items.delete"/> 1393 </para> 1394 1395 <para>To delete, do the following</para> 1396 <itemizedlist> 1397 <listitem> 1398 <para> Select one or more Hybridization Items and click on the <guibutton>Delete</guibutton> 1399 button in the menu bar. </para> 1400 <para> All the selected Hybridizations have been marked as deleted and are no longer available 1401 from the interface. </para> 1402 <para> Only by selecting from the <guilabel>view/preset…</guilabel> select box the 1403 <guilabel>Removed</guilabel> option, one can see those of the Hybridizations earmarked for 1404 deletion. They will be shown with a symbol in front of them. </para> 1405 </listitem> 1406 <listitem> 1407 <para> Alternately, navigating to the Hybridization Item View, one can hit the 1408 <guibutton>Delete</guibutton> to performed the task. As shown in the next picture, the 1409 Hybridization is then marked with the <inlinemediaobject> 1410 <imageobject> 1411 <imagedata fileref="figures/deleted.gif" format="GIF"/> 1412 </imageobject> 1413 </inlinemediaobject><guilabel>This item has been flagged for deletion</guilabel> 1414 </para> 1415 <figure id="write_docbook_doc.figures.hybridization-delete"> 1416 <title>Deleting Hybridizations from the Hybridization Item View</title> 1417 <screenshot> 1418 <mediaobject> 1419 <imageobject> 1420 <imagedata contentwidth="10cm" width="10cm" fileref="figures/hybridization-delete.png" format="PNG"/> 1421 </imageobject> 1422 </mediaobject> 1423 </screenshot> 1424 </figure> 1425 </listitem> 1426 </itemizedlist> 1427 <important> 1428 <para>To really delete an item from the database you must use the trashcan. Items deleted from 1429 the Trashcan can not be recovered. To learn more about the trashcan function, please refer to 1430 <xref linkend="trashcan"/> 1431 </para> 1432 </important> 1433 </sect2> 1434 </sect1> 36 1435 </chapter> -
trunk/doc/src/docbook/userdoc/hardware.xml
r3246 r3372 3 3 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 4 4 "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"> 5 <!-- 6 $Id$ 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 <chapter id="hardware"> 29 <title>Hardware</title> 30 <sect1 id="hardware.introduction"> 31 <title>Introduction</title> 32 <para>Information about laboratory equipment can be tracked in BASE2 using two structures, the use 33 of which is detailed in the following sections. </para> 34 </sect1> 35 <sect1 id="hardware.manage"> 36 <title>Managing Hardware</title> 7 37 8 Copyright (C) Authors contributing to this file. 38 <sect2 id="hardware.manage.typecreate"> 39 <title>Creating Hardware Types</title> 40 <para><guilabel>Hardware Type</guilabel> allows classification of hardwares based on their usage 41 and purpose in the laboratory workflow.</para> 42 <para> By default, BASE2 creates the 3 main Hardware Types and those correspond to the main 43 hardware families identified by <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html" 44 >MIAME requirements</ulink>. These 3 Hardware Types are <guilabel>Print Robot</guilabel>, 45 <guilabel>Scanner</guilabel> and <guilabel>Hybridization station</guilabel> 46 </para> 47 <para>In case those built-in Hardware Type are not enough, it is possible to create new ones. To 48 do so:</para> 49 <para>Go To <menuchoice> 50 <guimenu>Administrate</guimenu> 51 <guimenuitem>Types</guimenuitem> 52 <guisubmenu>Hardware Type</guisubmenu> 53 </menuchoice> 54 </para> 55 <para> Click on <guibutton>New…</guibutton>. </para> 56 <para>A 'Create' pop-up window opens</para> 57 <para>Fill in <guilabel>Name</guilabel> and <guilabel>Description</guilabel></para> 58 <figure id="write_docbook_doc.figures.hardwaretype"> 59 <title>The Hardware Type Create Window</title> 60 <screenshot> 61 <mediaobject> 62 <imageobject> 63 <imagedata contentwidth="7cm" width="7cm" fileref="figures/hardwaretype.png" format="PNG"/> 64 </imageobject> 65 </mediaobject> 66 </screenshot> 67 </figure> 68 <tip><para> 69 It is advised to define the Hardware Type <guilabel>Name</guilabel> attribute so that it is 70 compatible with the MIAME requirements and recommendations issues by microarray data 71 repositories. 72 </para></tip> 73 <para>Click on the 74 <inlinemediaobject> 75 <imageobject> 76 <imagedata fileref="figures/save.gif" format="GIF"/> 77 </imageobject> 78 </inlinemediaobject> 79 Save button to store the information in BASE2 or on the 80 <inlinemediaobject> 81 <imageobject> 82 <imagedata fileref="figures/cancel.gif" format="GIF"/> 83 </imageobject> 84 </inlinemediaobject> 85 button to abort. 86 </para> 87 </sect2> 88 <sect2 id="hardware.manage.create"> 89 <title>Creating Hardwares</title> 90 <para>In BASE2, Hardwares can be created by 2 routes:</para> 91 <orderedlist> 92 <listitem> 93 <para>Creating Hardwares from the Hardware Type List View page</para> 94 <para>Clicking on the <inlinemediaobject> 95 <imageobject> 96 <imagedata fileref="figures/add.gif" format="GIF"/> 97 </imageobject> 98 </inlinemediaobject> add hardware button. 99 </para> 100 <figure id="write_docbook_doc.figures.hardware-frompt"> 101 <title>Create New hardware from the Hardware Type List View</title> 102 <screenshot> 103 <mediaobject> 104 <imageobject> 105 <imagedata contentwidth="10cm" width="10cm" fileref="figures/hardware-frompt.png" format="PNG"/> 106 </imageobject> 107 </mediaobject> 108 </screenshot> 109 </figure> 110 </listitem> 111 <listitem> 112 <para>Creating Hardware from the Hardware List View page</para> 113 <para>Go to 114 <menuchoice> 115 <guimenu>View</guimenu> 116 <guimenuitem>Hardware</guimenuitem> 117 </menuchoice></para> 118 <para>Click on <guibutton>New…</guibutton> button 119 </para> 120 </listitem> 121 </orderedlist> 9 122 10 This file is part of BASE - BioArray Software Environment. 11 Available at http://base.thep.lu.se/ 123 <para>In both cases, a Hardware Create pop-up window opens. The window contains 2 mandatory fields:</para> 124 <itemizedlist> 125 <listitem> 126 <para> 127 <guilabel>Name</guilabel> and <guilabel>Hardware type</guilabel>.</para> 128 <para>The later is a select-list population from Hardware Types owned by or shared to the user.</para> 129 </listitem> 130 <listitem> 131 <para><guilabel>Version</guilabel> and <guilabel>Description</guilabel>, the other 2 fields, are optional and self explanatory.</para> 132 </listitem> 133 </itemizedlist> 134 <para>Click on the 135 <inlinemediaobject> 136 <imageobject> 137 <imagedata fileref="figures/save.gif" format="GIF"/> 138 </imageobject> 139 </inlinemediaobject> 140 Save button to store the information in BASE2 or on the 141 <inlinemediaobject> 142 <imageobject> 143 <imagedata fileref="figures/cancel.gif" format="GIF"/> 144 </imageobject> 145 </inlinemediaobject> 146 button to abort. 147 </para> 12 148 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="hardware"> 30 <?dbhtml dir="hardware"?> 31 <title>Hardware</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 149 </sect2> 150 <sect2 id="hardware.manage.detail_view"> 151 <title>Viewing/Editing Hardwares</title> 152 <itemizedlist> 153 <listitem> 154 <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or 155 <keycap>SHIFT</keycap> keys while clicking on the name of an Hardware Item, which is a live 156 link. </para> 157 </listitem> 158 <listitem> 159 <para> Alternately, navigating to the Hardware Item View, one can hit the 160 <guibutton>Edit…</guibutton> to performed the task.</para> 161 <para>In both cases, an Edit pop-up windows opens. It is essentially identical to a Create 162 window and allows updating information about a particular Hardware item stored in BASE2</para> 163 <figure id="write_docbook_doc.figures.hardware-itemview"> 164 <title>Hardware Item View</title> 165 <screenshot> 166 <mediaobject> 167 <imageobject> 168 <imagedata contentwidth="10cm" width="10cm" fileref="figures/hardware-itemview.png" format="PNG"/> 169 </imageobject> 170 </mediaobject> 171 </screenshot> 172 </figure> 173 </listitem> 174 </itemizedlist> 175 </sect2> 176 <sect2 id="hardware.manage.delete"> 177 <title>Deleting/Restoring Hardwares</title> 178 <para>As for other items in BASE2, Hardwares can be removed and restored. To do so, do the 179 following</para> 180 <itemizedlist> 181 <listitem> 182 <para>Select one or more Hardwares and click <guibutton>Delete</guibutton> button in the menu 183 bar. </para> 184 <para>All the selected Hardwares have been marked as deleted and are no longer available from 185 the interface. </para> 186 <para>Only by selecting from the <guilabel>view/preset…</guilabel> select box the 187 <guilabel>Removed</guilabel> option, one can see those of the Hardwares earmarked for 188 deletion. They will be shown with a symbol 189 <inlinemediaobject> 190 <imageobject> 191 <imagedata fileref="figures/deleted.gif" format="GIF"/> 192 </imageobject> 193 </inlinemediaobject> in front of them. </para> 194 </listitem> 195 <listitem> 196 <para>Alternately, navigating to the Hardware Item View, one can hit the 197 <guibutton>Delete</guibutton> to performed the task. </para> 198 </listitem> 199 <listitem> 200 <para>Deletion errors at this stage can be easily recovered. Select the item to recover from 201 the List View (be sure to check the <guilabel>Removed</guilabel> option in the 202 <guilabel>view/preset…</guilabel> filter) and hit the 203 <guibutton>Restore</guibutton> button to performed the task. </para> 204 </listitem> 205 </itemizedlist> 206 <important> 207 <para>To really delete an item from the database you must use the trashcan. Items 208 deleted from the Trashcan can not be recovered. To learn more about the trashcan function, please refer to <xref linkend="trashcan"/> </para> 209 </important> 210 </sect2> 211 </sect1> 36 212 </chapter> -
trunk/doc/src/docbook/userdoc/index.xml
r3246 r3372 29 29 <?dbhtml dir="userdoc"?> 30 30 <title>User documentation</title> 31 <include file= 31 <include file="about.xml"/> 32 32 <include file="webclient.xml"/> 33 33 <include file="project_permission.xml"/> … … 44 44 <include file="experiments_analysis.xml"/> 45 45 <include file="import_export_data.xml"/> 46 <include file="faqs.xml"/> 46 47 </part> -
trunk/doc/src/docbook/userdoc/protocols.xml
r3246 r3372 3 3 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 4 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 29 <chapter id="protocols"> 30 <?dbhtml dir="protocols"?> 31 <title>Protocols</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 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 <chapter id="protocol"> 29 <title>Protocols</title> 30 <sect1 id="protocol.introduction"> 31 <title>Introduction</title> 32 <para>Information about laboratory standard operating procedure and protocols can be tracked in 33 BASE2 using two structures, the use of which is detailed in the following sections. </para> 34 </sect1> 35 <sect1 id="protocol.manage"> 36 <title>Managing Protocols</title> 37 <para> </para> 38 39 <helptext external_id="protocol.view.properties" title="Protocol Types"> 40 41 <sect2 id="protocoltype.create"> 42 <title>Creating Protocol Types</title> 43 <para><guilabel>Protocol Type</guilabel> allows classification of protocols based on their usage 44 and purpose in the laboratory workflow. By default, BASE2 creates the 8 main Protocol Types and 45 those correspond to the main protocol families identified by MIAME requirements and applied in 46 a canonical DNA microarray experiment meant for surveying gene expression. These 8 protocol 47 types are namely <guilabel>Printing</guilabel>, 48 <guilabel>Sampling</guilabel>,<guilabel>Pooling</guilabel>,<guilabel>Extraction</guilabel>, 49 <guilabel>Labeling</guilabel>, <guilabel>Hybridization</guilabel>, 50 <guilabel>Scanning</guilabel>, <guilabel>Feature extraction</guilabel> 51 </para> 52 <para>New applications of DNA microarray technology, for instance DNA binding site 53 identification, imposes the creation of new Protocol Type in addition to those built-in in 54 BASE2.</para> 55 <para>In order to do so</para> 56 <para>Go To <menuchoice> 57 <guimenu>Administrate</guimenu> 58 <guimenuitem>Types</guimenuitem> 59 <guisubmenu>Protocol Type</guisubmenu> 60 </menuchoice> 61 </para> 62 <para> Click on <guibutton>New…</guibutton>. </para> 63 <para>A 'Create' pop-up window opens and allow to fill in name and description</para> 64 <tip> 65 <para>It is advised to define the Protocol Type <guilabel>Name</guilabel> attribute so that it 66 is compatible with the MIAME requirements and recommendations issues by microarray data 67 repositories.</para> 68 </tip> 69 <itemizedlist> 70 <listitem> 71 <figure id="write_docbook_doc.figures.protocoltype"> 72 <title>The Protocol Type Create Window</title> 73 <screenshot> 74 <mediaobject> 75 <imageobject> 76 <imagedata fileref="figures/protocoltype.png" format="PNG"/> 77 </imageobject> 78 </mediaobject> 79 </screenshot> 80 </figure> 81 </listitem> 82 </itemizedlist> 83 </sect2> 84 85 </helptext> 86 87 <sect2 id="protocol.create"> 88 <title>Creating Protocols</title> 89 <para>In BASE2, Protocols can be created by 2 routes. Either from the Protocol Type page or from 90 the Protocol Page. </para> 91 <orderedlist> 92 <listitem> 93 <para>Creating Protocols from the Protocol Type View</para> 94 <para> Clicking on the <guibutton>(+) add protocol</guibutton> button. </para> 95 <figure id="write_docbook_doc.figures.protocol-frompt"> 96 <title>Create New Protocol from the Protocol Type list view</title> 97 <screenshot> 98 <mediaobject> 99 <imageobject> 100 <imagedata fileref="figures/protocol-frompt.png" format="PNG"/> 101 </imageobject> 102 </mediaobject> 103 </screenshot> 104 </figure> 105 </listitem> 106 <listitem> 107 <para>Creating Protocols from the Protocol View</para> 108 <para>Go to <menuchoice> 109 <guimenu>View</guimenu> 110 <guimenuitem>Protocol</guimenuitem> 111 </menuchoice> Click on <guibutton>New…</guibutton> button </para> 112 <para> Either way causes a 'Create' pop-up window to open, it contains 2 tabs: 113 <guilabel>Protocol</guilabel> and <guilabel>Parameters</guilabel>. </para> 114 <itemizedlist> 115 <listitem> 116 <para> 117 <guilabel>Protocol</guilabel> 118 </para> 119 <para> This tab allows users to enter essential information about a protocol. Mandatory tags 120 are Protocol <guilabel>Name</guilabel> and <guilabel>Protocol Type</guilabel>, the later 121 being in the form of a drop-down list populated by Protocol Types shared to the users. This 122 list therefore varies and may evolve depending on additions and permissions. The tab has 123 also a dedicated field <guilabel>File</guilabel> to enable linking of external files, e.g. 124 pdf documents from kit providers to the protocol.</para> 125 <figure id="write_docbook_doc.figures.protocol-1"> 126 <title>The Protocol tab in the Protocol Create Window</title> 127 <screenshot> 128 <mediaobject> 129 <imageobject> 130 <imagedata fileref="figures/protocol-1.png" format="PNG"/> 131 </imageobject> 132 </mediaobject> 133 </screenshot> 134 </figure> 135 </listitem> 136 <listitem> 137 <para> 138 <guilabel>Parameters</guilabel> 139 </para> 140 <para> This tab allows BASE2 users to declare parameters attached to a particular protocol. 141 Parameters are selected from a list of Annotation Types which have been flagged as 142 parameters. Only those Annotation Types are available for selection using the <guibutton>Add 143 annotation types…</guibutton> 144 </para> 145 <figure id="write_docbook_doc.figures.protocol-2"> 146 <title>The Paramater tab from the Protocol Create Window</title> 147 <screenshot> 148 <mediaobject> 149 <imageobject> 150 <imagedata fileref="figures/protocol-2.png" format="PNG"/> 151 </imageobject> 152 </mediaobject> 153 </screenshot> 154 </figure> 155 </listitem> 156 </itemizedlist> 157 </listitem> 158 </orderedlist> 159 </sect2> 160 <sect2 id="protocol.detail_view"> 161 <title>Viewing/Editing Protocols</title> 162 <itemizedlist> 163 <listitem> 164 <para>From the Protocol List View, clicking on the Protocol <guilabel>Name</guilabel> opens a 165 detail view for that protocol, showing a summary of all information available in BASE2 about 166 that entity</para> 167 </listitem> 168 <listitem> 169 <para>Alternately, from the Protocol Item View, clicking the 170 <guibutton>Edit…</guibutton> performs the same task. </para> 171 <figure id="write_docbook_doc.figures.protocol-itemview"> 172 <title>Protocol Item View</title> 173 <screenshot> 174 <mediaobject> 175 <imageobject> 176 <imagedata fileref="figures/protocol-itemview.png" format="PNG"/> 177 </imageobject> 178 </mediaobject> 179 </screenshot> 180 </figure> 181 </listitem> 182 <listitem> 183 <para> Note from the Protocol Item view how protocol <guilabel>Paramaters</guilabel> are 184 listed. Clicking on the <guilabel>Parameter name</guilabel> will open the corresponding 185 Annotation Type element in an item view </para> 186 </listitem> 187 </itemizedlist> 188 189 </sect2> 190 <sect2 id="protocol.delete"> 191 <title>Deleting/Restoring Protocols</title> 192 <para>As for other items in BASE2, some can be removed and restored. To do so, do the following</para> 193 <itemizedlist> 194 <listitem> 195 <para>Select one or more protocols and click the <guibutton>Delete</guibutton> button in the 196 menu bar. </para> 197 <para>All the selected protocols have been marked as deleted and are no longer available from 198 the interface. </para> 199 <para>Only by selecting from the <guilabel>view/preset…</guilabel> select box the 200 <guilabel>Removed</guilabel> option, one can see those of the protocols earmarked for 201 deletion. They will be shown with a symbol in front of them. </para> 202 </listitem> 203 <listitem> 204 <para>Alternately, navigating to the Protocol Item View, one can hit the 205 <guibutton>Delete</guibutton> to performed the task. </para> 206 </listitem> 207 <listitem> 208 <para>Deletion errors at this stage can be easily recovered. Select the item to recover from 209 the List View (be sure to check the <guilabel>Removed</guilabel> option in the 210 <guilabel>view/preset…</guilabel> filter) and hit the 211 <guibutton>Restore</guibutton> button to performed the task. </para> 212 </listitem> 213 </itemizedlist> 214 <important> 215 <para>To really delete an item from the database you must use the <link linkend="trashcan" 216 >trashcan</link>. Items deleted from the Trashcan can not be recovered. </para> 217 </important> 218 </sect2> 219 </sect1> 36 220 </chapter> -
trunk/doc/src/docbook/userdoc/reporters.xml
r3246 r3372 3 3 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 4 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 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 --> 29 28 <chapter id="reporters"> 30 <?dbhtml dir="reporter"?> 31 <title>Reporters</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 29 <title>Reporters</title> 30 <sect1 id="reporters.introduction"> 31 <title>Introduction</title> 32 <para>Reporter, a term coined by the MAGE object model refers to spotted DNA sequence on a 33 microarray. Reporters are therefore usually described by a sequence and a series of database 34 identifiers qualifying that sequence. Reporters are generally understood as the thing biologists 35 are interested in when carrying out DNA microarray experiments.</para> 36 <para>In BASE2, Reporters also refer to Affymetrix Probeset ID but Reporters can be used to 37 describe genes, transcripts, exons or any other sequence entity of biological relevance. </para> 38 </sect1> 39 <sect1 id="reporters.manage"> 40 <title>Managing Reporters</title> 41 <para> </para> 42 <sect2 id="reporters.manage.typecreate"> 43 <title>Creating Reporter Types</title> 44 <para><guilabel>Reporter Type</guilabel> allows classification of reporters based on their usage 45 and qualification defined during the array design specification. To create a Reporter Type,</para> 46 <para>Go To <menuchoice> 47 <guimenu>Administrate</guimenu> 48 <guimenuitem>Types</guimenuitem> 49 <guisubmenu>Reporter Type</guisubmenu> 50 </menuchoice> 51 </para> 52 <para> Click on <guibutton>New…</guibutton>. </para> 53 <para>A 'Create' pop-up window opens and allow to fill in <guilabel>Name</guilabel> and 54 <guilabel>Description</guilabel> 55 </para> 56 <important> 57 <para>It is advised to define the Reporter Type <guilabel>Name</guilabel> attribute so that it 58 is compatible with the <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html">MIAME 59 requirements</ulink> and recommendations issues by microarray data repositories. Alternately, 60 the local reporter type could be submitted to those repositories for term inclusion.</para> 61 </important> 62 <figure id="write_docbook_doc.figures.reportertype"> 63 <title>The Reporter Type Create Window</title> 64 <screenshot> 65 <mediaobject> 66 <imageobject> 67 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reportertype.png" format="PNG"/> 68 </imageobject> 69 </mediaobject> 70 </screenshot> 71 </figure> 72 <para> One can classically follow the classification between negative control, positive control 73 and experimental for simplificity. </para> 74 </sect2> 75 <sect2 id="reporters.manage.create"> 76 <title>Creating Reporters</title> 77 <para>Go to <menuchoice> 78 <guimenu>View</guimenu> 79 <guimenuitem>Reporter</guimenuitem> 80 </menuchoice> 81 </para> 82 <para>Click on <guibutton>New…</guibutton>. </para> 83 <para> A 'Create' pop-up window opens, it contains 2 tabs: <guilabel>Reporter</guilabel> and 84 <guilabel>Extended properties</guilabel>. </para> 85 <itemizedlist> 86 <listitem> 87 <para> 88 <guilabel>Reporter</guilabel> 89 </para> 90 <para> This tab shows core information that would be common to all base2 instances. Two 91 mandatory information fields have to be filled in: <guilabel>Name</guilabel> and 92 <guilabel>External ID</guilabel> e.g. a database identifier. If one requires additional and 93 more advanced information about the Reporter, the extended properties tab should be used. </para> 94 <figure id="write_docbook_doc.figures.reporter-1"> 95 <title>The Reporter tab in the Reporter Create Window</title> 96 <screenshot> 97 <mediaobject> 98 <imageobject> 99 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-1.png" format="PNG"/> 100 </imageobject> 101 </mediaobject> 102 </screenshot> 103 </figure> 104 </listitem> 105 <listitem> 106 <para> 107 <guilabel>Extended properties</guilabel> 108 </para> 109 <para>In BASE2, the Reporter Items belong to a special class whose properties used to qualify 110 them can be defined and extended by system administrators. This is done by modifying the 111 'extended-properties.xml' file during database configuration or upgrade. The file can be found 112 under <filename class="directory"> 113 \\apache-tomcat-5.5.15\webapps\base\WEB-INF\classes</filename>. </para> 114 <important> 115 <para> For more information about database configuration and upgrade process, please refer to 116 <xref linkend="installation_upgrade.installation"/>. This allow storing of just the right 117 amount of information. </para> 118 </important> 119 <para> This tab displays all kind of reporter properties as defined in the extended_properties </para> 120 <figure id="write_docbook_doc.figures.reporter-2"> 121 <title>The extended properties tab from the Reporter Create Window</title> 122 <screenshot> 123 <mediaobject> 124 <imageobject> 125 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-2.png" format="PNG"/> 126 </imageobject> 127 </mediaobject> 128 </screenshot> 129 </figure> 130 </listitem> 131 </itemizedlist> 132 <para>Click on the <inlinemediaobject> 133 <imageobject> 134 <imagedata fileref="figures/save.gif" format="GIF"/> 135 </imageobject> 136 </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject> 137 <imageobject> 138 <imagedata fileref="figures/cancel.gif" format="GIF"/> 139 </imageobject> 140 </inlinemediaobject> button to abort. </para> 141 </sect2> 142 143 <sect2 id="reporter.manage.viewedit"> 144 <title>Viewing/Editing Reporters</title> 145 <itemizedlist> 146 <listitem> 147 <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or 148 <keycap>SHIFT</keycap> keys while clicking on the name of a Reporter Item, which is a live 149 link. </para> 150 </listitem> 151 <listitem> 152 <para> Alternately, navigating to the Reporter Item View, one can hit the 153 <guibutton>Edit…</guibutton> to performed the task.</para> 154 <para>In both cases, an Edit pop-up windows opens. It is essentially identical to a Create 155 window and allows updating information about a particular ArraySlide item stored in BASE2</para> 156 <figure id="write_docbook_doc.figures.reporter-itemview"> 157 <title>Reporter Item View</title> 158 <screenshot> 159 <mediaobject> 160 <imageobject> 161 <imagedata contentwidth="10cm" width="10cm" fileref="figures/reporter-itemview.png" format="PNG"/> 162 </imageobject> 163 </mediaobject> 164 </screenshot> 165 </figure> 166 </listitem> 167 168 <listitem> 169 <para>From the Reporter item View, note the <guilabel>extended properties</guilabel> section 170 which displays biological information and cross-references to external databases. Depending on 171 the configuration of the extended properties file, backlinks to primary databases can be 172 established. In the above picture, note the hyperlinks to <guilabel>OMIM</guilabel> and 173 Unigene <guilabel>Cluster ID</guilabel></para> 174 </listitem> 175 </itemizedlist> 176 </sect2> 177 178 <sect2 id="reporter.manage.delete"> 179 <title>Deleting Reporters</title> 180 <para>In BASE2, Reporters are treated differently from other items (e.g BioSources or Protocols).</para> 181 <para>Deleting Reporters from BASE2 does not mark those items for deletion as for other BASE2 182 items and do not rely on the Trashcan mechanism.</para> 183 <important> 184 <para> This specific handling of Reporters means that deletion events are unrecoverable. 185 Therefore, pressing the <guibutton>Delete</guibutton> button will always prompt for a 186 confirmation message as illustrated below. </para> 187 188 <figure id="write_docbook_doc.figures.reporter-delele-msg"> 189 <title>The Final Warning message when attempting to delete Reporters</title> 190 <screenshot> 191 <mediaobject> 192 <imageobject> 193 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-delete-msg.png" format="PNG"/> 194 </imageobject> 195 </mediaobject> 196 </screenshot> 197 </figure> 198 </important> 199 <para> Select one or more reporters and click <guibutton>Delete</guibutton> button in the menu 200 bar. </para> 201 </sect2> 202 <sect2 id="reporter.import"> 203 <title>Importing Reporters from files</title> 204 <para> Reporters are used to represent genes, transcripts, exons and therefore come in their 205 thousands. To solve this problem, BASE2 relies on <guilabel>Reporter import plugins</guilabel>. 206 Those need to be specifically configured to deal with a particular input file. This input file 207 can be typically be an Axon gal file which is a tab delimited file providing information about 208 Reporters and their annotations. </para> 209 210 <tip> 211 <para>As for any other plugin, configuration parameters can be saved as an xml file and 212 exchanged with another BASE2 instance, thereby reducing configuration burden (provided the 2 213 instances have identical extended properties xml files). </para> 214 </tip> 215 216 <para> Dealing with Affymetrix Probesets: </para> 217 <para> In BASE2, Affymetrix Probesets (when they exist) should be treated as Reporters.</para> 218 <para> The Affymetrix Probeset ID could be stored in both the name and the reporter external id 219 fields of the reporter table.</para> 220 <tip> 221 <para> Note that Affymetrix serves files containing Annotation about the Probesets ids from the 222 NetAffx web site. A plugin configuration can be defined to upload these files directly into the 223 Reporter table provided it has been modified to accomodate the relevant information. In order 224 to be able to deal with the Affymetrix NetAffx native files (<ulink 225 url="http://www.affymetrix.com/Auth/analysis/downloads/na22/ivt/HG-U133A_2.na22.annot.csv.zip/" 226 >Affymetrix HG-133A_2 annotations in csv format</ulink>) one would have to select the 227 separator as <guilabel>comma between "</guilabel> in order to avoid splitting on 'comma' 228 present in the Affymetrix annotation file, an event that would alter the import. </para> 229 </tip> 230 231 <tip> 232 <para>Storing the Affymetrix Probeset ID should be enough as most analysis tools allow retrieval 233 of updated information based on the Affymetrix probeset id from web resources. </para> 234 </tip> 235 236 </sect2> 237 238 <sect2 id="reporterlist.create"> 239 <title>Creating List of Reporters</title> 240 <para> BASE2 allows for defining sets of reporters for a particular use, for instance to define a 241 list of reporters to be used on an array. There are 2 ways to do so: </para> 242 <orderedlist> 243 <listitem> 244 <para>From the Reporter ListView page:</para> 245 <para>Click on the <guibutton>New Reporter List</guibutton> button.</para> 246 <para/> 247 <figure id="write_docbook_doc.figures.reporterlist-1"> 248 <title>The ReporterList Create Window called from the Reporter page</title> 249 <screenshot> 250 <mediaobject> 251 <imageobject> 252 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporterlist-1.png" format="PNG"/> 253 </imageobject> 254 </mediaobject> 255 </screenshot> 256 </figure> 257 </listitem> 258 <listitem> 259 <para>From View Menu:</para> 260 <para>Go to <menuchoice> 261 <guimenu>View</guimenu> 262 <guimenuitem>Reporter List</guimenuitem> 263 </menuchoice> 264 </para> 265 <para> Click on <guibutton>New…</guibutton> button from the ReporterList ListView </para> 266 <para> A 'Create' pop-up window opens allowing to fill-in Name and a short text description of 267 the newly created Reporter list </para> 268 <figure id="write_docbook_doc.figures.reporterlist-2"> 269 <title>The ReporterList Create Window called from the ReporterList page</title> 270 <screenshot> 271 <mediaobject> 272 <imageobject> 273 <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporterlist-2.png" format="PNG"/> 274 </imageobject> 275 </mediaobject> 276 </screenshot> 277 </figure> 278 </listitem> 279 </orderedlist> 280 <para>Click on the <inlinemediaobject> 281 <imageobject> 282 <imagedata fileref="figures/save.gif" format="GIF"/> 283 </imageobject> 284 </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject> 285 <imageobject> 286 <imagedata fileref="figures/cancel.gif" format="GIF"/> 287 </imageobject> 288 </inlinemediaobject> button to abort. </para> 289 </sect2> 290 </sect1> 36 291 </chapter> -
trunk/doc/src/docbook/userdoc/software.xml
r3246 r3372 30 30 <?dbhtml dir="software"?> 31 31 <title>Software</title> 32 <sect1> 33 <title></title> 34 <para></para> 35 </sect1> 32 <sect1 id="software.manage"> 33 <title>Managing Software</title> 34 35 <sect2 id="software.manage.typecreate"> 36 <title>Software Types</title> 37 <para><guilabel>There is only Software Type</guilabel> in BASE2 and it is not possible to create new types. This is a difference compared to the way Hardware can be managed.</para> 38 <para> By default, BASE2 creates the 1 Software Type: Feature Extraction</para> 39 </sect2> 40 <sect2 id="software.manage.create"> 41 <title>Creating Softwares</title> 42 <para>In BASE2, Softwares can be created by 2 routes:</para> 43 <orderedlist> 44 <listitem> 45 <para>Creating Softwares from the Software Type List View page</para> 46 <para>Clicking on the <inlinemediaobject> 47 <imageobject> 48 <imagedata fileref="figures/add.gif" format="GIF"/> 49 </imageobject> 50 </inlinemediaobject> add software button. 51 </para> 52 <figure id="write_docbook_doc.figures.software-frompt"> 53 <title>Create New software from the Software Type List View</title> 54 <screenshot> 55 <mediaobject> 56 <imageobject> 57 <imagedata contentwidth="10cm" width="10cm" fileref="figures/software-frompt.png" format="PNG"/> 58 </imageobject> 59 </mediaobject> 60 </screenshot> 61 </figure> 62 </listitem> 63 <listitem> 64 <para>Creating Software from the Software List View page</para> 65 <para>Go to 66 <menuchoice> 67 <guimenu>View</guimenu> 68 <guimenuitem>Software</guimenuitem> 69 </menuchoice></para> 70 <para>Click on <guibutton>New…</guibutton> button 71 </para> 72 </listitem> 73 </orderedlist> 74 75 <para>In both cases, a Software Create pop-up window opens. The window contains 2 mandatory fields:</para> 76 <itemizedlist> 77 <listitem> 78 <para> 79 <guilabel>Name</guilabel> and <guilabel>Software type</guilabel>.</para> 80 <para>The later is a select-list population from Software Types owned by or shared to the user.</para> 81 </listitem> 82 <listitem> 83 <para><guilabel>Version</guilabel> and <guilabel>Description</guilabel>, the other 2 fields, are optional and self explanatory.</para> 84 </listitem> 85 </itemizedlist> 86 <para>Click on the 87 <inlinemediaobject> 88 <imageobject> 89 <imagedata fileref="figures/save.gif" format="GIF"/> 90 </imageobject> 91 </inlinemediaobject> 92 Save button to store the information in BASE2 or on the 93 <inlinemediaobject> 94 <imageobject> 95 <imagedata fileref="figures/cancel.gif" format="GIF"/> 96 </imageobject> 97 </inlinemediaobject> 98 button to abort. 99 </para> 100 101 </sect2> 102 <sect2 id="software.manage.detail_view"> 103 <title>Viewing/Editing Softwares</title> 104 <itemizedlist> 105 <listitem> 106 <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or 107 <keycap>SHIFT</keycap> keys while clicking on the name of an Software Item, which is a live 108 link. </para> 109 </listitem> 110 <listitem> 111 <para> Alternately, navigating to the Software Item View, one can hit the 112 <guibutton>Edit…</guibutton> to performed the task.</para> 113 <para>In both cases, an Edit pop-up windows opens. It is essentially identical to a Create 114 window and allows updating information about a particular Software item stored in BASE2</para> 115 <figure id="write_docbook_doc.figures.software-itemview"> 116 <title>Software Item View</title> 117 <screenshot> 118 <mediaobject> 119 <imageobject> 120 <imagedata contentwidth="10cm" width="10cm" fileref="figures/software-itemview.png" format="PNG"/> 121 </imageobject> 122 </mediaobject> 123 </screenshot> 124 </figure> 125 </listitem> 126 </itemizedlist> 127 </sect2> 128 <sect2 id="software.manage.delete"> 129 <title>Deleting/Restoring Softwares</title> 130 <para>As for other items in BASE2, Softwares can be removed and restored. To do so, do the 131 following</para> 132 <itemizedlist> 133 <listitem> 134 <para>Select one or more Softwares and click <guibutton>Delete</guibutton> button in the menu 135 bar. </para> 136 <para>All the selected Softwares have been marked as deleted and are no longer available from 137 the interface. </para> 138 <para>Only by selecting from the <guilabel>view/preset…</guilabel> select box the 139 <guilabel>Removed</guilabel> option, one can see those of the protocols earmarked for 140 deletion. They will be shown with a symbol 141 <inlinemediaobject> 142 <imageobject> 143 <imagedata fileref="figures/deleted.gif" format="GIF"/> 144 </imageobject> 145 </inlinemediaobject> in front of them. </para> 146 </listitem> 147 <listitem> 148 <para>Alternately, navigating to the Software Item View, one can hit the 149 <guibutton>Delete</guibutton> to performed the task. </para> 150 </listitem> 151 <listitem> 152 <para>Deletion errors at this stage can be easily recovered. Select the item to recover from 153 the List View (be sure to check the <guilabel>Removed</guilabel> option in the 154 <guilabel>view/preset…</guilabel> filter) and hit the 155 <guibutton>Restore</guibutton> button to performed the task. </para> 156 </listitem> 157 </itemizedlist> 158 <important> 159 <para>To really delete an item from the database you must use the trashcan. Items 160 deleted from the Trashcan can not be recovered. To learn more about the trashcan function, please refer to <xref linkend="trashcan"/> </para> 161 </important> 162 </sect2> 163 </sect1> 36 164 </chapter>
Note: See TracChangeset
for help on using the changeset viewer.