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

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

References #1655: GUI improvements

  • Started to create screen shots with the new design for the user documentation.
  • Got rid of old .gif icons in the documentation and replaced them with .png versions.
  • Fixed some issues with placement of 'required information' in two dialogs.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 20.2 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 5971 2012-02-17 10:30:22Z 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    As a good practice, all array related information should be
39    entered into BASE prior to work on describing the sample
40    processing and hybridizations or other events making up an
41    experiment is begun.
42  </para>
43
44  <sect1 id="array_lims.arraydesign">
45    <title>Array designs</title>
46   
47    <para>
48      Array designs should be understood as a plan which can be realized during a printing
49      process producing microarray slides. During the course of the printing process, reagents
50      may run out leading to the interruption of this process. All slides created during this
51      printing process belong to the same printing batch. It is the array slide that will
52      eventually be used in a hybridization event. BASE allows user to track those 3 entities
53      with great details. This is an important functionality for users producing their own
54      arrays and for those caring for quality control and tracking of microarray slides in a
55      printing facility. The following sections detail how to use BASE to help in these
56      tasks.
57    </para>
58
59    <note>
60      <title>Non-array platforms also need array designs</title>
61      <para>
62        Array designs are needed also for non-array platforms (eg. sequencing). In this
63        case a "virtual array design" is created which is simply a list of all features
64        that is of interest in the experiment. Since there are no coordinates or positions
65        to identify features a unique id need to be constructed in some other way.
66        For example, in sequencing experiments we may use a GTF file to create a
67        virtual array design using the <emphasis>transcript_id</emphasis> and
68        <emphasis>chromosome</emphasis> as a unique identifier.
69      </para>
70    </note>
71
72    <para>
73      Use
74      <menuchoice>
75        <guimenu>Array LIMS</guimenu>
76        <guimenuitem>Array designs</guimenuitem>
77      </menuchoice>
78      to get to the list page with array designs.
79    </para>
80   
81    <sect2 id="array_lims.arraydesign.properties">
82      <title>Properties</title>
83
84        <figure id="array_lims.figures.arraydesign">
85          <title>Array design properties</title>
86          <screenshot>
87            <mediaobject>
88              <imageobject>
89                <imagedata 
90                  fileref="figures/arraydesign_edit.png" format="PNG" />
91              </imageobject>
92            </mediaobject>
93          </screenshot>
94        </figure>
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. In sequencing platforms, this value
129                is the number of lanes on a flow cell.
130              </para>
131            </listitem>
132          </varlistentry>
133          <varlistentry>
134            <term>
135              <guilabel>Description</guilabel>
136            </term>
137            <listitem>
138              <para>
139                Provide other useful information about the array design in this text
140                area.
141              </para>
142            </listitem>
143          </varlistentry>
144        </variablelist>
145        <para>
146          Click on the &gbSave; button to store the information in BASE or on the
147          &gbCancel; button to abort.
148        </para>
149        <seeother>
150          <other external_id="datafiles.edit">Data files</other>
151          <other external_id="annotations.edit">Annotations</other>
152          <other external_id="annotations.edit.inerited">Inherit annotations</other>
153        </seeother>
154        </helptext>
155       
156      <para>
157        The <guilabel>Data files</guilabel> tab allows BASE users to
158        attach files to the array design. The possible file types are defined
159        by the array design's platform. See <xref linkend="platforms.selectfiles"/> 
160        for more information.
161      </para>
162     
163      <para>
164        The <guilabel>Annotations</guilabel> tab allows BASE users to use
165        annotation types to refine array design description. More about annotating items
166        can be read in <xref linkend="annotations.annotating" />.
167      </para>
168     
169      <para>
170        This <guilabel>Inherited annotations</guilabel> tab contains a list of those annotations
171        that are inherited from the array design's parents (eg. plates). Information about
172        working with inherited annotations can be found in <xref linkend="annotations.inheriting" />.
173      </para>
174
175    </sect2>
176
177
178    <sect2 id="array_lims.arraydesign.importfeature">
179      <title>Importing features to an array design</title>
180
181      <para>
182        Importing features is an important step in order to fully
183        define an array design. It should be noted that BASE does not
184        enforce the immediate feature import upon creation of array
185        design. However, it is STRONGLY advised to do so when creating
186        an array design. Performing the import enables use of the
187        array design in downstream analysis with no further
188        trouble. It also matters when importing raw bioassay data and
189        matching those to the corresponding array design.
190      </para>
191
192      <para>
193        Depending on which platform and/or data files you selected when you
194        created the array design the process to import features is different.
195        For example, if you selected the Affymetrix platform, which is a file-only
196        platform, the feature information has already been extracted from
197        the CDF file (if you selected one). If the selected platform
198        doesn't extract information from the selected data file automatically
199        this may be done manually by executing an import plug-in.
200      </para>
201
202      <para>
203        From the array design item view, click on the &gbImport; button and use the
204        reporter map importer and an appropriate plug-in configuration when following the
205        instructions in
206        <xref linkend="import_data" />.
207        If the import run is successful, go to the array design list view. The
208        <guilabel>Has features</guilabel>
209        column will show
210        <guilabel>Yes (db: x, file: y)</guilabel>
211        where x is the number of features actually imported into the database.
212      </para>
213
214      <note>
215        <para>
216          The &gbImport; button only shows up if the logged in user has
217          enough permissions.
218        </para>
219      </note>     
220     
221      <note>
222        <title>Verify that probsets in a CDF file exist as reporters</title>
223        <para>
224          File-only platforms, such as Affymetrix, require that all probesets
225          must exist as reporters before data can be analysed. For other
226          platforms this is usually checked when importing the features to
227          the database. Since no import takes place for file-only platforms,
228          another manual step takes it place. Use the &gbImport; button
229          in the array design item view and select the
230          <guilabel>Affymetrix CDF probeset importer</guilabel> plug-in.
231          If you have enough permissions this function will also let you create
232          missing reporters.
233        </para>
234      </note>
235    </sect2>
236  </sect1>
237
238
239  <sect1 id="array_lims.arraybatch">
240    <title>Array batches</title>
241
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
280
281        <figure id="array_lims.figures.arraybatch">
282          <title>Array batch properties</title>
283          <screenshot>
284            <mediaobject>
285              <imageobject>
286                <imagedata 
287                  fileref="figures/arraybatch_edit.png" format="PNG" />
288              </imageobject>
289            </mediaobject>
290          </screenshot>
291        </figure>
292
293      <helptext external_id="arraybatch.edit" 
294        title="Edit array batch">
295     
296        <variablelist>
297          <varlistentry>
298            <term>
299              <guilabel>Name</guilabel>
300            </term>
301            <listitem>
302              <para>The name of the array batch (required).</para>
303            </listitem>
304          </varlistentry>
305          <varlistentry>
306            <term>
307              <guilabel>Array design</guilabel>
308            </term>
309            <listitem>
310              <para>Array design that is used for the batch.</para>
311            </listitem>
312          </varlistentry>
313          <varlistentry>
314            <term>
315              <guilabel>Print robot</guilabel>
316            </term>
317            <listitem>
318              <para>The print robot that is used.</para>
319            </listitem>
320          </varlistentry>
321          <varlistentry>
322            <term>
323              <guilabel>Protocol</guilabel>
324            </term>
325            <listitem>
326              <para>
327                The printing protocol that was followed when producing the array batch
328              </para>
329            </listitem>
330          </varlistentry>
331          <varlistentry>
332            <term>
333              <guilabel>Description</guilabel>
334            </term>
335            <listitem>
336              <para>
337                Provide other useful information about the array batch in this text
338                area.
339              </para>
340            </listitem>
341          </varlistentry>
342        </variablelist>
343        <para>
344          Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
345          button to abort.
346        </para>
347       
348        <seeother>
349          <other external_id="annotations.edit">Annotations</other>
350          <other external_id="annotations.edit.inerited">Inherit annotations</other>
351        </seeother>
352      </helptext>
353     
354  </sect1>
355
356  <sect1 id="array_lims.arrayslide">
357    <title>Array slides</title>
358    <para>
359      Use
360      <menuchoice>
361        <guimenu>Array LIMS</guimenu>
362        <guimenuitem>Array slides</guimenuitem>
363      </menuchoice>
364      to get to the list page of array slides.
365    </para>
366    <sect2 id="array_lims.arrayslide.create">
367      <title>Creating array slides</title>
368      <para>In BASE, array slides can be created, except the common way, by 2 routes:</para>
369      <variablelist>
370        <varlistentry>
371          <term>from the array batch list page</term>
372          <listitem>
373            <para>
374              Clicking on the
375              <guiicon>
376                <inlinemediaobject>
377                  <imageobject>
378                    <imagedata fileref="figures/add.png" format="PNG" />
379                  </imageobject>
380                </inlinemediaobject>
381              </guiicon>
382              icon in the
383              <guilabel>Slides</guilabel>
384              column for the batch you want to add a slide to. Corresponding button in
385              the view page of a batch is
386              <guibutton>New slide&hellip;</guibutton>
387              .
388            </para>
389          </listitem>
390        </varlistentry>
391        <varlistentry>
392          <term>using a wizard to create multiple slides simultaneously</term>
393          <listitem>
394            <para>
395              This can be started from three different places:
396              <itemizedlist>
397                <listitem>
398                  <para>
399                    array batch list view by clicking on
400                    <guiicon>
401                      <inlinemediaobject>
402                        <imageobject>
403                          <imagedata fileref="figures/new_wizard.png"
404                            format="PNG" />
405                        </imageobject>
406                      </inlinemediaobject>
407                    </guiicon>
408                    in the
409                    <guilabel>Slides</guilabel>
410                    column of the batch that should be used.
411                  </para>
412                </listitem>
413                <listitem>
414                  <para>
415                    Using the
416                    <guibutton>Create slides</guibutton>
417                    in a single item view of an array batch.
418                  </para>
419                </listitem>
420                <listitem>
421                  <para>
422                    In the list page of array slides, using the
423                    <guibutton>Create multiple&hellip;</guibutton>
424                    button
425                  </para>
426                </listitem>
427              </itemizedlist>
428              The wizard is described further down in
429              <xref linkend="array_lims.arrayslide.wizard" />.
430            </para>
431          </listitem>
432        </varlistentry>
433      </variablelist>
434
435      <figure id="write_docbook_doc.figures.arrayslide-single-create">
436        <title>Create new array slide</title>
437        <screenshot>
438          <mediaobject>
439            <imageobject>
440              <imagedata 
441                fileref="figures/arrayslide-single-create.png" format="PNG" />
442            </imageobject>
443          </mediaobject>
444        </screenshot>
445      </figure>
446      <helptext 
447        external_id="arrayslide.edit" 
448        title="Edit array slide">
449      <variablelist>
450        <varlistentry>
451          <term>
452            <guilabel>Name</guilabel>
453          </term>
454          <listitem>
455            <para>The name of the array slide (required).</para>
456          </listitem>
457        </varlistentry>
458        <varlistentry>
459          <term>
460            <guilabel>Barcode</guilabel>
461          </term>
462          <listitem>
463            <para>Does the array slide have a barcode, it can be put here.</para>
464          </listitem>
465        </varlistentry>
466        <varlistentry>
467          <term>
468            <guilabel>Destroyed</guilabel>
469          </term>
470          <listitem>
471            <para>
472              This check-box can be ticked to mark the slide as destroyed, lost or
473              damaged.
474            </para>
475          </listitem>
476        </varlistentry>
477        <varlistentry>
478          <term>
479            <guilabel>Array batch</guilabel>
480          </term>
481          <listitem>
482            <para>Array batch that the slide belongs to (required).</para>
483          </listitem>
484        </varlistentry>
485        <varlistentry>
486          <term>
487            <guilabel>Index</guilabel>
488          </term>
489          <listitem>
490            <para>The index of the array slide in selected array batch.</para>
491          </listitem>
492        </varlistentry>
493        <varlistentry>
494          <term>
495            <guilabel>Description</guilabel>
496          </term>
497          <listitem>
498            <para>
499              Any information useful information about the slide can be in this field.
500            </para>
501          </listitem>
502        </varlistentry>
503      </variablelist>
504      <para>
505        Click on the &gbSave; button to store the information in BASE or on the &gbCancel;
506        button to abort.
507      </para>
508        <seeother>
509          <other external_id="arrayslide.createwizard.1">Create array slides - step 1</other>
510          <other external_id="arrayslide.createwizard.2">Create array slides - step 2</other>
511        </seeother>
512      </helptext>
513    </sect2>
514   
515    <sect2 id="array_lims.arrayslide.wizard">
516        <title>Multiple slides wizard</title>
517        <para>
518          As mentioned above there is an alternative to create one slide at a time if you
519          have many to add. There is a wizard that can help you to create at the most 999
520          slides in one go. The wizard is in two steps:
521        </para>
522       
523          <figure id="array_lims.figures.arrayslide-wizard-step1">
524            <title>Create multiple array slides - step 1</title>
525            <screenshot>
526              <mediaobject>
527                <imageobject>
528                  <imagedata fileref="figures/arrayslide-wizard-step1.png" format="PNG" />
529                </imageobject>
530              </mediaobject>
531            </screenshot>
532          </figure>
533
534          <helptext external_id="arrayslide.createwizard.1" 
535            title="Create array slides - step 1">
536           
537            <para>
538              The first step reminds alot of the normal edit window of an array
539              slide:
540            </para>
541           
542            <variablelist>
543              <varlistentry>
544                <term>
545                  <guilabel>Name</guilabel>
546                </term>
547                <listitem>
548                  <para>
549                    The name prefix of the array slides. Each array slide will be
550                    numbered according to the <emphasis>start at</emphasis> and
551                    <emphasis>pad size</emphasis> settings below.
552                  </para>
553                </listitem>
554              </varlistentry>
555              <varlistentry>
556                <term>
557                  <guilabel>Array batch</guilabel>
558                </term>
559                <listitem>
560                  <para>Array batch that the slides belongs to (required).</para>
561                </listitem>
562              </varlistentry>
563              <varlistentry>
564                <term>
565                  <guilabel>Quantity</guilabel>
566                </term>
567                <listitem>
568                  <para>
569                    Number of slides to create with this wizard
570                    (required and must be between 1 and 999)
571                  </para>
572                </listitem>
573              </varlistentry>
574              <varlistentry>
575                <term>
576                  <guilabel>Start at</guilabel>
577                </term>
578                <listitem>
579                  <para>
580                    The index number to start from when indexing the
581                    name of the slides.
582                  </para>
583                </listitem>
584              </varlistentry>
585              <varlistentry>
586                <term>
587                  <guilabel>Pad size</guilabel>
588                </term>
589                <listitem>
590                  <para>
591                    The index will be filled out with zeros in front to
592                    always have this length.
593                  </para>
594                </listitem>
595              </varlistentry>
596            </variablelist>
597           
598            <para>
599              Click on &gbNext; to move on to the second step of the wizard.
600            </para>
601           
602            <seeother>
603              <other external_id="arrayslide.createwizard.2">Create array slides - step 2</other>
604              <other external_id="arrayslide.edit">Edit array slide</other>
605            </seeother>
606           
607          </helptext>
608         
609         
610          <figure id="array_lims.figures.arrayslide-wizard-step2">
611            <title>Create multiple array slides - step 2</title>
612            <screenshot>
613              <mediaobject>
614                <imageobject>
615                  <imagedata fileref="figures/arrayslide-wizard-step2.png" format="PNG" />
616                </imageobject>
617              </mediaobject>
618            </screenshot>
619          </figure>
620         
621          <helptext external_id="arrayslide.createwizard.2" title="Create array slides - step 2">
622            <para>
623              This step allows the names of the array slides to be adjusted
624              if needed. It is also possible to enter barcodes for each of the
625              new slides. The information can either be filled in one-by-one
626              or by using the "scratchpad" icon
627              <guiicon>
628                <inlinemediaobject>
629                  <imageobject>
630                    <imagedata fileref="figures/paste.png"
631                      format="PNG" />
632                  </imageobject>
633                </inlinemediaobject>
634              </guiicon>. This opens up a larger text window where the names or barcodes
635              can be entered one per line. This can be useful if the information can be
636              pasted from an external source.
637            </para>
638           
639            <seeother>
640              <other external_id="arrayslide.createwizard.1">Create array slides - step 1</other>
641              <other external_id="arrayslide.edit">Edit array slide</other>
642            </seeother>
643           
644            <para>
645              Click on the &gbSave; button to store the information in BASE or on the
646              &gbCancel; button to abort the wizard.
647            </para>
648         
649          </helptext>
650
651    </sect2>
652  </sect1>
653</chapter>
Note: See TracBrowser for help on using the repository browser.