source: trunk/doc/src/docbook/user/array_lims.xml @ 5783

<?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 5783 2011-10-05 10:34:24Z nicklas $
  
  Copyright (C) 2007 Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
  Copyright (C) 2007 Jari Häkkinen, Nicklas Nordborg
  
  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 3
  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 BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="array_lims" chunked="0">
  <title>Array LIMS</title>

  <para>
    Arrays are at the core of the BASE business and are essential
    elements to describe in order to
    be <ulink url='http://www.mged.org/Workgroups/MIAME/miame.html'>MIAME</ulink>
    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>
    As a good practice, all array related information should be
    entered into BASE prior to work on describing the sample
    processing and hybridizations events making up a microarray
    experiment is begun.
  </para>
  <para>
    BASE is engineered to support microarray printing facilities. The
    system therefore offers objects to describe plates, their
    geometries, and the events (<emphasis>e.g.</emphasis>, merging and
    printing) affecting them. The first section of this chapter deals
    with this functionality as well as plate management. Users buying
    arrays from commercial sources can ignore the plate management
    component and immediately jump to
    <xref linkend="array_lims.arraydesign" />.
  </para>

  <sect1 id="array_lims.platemanagement">
    <title>Plates</title>
    <para>TODO</para>
  </sect1>

  <sect1 id="array_lims.arraydesign">
    <title>Array designs</title>
    
    <para>
      Array designs 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. BASE 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 BASE to help in these
      tasks.
    </para>
    <tip>
      <para>
        It's highly recommended to have read
        <xref linkend="webclient.items" />
        before continuing with this chapter.
      </para>
    </tip>
    <para>
      Use
      <menuchoice>
        <guimenu>Array LIMS</guimenu>
        <guimenuitem>Array designs</guimenuitem>
      </menuchoice>
      to get to the list page with array designs.
    </para>
    
    <sect2 id="array_lims.arraydesign.properties">
      <title>Properties</title>
      <sect3 id="array_lims.arraydesign.properties.arraydesign">
        <title>Array design</title>
        
        <helptext external_id="arraydesign.edit" title="Edit array design">
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>Provide an sensible name for the design (required).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Platform</guilabel>
            </term>
            <listitem>
              <para>
                Select the platform / variant used for the
                array design. The selected options affects which
                files that can be selected on the <guilabel>Data files</guilabel>
                tab.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Arrays/slide</guilabel>
            </term>
            <listitem>
              <para>
                The number of sub-arrays that can be placed on a
                single slide. The default value is 1, but some 
                platforms, for example Illumina, has slides
                with 6 or 8 arrays.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Description</guilabel>
            </term>
            <listitem>
              <para>
                Provide other useful information about the array design in this text
                area.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>
          Click on the &gbSave; button to store the information in BASE or on the
          &gbCancel; button to abort.
        </para>
        <seeother>
          <other external_id="datafiles.edit">Data files</other>
          <other external_id="annotations.edit">Annotations</other>
          <other external_id="annotations.edit.inerited">Inherit annotations</other>
        </seeother>
        </helptext>
        
      </sect3>

      <sect3 id="array_lims.arraydesign.datafiles">
        <title>Data files</title>
        <para>
          This allows you to select files that contain data for the array design. 
          Read more about this in <xref linkend="platforms.selectfiles" />.
        </para>
      </sect3>
      
      <sect3 id="array_lims.arraydesign.annotations">
        <title>Annotations and inherited annotations</title>
        <para>
          This allows you to input values associated to annotation types devised to refine
          array design description. Read more about annotations in
          <xref linkend="annotations" />.
        </para>
      </sect3>
    </sect2>


    <sect2 id="array_lims.arraydesign.importfeature">
      <title>Importing features to an array design</title>

      <para>
        Importing features is an important step in order to fully
        define an array design. It should be noted that BASE does not
        enforce the immediate feature import upon creation of array
        design. However, it is STRONGLY advised to do so when creating
        an array design. Performing the import enables use of the
        array design in downstream analysis with no further
        trouble. It also matters when importing raw bioassay data and
        matching those to the corresponding array design.
      </para>

      <para>
        Depending on which platform and/or data files you selected when you
        created the array design the process to import features is different.
        For example, if you selected the Affymetrix platform, which is a file-only
        platform, the feature information has already been extracted from
        the CDF file (if you selected one). If the selected platform
        doesn't extract information from the selected data file automatically
        this may be done manually by executing an import plug-in.
      </para>

      <para>
        From the array design item view, click on the &gbImport; button and use the
        reporter map importer and an appropriate plug-in configuration when following the
        instructions in
        <xref linkend="import_data" />.
        If the import run is successful, go to the array design list view. The
        <guilabel>Has features</guilabel>
        column will show
        <guilabel>Yes (db: x, file: y)</guilabel>
        where x is the number of features actually imported into the database.
      </para>

      <note>
        <para>
          The &gbImport; button only shows up if the logged in user has 
          enough permissions.
        </para>
      </note>      
      
      <note>
        <title>Verify that probsets in a CDF file exist as reporters</title>
        <para>
          File-only platforms, such as Affymetrix, require that all probesets
          must exist as reporters before data can be analysed. For other
          platforms this is usually checked when importing the features to 
          the database. Since no import takes place for file-only platforms,
          another manual step takes it place. Use the &gbImport; button
          in the array design item view and select the 
          <guilabel>Affymetrix CDF probeset importer</guilabel> plug-in.
          If you have enough permissions this function will also let you create 
          missing reporters.
        </para>
      </note>
    </sect2>
  </sect1>


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

    <sect2 id="array_lims.arraybatch.create">
      <title>Creating array batches</title>
      <para>
        Beside the common way of creating items in BASE, an array batch can also be created
        directly from an array design, both in list view and single item view.
      </para>
      <variablelist>
        <varlistentry>
          <term>In list view of array design</term>
          <listitem>
            <para>
              Click on the
              <guiicon>
                <inlinemediaobject>
                  <imageobject>
                    <imagedata fileref="figures/add.png" format="PNG" />
                  </imageobject>
                </inlinemediaobject>
              </guiicon>  
              icon available from the
              <guilabel>Batches</guilabel>
              column of the array design you want to use.
              <tip>
                <para>
                  As default in BASE the
                  <guilabel>Batches</guilabel>
                  column is hidden and need therefore be made visible first, see
                  <xref linkend="webclient.itemlist.columns" />
                </para>
              </tip>
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
        <guibutton>New batch&hellip;</guibutton>
        is the corresponding button in single item view. The current array design will
        automatically be filled in the array design property for the new batch.
      </para>
    </sect2>
    <sect2 id="array_lims.arraybatch.properties">
      <title>Properties</title>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Name</guilabel>
          </term>
          <listitem>
            <para>The name of the array batch (required).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Array design</guilabel>
          </term>
          <listitem>
            <para>Array design that is used for the batch.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Print robot</guilabel>
          </term>
          <listitem>
            <para>The print robot that is used.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Protocol</guilabel>
          </term>
          <listitem>
            <para>
              The printing protocol that was followed when producing the array batch
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
        Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
        button to abort.
      </para>
      <para>
        See
        <xref linkend="annotations" />
        for information about annotating items and inherit annotations.
      </para>
      <para>
        How many slides each batch has can be found in the
        <guilabel>Slides</guilabel>
        column, list view page.
      </para>
    </sect2>
  </sect1>

  <sect1 id="array_lims.arrayslide">
    <title>Array slides</title>
    <para>
      Use
      <menuchoice>
        <guimenu>Array LIMS</guimenu>
        <guimenuitem>Array slides</guimenuitem>
      </menuchoice>
      to get to the list page of array slides.
    </para>
    <sect2 id="array_lims.arrayslide.create">
      <title>Creating array slides</title>
      <para>In BASE, array slides can be created, except the common way, by 2 routes:</para>
      <variablelist>
        <varlistentry>
          <term>from the array batch list page</term>
          <listitem>
            <para>
              Clicking on the
              <guiicon>
                <inlinemediaobject>
                  <imageobject>
                    <imagedata fileref="figures/add.png" format="PNG" />
                  </imageobject>
                </inlinemediaobject>
              </guiicon>
              icon in the
              <guilabel>Slides</guilabel>
              column for the batch you want to add a slide to. Corresponding button in
              the view page of a batch is
              <guibutton>New slide&hellip;</guibutton>
              .
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>using a wizard to create multiple slides simultaneously</term>
          <listitem>
            <para>
              This can be started from three different places:
              <itemizedlist>
                <listitem>
                  <para>
                    array batch list view by clicking on
                    <guiicon>
                      <inlinemediaobject>
                        <imageobject>
                          <imagedata fileref="figures/new_wizard.gif"
                            format="GIF" />
                        </imageobject>
                      </inlinemediaobject>
                    </guiicon>
                    in the
                    <guilabel>Slides</guilabel>
                    column of the batch that should be used.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    Using the
                    <guibutton>Create slides</guibutton>
                    in a single item view of an array batch.
                  </para>
                </listitem>
                <listitem>
                  <para>
                    In the list page of array slides, using the
                    <guibutton>Create multiple&hellip;</guibutton>
                    button
                  </para>
                </listitem>
              </itemizedlist>
              The wizard is described further down in
              <xref linkend="array_lims.arrayslide.properties.wizard" />
              .
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="array_lims.arrayslide.properties">
      <title>Properties</title>

      <figure id="write_docbook_doc.figures.arrayslide-single-create">
        <title>Create new array slide</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata 
                fileref="figures/arrayslide-single-create.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      <variablelist>
        <varlistentry>
          <term>
            <guilabel>Name</guilabel>
          </term>
          <listitem>
            <para>The name of the array slide (required).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Barcode</guilabel>
          </term>
          <listitem>
            <para>Does the array slide have a barcode, it can be put here.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Destroyed</guilabel>
          </term>
          <listitem>
            <para>
              This check-box can be ticked to mark the slide as destroyed, lost or
              damaged.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Array batch</guilabel>
          </term>
          <listitem>
            <para>Array batch that the slide belongs to (required).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Index</guilabel>
          </term>
          <listitem>
            <para>The index of the array slide in selected array batch.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            <guilabel>Description</guilabel>
          </term>
          <listitem>
            <para>
              Any information useful information about the slide can be in this field.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>
        Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
        button to abort.
      </para>
      <sect3 id="array_lims.arrayslide.properties.wizard">
        <title>Multiple slides wizard</title>
        <para>
          As mentioned above there is an alternative to create one slide at a time if you
          have many to add. There is a wizard that can help you to create at the most 999
          slides in one go. The wizard is in two steps, both showed in the picture
          <xref linkend="write_docbook_doc.figures.arrayslide-multiple-create" />
          .
          <orderedlist>
            <listitem>
              <para>
                The first step reminds alot of the normal edit window of an array
                slide, but there are some differences:
                <variablelist>
                  <varlistentry>
                    <term>
                      <guilabel>Quantity</guilabel>
                    </term>
                    <listitem>
                      <para>
                        Number of slides to create with this wizard
                        (required and must be between 1 and 999)
                      </para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      <guilabel>Start at</guilabel>
                    </term>
                    <listitem>
                      <para>
                        The index number to start from when indexing the
                        name of the slides.
                      </para>
                    </listitem>
                  </varlistentry>
                  <varlistentry>
                    <term>
                      <guilabel>Pad size</guilabel>
                    </term>
                    <listitem>
                      <para>
                        The index will be filled out with zeros in front to
                        always have this length.
                      </para>
                    </listitem>
                  </varlistentry>
                </variablelist>
                Press
                <guibutton>Next</guibutton>
                to continue to next step of the wizard.
                <important>
                  <para>
                    Be sure to get everything right before proceeding, because
                    it is not possible to go back from step 2.
                  </para>
                </important>
              </para>
            </listitem>
            <listitem>
              <para>
                In step 2 should the barcodes for the array slides be entered, for
                those which have one. The autogenerated names of the slides can also
                be changed if that is wanted, as long as no name-field is left
                empty.
              </para>
            </listitem>
          </orderedlist>

          <figure id="write_docbook_doc.figures.arrayslide-multiple-create">
            <title>Create multiple array slide</title>
            <screenshot>
              <mediaobject>
                <imageobject>
                  <imagedata scalefit="1" width="100%"
                    fileref="figures/arrayslide-multiple-create.png" format="PNG" />
                </imageobject>
              </mediaobject>
            </screenshot>
          </figure>
          Fill in the necessary information as exhaustively as possible.
        </para>
        <para>
          Click on the &gbSave; button to store the information in BASE or on the
          &gbCancel; button to abort.
        </para>
        <para>
          See
          <xref linkend="annotations" />
          for information about annotating items and inherit annotations. 
        </para>
      </sect3>
    </sect2>
  </sect1>
</chapter>