Changeset 3387


Ignore:
Timestamp:
May 28, 2007, 8:53:04 AM (14 years ago)
Author:
Nicklas Nordborg
Message:

Fixes #540. Major reorganisation. Added screen shots.

Location:
trunk/doc/src/docbook
Files:
3 added
1 edited

Legend:

Unmodified
Added
Removed

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

    r3382 r3387  
    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 <chapter id="protocol">
    29 <?dbhtml dir="protocols"?>
    30  <title>Protocols</title>
    31  <sect1 id="protocol.introduction">
    32   <title>Introduction</title>
    33   <para>Information about laboratory standard operating procedure and protocols can be tracked in
    34    BASE2 using two structures, the use of which is detailed in the following sections. </para>
    35  </sect1>
    36  <sect1 id="protocol.manage">
    37   <title>Managing Protocols</title>
    38   <para> </para>
    39 
    40  
    41 
    42    <sect2 id="protocoltype.create">
    43     <title>Creating Protocol Types</title>
    44     <helptext external_id="protocol.view.properties" title="Protocol Types">
    45     <para><guilabel>Protocol Type</guilabel> allows classification of protocols based on their usage
    46      and purpose in the laboratory workflow. By default, BASE2 creates the 8 main Protocol Types and
    47      those correspond to the main protocol families identified by MIAME requirements and applied in
    48      a canonical DNA microarray experiment meant for surveying gene expression. These 8 protocol
    49      types are namely <guilabel>Printing</guilabel>,
    50       <guilabel>Sampling</guilabel>,<guilabel>Pooling</guilabel>,<guilabel>Extraction</guilabel>,
    51       <guilabel>Labeling</guilabel>, <guilabel>Hybridization</guilabel>,
    52      <guilabel>Scanning</guilabel>, <guilabel>Feature extraction</guilabel>
    53     </para>
    54     <para>New applications of DNA microarray technology, for instance DNA binding site
    55      identification, imposes the creation of new Protocol Type in addition to those built-in in
    56      BASE2.</para>
    57     <para>In order to do so</para>
    58     <para>Go To <menuchoice>
    59       <guimenu>Administrate</guimenu>
    60       <guimenuitem>Types</guimenuitem>
    61       <guisubmenu>Protocol Type</guisubmenu>
    62      </menuchoice>
    63     </para>
    64     <para> Click on <guibutton>New&hellip;</guibutton>. </para>
    65     <para>A 'Create' pop-up window opens and allow to fill in name and description</para>
    66     <tip>
    67      <para>It is advised to define the Protocol Type <guilabel>Name</guilabel> attribute so that it
    68       is compatible with the MIAME requirements and recommendations issues by microarray data
    69       repositories.</para>
    70     </tip>
    71     <itemizedlist>
    72      <listitem>
    73       <figure id="write_docbook_doc.figures.protocoltype">
    74        <title>The Protocol Type Create Window</title>
    75        <screenshot>
    76     <mediaobject>
    77      <imageobject>
    78       <imagedata fileref="figures/protocoltype.png" format="PNG"/>
    79      </imageobject>
    80     </mediaobject>
    81    </screenshot>
    82       </figure>
    83      </listitem>
    84     </itemizedlist>
    85     </helptext>
    86    </sect2>
    87 
    88  
    89 
    90   <sect2 id="protocol.create">
    91    <title>Creating Protocols</title>
    92    <para>In BASE2, Protocols can be created by 2 routes. Either from the Protocol Type page or from
    93     the Protocol Page. </para>
    94    <orderedlist>
    95     <listitem>
    96      <para>Creating Protocols from the Protocol Type View</para>
    97      <para> Clicking on the <guibutton>(+) add protocol</guibutton> button. </para>
    98      <figure id="write_docbook_doc.figures.protocol-frompt">
    99       <title>Create New Protocol from the Protocol Type list view</title>
    100       <screenshot>
    101        <mediaobject>
    102         <imageobject>
    103          <imagedata fileref="figures/protocol-frompt.png" format="PNG"/>
    104         </imageobject>
    105        </mediaobject>
    106       </screenshot>
    107      </figure>
    108     </listitem>
    109     <listitem>
    110      <para>Creating Protocols from the Protocol View</para>
    111      <para>Go to <menuchoice>
    112        <guimenu>View</guimenu>
    113        <guimenuitem>Protocol</guimenuitem>
    114       </menuchoice> Click on <guibutton>New&hellip;</guibutton> button </para>
    115      <para> Either way causes a 'Create' pop-up window to open, it contains 2 tabs:
    116        <guilabel>Protocol</guilabel> and <guilabel>Parameters</guilabel>. </para>
    117      <itemizedlist>
    118       <listitem>
    119        <para>
    120         <guilabel>Protocol</guilabel>
    121        </para>
    122        <para> This tab allows users to enter essential information about a protocol. Mandatory tags
    123         are Protocol <guilabel>Name</guilabel> and <guilabel>Protocol Type</guilabel>, the later
    124         being in the form of a drop-down list populated by Protocol Types shared to the users. This
    125         list therefore varies and may evolve depending on additions and permissions. The tab has
    126         also a dedicated field <guilabel>File</guilabel> to enable linking of external files, e.g.
    127         pdf documents from kit providers to the protocol.</para>
    128        <figure id="write_docbook_doc.figures.protocol-1">
    129         <title>The Protocol tab in the Protocol Create Window</title>
    130         <screenshot>
    131       <mediaobject>
    132        <imageobject>
    133         <imagedata fileref="figures/protocol-1.png" format="PNG"/>
    134        </imageobject>
    135       </mediaobject>
    136      </screenshot>
    137        </figure>
    138       </listitem>
    139       <listitem>
    140        <para>
    141         <guilabel>Parameters</guilabel>
    142        </para>
    143        <para> This tab allows BASE2 users to declare parameters attached to a particular protocol.
    144         Parameters are selected from a list of Annotation Types which have been flagged as
    145         parameters. Only those Annotation Types are available for selection using the <guibutton>Add
    146          annotation types&hellip;</guibutton>
    147        </para>
    148        <figure id="write_docbook_doc.figures.protocol-2">
    149         <title>The Paramater tab from the Protocol Create Window</title>
    150         <screenshot>
    151       <mediaobject>
    152        <imageobject>
    153         <imagedata fileref="figures/protocol-2.png" format="PNG"/>
    154        </imageobject>
    155       </mediaobject>
    156      </screenshot>
    157        </figure>
    158       </listitem>
    159      </itemizedlist>
    160     </listitem>
    161    </orderedlist>
    162   </sect2>
    163   <sect2 id="protocol.detail_view">
    164    <title>Viewing/Editing Protocols</title>
    165    <itemizedlist>
    166     <listitem>
    167      <para>From the Protocol List View, clicking on the Protocol <guilabel>Name</guilabel> opens a
    168       detail view for that protocol, showing a summary of all information available in BASE2 about
    169       that entity</para>
    170     </listitem>
    171     <listitem>
    172      <para>Alternately, from the Protocol Item View, clicking the
    173       <guibutton>Edit&hellip;</guibutton> performs the same task. </para>
    174      <figure id="write_docbook_doc.figures.protocol-itemview">
    175       <title>Protocol Item View</title>
    176       <screenshot>
    177       <mediaobject>
    178        <imageobject>
    179         <imagedata fileref="figures/protocol-itemview.png" format="PNG"/>
    180        </imageobject>
    181       </mediaobject>
    182      </screenshot>
    183      </figure>
    184     </listitem>
    185     <listitem>
    186      <para> Note from the Protocol Item view how protocol <guilabel>Paramaters</guilabel> are
    187       listed. Clicking on the <guilabel>Parameter name</guilabel> will open the corresponding
    188       Annotation Type element in an item view </para>
    189     </listitem>
    190    </itemizedlist>
    191 
    192   </sect2>
    193   <sect2 id="protocol.delete">
    194    <title>Deleting/Restoring Protocols</title>
    195    <para>As for other items in BASE2, some can be removed and restored. To do so, do the following</para>
    196    <itemizedlist>
    197     <listitem>
    198      <para>Select one or more protocols and click the <guibutton>Delete</guibutton> button in the
    199       menu bar. </para>
    200      <para>All the selected protocols have been marked as deleted and are no longer available from
    201       the interface. </para>
    202      <para>Only by selecting from the <guilabel>view/preset&hellip;</guilabel> select box the
    203        <guilabel>Removed</guilabel> option, one can see those of the protocols earmarked for
    204       deletion. They will be shown with a symbol in front of them. </para>
    205     </listitem>
    206     <listitem>
    207      <para>Alternately, navigating to the Protocol Item View, one can hit the
    208       <guibutton>Delete</guibutton> to performed the task. </para>
    209     </listitem>
    210     <listitem>
    211      <para>Deletion errors at this stage can be easily recovered. Select the item to recover from
    212       the List View (be sure to check the <guilabel>Removed</guilabel> option in the
    213        <guilabel>view/preset&hellip;</guilabel> filter) and hit the
    214       <guibutton>Restore</guibutton> button to performed the task. </para>
    215     </listitem>
    216    </itemizedlist>
    217    <important>
    218     <para>To really delete an item from the database you must use the <link linkend="trashcan"
    219       >trashcan</link>. Items deleted from the Trashcan can not be recovered. </para>
    220    </important>
    221   </sect2>
    222  </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="protocols_protocoltypes">
     29  <?dbhtml dir="protocols"?>
     30  <title>Protocols and protocol types</title>
     31  <para>
     32    Information about laboratory standard operating procedure
     33    and protocols can be tracked in BASE2 using two structures,
     34    the use of which is detailed in the following sections.
     35  </para>
     36  <sect1 id="protocoltypes">
     37    <title>Protocol types</title>
     38
     39    <helptext external_id="protocoltype.view.properties"
     40      title="Protocol Types">
     41      <para>
     42        <guilabel>Protocol Type</guilabel>
     43        allows classification of protocols based on their
     44        usage and purpose in the laboratory workflow. By
     45        default, BASE2 creates the 8 main pProtocol types and
     46        those correspond to the main protocol families
     47        identified by MIAME requirements and applied in a
     48        canonical DNA microarray experiment meant for
     49        surveying gene expression. These 8 protocol types
     50        are namely
     51        <guilabel>Printing</guilabel>,
     52        <guilabel>Sampling</guilabel>,
     53        <guilabel>Pooling</guilabel>,
     54        <guilabel>Extraction</guilabel>,
     55        <guilabel>Labeling</guilabel>,
     56        <guilabel>Hybridization</guilabel>,
     57        <guilabel>Scanning</guilabel> and
     58        <guilabel>Feature extraction</guilabel>.
     59      </para>
     60      <para>
     61        New applications of DNA microarray technology, for
     62        instance DNA binding site identification, imposes
     63        the creation of new protocol type in addition to
     64        those built-in in BASE2.
     65      </para>
     66      <tip>
     67        <title>Follow MIAME recommendations</title>
     68        <para>
     69          It is advised to define the protocol type
     70          <guilabel>Name</guilabel>
     71          so that it is compatible with the
     72          MIAME requirements and recommendations issues by
     73          microarray data repositories.
     74        </para>
     75      </tip>
     76    </helptext>
     77   
     78    <para>
     79      You can manage the protocol types by going to
     80      <menuchoice>
     81        <guimenu>Administrate</guimenu>
     82        <guimenuitem>Types</guimenuitem>
     83        <guisubmenu>Protocol Type</guisubmenu>
     84      </menuchoice>.
     85    </para>
     86    <figure
     87      id="protocols.figures.protocoltype">
     88      <title>Protocol type properties</title>
     89      <screenshot>
     90        <mediaobject>
     91          <imageobject>
     92            <imagedata
     93              fileref="figures/edit_protocoltype.png" format="PNG" />
     94          </imageobject>
     95        </mediaobject>
     96      </screenshot>
     97    </figure>
     98   
     99    <helptext external_id="protocoltype.edit"
     100      title="Edit protocol type">
     101   
     102      <variablelist>
     103      <varlistentry>
     104        <term><guilabel>Name</guilabel></term>
     105        <listitem>
     106          <para>
     107            The name of the protocol type.
     108          </para>
     109        </listitem>
     110      </varlistentry>
     111      <varlistentry>
     112        <term><guilabel>Description</guilabel></term>
     113        <listitem>
     114          <para>
     115            A description of the protocol type.
     116          </para>
     117        </listitem>
     118      </varlistentry>
     119      </variablelist>
     120    </helptext>
     121  </sect1>
     122
     123  <sect1 id="protocols">
     124    <title>Protocols</title>
     125    <para>
     126      In BASE, protocols can be created by 2 routes. Either
     127      from the single-item view of a protocol type or from the
     128      list view of protocols.
     129    </para>
     130    <sect2 id="protocols.properties">
     131      <title>Protocol properties</title>
     132     
     133      <figure
     134        id="protocols.figures.edit_protocol">
     135        <title>Protocol properties</title>
     136        <screenshot>
     137          <mediaobject>
     138            <imageobject>
     139              <imagedata
     140                fileref="figures/edit_protocol.png" format="PNG" />
     141            </imageobject>
     142          </mediaobject>
     143        </screenshot>
     144      </figure>
     145     
     146      <helptext external_id="protocol.edit"
     147        title="Edit protocol">
     148       
     149        <para>
     150        This tab allows users to enter essential
     151        information about a protocol.
     152       
     153        <variablelist>
     154        <varlistentry>
     155          <term><guilabel>Name</guilabel></term>
     156          <listitem>
     157            <para>
     158            The name of the protocol.
     159            </para>
     160          </listitem>
     161        </varlistentry>
     162        <varlistentry>
     163          <term><guilabel>Type</guilabel></term>
     164          <listitem>
     165            <para>
     166            The protocol type of the protocol. The list
     167            may evolve depending on additions by the server
     168            administrator.
     169            </para>
     170          </listitem>
     171        </varlistentry>
     172        <varlistentry>
     173          <term><guilabel>File</guilabel></term>
     174          <listitem>
     175            <para>
     176            A document containing the protocol description,     
     177            e.g. pdf documents from kit providers to
     178            the protocol. Use the <guibutton>Select</guibutton>
     179            button to select or upload a file.
     180            </para>
     181          </listitem>
     182        </varlistentry>
     183        <varlistentry>
     184          <term><guilabel>Description</guilabel></term>
     185          <listitem>
     186            <para>
     187            A description of the protocol.
     188            </para>
     189          </listitem>
     190        </varlistentry>
     191        </variablelist>
     192        </para>   
     193       
     194        <seeother>
     195          <other external_id="protocol.edit.parameters">Protocol parameters</other>
     196        </seeother>
     197      </helptext>
     198    </sect2>
     199   
     200    <sect2 id="protocols.parameters">
     201      <title>Protocol parameters</title>
     202
     203      <helptext external_id="protocol.edit.parameters"
     204        title="Protocol parameters">
     205
     206        <para>
     207          BASE users may declare parameters attached to a particular
     208          protocol. Parameters are selected from a list of annotation
     209          types which have been flagged as parameters. Annotation
     210          types which has been selected as parameters show up in the
     211          regular annotation dialog whenever the protocol is used for
     212          an item. <nohelp>For more information see
     213          <xref linkend="annotations" />.</nohelp>
     214        </para>
     215   
     216        <nohelp>
     217        <figure
     218          id="protocols.figures.protocol_parameters">
     219          <title>Protocol parameters</title>
     220          <screenshot>
     221            <mediaobject>
     222              <imageobject>
     223                <imagedata
     224                  fileref="figures/protocol_parameters.png" format="PNG" />
     225              </imageobject>
     226            </mediaobject>
     227          </screenshot>
     228        </figure>
     229        </nohelp>
     230
     231        <variablelist>
     232        <varlistentry>
     233          <term><guilabel>Annotation types</guilabel></term>
     234          <listitem>
     235            <para>
     236            This list contains the annotation types selected
     237            as parameters for the protocol.
     238            </para>
     239          </listitem>
     240        </varlistentry>
     241        <varlistentry>
     242          <term><guibutton>Add annotation types</guibutton></term>
     243          <listitem>
     244            <para>
     245            Use this button to open a popup where you can select
     246            annotation type to use for parameters. The list only
     247            shows annotations types which has the
     248            <guilabel>Protocol parameter</guilabel> flag set.
     249            </para>
     250          </listitem>
     251        </varlistentry>
     252        <varlistentry>
     253          <term><guibutton>Remove</guibutton></term>
     254          <listitem>
     255            <para>
     256            Removes the selected annotation types from the list.
     257            </para>
     258          </listitem>
     259        </varlistentry>
     260        </variablelist>
     261     
     262        <seeother>
     263          <other external_id="protocol.edit">Edit protocol</other>
     264          <other external_id="annotations.edit">Annotations &amp; parameters</other>
     265        </seeother>
     266     
     267      </helptext>
     268    </sect2>
     269
     270  </sect1>
    223271</chapter>
Note: See TracChangeset for help on using the changeset viewer.