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

Last change on this file since 4401 was 4401, checked in by Jari Häkkinen, 14 years ago

Improved text and minor change to section order.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 17.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: array_lims.xml 4401 2008-08-20 13:58:58Z jari $
7 
8  Copyright (C) 2007 Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
9  Copyright (C) 2007 Jari Hakkinen, Nicklas Nordborg
10 
11  This file is part of BASE - BioArray Software Environment.
12  Available at http://base.thep.lu.se/
13 
14  BASE is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License
16  as published by the Free Software Foundation; either version 2
17  of the License, or (at your option) any later version.
18 
19  BASE is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  GNU General Public License for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with this program; if not, write to the Free Software
26  Foundation, Inc., 59 Temple Place - Suite 330,
27  Boston, MA  02111-1307, USA.
28-->
29
30<chapter id="array_lims" chunked="0">
31  <?dbhtml dir="array_lims"?>
32  <title>Array LIMS</title>
33
34  <para>
35    Arrays are at the core of the BASE business and are essential
36    elements to describe in order to
37    be <ulink url='http://www.mged.org/Workgroups/MIAME/miame.html'>MIAME</ulink>
38    compliant. It is also critical to track and manage information
39    about microarray design as accurately as possible since mistakes
40    could prove extremely costly in downstream analysis.
41  </para>
42  <para>
43    As a good practice, all array related information should be
44    entered into BASE prior to work on describing the sample
45    processing and hybridizations events making up a microarray
46    experiment is begun.
47  </para>
48  <para>
49    BASE is engineered to support microarray printing facilities. The
50    system therefore offers objects to describe plates, their
51    geometries, and the events (<emphasis>e.g.</emphasis>, merging and
52    printing) affecting them. The first section of this chapter deals
53    with this functionality as well as plate management. Users buying
54    arrays from commercial sources can ignore the plate management
55    component and immediately jump to
56    <xref linkend="array_lims.arraydesign" />.
57  </para>
58
59  <sect1 id="array_lims.platemanagement">
60    <title>Plates</title>
61    <para>TODO</para>
62  </sect1>
63
64  <sect1 id="array_lims.arraydesign">
65    <title>Array designs</title>
66   
67    <para>
68      Array designs should be understood as a plan which can be realized during a printing
69      process producing microarray slides. During the course of the printing process, reagents
70      may run out leading to the interruption of this process. All slides created during this
71      printing process belong to the same printing batch. It is the array slide that will
72      eventually be used in a hybridization event. BASE allows user to track those 3 entities
73      with great details. This is an important functionality for users producing their own
74      arrays and for those caring for quality control and tracking of microarray slides in a
75      printing facility. The following sections detail how to use BASE to help in these
76      tasks.
77    </para>
78    <tip>
79      <para>
80        It's highly recommended to have read
81        <xref linkend="webclient.items" />
82        before continuing with this chapter.
83      </para>
84    </tip>
85    <para>
86      Use
87      <menuchoice>
88        <guimenu>Array LIMS</guimenu>
89        <guimenuitem>Array designs</guimenuitem>
90      </menuchoice>
91      to get to the list page with array designs.
92    </para>
93   
94    <sect2 id="array_lims.arraydesign.properties">
95      <title>Properties</title>
96      <sect3 id="array_lims.arraydesign.properties.arraydesign">
97        <title>Array design</title>
98       
99        <helptext external_id="arraydesign.edit" title="Edit array design">
100        <variablelist>
101          <varlistentry>
102            <term>
103              <guilabel>Name</guilabel>
104            </term>
105            <listitem>
106              <para>Provide an sensible name for the design (required).</para>
107            </listitem>
108          </varlistentry>
109          <varlistentry>
110            <term>
111              <guilabel>Platform</guilabel>
112            </term>
113            <listitem>
114              <para>
115                Select the platform / variant used for the
116                array design. The selected options affects which
117                files that can be selected on the <guilabel>Data files</guilabel>
118                tab.
119              </para>
120            </listitem>
121          </varlistentry>
122          <varlistentry>
123            <term>
124              <guilabel>Arrays/slide</guilabel>
125            </term>
126            <listitem>
127              <para>
128                The number of sub-arrays that can be placed on a
129                single slide. The default value is 1, but some
130                platforms, for example Illumina, has slides
131                with 6 or 8 arrays.
132              </para>
133            </listitem>
134          </varlistentry>
135          <varlistentry>
136            <term>
137              <guilabel>Description</guilabel>
138            </term>
139            <listitem>
140              <para>
141                Provide other useful information about the array design in this text
142                area.
143              </para>
144            </listitem>
145          </varlistentry>
146        </variablelist>
147        <para>
148          Click on the &gbSave; button to store the information in BASE or on the
149          &gbCancel; button to abort.
150        </para>
151        <seeother>
152          <other external_id="datafiles.edit">Data files</other>
153          <other external_id="annotations.edit">Annotations</other>
154          <other external_id="annotations.edit.inerited">Inherit annotations</other>
155        </seeother>
156        </helptext>
157       
158      </sect3>
159
160      <sect3 id="array_lims.arraydesign.properties.annotations">
161        <title>Annotations and inherited annotations</title>
162        <para>
163          This allows you to input values associated to annotation types devised to refine
164          array design description. Read more about annotations in
165          <xref linkend="annotations" />.
166        </para>
167      </sect3>
168    </sect2>
169
170
171    <sect2 id="array_lims.arraydesign.importfeature">
172      <title>Importing features to an array design</title>
173
174      <para>
175        Importing features is an important step in order to fully
176        define an array design. It should be noted that BASE does not
177        enforce the immediate feature import upon creation of array
178        design. However, it is STRONGLY advised to do so when creating
179        an array design. Performing the import enables use of the
180        array design in downstream analysis with no further
181        trouble. It also matters when importing raw bioassay data and
182        matching those to the corresponding array design.
183      </para>
184
185      <para>
186        Depending on which platform and/or data files you selected when you
187        created the array design the process to import features is different.
188        For example, if you selected the Affymetrix platform, which is a file-only
189        platform, the feature information has already been extracted from
190        the CDF file (if you selected one). If the selected platform
191        doesn't extract information from the selected data file automatically
192        this may be done manually by executing an import plug-in.
193      </para>
194
195      <para>
196        From the array design item view, click on the &gbImport; button and use the
197        reporter map importer and an appropriate plug-in configuration when following the
198        instructions in
199        <xref linkend="import_export_data.import" />.
200        If the import run is successful, go to the array design list view. The
201        <guilabel>Has features</guilabel>
202        column will show
203        <guilabel>Yes (db: x, file: y)</guilabel>
204        where x is the number of features actually imported into the database.
205      </para>
206
207      <note>
208        <para>
209          The &gbImport; button only shows up if the logged in user has
210          enough permissions.
211        </para>
212      </note>     
213     
214      <note>
215        <title>Verify that probsets in a CDF file exist as reporters</title>
216        <para>
217          File-only platforms, such as Affymetrix, require that all probesets
218          must exist as reporters before data can be analysed. For other
219          platforms this is usually checked when importing the features to
220          the database. Since no import takes place for file-only platforms,
221          another manual step takes it place. Use the &gbImport; button
222          in the array design item view and select the
223          <guilabel>Affymetrix CDF probeset importer</guilabel> plug-in.
224          If you have enough permissions this function will also let you create
225          missing reporters.
226        </para>
227      </note>
228    </sect2>
229  </sect1>
230
231
232  <sect1 id="array_lims.arraybatch">
233    <title>Array batches</title>
234
235    <sect2 id="array_lims.arraybatch.create">
236      <title>Creating array batches</title>
237      <para>
238        Beside the common way of creating items in BASE, an array batch can also be created
239        directly from an array design, both in list view and single item view.
240      </para>
241      <variablelist>
242        <varlistentry>
243          <term>In list view of array design</term>
244          <listitem>
245            <para>
246              Click on the
247              <guiicon>
248                <inlinemediaobject>
249                  <imageobject>
250                    <imagedata fileref="figures/add.png" format="PNG" />
251                  </imageobject>
252                </inlinemediaobject>
253              </guiicon> 
254              icon available from the
255              <guilabel>Batches</guilabel>
256              column of the array design you want to use.
257              <tip>
258                <para>
259                  As default in BASE the
260                  <guilabel>Batches</guilabel>
261                  column is hidden and need therefore be made visible first, see
262                  <xref linkend="webclient.itemlist.columns" />
263                </para>
264              </tip>
265            </para>
266          </listitem>
267        </varlistentry>
268      </variablelist>
269      <para>
270        <guibutton>New batch&hellip;</guibutton>
271        is the corresponding button in single item view. The current array design will
272        automatically be filled in the array design property for the new batch.
273      </para>
274    </sect2>
275    <sect2 id="array_lims.arraybatch.properties">
276      <title>Properties</title>
277      <variablelist>
278        <varlistentry>
279          <term>
280            <guilabel>Name</guilabel>
281          </term>
282          <listitem>
283            <para>The name of the array batch (required).</para>
284          </listitem>
285        </varlistentry>
286        <varlistentry>
287          <term>
288            <guilabel>Array design</guilabel>
289          </term>
290          <listitem>
291            <para>Array design that is used for the batch.</para>
292          </listitem>
293        </varlistentry>
294        <varlistentry>
295          <term>
296            <guilabel>Print robot</guilabel>
297          </term>
298          <listitem>
299            <para>The print robot that is used.</para>
300          </listitem>
301        </varlistentry>
302        <varlistentry>
303          <term>
304            <guilabel>Protocol</guilabel>
305          </term>
306          <listitem>
307            <para>
308              The printing protocol that was followed when producing the array batch
309            </para>
310          </listitem>
311        </varlistentry>
312      </variablelist>
313      <para>
314        Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
315        button to abort.
316      </para>
317      <para>
318        See
319        <xref linkend="annotations" />
320        for information about annotating items and inherit annotations.
321      </para>
322      <para>
323        How many slides each batch has can be found in the
324        <guilabel>Slides</guilabel>
325        column, list view page.
326      </para>
327    </sect2>
328  </sect1>
329
330  <sect1 id="array_lims.arrayslide">
331    <title>Array slides</title>
332    <para>
333      Use
334      <menuchoice>
335        <guimenu>Array LIMS</guimenu>
336        <guimenuitem>Array slides</guimenuitem>
337      </menuchoice>
338      to get to the list page of array slides.
339    </para>
340    <sect2 id="array_lims.arrayslide.create">
341      <title>Creating array slides</title>
342      <para>In BASE, array slides can be created, except the common way, by 2 routes:</para>
343      <variablelist>
344        <varlistentry>
345          <term>from the array batch list page</term>
346          <listitem>
347            <para>
348              Clicking on the
349              <guiicon>
350                <inlinemediaobject>
351                  <imageobject>
352                    <imagedata fileref="figures/add.png" format="PNG" />
353                  </imageobject>
354                </inlinemediaobject>
355              </guiicon>
356              icon in the
357              <guilabel>Slides</guilabel>
358              column for the batch you want to add a slide to. Corresponding button in
359              the view page of a batch is
360              <guibutton>New slide&hellip;</guibutton>
361              .
362            </para>
363          </listitem>
364        </varlistentry>
365        <varlistentry>
366          <term>using a wizard to create multiple slides simultaneously</term>
367          <listitem>
368            <para>
369              This can be started from three different places:
370              <itemizedlist>
371                <listitem>
372                  <para>
373                    array batch list view by clicking on
374                    <guiicon>
375                      <inlinemediaobject>
376                        <imageobject>
377                          <imagedata fileref="figures/new_wizard.gif"
378                            format="GIF" />
379                        </imageobject>
380                      </inlinemediaobject>
381                    </guiicon>
382                    in the
383                    <guilabel>Slides</guilabel>
384                    column of the batch that should be used.
385                  </para>
386                </listitem>
387                <listitem>
388                  <para>
389                    Using the
390                    <guibutton>Create slides</guibutton>
391                    in a single item view of an array batch.
392                  </para>
393                </listitem>
394                <listitem>
395                  <para>
396                    In the list page of array slides, using the
397                    <guibutton>Create multiple&hellip;</guibutton>
398                    button
399                  </para>
400                </listitem>
401              </itemizedlist>
402              The wizard is described further down in
403              <xref linkend="array_lims.arrayslide.properties.wizard" />
404              .
405            </para>
406          </listitem>
407        </varlistentry>
408      </variablelist>
409    </sect2>
410    <sect2 id="array_lims.arrayslide.properties">
411      <title>Properties</title>
412
413      <figure id="write_docbook_doc.figures.arrayslide-single-create">
414        <title>Create new array slide</title>
415        <screenshot>
416          <mediaobject>
417            <imageobject>
418              <imagedata 
419                fileref="figures/arrayslide-single-create.png" format="PNG" />
420            </imageobject>
421          </mediaobject>
422        </screenshot>
423      </figure>
424      <variablelist>
425        <varlistentry>
426          <term>
427            <guilabel>Name</guilabel>
428          </term>
429          <listitem>
430            <para>The name of the array slide (required).</para>
431          </listitem>
432        </varlistentry>
433        <varlistentry>
434          <term>
435            <guilabel>Barcode</guilabel>
436          </term>
437          <listitem>
438            <para>Does the array slide have a barcode, it can be put here.</para>
439          </listitem>
440        </varlistentry>
441        <varlistentry>
442          <term>
443            <guilabel>Destroyed</guilabel>
444          </term>
445          <listitem>
446            <para>
447              This check-box can be ticked to mark the slide as destroyed, lost or
448              damaged.
449            </para>
450          </listitem>
451        </varlistentry>
452        <varlistentry>
453          <term>
454            <guilabel>Array batch</guilabel>
455          </term>
456          <listitem>
457            <para>Array batch that the slide belongs to (required).</para>
458          </listitem>
459        </varlistentry>
460        <varlistentry>
461          <term>
462            <guilabel>Index</guilabel>
463          </term>
464          <listitem>
465            <para>The index of the array slide in selected array batch.</para>
466          </listitem>
467        </varlistentry>
468        <varlistentry>
469          <term>
470            <guilabel>Description</guilabel>
471          </term>
472          <listitem>
473            <para>
474              Any information useful information about the slide can be in this field.
475            </para>
476          </listitem>
477        </varlistentry>
478      </variablelist>
479      <para>
480        Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
481        button to abort.
482      </para>
483      <sect3 id="array_lims.arrayslide.properties.wizard">
484        <title>Multiple slides wizard</title>
485        <para>
486          As mentioned above there is an alternative to create one slide at a time if you
487          have many to add. There is a wizard that can help you to create at the most 999
488          slides in one go. The wizard is in two steps, both showed in the picture
489          <xref linkend="write_docbook_doc.figures.arrayslide-multiple-create" />
490          .
491          <orderedlist>
492            <listitem>
493              <para>
494                The first step reminds alot of the normal edit window of an array
495                slide, but there are some differences:
496                <variablelist>
497                  <varlistentry>
498                    <term>
499                      <guilabel>Quantity</guilabel>
500                    </term>
501                    <listitem>
502                      <para>
503                        Number of slides to create with this wizard
504                        (required and must be between 1 and 999)
505                      </para>
506                    </listitem>
507                  </varlistentry>
508                  <varlistentry>
509                    <term>
510                      <guilabel>Start at</guilabel>
511                    </term>
512                    <listitem>
513                      <para>
514                        The index number to start from when indexing the
515                        name of the slides.
516                      </para>
517                    </listitem>
518                  </varlistentry>
519                  <varlistentry>
520                    <term>
521                      <guilabel>Pad size</guilabel>
522                    </term>
523                    <listitem>
524                      <para>
525                        The index will be filled out with zeros in front to
526                        always have this length.
527                      </para>
528                    </listitem>
529                  </varlistentry>
530                </variablelist>
531                Press
532                <guibutton>Next</guibutton>
533                to continue to next step of the wizard.
534                <important>
535                  <para>
536                    Be sure to get everything right before proceeding, because
537                    it is not possible to go back from step 2.
538                  </para>
539                </important>
540              </para>
541            </listitem>
542            <listitem>
543              <para>
544                In step 2 should the barcodes for the array slides be entered, for
545                those which have one. The autogenerated names of the slides can also
546                be changed if that is wanted, as long as no name-field is left
547                empty.
548              </para>
549            </listitem>
550          </orderedlist>
551
552          <figure id="write_docbook_doc.figures.arrayslide-multiple-create">
553            <title>Create multiple array slide</title>
554            <screenshot>
555              <mediaobject>
556                <imageobject>
557                  <imagedata scalefit="1" width="100%"
558                    fileref="figures/arrayslide-multiple-create.png" format="PNG" />
559                </imageobject>
560              </mediaobject>
561            </screenshot>
562          </figure>
563          Fill in the necessary information as exhaustively as possible.
564        </para>
565        <para>
566          Click on the &gbSave; button to store the information in BASE or on the
567          &gbCancel; button to abort.
568        </para>
569        <para>
570          See
571          <xref linkend="annotations" />
572          for information about annotating items and inherit annotations.
573        </para>
574      </sect3>
575    </sect2>
576  </sect1>
577</chapter>
Note: See TracBrowser for help on using the repository browser.