source: trunk/doc/src/docbook/userdoc/experiments.xml @ 3318

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

Split 'Experiments and analysis' into several files.
Wrote 'Scans and images' section and part of 'Raw bioassays' section.

File size: 13.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 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: experiments_analysis.xml 3308 2007-05-08 12:34:07Z 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
29<sect1 id="experiments_analysis.experiments">
30  <title>Experiments</title>
31  <para>TODO</para>
32
33  <sect2 id="experiments_analysis.experiment.properties">
34    <title>Experiment properties</title>
35   
36    <para>TODO</para>
37   
38  </sect2>
39 
40  <sect2 id="experiments_analysis.experiment.overview">
41    <title>Experiment overview</title>
42   
43    <para>
44      With the <guilabel>Experiment overview</guilabel> 
45      function you can get an overview of all hybridizations,
46      extracts, samples, annotations, etc. used in an
47      experiment. The overview includes a lot of checks
48      that validates your experimental setup for missing
49      or possibly incorrect information.
50    </para>
51   
52    <para>
53      You can access the overview of an experiment by navigating
54      to the single-item view of the experiment you are interested in.
55      Then, switch to the <guilabel>Overview</guilabel> tab that
56      is present on that page. Here is an example of what is displayed:
57    </para>
58   
59    <figure id="experiments_analysis.figures.experimentoverview">
60      <title>The experiment overview</title>
61      <screenshot>
62        <mediaobject>
63          <imageobject><imagedata 
64            fileref="figures/experiment_overview.png" format="PNG"
65            /></imageobject>
66        </mediaobject>
67      </screenshot>
68    </figure>
69   
70    <helptext external_id="experiment.overview " 
71      title="Experiment overview">
72    <para>
73      The page is divided into three sections:
74    </para>
75   
76    <itemizedlist>
77      <listitem>
78        <para>
79        To the left is a tree displaying all items
80        in the experiment and how they are linked to
81        each other.
82        </para>
83      </listitem>
84     
85      <listitem>
86        <para>
87        The lower right shows a list of warnings and error
88        messages that was found when validating the experiment.
89        <nohelp>
90        In the example you can see that we have failed to
91        specify a value for the <guilabel>Temperature</guilabel>
92        protocol parameter for one of the samples.
93        </nohelp>
94        </para>
95      </listitem>
96       
97      <listitem>
98        <para>
99          The upper right shows information about the
100          currently selected item in the tree. This part also
101          contains more information errors or warnings for this
102          item. It may also present you with one or more suggestions
103          about how to fix the problem and with a link that
104          takes you to the most probable location where you can fix
105          the error or warning.
106        </para>
107       
108        <note>
109          <title>No links?</title>
110          If you don't have permission to change things no links
111          will be shown.
112        </note>
113       
114      </listitem>
115       
116    </itemizedlist>
117   
118    <seeother>
119      <other external_id="experiment.overview.validationoptions"
120        >Validation options</other>
121      <other external_id="experiment.overview.fixfailures"
122        >How to fix validation failures</other>
123    </seeother>
124   
125    </helptext>
126   
127    <sect3 id="experiments_analysis.validationoptions">
128      <title>Validation options</title>
129      <para>
130        Click on the <guibutton>Validation options</guibutton>
131        button in the toolbar to open the <guilabel>Validation
132        options</guilabel> dialog.
133      </para>
134     
135      <figure id="experiments_analysis.figures.validationoptions">
136        <title>Validation options</title>
137        <screenshot>
138          <mediaobject>
139            <imageobject><imagedata 
140              fileref="figures/validation_options.png" format="PNG"
141              /></imageobject>
142          </mediaobject>
143        </screenshot>
144      </figure>         
145     
146      <helptext external_id="experiment.overview.validationoptions" 
147        title="Validation options">
148        <para>
149          The validation procedure is highly
150          configurable and you can select what you want to
151          ignore, or something should be displayed as an error
152          or warning.
153        </para>
154       
155        <variablelist>
156          <varlistentry>
157            <term>
158            <indexterm><primary>Presets</primary><secondary>experiment validation</secondary></indexterm>
159            <guilabel>Presets</guilabel></term>
160            <listitem>
161              <para>
162              The list contains predefined and
163              user defined validation options.
164              Use the <guibutton>Save as&hellip;</guibutton>
165              button to save the current options as a user defined
166              preset. The <guibutton>Remove&hellip;</guibutton>
167              button is used to remove the currently selected
168              preset. Predefined presets can't be deleted.
169              </para>
170            </listitem>
171          </varlistentry>
172         
173          <varlistentry>
174            <term><guilabel>Project defaults</guilabel></term>
175            <listitem>
176              <para>
177              The options in this section are used to check
178              if your experiment uses the same values as set
179              by the project default values of the currently active
180              project<nohelp>
181              (see <xref linkend="project_permission.projects" />)</nohelp>.
182              If no project is active or if the active project doesn't
183              have default values these options are ignored.
184              </para>
185            </listitem>
186           
187          </varlistentry>
188         
189          <varlistentry>
190            <term><guilabel>Missing items</guilabel></term>
191            <listitem>
192              <para>
193              The options in this section are used to check if
194              you have specified values for optional items.
195              For example, there is an option that warns you if
196              you havn't specified a protocol.
197              </para>
198            </listitem>
199          </varlistentry>
200         
201          <varlistentry>
202            <term><guilabel>Annotations</guilabel></term>
203            <listitem>
204              <para>
205              The options in this section are used to check
206              problems related to annotations. The most
207              important ones are listed here:
208              </para>
209             
210              <itemizedlist>
211              <listitem>
212                <simpara>
213                <emphasis>Missing MIAME annotation value</emphasis>:
214                Checks that you have specified values
215                for all annotations marked as
216                <guilabel>Required for MIAME</guilabel>.
217                </simpara>
218              </listitem>
219             
220              <listitem>
221                <simpara>
222                <emphasis>Missing factor value</emphasis>:
223                Checks that you have specified values for
224                all annotations used as experimental factors in
225                the experiment.
226                </simpara>
227              </listitem>
228             
229              <listitem>
230                <simpara>
231                <emphasis>Missing parameter value</emphasis>:
232                Checks that you have specified values
233                for all protocol parameters.
234                </simpara>
235              </listitem>
236
237              <listitem>
238                <simpara>
239                <emphasis>Annotation is protocol parameter</emphasis>:
240                Checks if an item has been annotated with a
241                an annotation that is actually a protocol parameter.
242                </simpara>
243              </listitem>
244
245              <listitem>
246                <simpara>
247                <emphasis>Annotation has invalid value</emphasis>:
248                Checks if annotation values are correct with
249                respect to the rules given by the annotation type.
250                This might include numeric values that are outside
251                the valid range, or values not in the list
252                of allows values for an enumerated annotation type.
253                </simpara>
254              </listitem>
255
256              <listitem>
257                <simpara>
258                <emphasis>Inheriting annotation from non-parent</emphasis>:
259                Checks if inherited annotations really comes from a
260                parent item. This might happen if you rearrange
261                parent-child relationship because you found that
262                they were incorrectly linked.
263                </simpara>
264              </listitem>
265              </itemizedlist>
266             
267           
268            </listitem>
269          </varlistentry>
270         
271          <varlistentry>
272            <term><guilabel>Denied access</guilabel></term>
273            <listitem>
274              <para>
275              The options in this section are used to
276              check if you don't have access (read permission)
277              to an item in the experiment hierarchy. If this
278              happens the validation can't proceed in that branch.
279              This might mask other validation problems.
280              </para>
281            </listitem>
282          </varlistentry>
283         
284          <varlistentry>
285            <term><guilabel>Other</guilabel></term>
286            <listitem>
287              <para>
288              This section collects options that doesn't fit
289              into any of the other sections. The most
290              important options are:
291              </para>
292             
293              <itemizedlist>
294                <listitem>
295                  <simpara>
296                  <emphasis>Array deign mismatch</emphasis>:
297                  Checks if the array design specified for
298                  a raw bioassay is the same array design
299                  specified for the hybridization.
300                  </simpara>
301                </listitem>
302               
303                <listitem>
304                  <simpara>
305                  <emphasis>Multiple array designs</emphasis>:
306                  Checks if all raw bioassays use the
307                  same array design or not.
308                  </simpara>
309                </listitem>
310             
311                <listitem>
312                  <simpara>
313                  <emphasis>Incorrect number of labled extracts</emphasis>:
314                  Checks if the number of labeled extracts
315                  match the number of channels for the experiment.
316                  </simpara>
317                </listitem>
318
319                <listitem>
320                  <simpara>
321                  <emphasis>Non-unique name</emphasis>:
322                  Checks if two items of the same type
323                  have the same name. A unique name if important
324                  when exporting data in Tab2Mage format.
325                  </simpara>
326                </listitem>
327
328                <listitem>
329                  <simpara>
330                  <emphasis>Circular reference to pooled item</emphasis>:
331                  If you have used pooling, checks that no
332                  circular references have been created.
333                  </simpara>
334                </listitem>
335             
336              </itemizedlist>
337             
338            </listitem>
339          </varlistentry>
340         
341        </variablelist>
342       
343        <para>
344          Click on the <guibutton>Save</guibutton> button
345          to use the current settings. The display will
346          automatically refresh itself.
347        </para>
348       
349      </helptext>
350     
351      <helptext external_id="experiment.overview.validationoptions.savepreset" 
352        title="Save preset" webonly="1">
353       
354        <para>
355        Saves all validation options as a preset.
356        </para>
357       
358        <variablelist>
359          <varlistentry>
360            <term><guilabel>Name</guilabel></term>
361            <listitem>
362              <para>
363                The name of the preset. The name must be unique
364                and if a preset with the same name already exists
365                you will be asked if you want to overwrite it or not.
366              </para>
367            </listitem>
368          </varlistentry>
369        </variablelist>
370       
371        <para>
372          Click on the <guibutton>Save</guibutton> button
373          to save the preset or <guibutton>Cancel</guibutton>
374          to abort.
375        </para>
376      </helptext>
377     
378    </sect3>
379   
380    <sect3 id="experiments_analysis.fixfailures">
381      <title>Fixing validation failures</title>
382      <helptext external_id="experiment.overview.fixfailures" 
383        title="How to fix validation failures">
384       
385        <para>
386        The experiment overview includes a function that allows
387        you to quickly fix most of the problems found during the
388        validation. The easiest way to use the function is:
389        </para>
390       
391        <orderedlist>
392          <listitem>
393            <simpara>
394            Click on an error or warning in the list of failures in
395            the lower right
396            pane. The tree in the left pane and the item overview in the
397            top right pane will automatically be updated to show the
398            exact location of the faulty item.
399            </simpara>
400          </listitem>
401          <listitem>
402            <simpara>
403            The upper right pane should contain a list labeled
404            <guilabel>Failure details</guilabel> with more information
405            about each failure and also one or more suggestions for fixing
406            the problem. For example, a failure due to a missing item
407            should suggest that you add or select an item.
408            </simpara>
409          </listitem>
410         
411          <listitem>
412            <simpara>
413            The suggestions should also have links that takes
414            you to an edit view where you can do the changes.
415            </simpara>
416          </listitem>
417         
418          <listitem>
419            <simpara>
420            After saving the changes you must click on the
421            <guibutton>Revalidate</guibutton> button to update
422            interface. If you want, you can fix more than one
423            failure before clicking on the button.
424            </simpara>
425          </listitem>
426           
427        </orderedlist>
428     
429      </helptext>
430    </sect3>
431   
432  </sect2>
433 
434  <sect2 id="experiments_analysis.magexport">
435    <title>Tab2Mage export</title>
436    <para>TODO</para>
437  </sect2>
438
439</sect1>
Note: See TracBrowser for help on using the repository browser.