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

Last change on this file since 5783 was 5783, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

Experiments and analysis chapter.

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