source: trunk/doc/src/docbook/userdoc/platforms.xml @ 5706

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

References #1590: Documentation cleanup

User documentation chapter 10 to 15. Added new chapter about "Item subtypes". Removed sections about protocol types, hardware types and software types. Merged "Hardware" and "Software" into a single chapter.

Added some menu separators in the New annotation type menu.

As usual, screen shots have not yet been updated.

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