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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    <!--
     $Id: protocols.xml 3372 2007-05-24 08:45:06Z philippe $
     
     Copyright (C) Authors contributing to this file.
     
     This file is part of BASE - BioArray Software Environment.
     Available at http://base.thep.lu.se/
     
     BASE is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.
     
     BASE is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA  02111-1307, USA.
    -->                   
<chapter id="protocol">
 <title>Protocols</title>
 <sect1 id="protocol.introduction">
  <title>Introduction</title>
  <para>Information about laboratory standard operating procedure and protocols can be tracked in
   BASE2 using two structures, the use of which is detailed in the following sections. </para>
 </sect1>
 <sect1 id="protocol.manage">
  <title>Managing Protocols</title>
  <para> </para>

  <helptext external_id="protocol.view.properties" title="Protocol Types">

   <sect2 id="protocoltype.create">
    <title>Creating Protocol Types</title>
    <para><guilabel>Protocol Type</guilabel> allows classification of protocols based on their usage
     and purpose in the laboratory workflow. By default, BASE2 creates the 8 main Protocol Types and
     those correspond to the main protocol families identified by MIAME requirements and applied in
     a canonical DNA microarray experiment meant for surveying gene expression. These 8 protocol
     types are namely <guilabel>Printing</guilabel>,
      <guilabel>Sampling</guilabel>,<guilabel>Pooling</guilabel>,<guilabel>Extraction</guilabel>,
      <guilabel>Labeling</guilabel>, <guilabel>Hybridization</guilabel>,
     <guilabel>Scanning</guilabel>, <guilabel>Feature extraction</guilabel>
    </para>
    <para>New applications of DNA microarray technology, for instance DNA binding site
     identification, imposes the creation of new Protocol Type in addition to those built-in in
     BASE2.</para>
    <para>In order to do so</para>
    <para>Go To <menuchoice>
      <guimenu>Administrate</guimenu>
      <guimenuitem>Types</guimenuitem>
      <guisubmenu>Protocol Type</guisubmenu>
     </menuchoice>
    </para>
    <para> Click on <guibutton>New&hellip;</guibutton>. </para>
    <para>A 'Create' pop-up window opens and allow to fill in name and description</para>
    <tip>
     <para>It is advised to define the Protocol Type <guilabel>Name</guilabel> attribute so that it
      is compatible with the MIAME requirements and recommendations issues by microarray data
      repositories.</para>
    </tip>
    <itemizedlist>
     <listitem>
      <figure id="write_docbook_doc.figures.protocoltype">
       <title>The Protocol Type Create Window</title>
       <screenshot>
    <mediaobject>
     <imageobject>
      <imagedata fileref="figures/protocoltype.png" format="PNG"/>
     </imageobject>
    </mediaobject>
   </screenshot>
      </figure>
     </listitem>
    </itemizedlist>
   </sect2>

  </helptext>

  <sect2 id="protocol.create">
   <title>Creating Protocols</title>
   <para>In BASE2, Protocols can be created by 2 routes. Either from the Protocol Type page or from
    the Protocol Page. </para>
   <orderedlist>
    <listitem>
     <para>Creating Protocols from the Protocol Type View</para>
     <para> Clicking on the <guibutton>(+) add protocol</guibutton> button. </para>
     <figure id="write_docbook_doc.figures.protocol-frompt">
      <title>Create New Protocol from the Protocol Type list view</title>
      <screenshot>
       <mediaobject>
        <imageobject>
         <imagedata fileref="figures/protocol-frompt.png" format="PNG"/>
        </imageobject>
       </mediaobject>
      </screenshot>
     </figure>
    </listitem>
    <listitem>
     <para>Creating Protocols from the Protocol View</para>
     <para>Go to <menuchoice>
       <guimenu>View</guimenu>
       <guimenuitem>Protocol</guimenuitem>
      </menuchoice> Click on <guibutton>New&hellip;</guibutton> button </para>
     <para> Either way causes a 'Create' pop-up window to open, it contains 2 tabs:
       <guilabel>Protocol</guilabel> and <guilabel>Parameters</guilabel>. </para>
     <itemizedlist>
      <listitem>
       <para>
        <guilabel>Protocol</guilabel>
       </para>
       <para> This tab allows users to enter essential information about a protocol. Mandatory tags
        are Protocol <guilabel>Name</guilabel> and <guilabel>Protocol Type</guilabel>, the later
        being in the form of a drop-down list populated by Protocol Types shared to the users. This
        list therefore varies and may evolve depending on additions and permissions. The tab has
        also a dedicated field <guilabel>File</guilabel> to enable linking of external files, e.g.
        pdf documents from kit providers to the protocol.</para>
       <figure id="write_docbook_doc.figures.protocol-1">
        <title>The Protocol tab in the Protocol Create Window</title>
        <screenshot>
      <mediaobject>
       <imageobject>
        <imagedata fileref="figures/protocol-1.png" format="PNG"/>
       </imageobject>
      </mediaobject>
     </screenshot>
       </figure>
      </listitem>
      <listitem>
       <para>
        <guilabel>Parameters</guilabel>
       </para>
       <para> This tab allows BASE2 users to declare parameters attached to a particular protocol.
        Parameters are selected from a list of Annotation Types which have been flagged as
        parameters. Only those Annotation Types are available for selection using the <guibutton>Add
         annotation types&hellip;</guibutton>
       </para>
       <figure id="write_docbook_doc.figures.protocol-2">
        <title>The Paramater tab from the Protocol Create Window</title>
        <screenshot>
      <mediaobject>
       <imageobject>
        <imagedata fileref="figures/protocol-2.png" format="PNG"/>
       </imageobject>
      </mediaobject>
     </screenshot>
       </figure>
      </listitem>
     </itemizedlist>
    </listitem>
   </orderedlist>
  </sect2>
  <sect2 id="protocol.detail_view">
   <title>Viewing/Editing Protocols</title>
   <itemizedlist>
    <listitem>
     <para>From the Protocol List View, clicking on the Protocol <guilabel>Name</guilabel> opens a
      detail view for that protocol, showing a summary of all information available in BASE2 about
      that entity</para>
    </listitem>
    <listitem>
     <para>Alternately, from the Protocol Item View, clicking the
      <guibutton>Edit&hellip;</guibutton> performs the same task. </para>
     <figure id="write_docbook_doc.figures.protocol-itemview">
      <title>Protocol Item View</title>
      <screenshot>
      <mediaobject>
       <imageobject>
        <imagedata fileref="figures/protocol-itemview.png" format="PNG"/>
       </imageobject>
      </mediaobject>
     </screenshot>
     </figure>
    </listitem>
    <listitem>
     <para> Note from the Protocol Item view how protocol <guilabel>Paramaters</guilabel> are
      listed. Clicking on the <guilabel>Parameter name</guilabel> will open the corresponding
      Annotation Type element in an item view </para>
    </listitem>
   </itemizedlist>

  </sect2>
  <sect2 id="protocol.delete">
   <title>Deleting/Restoring Protocols</title>
   <para>As for other items in BASE2, some can be removed and restored. To do so, do the following</para>
   <itemizedlist>
    <listitem>
     <para>Select one or more protocols and click the <guibutton>Delete</guibutton> button in the
      menu bar. </para>
     <para>All the selected protocols have been marked as deleted and are no longer available from
      the interface. </para>
     <para>Only by selecting from the <guilabel>view/preset&hellip;</guilabel> select box the
       <guilabel>Removed</guilabel> option, one can see those of the protocols earmarked for
      deletion. They will be shown with a symbol in front of them. </para>
    </listitem>
    <listitem>
     <para>Alternately, navigating to the Protocol Item View, one can hit the
      <guibutton>Delete</guibutton> to performed the task. </para>
    </listitem>
    <listitem>
     <para>Deletion errors at this stage can be easily recovered. Select the item to recover from
      the List View (be sure to check the <guilabel>Removed</guilabel> option in the
       <guilabel>view/preset&hellip;</guilabel> filter) and hit the
      <guibutton>Restore</guibutton> button to performed the task. </para>
    </listitem>
   </itemizedlist>
   <important>
    <para>To really delete an item from the database you must use the <link linkend="trashcan"
      >trashcan</link>. Items deleted from the Trashcan can not be recovered. </para>
   </important>
  </sect2>
 </sect1>
</chapter>