Changeset 3372


Ignore:
Timestamp:
May 24, 2007, 10:45:06 AM (16 years ago)
Author:
philippe
Message:
 
Location:
trunk/doc/src/docbook/userdoc
Files:
1 added
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/userdoc/annotations.xml

    r3246 r3372  
    22<!DOCTYPE chapter PUBLIC
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    4     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    5 <!--
    6   $Id$
    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 -->
     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    -->
    2828
    2929<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&hellip;</guibutton> and select one of the 8 different
     60                types which can be split in 4 main groups</para>
     61            <itemizedlist spacing="compact">
     62                <listitem>
     63                    <para><guilabel>Integer</guilabel>, <guilabel>Long</guilabel>,
     64                        <guilabel>Float</guilabel> and <guilabel>Double</guilabel> for Numerical
     65                        Annotation Types.</para>
     66                </listitem>
     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&hellip;</guibutton></para>
     274            <para>a pop-up window opens.</para>
     275            <para>It contains 2 tabs, one for declaring name and description of the newly created
     276                category, the second tab is to provide the list of annotation type to be grouped
     277                together under this container.</para>
     278            <example id="annotation_types.example.atcategory">
     279                <title>A category 'Hematology Descriptors' could be created to group together
     280                    Annotation Types such as 'Lymphocyte count' and 'Hematocrite' </title>
     281            </example>
     282            <example id="annotation_types.example.atcategory-2">
     283                <title>A category 'Plasma Clinical Descriptors' could be created to group together
     284                    Annotation Types such as 'ALT activity (UI/mL)' and 'LDH activity (UI/mL').
     285                </title>
     286            </example>
     287        </sect2>
     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
    36508</chapter>

  • trunk/doc/src/docbook/userdoc/biomaterials.xml

    r3246 r3372  
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    44    "../../../../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&hellip;</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&hellip;</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&hellip;</guibutton> button </para>
     328     <para> A 'Create' pop-up window opens, it contains 4 tabs: <guilabel>Sample</guilabel>,
     329       <guilabel>Parents</guilabel>, <guilabel> Annotations &amp; 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 &amp; 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 &amp; 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&hellip;</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&hellip;</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&hellip;</guibutton> button </para>
     600     <para> A 'Create' pop-up window opens, it contains 4 tabs: <guilabel>Extract</guilabel>,
     601       <guilabel>Parents</guilabel>, <guilabel> Annotations &amp; 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 &amp; 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 &amp; 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&hellip;</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&hellip;</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&hellip;</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&hellip;</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&hellip;</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 &amp;
     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 &amp; 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 &amp; 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&hellip;</guibutton> button, the usage of which is detailed now.</para>
     1047     <para>The <guibutton>Pool&hellip;</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&hellip;</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&hellip;</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 &amp; 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 &amp; 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 &amp; 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&hellip;</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>
    361435</chapter>

  • trunk/doc/src/docbook/userdoc/hardware.xml

    r3246 r3372  
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    44    "../../../../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>
    737
    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&hellip;</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&hellip;</guibutton> button
     119      </para>
     120    </listitem>
     121   </orderedlist>
    9122
    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>
    12148
    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&hellip;</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&hellip;</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&hellip;</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>
    36212</chapter>

  • trunk/doc/src/docbook/userdoc/index.xml

    r3246 r3372  
    2929  <?dbhtml dir="userdoc"?>
    3030  <title>User documentation</title>
    31   <include file= "about.xml"/>
     31  <include file="about.xml"/>
    3232  <include file="webclient.xml"/>
    3333  <include file="project_permission.xml"/>
    … …  
    4444  <include file="experiments_analysis.xml"/>
    4545  <include file="import_export_data.xml"/>
     46  <include file="faqs.xml"/>
    4647</part>

  • trunk/doc/src/docbook/userdoc/protocols.xml

    r3246 r3372  
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    44    "../../../../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&hellip;</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&hellip;</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&hellip;</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&hellip;</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&hellip;</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&hellip;</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>
    36220</chapter>

  • trunk/doc/src/docbook/userdoc/reporters.xml

    r3246 r3372  
    33    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    44    "../../../../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    -->               
    2928<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&hellip;</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&hellip;</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&hellip;</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&hellip;</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>
    36291</chapter>

  • trunk/doc/src/docbook/userdoc/software.xml

    r3246 r3372  
    3030  <?dbhtml dir="software"?>
    3131  <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&hellip;</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&hellip;</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&hellip;</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&hellip;</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>
    36164</chapter>
Note: See TracChangeset for help on using the changeset viewer.