source: trunk/doc/src/docbook/userdoc/reporters.xml @ 3596

<?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: reporters.xml 3596 2007-07-24 12:14:09Z nicklas $
  
  Copyright (C) Authors contributing to this file.
  
  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 2
  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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->
<chapter id="reporters" chunked="0">
  <?dbhtml dir="reporters"?>
  <title>Reporters</title>
  <sect1 id="reporters.introduction">
    <title>Introduction</title>
    <helptext external_id="reporter.view.properties" 
      title="About reporters">
    <para>
      Reporter, a term coined by the MAGE object model refers to
      spotted DNA sequence on a microarray. Reporters are
      therefore usually described by a sequence and a series of
      database identifiers qualifying that sequence. Reporters are
      generally understood as the thing biologists are interested
      in when carrying out DNA microarray experiments.
    </para>
    <para>
      In BASE2, reporters also refer to Affymetrix Probeset ID but
      reporters can be used to describe genes, transcripts, exons
      or any other sequence entity of biological relevance.
    </para>
    </helptext>
  </sect1>
  
  <sect1 id="reportertypes">
    <title>Reporter types</title>
    
    <helptext external_id="reportertype.view.properties" 
      title="About reporter types">
    <para>
      <guilabel>Reporter Type</guilabel>
      allows classification of reporters based on their usage
      and qualification defined during the array design
      specification.
    </para>
    </helptext>
    
    <para>
      You can manage the reporter types by going to
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Types</guimenuitem>
        <guisubmenu>Reporter types</guisubmenu>
      </menuchoice>.
    </para>
    
    <figure
      id="reporterstypes.figures.properties">
      <title>Reporter type properties</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata
              fileref="figures/reportertype.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>
    
    <helptext external_id="reportertype.edit" 
      title="Reporter type properties">
      
      <variablelist>
      <varlistentry>
        <term><guilabel>Name</guilabel></term>
        <listitem>
          <para>
          The name of the reporter type. It is advised to define the name
          so that it is compatible with the
          <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html"
            >MIAME requirements</ulink>
          and recommendations issues by microarray data
          repositories. Alternately, the local reporter type
          could be submitted to those repositories for term
          inclusion.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><guilabel>Description</guilabel></term>
        <listitem>
          <para>
          A description of the reporter type.
          </para>
        </listitem>
      </varlistentry>
      </variablelist>
    </helptext>
    
  </sect1>


  <sect1 id="reporter.manage">
    <title>Reporters</title>
    
    <para>
      Go to
      <menuchoice>
        <guimenu>View</guimenu>
        <guimenuitem>Reporter</guimenuitem>
      </menuchoice> to view and manage the reporters.
    </para>
    
    <sect2 id="reporters.import">
      <title>Import/update reporter from files</title>
      
      <para>
        Reporters are used to represent genes, transcripts,
        exons and therefore come in their thousands. To solve
        this problem, BASE2 relies on
        <emphasis>Reporter import plug-ins</emphasis>.
        Those need to be specifically configured to deal with
        a particular input file format. This input file can be
        typically be an Axon GAL file or an Affymetrix CSV file
        which both provide information about reporters and their
        annotations. See <xref linkend="import_export_data.import" />
        for more information about importing and <xref 
        linkend="plugins.configuration" />
        for more information about configuring file formats.
      </para>
      
      <tip>
        <title>Exchanging plug-in configurations</title>
        <para>
          As for any other plug-in, configuration parameters
          can be saved as an XML file and exchanged with
          another BASE2 instance, thereby reducing
          configuration burden (provided the 2 instances have
          identical <filename>extended-properties.xml</filename> files).
          See <xref linkend="resources.coreplugins" /> for information
          about available configuration files.
        </para>
      </tip>

      <note>
        <title>Dealing with Affymetrix probesets</title>
        <para>
        In BASE2, Affymetrix probesets should be treated as reporters.
        The probeset ID could be stored in both the
        <guilabel>Name</guilabel> and the <guilabel>External ID</guilabel>
        fields of the reporter table.
        Storing the probeset ID should be enough
        as most analysis tools allow retrieval of updated
        information based on the probeset ID from
        web resources.
        </para>
      </note>
      
    </sect2>
    
    <sect2 id="reporters.create">
      <title>Manual management of reporters</title>
      
      <para>
        Reporters can also be created or edited manually
        one-by-one. This follows the same pattern as for 
        all other items and is described in general terms
        in <xref linkend="webclient.items"/>.
      </para>
      
      <sect3 id="reporters.properties">
        <title>Reporter properties</title>
        
        <figure id="reporters.figures.properties">
          <title>Reporter properties</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/reporter-1.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="reporter.edit" 
          title="Reporer properties">
          
          <para>
            This tab shows core information that would be
            common to all BASE instances.
          </para>
          
          <variablelist>
          <varlistentry>
            <term><guilabel>Name</guilabel></term>
            <listitem>
              <para>
              The name of the reporter. This is often the same 
              as the <guilabel>External ID</guilabel>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel>External ID</guilabel></term>
            <listitem>
              <para>
              The external ID of the reporter as it is defined in
              some database. The ID must be unique within BASE. The
              external ID is what plug-ins uses to match reporter 
              information found in raw data files, array design files, 
              etc.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel>Type</guilabel></term>
            <listitem>
              <para>
              Optionally select a reporter type.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guilabel>Gene symbol</guilabel></term>
            <listitem>
              <para>
              The gene this reporter represents.
              </para>
            </listitem>
          </varlistentry>
          </variablelist>
          
          <seeother>
            <other external_id="reporter.view.properties">About reporters</other>
            <other external_id="reporter.edit.extended">Extended properties</other>
          </seeother>
        </helptext>
      </sect3>
      
      <sect3 id="reporters.extended_properties">
        <title>Extended properties</title>
        
        <figure id="reporters.figures.extended_properties">
          <title>Extended reporter properties</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/reporter-2.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </screenshot>
        </figure>
        
        <helptext external_id="reporter.edit.extended" 
          title="Extended reporter properties">
        
          <para>
            Reporters belong to a special class whose properties 
            can be defined and extended by system
            administrators. This is done by modifying the
            <filename>extended-properties.xml</filename> file during 
            database configuration or upgrade. All fields on
            this tab are automatically generated based on this 
            configuration and can be different from one server
            to the next.      
            <nohelp>
            See <xref linkend="installation_upgrade.installation" />
            and <xref linkend="appendix.extendedproperties" />
            for more information.
            </nohelp>
            
            <note>
              <para>
                It is possible to configure the extended properties
                so that links to the primary external databases can
                be made. For example, the <guilabel>Cluster ID</guilabel>
                is linked to the <ulink 
                  url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene"
                  >Unigene database at NCBI</ulink>.
              </para>
            </note>
          </para>
        
          <seeother>
            <other external_id="reporter.edit">Reporter properties</other>
          </seeother>
        </helptext>
      </sect3>
    </sect2>
 

    <sect2 id="reporter.delete">
      <title>Deleting reporters</title>
      
      <important>
        <title>Deleted reporters cannot be restored</title>
        <para>
          Reporters are treated differently from other
          items (e.g biosources or protocols) since they
          does not use the trashcan mechanism (see <xref linkend="trashcan" />).
          The deletion happens immediately and is an unrecoverable
          event. BASE will always show a warning message which you must
          confirm before the reporters are deleted.
        </para>
      </important>
      
      <para>
        Reporters which has been referenced to from reporter lists, raw data, array
        designs, plates or any other item cannot be deleted.
      </para>
      
      <sect3 id="reporter.delete.batch">
        <title>Batch deletion</title>
        <para>
          A common problem is to delete reporters that has been accidentaly
          created. The regular web interface is usually no good since it
          only allows you to select at most 99 reporters at a time. To solve
          this problem the reporter import plug-in can be used in delete mode.
          You can use the same file as you used when importing. Just select
          the <userinput>delete</userinput> option for the <guilabel>mode</guilabel>
          parameter in the configuration wizard and continue as usual. 
          If the plug-in is used in delete mode from a reporter list it will
          only remove the reporters from the reporter list. The reporters are not
          deleted from the database.
        </para>
        
        <note>
          <para>
          It may be a bit confusing to delete things from an import plug-in. But
          since plug-ins can only belong to one category and we wanted to re-use
          existing file format definitions this was our only option.
          </para>
        </note>
      </sect3>
      
    </sect2>

  </sect1>

  <sect1 id="reporterlists">
    <title>Reporter lists</title>
    <para>
      BASE2 allows for defining sets of reporters for a
      particular use, for instance to define a list of
      reporters to be used on an array. There are 2 ways to do
      so:
    </para>
    <orderedlist>
      <listitem>
        <para>
          Use the <guibutton>New reporter list</guibutton> button on the 
          <menuchoice>
            <guimenu>View</guimenu>
            <guimenuitem>Reporters</guimenuitem>
          </menuchoice> page.
        </para>
      </listitem>
      
      <listitem>
        <para>
          Use the <guibutton>New</guibutton> button on the 
          <menuchoice>
            <guimenu>View</guimenu>
            <guimenuitem>Reporter lists</guimenuitem>
          </menuchoice> page.
        </para>
      </listitem>
      </orderedlist>
      
      <figure
        id="reporterlists.figures.create">
        <title>
          The Create reporter list called from
          the reporters page.
        </title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/reporterlist-1.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    
      <helptext external_id="reporterlist.edit" 
        title="Create reporter list">
        
        <variablelist>
        <varlistentry>
          <term><guilabel>Name</guilabel></term>
          <listitem>
            <para>
            The name of the reporter list.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Exernal ID</guilabel></term>
          <listitem>
            <para>
            An optional external ID. This value is useful,
            for example, for a tool that automatically
            updates the reporter list from som external source.
            It is not used by BASE.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Which reporters</guilabel></term>
          <listitem>
            <para>
            Select one of the options for specifying which reporters
            should be included in the list. 
            <note>
              This option is only available when creating a 
              reporter list from the 
              <menuchoice>
                <guimenu>View</guimenu>
                <guimenuitem>Reporters</guimenuitem>
              </menuchoice> page, not when editing 
              an existing list or creating it from the 
              <menuchoice>
                <guimenu>View</guimenu>
                <guimenuitem>Reporter lists</guimenuitem>
              </menuchoice> page.
            </note>
            
            <tip>
              <para>
              To add or remove reporters to the list use the
              <guilabel>Reporters</guilabel> tab on the single-item
              view page of a reporter list. This tab lists all 
              reporters in the list and there are functions for
              removing, adding and importing reporters to the list.
              </para>
            </tip>
            
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><guilabel>Description</guilabel></term>
          <listitem>
            <para>
            A description of the reporter list.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
      </helptext>

  </sect1>
</chapter>