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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: platforms.xml 5706 2011-08-23 13:20:30Z nicklas $
  
  Copyright (C) 2007 Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->
<chapter id="platforms" chunked="0">
  <?dbhtml dir="platforms"?>
  <title>Experimental platforms and data file types</title>
  
  <sect1 id="platforms.platform">
    <title>Platforms</title>

    <helptext external_id="platform.view.properties" title="Platforms">
    <para>
      An experimental platform in BASE can be seen as an item 
      representing the set of data file types that are produced
      or needed by a given experimental setup. For example, the
      Affymetrix platform (as defined in BASE) uses CEL files for 
      raw data and CDF files for array design information.
    </para>
    
    <para>
      The concept of a platform is also tightly coupled to the
      ability to keep data in files instead of importing it to 
      the database. When you have selected a platform for a
      raw bioassay or an array design, you also know which files
      you should provide.
    </para>
    
    <para>
      BASE comes pre-installed with two platforms; A generic platform
      and the Affymetrix platform. Other platforms, such as Illumina,
      are available as non-core plug-in packages, see
      <xref linkend="resources.plugins" />. An administrator may
      define additional platforms and file types.
    </para>
    
    <seeother>
      <other external_id="platform.edit">Edit platform</other>
      <other external_id="datafiletype.view.properties">Data file types</other>
    </seeother>
    </helptext> 



    <para>
      You can manage platforms going to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Platforms</guimenuitem>
        <guisubmenu>Experimental platforms</guisubmenu>
      </menuchoice>.
    </para>
    
    <figure
      id="platforms.figures.platform">
      <title>Platform properties</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata
              fileref="figures/edit_platform.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
    
    <helptext external_id="platform.edit" 
      title="Edit platform">
    
      <variablelist>
      <varlistentry>
        <term><guilabel>Name</guilabel></term>
        <listitem>
          <para>
            The name of the platform
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>External ID</guilabel></term>
        <listitem>
          <para>
            An ID that is used to identify the platform. The ID must
            be unique and can't be changed once the platform has been
            created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>File-only</guilabel></term>
        <listitem>
          <para>
            If the platform is a file-only platform or not. File-only
            platforms can't have it's data imported into the database.
            This option can't be changed once the platform has been created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Raw data type</guilabel></term>
        <listitem>
          <para>
            If you have selected <guilabel>file-only=no</guilabel>, you
            may select a raw data type. This will lock this platform to the
            selected raw data type. If you select <guilabel>- any -</guilabel>,
            raw data of any raw data type can be used. 
            This option can't be changed once the platform has been created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Channels</guilabel></term>
        <listitem>
          <para>
            If you have selected <guilabel>file-only=yes</guilabel>, you
            must enter the number of channels the platform uses. This information
            is needed in the analysis module of BASE to create the proper
            database tables. This option can't be changed once the platform has
            been created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Description</guilabel></term>
        <listitem>
          <para>
            A description of the platform.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
      
      <seeother>
        <other external_id="platform.edit.filetypes">Select data file types</other>
      </seeother>
      
    </helptext> 
    
    
    <figure
      id="platforms.figures.platformfiletypes">
      <title>Select data file types</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata
              fileref="figures/edit_platformfiletypes.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
    
    <helptext external_id="platform.edit.filetypes" 
      title="Select data file types">
    
      <variablelist>
      <varlistentry>
        <term><guilabel>Data file types</guilabel></term>
        <listitem>
          <para>
            This list contains the file types already associated with
            this platform. An [x] at the end of the name indicates 
            a required file.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Required</guilabel></term>
        <listitem>
          <para>
            This checkbox will modify the required flag for the
            selected file types.
          </para>
          
          <note>
            <para>
            The requried flag is not a hard requirement. It is only
            used for generating warnings when validating an experiment.
            </para>
          </note>
          
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Add data file types</guilabel></term>
        <listitem>
          <para>
            Opens a popup window that allows you to add more
            file types to the platform.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Remove</guilabel></term>
        <listitem>
          <para>
            Removes the selected file types from the platform.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
      
      <seeother>
        <other external_id="datafiletype.view.properties">Data file types</other>
      </seeother>
      
    </helptext>
    
    <sect2 id="platforms.variants">
      <title>Platform variants</title>

      <para>
        It is possible for an administrator to define variants of
        a platform. The main purpose for this is to be able to 
        select additional file types that are only used in some cases.
        The file types defined by the parent platform are always inherited
        by the variants.
      </para>
      
      <para>
        You can create new variants from the single-item view
        of a platform. This view also has a <guilabel>Variants</guilabel>
        tab which lists all variants that has been defined for a platform.
      </para>
      
    </sect2>
    
  </sect1>

  <sect1 id="platforms.datafiletypes">
    <title>Data file types</title>
    
    <helptext external_id="datafiletype.view.properties" title="Data file types">
      <para>
        Each file type used by a platform must be registered as a 
        <guilabel>data file type</guilabel>. For example, <guilabel>CEL</guilabel>
        and <guilabel>CDF</guilabel> files are file types used by the <guilabel>Affymetrix</guilabel>
        platform. There are several purposes of a data file type:
      </para>
      
      <itemizedlist>
      <listitem>
        <para>
        Describe the file type and make it identifiable. Each file type must have
        a unique ID which makes it possible to find out if a specific file
        has been added to an item. For example, to find the CEL file of
        a raw bioassay.
        </para>
      </listitem>
      
      <listitem>
        <para>
        Connect a specific file type with a generic file type. For example,
        the CEL file is used to store raw data for an experiment. Another
        platform may use a different file type. Both file types
        are of the generic type <guilabel>raw data</guilabel>. This makes it possible
        for client applications or plug-ins to find the raw data for an
        experiment without actually knowing which file types that are
        used on various platforms.
        </para>
      </listitem>
      
      <listitem>
        <para>
        Make it possible to validate and extract metadata from attached files.
        This is done by extensions. Currently, BASE ships 
        with extensions for CEL and CDF files, but the administrator may have installed
        extensions for other file types. See <xref linkend="extensions_developer.fileset_validator"/> 
        for more information about creating extensions.
        </para>
      </listitem>
      </itemizedlist>
      
      <seeother>
        <other external_id="datafiletype.edit">Edit data file type</other>
        <other external_id="platform.view.properties">Platforms</other>
      </seeother>
    </helptext>
    
    <para>
      You can manage data file types by going to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Platforms</guimenuitem>
        <guisubmenu>Data file types</guisubmenu>
      </menuchoice>.
    </para>
    
    <figure
      id="platforms.figures.datafiletypes">
      <title>Data file type properties</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata
              fileref="figures/edit_datafiletype.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure> 
    
    <helptext external_id="datafiletype.edit" 
      title="Edit data file type">
    
      <variablelist>
      <varlistentry>
        <term><guilabel>Name</guilabel></term>
        <listitem>
          <para>
            The name of the file type.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>External ID</guilabel></term>
        <listitem>
          <para>
            An ID that is used to identify the file type. The ID must
            be unique and can't be changed once the file type has been
            created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Item type</guilabel></term>
        <listitem>
          <para>
            The type of item files of this file type can be
            attached to. This option can't be changed once the file
            type has been created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>File extension</guilabel></term>
        <listitem>
          <para>
            The commonly used file extension for files of this type.
            Optional.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Generic type</guilabel></term>
        <listitem>
          <para>
            The generic type of data that files of this type
            contains. For example, CEL files contains raw data and
            CDF files contains a reporter map (in BASE terms).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Description</guilabel></term>
        <listitem>
          <para>
            A description of the file type.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>   

      <seeother>
        <other external_id="platform.edit">Edit platform</other>
        <other external_id="platform.edit.filetypes">Select platform file types</other>
      </seeother>

    </helptext>     

    <helptext external_id="datafiles.edit" title="Data files" webonly="1">
      <para>
      On this tab you can select files for each of the file types
      defined by the platform you selected on the <guilabel>Properties</guilabel>
      tab. You may enter the path manually for each file or you can use the
      &gbBrowse; button to select a file from the file manager.
      </para>
      
      <variablelist>
      <varlistentry>
        <term><guilabel>Validate</guilabel></term>
        <listitem>
          <para>
            Mark this checkbox if you want to validate and extract metadata
            from the selected files. The checkbox is automatically checked 
            if you remove or select a different file. 
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
      
      <note>
        <para>
          Validation and metadata extraction is performed by extensions.
          The checkbox is only visible if there is at least one 
          installed extension that supports validation of the
          current file types.
        </para>
      </note>
      
    </helptext>

  </sect1>

</chapter>