source: trunk/doc/src/docbook/userdoc/reporters.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 Id
File size: 15.0 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 5706 2011-08-23 13:20:30Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Philippe Rocca-Serra, Martin Svensson
9  Copyright (C) 2008 Jari Häkkinen
10 
11  This file is part of BASE - BioArray Software Environment.
12  Available at http://base.thep.lu.se/
13 
14  BASE is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License
16  as published by the Free Software Foundation; either version 3
17  of the License, or (at your option) any later version.
18 
19  BASE is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  GNU General Public License for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with BASE. If not, see <http://www.gnu.org/licenses/>.
26-->
27<chapter id="reporters" chunked="0">
28  <?dbhtml dir="reporters"?>
29  <title>Reporters</title>
30  <sect1 id="reporters.introduction">
31    <title>Introduction</title>
32    <helptext external_id="reporter.view.properties" 
33      title="About reporters">
34    <para>
35      Reporter, a term coined by the MAGE object model refers to
36      spotted DNA sequence on a microarray. Reporters are
37      therefore usually described by a sequence and a series of
38      database identifiers qualifying that sequence. Reporters are
39      generally understood as the thing biologists are interested
40      in when carrying out DNA microarray experiments.
41    </para>
42    <para>
43      In BASE, reporters also refer to Affymetrix Probeset ID but
44      reporters can be used to describe genes, transcripts, exons
45      or any other sequence entity of biological relevance.
46    </para>
47    </helptext>
48  </sect1>
49 
50  <sect1 id="reportertypes">
51    <title>Reporter types</title>
52   
53    <helptext external_id="reportertype.view.properties" 
54      title="About reporter types">
55    <para>
56      <guilabel>Reporter Type</guilabel>
57      allows classification of reporters based on their usage
58      and qualification defined during the array design
59      specification.
60    </para>
61    </helptext>
62   
63    <para>
64      You can manage the reporter types by going to
65      <menuchoice>
66        <guimenu>Administrate</guimenu>
67        <guimenuitem>Types</guimenuitem>
68        <guisubmenu>Reporter types</guisubmenu>
69      </menuchoice>.
70    </para>
71   
72    <figure
73      id="reporterstypes.figures.properties">
74      <title>Reporter type properties</title>
75      <screenshot>
76        <mediaobject>
77          <imageobject>
78            <imagedata
79              fileref="figures/reportertype.png" format="PNG" />
80          </imageobject>
81        </mediaobject>
82      </screenshot>
83    </figure>
84   
85    <helptext external_id="reportertype.edit" 
86      title="Reporter type properties">
87     
88      <variablelist>
89      <varlistentry>
90        <term><guilabel>Name</guilabel></term>
91        <listitem>
92          <para>
93          The name of the reporter type. It is advised to define the name
94          so that it is compatible with the
95          <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html"
96            >MIAME requirements</ulink>
97          and recommendations issues by microarray data
98          repositories. Alternately, the local reporter type
99          could be submitted to those repositories for term
100          inclusion.
101          </para>
102        </listitem>
103      </varlistentry>
104      <varlistentry>
105        <term><guilabel>Description</guilabel></term>
106        <listitem>
107          <para>
108          A description of the reporter type.
109          </para>
110        </listitem>
111      </varlistentry>
112      </variablelist>
113    </helptext>
114   
115  </sect1>
116
117
118  <sect1 id="reporter.manage">
119    <title>Reporters</title>
120   
121    <para>
122      Go to
123      <menuchoice>
124        <guimenu>View</guimenu>
125        <guimenuitem>Reporter</guimenuitem>
126      </menuchoice> to view and manage the reporters.
127    </para>
128   
129    <sect2 id="reporters.import">
130      <title>Import/update reporter from files</title>
131     
132      <para>
133        Reporters are used to represent genes, transcripts,
134        exons and therefore come in their thousands. To solve
135        this problem, BASE relies on
136        <emphasis>Reporter import plug-ins</emphasis>.
137        Those need to be specifically configured to deal with
138        a particular input file format. This input file can be
139        typically be an Axon GAL file or an Affymetrix CSV file
140        which both provide information about reporters and their
141        annotations. See <xref linkend="import_data" />
142        for more information about importing and <xref 
143        linkend="plugins.configuration" />
144        for more information about configuring file formats.
145      </para>
146     
147      <note>
148        <title>Dealing with Affymetrix probesets</title>
149        <para>
150        In BASE, Affymetrix probesets should be treated as reporters.
151        The probeset ID could be stored in both the
152        <guilabel>Name</guilabel> and the <guilabel>External ID</guilabel>
153        fields of the reporter table.
154        Storing the probeset ID should be enough
155        as most analysis tools allow retrieval of updated
156        information based on the probeset ID from
157        web resources.
158        </para>
159        <para>
160          For some Affymetrix chips the associated CSV file does not
161          list all reporters on the actual chip. This will lead to
162          problems in later use of the affected chip types. Simply use
163          the associated CDF file to import the missing probesets into
164          BASE, make sure not to upgrade existing reporters when
165          starting the plug-in.
166        </para>
167      </note>
168     
169    </sect2>
170   
171    <sect2 id="reporters.create">
172      <title>Manual management of reporters</title>
173     
174      <para>
175        Reporters can also be created or edited manually
176        one-by-one. This follows the same pattern as for
177        all other items and is described in general terms
178        in <xref linkend="webclient.items"/>.
179      </para>
180     
181      <sect3 id="reporters.properties">
182        <title>Reporter properties</title>
183       
184        <figure id="reporters.figures.properties">
185          <title>Reporter properties</title>
186          <screenshot>
187            <mediaobject>
188              <imageobject>
189                <imagedata fileref="figures/reporter-1.png" format="PNG" />
190              </imageobject>
191            </mediaobject>
192          </screenshot>
193        </figure>
194       
195        <helptext external_id="reporter.edit" 
196          title="Reporer properties">
197         
198          <para>
199            This tab shows core information that would be
200            common to all BASE instances.
201          </para>
202         
203          <variablelist>
204          <varlistentry>
205            <term><guilabel>Name</guilabel></term>
206            <listitem>
207              <para>
208              The name of the reporter. This is often the same
209              as the <guilabel>External ID</guilabel>.
210              </para>
211            </listitem>
212          </varlistentry>
213          <varlistentry>
214            <term><guilabel>External ID</guilabel></term>
215            <listitem>
216              <para>
217              The external ID of the reporter as it is defined in
218              some database. The ID must be unique within BASE. The
219              external ID is what plug-ins uses to match reporter
220              information found in raw data files, array design files,
221              etc.
222              </para>
223            </listitem>
224          </varlistentry>
225          <varlistentry>
226            <term><guilabel>Type</guilabel></term>
227            <listitem>
228              <para>
229              Optionally select a reporter type.
230              </para>
231            </listitem>
232          </varlistentry>
233          <varlistentry>
234            <term><guilabel>Gene symbol</guilabel></term>
235            <listitem>
236              <para>
237              The gene this reporter represents.
238              </para>
239            </listitem>
240          </varlistentry>
241          </variablelist>
242         
243          <seeother>
244            <other external_id="reporter.view.properties">About reporters</other>
245            <other external_id="reporter.edit.extended">Extended properties</other>
246          </seeother>
247        </helptext>
248      </sect3>
249     
250      <sect3 id="reporters.extended_properties">
251        <title>Extended properties</title>
252       
253        <figure id="reporters.figures.extended_properties">
254          <title>Extended reporter properties</title>
255          <screenshot>
256            <mediaobject>
257              <imageobject>
258                <imagedata fileref="figures/reporter-2.png" format="PNG" />
259              </imageobject>
260            </mediaobject>
261          </screenshot>
262        </figure>
263       
264        <helptext external_id="reporter.edit.extended" 
265          title="Extended reporter properties">
266       
267          <para>
268            Reporters belong to a special class whose properties
269            can be defined and extended by system
270            administrators. This is done by modifying the
271            <filename>extended-properties.xml</filename> file during
272            database configuration or upgrade. All fields on
273            this tab are automatically generated based on this
274            configuration and can be different from one server
275            to the next.     
276            <nohelp>
277            See <xref linkend="installation_upgrade.installation" />
278            and <xref linkend="appendix.extendedproperties" />
279            for more information.
280            </nohelp>
281           
282            <note>
283              <para>
284                It is possible to configure the extended properties
285                so that links to the primary external databases can
286                be made. For example, the <guilabel>Cluster ID</guilabel>
287                is linked to the <ulink 
288                  url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene"
289                  >UniGene database at NCBI</ulink>.
290              </para>
291            </note>
292          </para>
293       
294          <seeother>
295            <other external_id="reporter.edit">Reporter properties</other>
296          </seeother>
297        </helptext>
298      </sect3>
299    </sect2>
300 
301
302    <sect2 id="reporter.delete">
303      <title>Deleting reporters</title>
304     
305      <important>
306        <title>Deleted reporters cannot be restored</title>
307        <para>
308          Reporters are treated differently from other
309          items (e.g biosources or protocols) since they
310          does not use the trashcan mechanism (see
311          <xref linkend="webclient.trashcan" />).
312          The deletion happens immediately and is an unrecoverable
313          event. BASE will always show a warning message which you must
314          confirm before the reporters are deleted.
315        </para>
316      </important>
317     
318      <para>
319        Reporters which has been referenced to from reporter lists, raw data, array
320        designs, plates or any other item cannot be deleted.
321      </para>
322     
323      <sect3 id="reporter.delete.batch">
324        <title>Batch deletion</title>
325        <para>
326          A common problem is to delete reporters that has been accidentally
327          created. The regular web interface is usually no good since it
328          only allows you to delete a limited number of reporters at a time. To solve
329          this problem the reporter import plug-in can be used in delete mode.
330          You can use the same file as you used when importing. Just select
331          the <userinput>delete</userinput> option for the <guilabel>mode</guilabel>
332          parameter in the configuration wizard and continue as usual.
333          If the plug-in is used in delete mode from a reporter list it will
334          only remove the reporters from the reporter list. The reporters are not
335          deleted from the database.
336        </para>
337       
338        <note>
339          <para>
340          It may be a bit confusing to delete things from an import plug-in. But
341          since plug-ins can only belong to one category and we wanted to re-use
342          existing file format definitions this was our only option.
343          </para>
344        </note>
345      </sect3>
346     
347    </sect2>
348
349  </sect1>
350
351  <sect1 id="reporterlists">
352    <title>Reporter lists</title>
353    <para>
354      BASE allows for defining sets of reporters for a
355      particular use, for instance to define a list of
356      reporters to be used on an array. There are several ways to do
357      so:
358    </para>
359    <itemizedlist>
360      <listitem>
361        <para>
362          Use the <guibutton>New reporter list</guibutton> button on the
363          <menuchoice>
364            <guimenu>View</guimenu>
365            <guimenuitem>Reporters</guimenuitem>
366          </menuchoice> page. This creates a reporter list with the current
367          selection or filtered out reporters.
368        </para>
369      </listitem>
370     
371      <listitem>
372        <para>
373          Use the <guibutton>New</guibutton> button on the
374          <menuchoice>
375            <guimenu>View</guimenu>
376            <guimenuitem>Reporter lists</guimenuitem>
377          </menuchoice> page. This creates an initially empty reporter list
378          that can be filled later.
379        </para>
380      </listitem>
381     
382      <listitem>
383        <para>
384          Use the <guibutton>New reporter list</guibutton> button on the
385          <guilabel>Features</guilabel> tab on the single-item view page
386          for an array design. This creates a reporter list with all or some of
387          the reporters used on the array design.
388        </para>
389      </listitem>
390     
391      <listitem>
392        <para>
393          Use the <guibutton>New reporter list</guibutton> button on the
394          <guilabel>Raw data</guilabel> tab on the single-item view page
395          for a raw bioassay. This creates a reporter list with all or some of
396          the reporters used by the raw bioassay.
397        </para>
398      </listitem>
399     
400      <listitem>
401        <para>
402          Use the <guibutton>New reporter list</guibutton> button on the
403          <guilabel>Spot data</guilabel> tab on the single-item view page
404          for a bioassay set in the experiment analysis section.
405          This creates a reporter list with all or some of
406          the reporters used by the current bioassay set.
407        </para>
408      </listitem>
409     
410      <listitem>
411        <para>
412          Use the <guibutton>New reporter list</guibutton> button on the
413          <guilabel>Reporter search</guilabel> tab in experiment explorer.
414          This creates a reporter list with all or some of
415          the reporters used by the current bioassay set.
416        </para>
417      </listitem>
418     
419      </itemizedlist>
420     
421      <figure
422        id="reporterlists.figures.create">
423        <title>
424          The Create reporter list called from
425          the reporters page.
426        </title>
427        <screenshot>
428          <mediaobject>
429            <imageobject>
430              <imagedata fileref="figures/reporterlist-1.png" format="PNG" />
431            </imageobject>
432          </mediaobject>
433        </screenshot>
434      </figure>
435   
436      <helptext external_id="reporterlist.edit" 
437        title="Create reporter list">
438       
439        <variablelist>
440        <varlistentry>
441          <term><guilabel>Name</guilabel></term>
442          <listitem>
443            <para>
444            The name of the reporter list.
445            </para>
446          </listitem>
447        </varlistentry>
448        <varlistentry>
449          <term><guilabel>External ID</guilabel></term>
450          <listitem>
451            <para>
452            An optional external ID. This value is useful,
453            for example, for a tool that automatically
454            updates the reporter list from some external source.
455            It is not used by BASE.
456            </para>
457          </listitem>
458        </varlistentry>
459        <varlistentry>
460          <term><guilabel>Which reporters</guilabel></term>
461          <listitem>
462            <para>
463            Select one of the options for specifying which reporters
464            should be included in the list. This option is only available
465            when creating a new reporter list, not when editing an existing
466            list.
467            </para>
468          </listitem>
469        </varlistentry>
470        <varlistentry>
471          <term><guilabel>Description</guilabel></term>
472          <listitem>
473            <para>
474            A description of the reporter list.
475            </para>
476          </listitem>
477        </varlistentry>
478        </variablelist>
479
480        <tip>
481          <para>
482          To add or remove reporters to the list use the
483          <guilabel>Reporters</guilabel> tab on the single-item
484          view page of a reporter list. This tab lists all
485          reporters in the list and there are functions for
486          removing, adding and importing reporters to the list.
487          </para>
488        </tip>
489
490
491      </helptext>
492
493  </sect1>
494</chapter>
Note: See TracBrowser for help on using the repository browser.