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

Last change on this file since 3403 was 3403, checked in by Nicklas Nordborg, 14 years ago

Fixes #533.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 12.9 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: reporters.xml 3403 2007-05-29 11:26:33Z nicklas $
7 
8  Copyright (C) Authors contributing to this file.
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 2
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 this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28<chapter id="reporters" chunked="0">
29  <?dbhtml dir="reporters"?>
30  <title>Reporters</title>
31  <sect1 id="reporters.introduction">
32    <title>Introduction</title>
33    <helptext external_id="reporter.view.properties" 
34      title="About reporters">
35    <para>
36      Reporter, a term coined by the MAGE object model refers to
37      spotted DNA sequence on a microarray. Reporters are
38      therefore usually described by a sequence and a series of
39      database identifiers qualifying that sequence. Reporters are
40      generally understood as the thing biologists are interested
41      in when carrying out DNA microarray experiments.
42    </para>
43    <para>
44      In BASE2, reporters also refer to Affymetrix Probeset ID but
45      reporters can be used to describe genes, transcripts, exons
46      or any other sequence entity of biological relevance.
47    </para>
48    </helptext>
49  </sect1>
50 
51  <sect1 id="reportertypes">
52    <title>Reporter types</title>
53   
54    <helptext external_id="reportertype.view.properties" 
55      title="About reporter types">
56    <para>
57      <guilabel>Reporter Type</guilabel>
58      allows classification of reporters based on their usage
59      and qualification defined during the array design
60      specification.
61    </para>
62    </helptext>
63   
64    <para>
65      You can manage the reporter types by going to
66      <menuchoice>
67        <guimenu>Administrate</guimenu>
68        <guimenuitem>Types</guimenuitem>
69        <guisubmenu>Reporter types</guisubmenu>
70      </menuchoice>.
71    </para>
72   
73    <figure
74      id="protocols.figures.protocoltype">
75      <title>Reporter type properties</title>
76      <screenshot>
77        <mediaobject>
78          <imageobject>
79            <imagedata
80              fileref="figures/reportertype.png" format="PNG" />
81          </imageobject>
82        </mediaobject>
83      </screenshot>
84    </figure>
85   
86    <helptext external_id="reportertype.edit" 
87      title="Reporter type properties">
88     
89      <variablelist>
90      <varlistentry>
91        <term><guilabel>Name</guilabel></term>
92        <listitem>
93          <para>
94          The name of the reporter type. It is advised to define the name
95          so that it is compatible with the
96          <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html"
97            >MIAME requirements</ulink>
98          and recommendations issues by microarray data
99          repositories. Alternately, the local reporter type
100          could be submitted to those repositories for term
101          inclusion.
102          </para>
103        </listitem>
104      </varlistentry>
105      <varlistentry>
106        <term><guilabel>Description</guilabel></term>
107        <listitem>
108          <para>
109          A description of the reporter type.
110          </para>
111        </listitem>
112      </varlistentry>
113      </variablelist>
114    </helptext>
115   
116  </sect1>
117
118
119  <sect1 id="reporter.manage">
120    <title>Reporters</title>
121   
122    <para>
123      Go to
124      <menuchoice>
125        <guimenu>View</guimenu>
126        <guimenuitem>Reporter</guimenuitem>
127      </menuchoice> to view and manage the reporters.
128    </para>
129   
130    <sect2 id="reporters.import">
131      <title>Import/update reporter from files</title>
132     
133      <para>
134        Reporters are used to represent genes, transcripts,
135        exons and therefore come in their thousands. To solve
136        this problem, BASE2 relies on
137        <emphasis>Reporter import plug-ins</emphasis>.
138        Those need to be specifically configured to deal with
139        a particular input file format. This input file can be
140        typically be an Axon GAL file or an Affymetrix CSV file
141        which both provide information about reporters and their
142        annotations. See <xref linkend="import_export_data.import" />
143        for more information about importing and <xref 
144        linkend="plugins.configuration" />
145        for more information about configuring file formats.
146      </para>
147     
148      <tip>
149        <title>Exchanging plug-in configurations</title>
150        <para>
151          As for any other plug-in, configuration parameters
152          can be saved as an XML file and exchanged with
153          another BASE2 instance, thereby reducing
154          configuration burden (provided the 2 instances have
155          identical <filename>extended-properties.xml</filename> files).
156          See <xref linkend="resources.coreplugins" /> for information
157          about available configuration files.
158        </para>
159      </tip>
160
161      <note>
162        <title>Dealing with Affymetrix probesets</title>
163        <para>
164        In BASE2, Affymetrix probesets should be treated as reporters.
165        The probeset ID could be stored in both the
166        <guilabel>Name</guilabel> and the <guilabel>External ID</guilabel>
167        fields of the reporter table.
168        Storing the probeset ID should be enough
169        as most analysis tools allow retrieval of updated
170        information based on the probeset ID from
171        web resources.
172        </para>
173      </note>
174     
175    </sect2>
176   
177    <sect2 id="reporters.create">
178      <title>Manual management of reporters</title>
179     
180      <para>
181        Reporters can also be created or edited manually
182        one-by-one. This follows the same pattern as for
183        all other items and is described in general terms
184        in <xref linkend="webclient.items"/>.
185      </para>
186     
187      <sect3 id="reporters.properties">
188        <title>Reporter properties</title>
189       
190        <figure id="reporters.figures.properties">
191          <title>Reporter properties</title>
192          <screenshot>
193            <mediaobject>
194              <imageobject>
195                <imagedata fileref="figures/reporter-1.png" format="PNG" />
196              </imageobject>
197            </mediaobject>
198          </screenshot>
199        </figure>
200       
201        <helptext external_id="reporter.edit" 
202          title="Reporer properties">
203         
204          <para>
205            This tab shows core information that would be
206            common to all BASE instances.
207          </para>
208         
209          <variablelist>
210          <varlistentry>
211            <term><guilabel>Name</guilabel></term>
212            <listitem>
213              <para>
214              The name of the reporter. This is often the same
215              as the <guilabel>External ID</guilabel>.
216              </para>
217            </listitem>
218          </varlistentry>
219          <varlistentry>
220            <term><guilabel>External ID</guilabel></term>
221            <listitem>
222              <para>
223              The external ID of the reporter as it is defined in
224              some database. The ID must be unique within BASE. The
225              external ID is what plug-ins uses to match reporter
226              information found in raw data files, array design files,
227              etc.
228              </para>
229            </listitem>
230          </varlistentry>
231          <varlistentry>
232            <term><guilabel>Type</guilabel></term>
233            <listitem>
234              <para>
235              Optionally select a reporter type.
236              </para>
237            </listitem>
238          </varlistentry>
239          <varlistentry>
240            <term><guilabel>Gene symbol</guilabel></term>
241            <listitem>
242              <para>
243              The gene this reporter represents.
244              </para>
245            </listitem>
246          </varlistentry>
247          </variablelist>
248         
249          <seeother>
250            <other external_id="reporter.view.properties">About reporters</other>
251            <other external_id="reporter.edit.extended">Extended properties</other>
252          </seeother>
253        </helptext>
254      </sect3>
255     
256      <sect3 id="reporters.extended_properties">
257        <title>Extended properties</title>
258       
259        <figure id="reporters.figures.extended_properties">
260          <title>Extended reporter properties</title>
261          <screenshot>
262            <mediaobject>
263              <imageobject>
264                <imagedata fileref="figures/reporter-2.png" format="PNG" />
265              </imageobject>
266            </mediaobject>
267          </screenshot>
268        </figure>
269       
270        <helptext external_id="reporter.edit.extended" 
271          title="Extended reporter properties">
272       
273          <para>
274            Reporters belong to a special class whose properties
275            can be defined and extended by system
276            administrators. This is done by modifying the
277            <filename>extended-properties.xml</filename> file during
278            database configuration or upgrade. All fields on
279            this tab are automatically generated based on this
280            configuration and can be different from one server
281            to the next.     
282            <nohelp>
283            See <xref linkend="installation_upgrade.installation" />
284            and <xref linkend="appendix.extendedproperties" />
285            for more information.
286            </nohelp>
287           
288            <note>
289              <para>
290                It is possible to configure the extended properties
291                so that links to the primary external databases can
292                be made. For example, the <guilabel>Cluster ID</guilabel>
293                is linked to the <ulink 
294                  url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene"
295                  >Unigene database at NCBI</ulink>.
296              </para>
297            </note>
298          </para>
299       
300          <seeother>
301            <other external_id="reporter.edit">Reporter properties</other>
302          </seeother>
303        </helptext>
304      </sect3>
305    </sect2>
306 
307
308    <sect2 id="reporter.delete">
309      <title>Deleting reporters</title>
310     
311      <important>
312        <title>Deleted reporters can't be restored</title>
313        <para>
314          Reporters are treated differently from other
315          items (e.g biosources or protocols) since they
316          doesn't use the trashcan mechanism (see <xref linkend="trashcan" />).
317          The deletion happens immediately and is an unrecoverable
318          event. BASE will always show a warning message which you must
319          confirm before the reporters are deleted.
320        </para>
321      </important>
322     
323      <para>
324        Reporters which has been referenced to from raw data, array
325        designs, plates or any other item can't be deleted.
326      </para>
327    </sect2>
328
329  </sect1>
330
331  <sect1 id="reporterlists">
332    <title>Reporter lists</title>
333    <para>
334      BASE2 allows for defining sets of reporters for a
335      particular use, for instance to define a list of
336      reporters to be used on an array. There are 2 ways to do
337      so:
338    </para>
339    <orderedlist>
340      <listitem>
341        <para>
342          Use the <guibutton>New reporter list</guibutton> button on the
343          <menuchoice>
344            <guimenu>View</guimenu>
345            <guimenuitem>Reporters</guimenuitem>
346          </menuchoice> page.
347        </para>
348      </listitem>
349     
350      <listitem>
351        <para>
352          Use the <guibutton>New</guibutton> button on the
353          <menuchoice>
354            <guimenu>View</guimenu>
355            <guimenuitem>Reporter lists</guimenuitem>
356          </menuchoice> page.
357        </para>
358      </listitem>
359      </orderedlist>
360     
361      <figure
362        id="reporterlists.figures.create">
363        <title>
364          The Create reporter list called from
365          the reporters page.
366        </title>
367        <screenshot>
368          <mediaobject>
369            <imageobject>
370              <imagedata fileref="figures/reporterlist-1.png" format="PNG" />
371            </imageobject>
372          </mediaobject>
373        </screenshot>
374      </figure>
375   
376      <helptext external_id="reporterlist.edit" 
377        title="Create reporter list">
378       
379        <variablelist>
380        <varlistentry>
381          <term><guilabel>Name</guilabel></term>
382          <listitem>
383            <para>
384            The name of the reporter list.
385            </para>
386          </listitem>
387        </varlistentry>
388        <varlistentry>
389          <term><guilabel>Exernal ID</guilabel></term>
390          <listitem>
391            <para>
392            An optional external ID. This value is useful,
393            for example, for a tool that automatically
394            updates the reporter list from som external source.
395            It is not used by BASE.
396            </para>
397          </listitem>
398        </varlistentry>
399        <varlistentry>
400          <term><guilabel>Which reporters</guilabel></term>
401          <listitem>
402            <para>
403            Select one of the options for specifying which reporters
404            should be included in the list.
405            <note>
406              This option is only available when creating a
407              reporter list from the
408              <menuchoice>
409                <guimenu>View</guimenu>
410                <guimenuitem>Reporters</guimenuitem>
411              </menuchoice> page, not when editing
412              an existing list or creating it from the
413              <menuchoice>
414                <guimenu>View</guimenu>
415                <guimenuitem>Reporter lists</guimenuitem>
416              </menuchoice> page.
417            </note>
418           
419            <tip>
420              <para>
421              To add or remove reporters to the list use the
422              <guilabel>Reporters</guilabel> tab on the single-item
423              view page of a reporter list. This tab lists all
424              reporters in the list and there are functions for
425              removing, adding and importing reporters to the list.
426              </para>
427            </tip>
428           
429            </para>
430          </listitem>
431        </varlistentry>
432        <varlistentry>
433          <term><guilabel>Description</guilabel></term>
434          <listitem>
435            <para>
436            A description of the reporter list.
437            </para>
438          </listitem>
439        </varlistentry>
440        </variablelist>
441      </helptext>
442
443  </sect1>
444</chapter>
Note: See TracBrowser for help on using the repository browser.