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

Last change on this file since 3394 was 3394, checked in by Martin Svensson, 14 years ago

Replaced the most common guibutton:s with entities

  • 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 3394 2007-05-28 11:23:40Z martin $
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">
29<?dbhtml dir="reporters"?>
30 <title>Reporters</title>
31 <sect1 id="reporters.introduction">
32  <title>Introduction</title>
33  <para>Reporter, a term coined by the MAGE object model refers to spotted DNA sequence on a
34   microarray. Reporters are therefore usually described by a sequence and a series of database
35   identifiers qualifying that sequence. Reporters are generally understood as the thing biologists
36   are interested in when carrying out DNA microarray experiments.</para>
37  <para>In BASE2, Reporters also refer to Affymetrix Probeset ID but Reporters can be used to
38   describe genes, transcripts, exons or any other sequence entity of biological relevance. </para>
39 </sect1>
40 <sect1 id="reporters.manage">
41  <title>Managing Reporters</title>
42  <para> </para>
43  <sect2 id="reporters.manage.typecreate">
44   <title>Creating Reporter Types</title>
45   <para><guilabel>Reporter Type</guilabel> allows classification of reporters based on their usage
46    and qualification defined during the array design specification. To create a Reporter Type,</para>
47   <para>Go To <menuchoice>
48     <guimenu>Administrate</guimenu>
49     <guimenuitem>Types</guimenuitem>
50     <guisubmenu>Reporter Type</guisubmenu>
51    </menuchoice>
52   </para>
53   <para> Click on &gbNew;. </para>
54   <para>A 'Create' pop-up window opens and allow to fill in <guilabel>Name</guilabel> and
55     <guilabel>Description</guilabel>
56   </para>
57   <important>
58    <para>It is advised to define the Reporter Type <guilabel>Name</guilabel> attribute so that it
59     is compatible with the <ulink url="http://www.mged.org/Workgroups/MIAME/miame.html">MIAME
60      requirements</ulink> and recommendations issues by microarray data repositories. Alternately,
61     the local reporter type could be submitted to those repositories for term inclusion.</para>
62   </important>
63   <figure id="write_docbook_doc.figures.reportertype">
64    <title>The Reporter Type Create Window</title>
65    <screenshot>
66    <mediaobject>
67     <imageobject>
68      <imagedata contentwidth="7cm" width="7cm" fileref="figures/reportertype.png" format="PNG"/>
69     </imageobject>
70    </mediaobject>
71   </screenshot>
72   </figure>
73   <para> One can classically follow the classification between negative control, positive control
74    and experimental for simplificity. </para>
75  </sect2>
76  <sect2 id="reporters.manage.create">
77   <title>Creating Reporters</title>
78   <para>Go to <menuchoice>
79     <guimenu>View</guimenu>
80     <guimenuitem>Reporter</guimenuitem>
81    </menuchoice>
82   </para>
83   <para>Click on &gbNew;. </para>
84   <para> A 'Create' pop-up window opens, it contains 2 tabs: <guilabel>Reporter</guilabel> and
85     <guilabel>Extended properties</guilabel>. </para>
86   <itemizedlist>
87    <listitem>
88     <para>
89      <guilabel>Reporter</guilabel>
90     </para>
91     <para> This tab shows core information that would be common to all base2 instances. Two
92      mandatory information fields have to be filled in: <guilabel>Name</guilabel> and
93       <guilabel>External ID</guilabel> e.g. a database identifier. If one requires additional and
94      more advanced information about the Reporter, the extended properties tab should be used. </para>
95     <figure id="write_docbook_doc.figures.reporter-1">
96      <title>The Reporter tab in the Reporter Create Window</title>
97      <screenshot>
98      <mediaobject>
99       <imageobject>
100        <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-1.png" format="PNG"/>
101       </imageobject>
102      </mediaobject>
103     </screenshot>
104     </figure>
105    </listitem>
106    <listitem>
107     <para>
108      <guilabel>Extended properties</guilabel>
109     </para>
110     <para>In BASE2, the Reporter Items belong to a special class whose properties used to qualify
111      them can be defined and extended by system administrators. This is done by modifying the
112      'extended-properties.xml' file during database configuration or upgrade. The file can be found
113      under <filename class="directory">
114      \\apache-tomcat-5.5.15\webapps\base\WEB-INF\classes</filename>. </para>
115     <important>
116      <para> For more information about database configuration and upgrade process, please refer to
117        <xref linkend="installation_upgrade.installation"/>. This allow storing of just the right
118       amount of information. </para>
119     </important>
120     <para> This tab displays all kind of reporter properties as defined in the extended_properties </para>
121     <figure id="write_docbook_doc.figures.reporter-2">
122      <title>The extended properties tab from the Reporter Create Window</title>
123      <screenshot>
124      <mediaobject>
125       <imageobject>
126        <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-2.png" format="PNG"/>
127       </imageobject>
128      </mediaobject>
129     </screenshot>
130     </figure>
131    </listitem>
132   </itemizedlist>
133   <para>Click on the <inlinemediaobject>
134     <imageobject>
135      <imagedata fileref="figures/save.gif" format="GIF"/>
136     </imageobject>
137    </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject>
138     <imageobject>
139      <imagedata fileref="figures/cancel.gif" format="GIF"/>
140     </imageobject>
141    </inlinemediaobject> button to abort. </para>
142  </sect2>
143
144  <sect2 id="reporter.manage.viewedit">
145   <title>Viewing/Editing Reporters</title>
146   <itemizedlist>
147    <listitem>
148     <para> Press and hold one of the <keycap>CTRL</keycap>, <keycap>ALT</keycap> or
149      <keycap>SHIFT</keycap> keys while clicking on the name of a Reporter Item, which is a live
150      link. </para>
151    </listitem>
152    <listitem>
153     <para> Alternately, navigating to the Reporter Item View, one can hit the
154       &gbEdit; to performed the task.</para>
155     <para>In both cases, an Edit pop-up windows opens. It is essentially identical to a Create
156      window and allows updating information about a particular ArraySlide item stored in BASE2</para>
157     <figure id="write_docbook_doc.figures.reporter-itemview">
158      <title>Reporter Item View</title>
159      <screenshot>
160       <mediaobject>
161        <imageobject>
162         <imagedata contentwidth="10cm" width="10cm" fileref="figures/reporter-itemview.png" format="PNG"/>
163        </imageobject>
164       </mediaobject>
165      </screenshot>
166     </figure>
167    </listitem>
168
169    <listitem>
170     <para>From the Reporter item View, note the <guilabel>extended properties</guilabel> section
171      which displays biological information and cross-references to external databases. Depending on
172      the configuration of the extended properties file, backlinks to primary databases can be
173      established. In the above picture, note the hyperlinks to <guilabel>OMIM</guilabel> and
174      Unigene <guilabel>Cluster ID</guilabel></para>
175    </listitem>
176   </itemizedlist>
177  </sect2>
178
179  <sect2 id="reporter.manage.delete">
180   <title>Deleting Reporters</title>
181   <para>In BASE2, Reporters are treated differently from other items (e.g BioSources or Protocols).</para>
182   <para>Deleting Reporters from BASE2 does not mark those items for deletion as for other BASE2
183    items and do not rely on the Trashcan mechanism.</para>
184   <important>
185    <para> This specific handling of Reporters means that deletion events are unrecoverable.
186     Therefore, pressing the &gbDelete; button will always prompt for a
187     confirmation message as illustrated below. </para>
188
189    <figure id="write_docbook_doc.figures.reporter-delele-msg">
190     <title>The Final Warning message when attempting to delete Reporters</title>
191     <screenshot>
192    <mediaobject>
193     <imageobject>
194      <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporter-delete-msg.png" format="PNG"/>
195     </imageobject>
196    </mediaobject>
197   </screenshot>
198    </figure>
199   </important>
200   <para> Select one or more reporters and click &gbDelete; button in the menu
201    bar. </para>
202  </sect2>
203  <sect2 id="reporter.import">
204   <title>Importing Reporters from files</title>
205   <para> Reporters are used to represent genes, transcripts, exons and therefore come in their
206    thousands. To solve this problem, BASE2 relies on <guilabel>Reporter import plugins</guilabel>.
207    Those need to be specifically configured to deal with a particular input file. This input file
208    can be typically be an Axon gal file which is a tab delimited file providing information about
209    Reporters and their annotations. </para>
210
211   <tip>
212    <para>As for any other plugin, configuration parameters can be saved as an xml file and
213     exchanged with another BASE2 instance, thereby reducing configuration burden (provided the 2
214     instances have identical extended properties xml files). </para>
215   </tip>
216
217   <para> Dealing with Affymetrix Probesets: </para>
218   <para> In BASE2, Affymetrix Probesets (when they exist) should be treated as Reporters.</para>
219   <para> The Affymetrix Probeset ID could be stored in both the name and the reporter external id
220    fields of the reporter table.</para>
221   <tip>
222    <para> Note that Affymetrix serves files containing Annotation about the Probesets ids from the
223     NetAffx web site. A plugin configuration can be defined to upload these files directly into the
224     Reporter table provided it has been modified to accomodate the relevant information. In order
225     to be able to deal with the Affymetrix NetAffx native files (<ulink
226      url="http://www.affymetrix.com/Auth/analysis/downloads/na22/ivt/HG-U133A_2.na22.annot.csv.zip/"
227      >Affymetrix HG-133A_2 annotations in csv format</ulink>) one would have to select the
228     separator as <guilabel>comma between "</guilabel> in order to avoid splitting on 'comma'
229     present in the Affymetrix annotation file, an event that would alter the import. </para>
230   </tip>
231
232   <tip>
233    <para>Storing the Affymetrix Probeset ID should be enough as most analysis tools allow retrieval
234     of updated information based on the Affymetrix probeset id from web resources. </para>
235   </tip>
236
237  </sect2>
238
239  <sect2 id="reporterlist.create">
240   <title>Creating List of Reporters</title>
241   <para> BASE2 allows for defining sets of reporters for a particular use, for instance to define a
242    list of reporters to be used on an array. There are 2 ways to do so: </para>
243   <orderedlist>
244    <listitem>
245     <para>From the Reporter ListView page:</para>
246     <para>Click on the <guibutton>New Reporter List</guibutton> button.</para>
247     <para/>
248     <figure id="write_docbook_doc.figures.reporterlist-1">
249      <title>The ReporterList Create Window called from the Reporter page</title>
250      <screenshot>
251      <mediaobject>
252       <imageobject>
253        <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporterlist-1.png" format="PNG"/>
254       </imageobject>
255      </mediaobject>
256     </screenshot>
257     </figure>
258    </listitem>
259    <listitem>
260     <para>From View Menu:</para>
261     <para>Go to <menuchoice>
262       <guimenu>View</guimenu>
263       <guimenuitem>Reporter List</guimenuitem>
264      </menuchoice>
265     </para>
266     <para> Click on &gbNew; button from the ReporterList ListView </para>
267     <para> A 'Create' pop-up window opens allowing to fill-in Name and a short text description of
268      the newly created Reporter list </para>
269     <figure id="write_docbook_doc.figures.reporterlist-2">
270      <title>The ReporterList Create Window called from the ReporterList page</title>
271      <screenshot>
272      <mediaobject>
273       <imageobject>
274        <imagedata contentwidth="7cm" width="7cm" fileref="figures/reporterlist-2.png" format="PNG"/>
275       </imageobject>
276      </mediaobject>
277     </screenshot>
278     </figure>
279    </listitem>
280   </orderedlist>
281   <para>Click on the <inlinemediaobject>
282     <imageobject>
283      <imagedata fileref="figures/save.gif" format="GIF"/>
284     </imageobject>
285    </inlinemediaobject> Save button to store the information in BASE2 or on the <inlinemediaobject>
286     <imageobject>
287      <imagedata fileref="figures/cancel.gif" format="GIF"/>
288     </imageobject>
289    </inlinemediaobject> button to abort. </para>
290  </sect2>
291 </sect1>
292</chapter>
Note: See TracBrowser for help on using the repository browser.