source: trunk/doc/src/docbook/user/platforms.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 Date Id
File size: 13.1 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: platforms.xml 5783 2011-10-05 10:34:24Z nicklas $
7 
8  Copyright (C) 2007 Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26<chapter id="platforms" chunked="0">
27  <title>Experimental platforms and data file types</title>
28 
29  <sect1 id="platforms.platform">
30    <title>Platforms</title>
31
32    <helptext external_id="platform.view.properties" title="Platforms">
33    <para>
34      An experimental platform in BASE can be seen as an item
35      representing the set of data file types that are produced
36      or needed by a given experimental setup. For example, the
37      Affymetrix platform (as defined in BASE) uses CEL files for
38      raw data and CDF files for array design information.
39    </para>
40   
41    <para>
42      The concept of a platform is also tightly coupled to the
43      ability to keep data in files instead of importing it to
44      the database. When you have selected a platform for a
45      raw bioassay or an array design, you also know which files
46      you should provide.
47    </para>
48   
49    <para>
50      BASE comes pre-installed with two platforms; A generic platform
51      and the Affymetrix platform. Other platforms, such as Illumina,
52      are available as non-core plug-in packages, see
53      <xref linkend="resources.plugins" />. An administrator may
54      define additional platforms and file types.
55    </para>
56   
57    <seeother>
58      <other external_id="platform.edit">Edit platform</other>
59      <other external_id="datafiletype.view.properties">Data file types</other>
60    </seeother>
61    </helptext> 
62
63
64
65    <para>
66      You can manage platforms going to
67      <menuchoice>
68        <guimenu>Administrate</guimenu>
69        <guimenuitem>Platforms</guimenuitem>
70        <guisubmenu>Experimental platforms</guisubmenu>
71      </menuchoice>.
72    </para>
73   
74    <figure
75      id="platforms.figures.platform">
76      <title>Platform properties</title>
77      <screenshot>
78        <mediaobject>
79          <imageobject>
80            <imagedata
81              fileref="figures/edit_platform.png" format="PNG" />
82          </imageobject>
83        </mediaobject>
84      </screenshot>
85    </figure> 
86   
87    <helptext external_id="platform.edit" 
88      title="Edit platform">
89   
90      <variablelist>
91      <varlistentry>
92        <term><guilabel>Name</guilabel></term>
93        <listitem>
94          <para>
95            The name of the platform
96          </para>
97        </listitem>
98      </varlistentry>
99      <varlistentry>
100        <term><guilabel>External ID</guilabel></term>
101        <listitem>
102          <para>
103            An ID that is used to identify the platform. The ID must
104            be unique and can't be changed once the platform has been
105            created.
106          </para>
107        </listitem>
108      </varlistentry>
109      <varlistentry>
110        <term><guilabel>File-only</guilabel></term>
111        <listitem>
112          <para>
113            If the platform is a file-only platform or not. File-only
114            platforms can't have it's data imported into the database.
115            This option can't be changed once the platform has been created.
116          </para>
117        </listitem>
118      </varlistentry>
119      <varlistentry>
120        <term><guilabel>Raw data type</guilabel></term>
121        <listitem>
122          <para>
123            If you have selected <guilabel>file-only=no</guilabel>, you
124            may select a raw data type. This will lock this platform to the
125            selected raw data type. If you select <guilabel>- any -</guilabel>,
126            raw data of any raw data type can be used.
127            This option can't be changed once the platform has been created.
128          </para>
129        </listitem>
130      </varlistentry>
131      <varlistentry>
132        <term><guilabel>Channels</guilabel></term>
133        <listitem>
134          <para>
135            If you have selected <guilabel>file-only=yes</guilabel>, you
136            must enter the number of channels the platform uses. This information
137            is needed in the analysis module of BASE to create the proper
138            database tables. This option can't be changed once the platform has
139            been created.
140          </para>
141        </listitem>
142      </varlistentry>
143      <varlistentry>
144        <term><guilabel>Description</guilabel></term>
145        <listitem>
146          <para>
147            A description of the platform.
148          </para>
149        </listitem>
150      </varlistentry>
151      </variablelist>
152     
153      <seeother>
154        <other external_id="platform.edit.filetypes">Select data file types</other>
155      </seeother>
156     
157    </helptext> 
158   
159   
160    <figure
161      id="platforms.figures.platformfiletypes">
162      <title>Select data file types</title>
163      <screenshot>
164        <mediaobject>
165          <imageobject>
166            <imagedata
167              fileref="figures/edit_platformfiletypes.png" format="PNG" />
168          </imageobject>
169        </mediaobject>
170      </screenshot>
171    </figure> 
172   
173    <helptext external_id="platform.edit.filetypes" 
174      title="Select data file types">
175   
176      <variablelist>
177      <varlistentry>
178        <term><guilabel>Data file types</guilabel></term>
179        <listitem>
180          <para>
181            This list contains the file types already associated with
182            this platform. An [x] at the end of the name indicates
183            a required file.
184          </para>
185        </listitem>
186      </varlistentry>
187      <varlistentry>
188        <term><guilabel>Required</guilabel></term>
189        <listitem>
190          <para>
191            This checkbox will modify the required flag for the
192            selected file types.
193          </para>
194         
195          <note>
196            <para>
197            The requried flag is not a hard requirement. It is only
198            used for generating warnings when validating an experiment.
199            </para>
200          </note>
201         
202        </listitem>
203      </varlistentry>
204      <varlistentry>
205        <term><guilabel>Add data file types</guilabel></term>
206        <listitem>
207          <para>
208            Opens a popup window that allows you to add more
209            file types to the platform.
210          </para>
211        </listitem>
212      </varlistentry>
213      <varlistentry>
214        <term><guilabel>Remove</guilabel></term>
215        <listitem>
216          <para>
217            Removes the selected file types from the platform.
218          </para>
219        </listitem>
220      </varlistentry>
221      </variablelist>
222     
223      <seeother>
224        <other external_id="datafiletype.view.properties">Data file types</other>
225      </seeother>
226     
227    </helptext>
228   
229  </sect1>
230
231  <sect1 id="platforms.variants">
232    <title>Platform variants</title>
233
234    <para>
235      It is possible for an administrator to define variants of
236      a platform. The main purpose for this is to be able to
237      select additional file types that are only used in some cases.
238      The file types defined by the parent platform are always inherited
239      by the variants.
240    </para>
241   
242    <para>
243      You can create new variants from the single-item view
244      of a platform. This view also has a <guilabel>Variants</guilabel>
245      tab which lists all variants that has been defined for a platform.
246    </para>
247   
248  </sect1>
249
250  <sect1 id="platforms.datafiletypes">
251    <title>Data file types</title>
252   
253    <helptext external_id="datafiletype.view.properties" title="Data file types">
254      <para>
255        Each file type used by a platform must be registered as a
256        <guilabel>data file type</guilabel>. For example, <guilabel>CEL</guilabel>
257        and <guilabel>CDF</guilabel> files are file types used by the <guilabel>Affymetrix</guilabel>
258        platform. There are several purposes of a data file type:
259      </para>
260     
261      <itemizedlist>
262      <listitem>
263        <para>
264        Describe the file type and make it identifiable. Each file type must have
265        a unique ID which makes it possible to find out if a specific file
266        has been added to an item. For example, to find the CEL file of
267        a raw bioassay.
268        </para>
269      </listitem>
270     
271      <listitem>
272        <para>
273        Connect a specific file type with a generic file type. For example,
274        the CEL file is used to store raw data for an experiment. Another
275        platform may use a different file type. Both file types
276        are of the generic type <guilabel>raw data</guilabel>. This makes it possible
277        for client applications or plug-ins to find the raw data for an
278        experiment without actually knowing which file types that are
279        used on various platforms.
280        </para>
281      </listitem>
282     
283      <listitem>
284        <para>
285        Make it possible to validate and extract metadata from attached files.
286        This is done by extensions. Currently, BASE ships
287        with extensions for CEL and CDF files, but the administrator may have installed
288        extensions for other file types. See <xref linkend="extensions_developer.fileset_validator"/> 
289        for more information about creating extensions.
290        </para>
291      </listitem>
292      </itemizedlist>
293     
294      <seeother>
295        <other external_id="datafiletype.edit">Edit data file type</other>
296        <other external_id="platform.view.properties">Platforms</other>
297      </seeother>
298    </helptext>
299   
300    <para>
301      You can manage data file types by going to
302      <menuchoice>
303        <guimenu>Administrate</guimenu>
304        <guimenuitem>Platforms</guimenuitem>
305        <guisubmenu>Data file types</guisubmenu>
306      </menuchoice>.
307    </para>
308   
309    <figure
310      id="platforms.figures.datafiletypes">
311      <title>Data file type properties</title>
312      <screenshot>
313        <mediaobject>
314          <imageobject>
315            <imagedata
316              fileref="figures/edit_datafiletype.png" format="PNG" />
317          </imageobject>
318        </mediaobject>
319      </screenshot>
320    </figure> 
321   
322    <helptext external_id="datafiletype.edit" 
323      title="Edit data file type">
324   
325      <variablelist>
326      <varlistentry>
327        <term><guilabel>Name</guilabel></term>
328        <listitem>
329          <para>
330            The name of the file type.
331          </para>
332        </listitem>
333      </varlistentry>
334      <varlistentry>
335        <term><guilabel>External ID</guilabel></term>
336        <listitem>
337          <para>
338            An ID that is used to identify the file type. The ID must
339            be unique and can't be changed once the file type has been
340            created.
341          </para>
342        </listitem>
343      </varlistentry>
344      <varlistentry>
345        <term><guilabel>Item type</guilabel></term>
346        <listitem>
347          <para>
348            The type of item files of this file type can be
349            attached to. This option can't be changed once the file
350            type has been created.
351          </para>
352        </listitem>
353      </varlistentry>
354      <varlistentry>
355        <term><guilabel>File extension</guilabel></term>
356        <listitem>
357          <para>
358            The commonly used file extension for files of this type.
359            Optional.
360          </para>
361        </listitem>
362      </varlistentry>
363      <varlistentry>
364        <term><guilabel>Generic type</guilabel></term>
365        <listitem>
366          <para>
367            The generic type of data that files of this type
368            contains. For example, CEL files contains raw data and
369            CDF files contains a reporter map (in BASE terms).
370          </para>
371        </listitem>
372      </varlistentry>
373      <varlistentry>
374        <term><guilabel>Description</guilabel></term>
375        <listitem>
376          <para>
377            A description of the file type.
378          </para>
379        </listitem>
380      </varlistentry>
381      </variablelist>   
382
383      <seeother>
384        <other external_id="platform.edit">Edit platform</other>
385        <other external_id="platform.edit.filetypes">Select platform file types</other>
386      </seeother>
387
388    </helptext>     
389
390  </sect1>
391 
392  <sect1 id="platforms.selectfiles">
393    <title>Selecting files for an item</title>
394
395    <para>
396      Selecting files for an item follows the same pattern
397      for all items that supports it. They all have a
398      <guilabel>Data files</guilabel> tab in their edit view.
399      On this tab you can select files for all file types
400      that are defined by the platform or subtype of the item.
401    </para>
402
403    <figure
404      id="platforms.figures.selectfiles">
405      <title>Selecting files for an array design</title>
406      <screenshot>
407        <mediaobject>
408          <imageobject>
409            <imagedata
410              fileref="figures/select_files.png" format="PNG" />
411          </imageobject>
412        </mediaobject>
413      </screenshot>
414    </figure>
415
416    <helptext external_id="datafiles.edit" title="Data files">
417      <para>
418      The list contains all file types that are defined by by the platform or subtype that
419      is selected on the <guilabel>Properties</guilabel>
420      tab. Use the &gbBrowse; or <guibutton>Add</guibutton> icons to select files from
421      the file manager. Note that for some file types only a single file can be selected,
422      but for other file types multiple files are allowed. The dropdown list contains
423      recently used files as well as an option to clear the selected file.
424      </para>
425     
426      <variablelist>
427      <varlistentry>
428        <term><guilabel>Validate files</guilabel></term>
429        <listitem>
430          <para>
431            Mark this checkbox if you want to validate and extract metadata
432            from the selected files. The checkbox is automatically checked
433            if changes are made.
434          </para>
435        </listitem>
436      </varlistentry>
437      </variablelist>
438     
439      <note>
440        <para>
441          Validation and metadata extraction is performed by extensions.
442          The checkbox is only visible if there is at least one
443          installed extension that supports validation of the
444          current file types.
445        </para>
446      </note>
447     
448    </helptext>
449  </sect1>
450
451</chapter>
Note: See TracBrowser for help on using the repository browser.