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

<?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 3420 2007-05-31 09:55:37Z 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
      <xref linkend="array_lims.arraydesign" />
      .
    </para>

  </sect1>

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

  <sect1 id="array_lims.arraydesign">
    <title>Array designs</title>
    <para>
      Array design 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>
    <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>
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>Provide an unique sensible name for the design (required).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Affy chip</guilabel>
            </term>
            <listitem>
              <para>
                This is a checkbox for providing a boolean entry, essentially
                telling the system whether the array design 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 some 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>
          <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 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 array design 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
          <xref linkend="array_lims.arraydesign.properties.importfeature" />
          .
        </para>
      </sect3>

      <sect3 id="array_lims.arraydesign.properties.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>


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

        <para>
          For non-affymetrix arraydesigns, importing features is an important step in
          order to fully define an array design. It should be noted that BASE2 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. Doing so enables to
          use the array design for downstream analysis with no further trouble. It also
          matters when importing raw bioassay data and matching those to the corresponding
          array design.
        </para>

        <para>
          This section applies only to non-affymetrix array design 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 array design item view, click on the &gbImport; button and use the
          reporter map importer and an appropriate plugin configuration when following the
          instructions in
          <xref linkend="import_export_data.import" />
          .
        </para>
        <note>
          <para>
            The button only shows up if the logged in user has enough permissions.
          </para>
        </note>
        <para>
          If the import run is successful, go to the array design 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>
      </sect3>
    </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
              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="figures/add.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
              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 BASE2 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 BASE2, 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
              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="figures/add.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
              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
                    <inlinemediaobject>
                      <imageobject>
                        <imagedata fileref="figures/new_wizard.gif"
                          format="GIF" />
                      </imageobject>
                    </inlinemediaobject>
                    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 contentwidth="10cm" width="10cm"
                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 BASE2 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 contentwidth="10cm" width="10cm"
                    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 BASE2 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>