source: trunk/doc/src/docbook/userdoc/array_lims.xml @ 3394

<?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: array_lims.xml 3394 2007-05-28 11:23:40Z martin $

  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="array_lims">
  <?dbhtml dir="array_lims"?>
  <title>Array LIMS</title>
  <sect1 id="array_lims.introduction">
    <title>Introduction</title>

    <para>Arrays are at the core of the BASE2 business and are essential elements to describe in
      order to be MIAME compliant. It is also critical to track and manage information about
      microarray design as accurately as possible since mistakes could prove extremely costly
      in downstream analysis.</para>
    <para>Finally, as a good practice, all Array related information should be entered into
      BASE2 system prior to start describing the sample processing and hybridizations events
      making up a microarray experiment.</para>

    <para>BASE2 has been engineered to support microarray printing facilities. The system
      therefore offers objects to describe plates, their geometries and the events (merging,
      printing) affected them. The first section of the chapter deals with this functionality.
      as well as plate management.</para>

    <para>For users buying their arrays from commercial sources, the Plate Management component
      can be ignored and they can go immediately to the second section <xref
        linkend="array_lims.arraydesign"/> of the chapter.</para>

  </sect1>

  <sect1 id="array_lims.platemanagement">
    <title>Managing Plates</title>
    <para>TO DO</para>
  </sect1>

  <sect1 id="array_lims.arraydesign">
    <title>Managing ArrayDesigns</title>
    <para> ArrayDesign should be understood as a plan which can be realized during a printing
      process producing microarray slides. During the course of the printing process, reagents
      may run out leading to the interruption of this process. All slides created during this
      printing process belong to the same printing 'batch'. It is the array slide that will
      eventually be used in a Hybridization event. BASE2 allows user to track those 3 entities
      with great details. This is an important functionality for users producing their own
      arrays and for those caring for quality control and tracking of microarray slides in a
      printing facility. The following sections detail how to use BASE2 to help in these
      tasks. </para>
    <sect2 id="array_lims.arraydesign.create">
      <title>Creating ArrayDesigns</title>
      <para>To create an ArrayDesign, do the following</para>
      <para>Go To <menuchoice>
          <guimenu>Array LIMS</guimenu>
          <guimenuitem>Array designs</guimenuitem>
        </menuchoice>
      </para>
      <para>The ArrayDesign List view now presents all ArrayDesigns available to the user
        (shared to or owned by).</para>
      <para>Click on &gbNew; button</para>
      <para>A 'Create' pop-up window opens. It contains 3 tabs</para>

      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Array design</guilabel>
          </term>
          <listitem>

            <para>The tab contains four fields, namely:</para>

            <variablelist>

              <varlistentry>
                <term>
                  <guilabel>Name</guilabel>
                </term>
                <listitem>
                  <para> Provide a unique sensible name for the design. Possibly
                    follow the convention [organisation-species-feature
                    number-version] as in EMBL-Hsapiens-wholegenome-45k-v1. For
                    commercial platforms such as Agilent and Affymetrix, it is
                    probably better to use the commercial names, such as Agilent
                    Whole Mouse Genome G4122A or HG_U133A respectively</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>
                  <guilabel>Description</guilabel>
                </term>
                <listitem>
                  <para>Provide a short but meaningful of the ArrayDesign</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>
                  <guilabel>Affy Chip</guilabel>
                </term>
                <listitem>
                  <para>This is a radio button for providing a boolean entry,
                    essentially telling the system whether the ArrayDesign being
                    created is of Affymetrix technology or not.</para>
                  <warning>
                    <para>As indicated on the interface, once saved, this
                      information cannot be modified, so if a mistake is made,
                      the entry will have to be deleted.</para>
                  </warning>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>
                  <guilabel>CDF file</guilabel>
                </term>
                <listitem>
                  <para>This field allows to upload an Affymetrix CDF file. A CDF
                    file is a binary file describing Affymetrix chip layout.
                    This file is necessary for performing analysis using BASE2
                    plugins (e.g RMAExpress plugin).</para>
                  <note>
                    <para>Affymetrix users, you can also upload CLF or BPMAP
                      files defined for exon and tiling arrays
                    respectively.</para>
                  </note>
                </listitem>
              </varlistentry>

            </variablelist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <guilabel>Annotations</guilabel>
          </term>
          <listitem>
            <para>This tab allows to input values associated to Annotation Types devised
              to refine ArrayDesign description.</para>
            <para>The windows will be empty if no Annotation Types have been declared to
              annotation ArrayDesign item or if none are shared to the user</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <guilabel>Inherited Annotations</guilabel>
          </term>
          <listitem>
            <para>TO DO</para>
          </listitem>
        </varlistentry>

      </variablelist>
      <para>Click on the &gbSave; button to store the information in BASE2 or on the
          &gbCancel; button to abort. </para>
      <para>Upon saving, the Array Design List View page is displayed. Users should pay
        attention to the column <guilabel>Has features</guilabel>. Unless an Affymetrix
        ArrayDesign was created, the value will be by default set to
        <guilabel>no</guilabel>. For all other cases, this value will only be updated
        following <guilabel>Importing the Features</guilabel>, a process which is detailed
        in the next section.</para>

    </sect2>

    <sect2 id="array_lims.arraydesign.importfeature">
      <title>Importing Features associated to an ArrayDesign</title>
      <important>
        <para>For non-Affymetrix ArrayDesigns, Importing Features is an important step in
          order to fully define an ArrayDesign. It should be noted that BASE2 does not
          enforce the immediate Feature import upon creation of ArrayDesign. However, It
          is STRONGLY advised to do so when creating an ArrayDesign. Doing so enables to
          use the Array Design for downstream analysis with no further trouble. It also
          matters when importing rawBioassay data and matching those to the corresponding
          ArrayDesign. It is interesting to note that the processes of importing features
          associated to Array Design and importing Data associated to Raw BioAssay are in
          essence very similar.</para> Please see section <xref
          linkend="experiments_analysis.rawbioassay.rawdata"/> for more information. </important>
      <para>This section applies only to non-affymetrix ArrayDesign since Affymetrix designs
        are handled differently. For Affymetrix platform, features are considered imported
        when the Affymetrix CDF file is actually uploaded.</para>
      <para>From the ArrayDesign Item View, click on the &gbImport;
      button.</para>.<note>
        <para>The button only shows up if the logged in user has enough permissions.</para>
      </note>
      <para>A plugin interface is launched. One can either run the import using the autodetect
        settings or for more control, select a <guilabel>'Reporter Map Importer'</guilabel>
        plugin and then choose a <guilabel>plugin configuration</guilabel> available from
        the drop-down list populated from configurations shared to or owned by the user.</para>
      <para>BASE2 ships with Reporter Map Importer plugin configurations allowing to import
        features from Axon gal files and also gpr files (2 configurations_Block/Column/Row
        and Block/Row/Column for each file formats) and for Agilent FeatureExtraction files
        (to be confirmed). </para>
      <para>For more about the plugin configuration, refer to section <xref
          linkend="plugins.installation"/>.</para>
      <para>If the import run is successful, go to the ArrayDesign List view. The
          <guilabel>Has features</guilabel> column will show <guilabel>Yes (n)</guilabel>
        where n is the number of features actually present on the microarray and now
        associated to the newly created ArrayDesign.</para>
      <tip>
        <para>A list of Reporter Map Importer plugin configurations is maintained at BASE2
          site and each can be downloaded as xml file from 
          <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html"/>.</para>
      </tip>
    </sect2>
    <para>If both actions have been successfully completed, the ArrayDesign is now fully defined
      and ArrayBatches and Array slides items can be created. This process is described in the
      following sections.</para>


    <sect2 id="array_lims.arraydesign.detail_view">
      <title>Viewing/Editing ArrayDesigns</title>
      <itemizedlist>
        <listitem>
          <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or
              <keycap>SHIFT</keycap> keys while clicking on the name of an ArrayDesign
            Item, which is a live link. </para>
        </listitem>
        <listitem>
          <para> Alternately, navigating to the ArrayDesign Item View, one can hit the
              &gbEdit; to performed the task.</para>
          <para>In both cases, an Edit pop-up windows opens. It is essentially identical
            to a Create window and allows updating information about a particular
            ArrayDesign item stored in BASE2.</para>
          <figure id="write_docbook_doc.figures.arraydesign-itemview">
            <title>ArrayDesign Item View</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/arraydesign-itemview.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        </listitem>
        <listitem>
          <para>From the ArrayDesign item View, all associated
            <guilabel>ArrayBatches</guilabel> are indicated as navigable links. Also
            present on the ArrayDesign Item View are the links back to
            <guilabel>Plates</guilabel> possibly used to define the ArrayDesign (none
            used in the screenshot).</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="array_lims.arraydesign.delete">
      <title>Deleting/Restoring ArrayDesigns</title>
      <para>As for other items in BASE2, ArrayDesigns can be removed and restored. To do so,
        do the following:</para>
      <itemizedlist>
        <listitem>
          <para>Select one or more ArrayDesigns and click &gbDelete;
            button in the menu bar. </para>
          <para>All the selected ArrayDesigns 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
            ArrayDesigns earmarked for deletion. They will be shown with a symbol <inlinemediaobject>
              <imageobject>
                <imagedata fileref="figures/deleted.gif" format="GIF"/>
              </imageobject>
            </inlinemediaobject> in front of them. </para>
        </listitem>
        <listitem>
          <para>Alternately, navigating to the ArrayDesign Item View, one can hit the
              &gbDelete; 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
              &gbRestore; button to performed the task. </para>
        </listitem>
      </itemizedlist>
      <important>
        <para>To really delete an item from the database you must use the trashcan. Items
          deleted from the Trashcan can not be recovered. To learn more about the trashcan
          function, please refer to <xref linkend="trashcan"/>
        </para>
      </important>
    </sect2>

  </sect1>
  <sect1 id="array_lims.arraybatch">
    <title>Managing Array Batches</title>

    <sect2 id="array_lims.arraybatch.create">
      <title>Creating Array Batches </title>
      <para>In BASE2, Array Batches can be created by 2 routes:</para>
      <orderedlist>
        <listitem>
          <para>Creating Array Batch from the ArrayDesign List View page</para>
          <para>Clicking on the <inlinemediaobject>
              <imageobject>
                <imagedata fileref="figures/add.gif" format="GIF"/>
              </imageobject>
            </inlinemediaobject> add Array batch button available from the
              <guilabel>Batches</guilabel> column of the ArrayDesign list view page.
          </para>
        </listitem>
        <listitem>
          <para>Creating ArrayBatch from the ArrayBatch List View page</para>
          <para>Go to <menuchoice>
              <guimenu>Array LIMS</guimenu>
              <guimenuitem>Array batches</guimenuitem>
            </menuchoice></para>
          <para>Click on &gbNew; button </para>
        </listitem>
      </orderedlist>

      <para>In both cases, an ArrayBatch Create pop-up window opens. The window contains 2
        mandatory fields:</para>
      <figure id="write_docbook_doc.figures.arraybatch-create">
        <title>Create New Array batch from the ArrayDesign List View</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata contentwidth="10cm" width="10cm" fileref="figures/arraybatch-create.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      <itemizedlist>
        <listitem>
          <para>
            <guilabel>Name</guilabel> and <guilabel>ArrayDesign</guilabel>.</para>
          <para>The later is a select-list population from ArrayDesigns owned by or shared
            to the user.</para>
        </listitem>
        <listitem>
          <para><guilabel>Print robot</guilabel> and <guilabel>Protocol</guilabel>, the
            other 2 fields, are optional and self explanatory.</para>
        </listitem>
      </itemizedlist>
      <para>Click on the &gbSave; button to store the information in BASE2 or on the 
      &gbCancel; button to abort.</para>
    </sect2>

    <sect2 id="array_lims.arraybatch.detail_view">
      <title>Viewing/Editing ArrayBatches</title>
      <itemizedlist>
        <listitem>
          <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or
              <keycap>SHIFT</keycap> keys while clicking on the name of an ArrayBatch
            Item, which is a live link. </para>
        </listitem>
        <listitem>
          <para> Alternately, navigating to the ArrayBatch Item View, one can hit the
              &gbEdit; to performed the task.</para>
          <para>In both cases, an Edit pop-up windows opens. It is essentially identical
            to a Create window and allows updating information about a particular
            ArrayBatch item stored in BASE2</para>
          <figure id="write_docbook_doc.figures.arraybatch-itemview">
            <title>ArrayBatch Item View</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/arraybatch-itemview.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        </listitem>
        <listitem>
          <para>From the ArrayBatch item View, all associated <guilabel/>ArraySlides are
            indicated as their use in Hybridization events. Both ArraySlides and
            Hybridizations are clickable items, enabling easy navigation.</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="array_lims.arraybatch.delete">
      <title>Deleting/Restoring ArrayBatches</title>
      <para>As for other items in BASE2, ArrayBatches can be removed and restored. To do so,
        do the following</para>
      <itemizedlist>
        <listitem>
          <para>Select one or more ArrayBatches and click &gbDelete;
            button in the menu bar. </para>
          <para>All the selected ArrayBatches 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
            ArrayBatches earmarked for deletion. They will be shown with a symbol <inlinemediaobject>
              <imageobject>
                <imagedata fileref="figures/deleted.gif" format="GIF"/>
              </imageobject>
            </inlinemediaobject> in front of them. </para>
        </listitem>
        <listitem>
          <para>Alternately, navigating to the ArrayBatch Item View, one can hit the
              &gbDelete; 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
              &gbRestore; button to performed the task. </para>
        </listitem>
      </itemizedlist>
      <important>
        <para>To really delete an item from the database you must use the trashcan. Items
          deleted from the Trashcan can not be recovered. To learn more about the trashcan
          function, please refer to <xref linkend="trashcan"/>
        </para>
      </important>
    </sect2>
  </sect1>
  <sect1 id="array_lims.arrayslide">
    <title>Managing Array Slides</title>
    <sect2 id="array_lims.arrayslide.create">
      <title>Creating Array Slides </title>
      <para>In BASE2, Array Slides can be created by 2 routes:</para>
      <orderedlist>
        <listitem>
          <para>Creating Array Slides from the ArrayBatch View page</para>
          <para>Clicking on the <inlinemediaobject>
              <imageobject>
                <imagedata fileref="figures/add.gif" format="GIF"/>
              </imageobject>
            </inlinemediaobject> add Array slides button. </para>
          <figure id="write_docbook_doc.figures.arrayslide-single-create">
            <title>Create New Array Slide from the ArrayBatch List View</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/arrayslide-single-create.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        </listitem>
        <listitem>
          <para>Creating ArraySlides from the ArrayBatch List View page</para>
          <para>Go to <menuchoice>
              <guimenu>Array LIMS</guimenu>
              <guimenuitem>Array slides</guimenuitem>
            </menuchoice></para>
          <para>Click on &gbNew; button </para>
        </listitem>
      </orderedlist>

      <para>In both cases, an ArraySlide Create pop-up window opens. The window contains 2
        mandatory fields:</para>
      <itemizedlist>
        <listitem>
          <para>
            <guilabel>Name</guilabel> and <guilabel>ArrayBatch</guilabel>.</para>
          <para>The later is a select-list populated with ArrayBatches owned by or shared
            to the user.</para>
        </listitem>
        <listitem>
          <para><guilabel>Barcode</guilabel>, <guilabel>Index</guilabel> and
              <guilabel>Destroyed</guilabel>, a tick box enabling to record microarray
            slides lost by accident.</para>
        </listitem>
      </itemizedlist>
      <para>Click on the &gbSave; button to store the information in BASE2 or on the 
          &gbCancel; button to abort. </para>

      <para> In addition to this classic way of creating BASE items, Arrays Slides can be
        created with a wizard available from both the ArraySlide Item view or from the
        ArrayBatch List View page. To call the wizard:</para>
      <para>Click on the <inlinemediaobject>
          <imageobject>
            <imagedata fileref="figures/new_wizard.gif" format="GIF"/>
          </imageobject>
        </inlinemediaobject> add multiple Array slides button in the
        <guilabel>Slides</guilabel> column of the ArrayBatch List view page.</para>

      <para> or </para>
      <para>Click on the <inlinemediaobject>
          <imageobject>
            <imagedata fileref="figures/new_wizard.gif" format="GIF"/>
          </imageobject>
        </inlinemediaobject>
        <guibutton>Create multiple&hellip;</guibutton> button from the menu bar of the
        ArraySlides List View page </para>

      <para>Either way will open the wizard window as shown below</para>
      <figure id="write_docbook_doc.figures.arrayslide-multiple-create">
        <title>Create Multiple Array Slide from the ArrayBatch List View wizard</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata contentwidth="10cm" width="10cm" fileref="figures/arrayslide-multiple-create.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>Fill in the necessary information as exhaustively as possible.</para>
      <para>Click on the &gbSave; button to store the information in BASE2 
      or on the &gbCancel; button to abort. </para>
    </sect2>

    <sect2 id="array_lims.arrayslide.detail_view">
      <title>Viewing/Editing ArraySlides</title>
      <itemizedlist>
        <listitem>
          <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or
              <keycap>SHIFT</keycap> keys while clicking on the name of an ArraySlide
            Item, which is a live link. </para>
        </listitem>
        <listitem>
          <para> Alternately, navigating to the ArraySlide Item View, one can hit the
              &gbEdit; to performed the task.</para>
          <para>In both cases, an Edit pop-up windows opens. It is essentially identical
            to a Create window and allows updating information about a particular
            ArraySlide item stored in BASE2</para>
          <figure id="write_docbook_doc.figures.arrayslide-itemview">
            <title>ArraySlide Item View</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata contentwidth="10cm" width="10cm" fileref="figures/arrayslide-itemview.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
        </listitem>

        <listitem>
          <para>From the ArraySlide item View, the associated
            <guilabel>Hybridization</guilabel> can be indicated as navigable
          links</para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="array_lims.arrayslide.delete">
      <title>Deleting/Restoring ArraySlides</title>
      <para>As for other items in BASE2, ArraySlides can be removed and restored. To do so, do
        the following</para>
      <itemizedlist>
        <listitem>
          <para>Select one or more ArraySlides and click &gbDelete;
            button in the menu bar. </para>
          <para>All the selected ArraySlides 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
            ArraySlides earmarked for deletion. They will be shown with a symbol <inlinemediaobject>
              <imageobject>
                <imagedata fileref="figures/deleted.gif" format="GIF"/>
              </imageobject>
            </inlinemediaobject> in front of them. </para>
        </listitem>
        <listitem>
          <para>Alternately, navigating to the ArraySlide Item View, one can hit the
              &gbDelete; 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
              &gbRestore; button to performed the task. </para>
        </listitem>
      </itemizedlist>
      <important>
        <para>To really delete an item from the database you must use the trashcan. Items
          deleted from the Trashcan can not be recovered. To learn more about the trashcan
          function, please refer to <xref linkend="trashcan"/>
        </para>
      </important>
    </sect2>


  </sect1>

</chapter>