source: trunk/doc/src/docbook/user/experiments.xml @ 6961

Last change on this file since 6961 was 6961, checked in by Nicklas Nordborg, 6 years ago

References #1941: Store experimental factor values as part experiments

Updated documentation and screen shots related to the new functionality.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Date
File size: 11.1 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.xml 6961 2015-10-01 11:23:03Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
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 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<sect1 id="experiments_analysis.experiments">
28  <?dbhtml filename="experiments.html" ?>
29  <title>Experiments</title>
30  <para>
31    Experiments are the starting point for analysis. When you have
32    uploaded and imported your raw data, collected and registered all
33    information and annotations about samples, bioassays, and other
34    items, it is time to collect everything in an experiment.
35  </para>
36 
37  <para>
38    To create a new experiment you can either mark one ore more
39    raw biossays on the raw bioassays list view and use the
40    <guibutton>New experiment</guibutton> button. You can also
41    create a new experiment from the experiments list view.
42  </para>
43
44  <sect2 id="experiments_analysis.experiment.properties">
45    <title>Experiment properties</title>
46   
47    <figure id="experiments_analysis.figures.experiment_properties">
48      <title>Experiment properties</title>
49      <screenshot>
50        <mediaobject>
51          <imageobject><imagedata 
52            fileref="figures/experiment_properties.png" format="PNG"
53            /></imageobject>
54        </mediaobject>
55      </screenshot>
56    </figure>         
57   
58   
59    <helptext external_id="experiment.edit" title="Edit experiment">
60   
61      <variablelist>
62      <varlistentry>
63        <term><guilabel>Name</guilabel></term>
64        <listitem>
65          <para>
66            The name of the experiment.
67          </para>
68        </listitem>
69      </varlistentry>
70     
71      <varlistentry>
72        <term><guilabel>Raw data type</guilabel></term>
73        <listitem>
74          <para>
75            The raw data type to use in the experiment. All raw bioassays
76            must have raw data with this type.
77          </para>
78        </listitem>
79      </varlistentry>
80
81      <varlistentry>
82        <term><guilabel>Directory</guilabel></term>
83        <listitem>
84          <para>
85            A directory in the BASE file system where plug-ins
86            can save files that are generated during the analysis.
87            This is optional and if not given the plug-ins must ask
88            about a directory each time they need it. Use the
89            <guibutton>Select</guibutton> button to browse the file system
90            or create a new directory.
91          </para>
92        </listitem>
93      </varlistentry>
94     
95      <varlistentry>
96        <term><guilabel>Raw bioassays</guilabel></term>
97        <listitem>
98          <para>
99            The raw bioassays you want to analyze in this experiment. If
100            you created the experiment from the raw bioassays list the
101            selected raw bioassays are already filled in. Use the
102            <guibutton>Add raw bioassays</guibutton> button to add more
103            raw bioassays or the &gbRemove; button
104            to remove the selected raw bioassays from the list.
105          </para>
106        </listitem>
107      </varlistentry>
108     
109      <varlistentry>
110        <term><guilabel>Description</guilabel></term>
111        <listitem>
112          <para>
113            A description of the experiment.
114          </para>
115        </listitem>
116      </varlistentry>
117
118      </variablelist>
119     
120      <para>
121        Click on the &gbSave; button to save the
122        changes or on &gbCancel; to abort.
123      </para>
124     
125      <seeother>
126        <other external_id="experiment.edit.publication">Publication</other>
127        <other external_id="experiment.edit.factors">Experimental factors</other>
128      </seeother>
129    </helptext>
130   
131    <sect3 id="experiments_analysis.experiment.publication">
132      <title>The publication tab</title>
133     
134    <figure id="experiments_analysis.figures.experiment_publication">
135      <title>Experiment publication</title>
136      <screenshot>
137        <mediaobject>
138          <imageobject><imagedata 
139            fileref="figures/experiment_publication.png" format="PNG"
140            /></imageobject>
141        </mediaobject>
142      </screenshot>
143    </figure>         
144
145      <helptext external_id="experiment.edit.publication" 
146        title="Experiment publication">
147
148        <para>
149          On this tab you can enter information about a publication
150          that is the result of the experiment. All of this information
151          is optional.
152        </para>
153       
154        <variablelist>
155        <varlistentry>
156          <term><guilabel>PubMedId</guilabel></term>
157          <listitem>
158            <para>
159              The ID of the publication in the
160              <ulink url="http://www.ncbi.nlm.nih.gov/pubmed/"
161                >PubMed</ulink> database.
162            </para>
163          </listitem>
164        </varlistentry>
165        <varlistentry>
166          <term><guilabel>Title</guilabel></term>
167          <listitem>
168            <para>
169              The title of the publication.
170            </para>
171          </listitem>
172        </varlistentry>
173        <varlistentry>
174          <term><guilabel>Publication date</guilabel></term>
175          <listitem>
176            <para>
177              The date the article was published. Use the
178              <guibutton>Calendar</guibutton> button to select
179              a date from a pop-up window.
180            </para>
181          </listitem>
182        </varlistentry>
183        <varlistentry>
184          <term><guilabel>Abstract</guilabel></term>
185          <listitem>
186            <para>
187              The article abstract.
188            </para>
189          </listitem>
190        </varlistentry>
191        <varlistentry>
192          <term><guilabel>Experiment design</guilabel></term>
193          <listitem>
194            <para>
195              An explanation of the experiment design.
196            </para>
197          </listitem>
198        </varlistentry>
199        <varlistentry>
200          <term><guilabel>Experiment type</guilabel></term>
201          <listitem>
202            <para>
203              A description of the experiment type.
204            </para>
205          </listitem>
206        </varlistentry>
207        <varlistentry>
208          <term><guilabel>Affiliations</guilabel></term>
209          <listitem>
210            <para>
211              Partners and other related organisations that
212              have helped with the experiment.
213            </para>
214          </listitem>
215        </varlistentry>
216        <varlistentry>
217          <term><guilabel>Authors</guilabel></term>
218          <listitem>
219            <para>
220              The list of authors of the publication.
221            </para>
222          </listitem>
223        </varlistentry>
224        <varlistentry>
225          <term><guilabel>Publication</guilabel></term>
226          <listitem>
227            <para>
228              The body text of the publication.
229            </para>
230          </listitem>
231        </varlistentry>
232        </variablelist>
233       
234        <para>
235          Click on the &gbSave; button to save the
236          changes or on &gbCancel; to abort.
237        </para>
238     
239        <seeother>
240          <other external_id="experiment.edit">Experiment properties</other>
241          <other external_id="experiment.edit.factors">Experimental factors</other>
242        </seeother>
243      </helptext>
244    </sect3>
245   
246  </sect2>
247 
248  <sect2 id="experiments_analysis.experiment.factors">
249    <title>Experimental factors</title>
250   
251    <figure id="experiments_analysis.figures.experiment_factors">
252      <title>Experimental factors</title>
253      <screenshot>
254        <mediaobject>
255          <imageobject><imagedata 
256            fileref="figures/experiment_factors.png" format="PNG"
257            /></imageobject>
258        </mediaobject>
259      </screenshot>
260    </figure>
261    <helptext external_id="experiment.edit.factors" 
262      title="Experimental factors">
263   
264      <para>
265        The experimental factors of an experiment are the variables
266        you are studying in the experiment. Typically the value of
267        an experimental factor is varied between samples or group of samples.
268        Different treatment methods is an example of an experimental factor.
269      </para>
270     
271      <para>
272        In the BASE world an experimental factor is the same as an annotation
273        type. Since you probably have lots of annotations on your items that are not
274        relevant for the experiment you must select the annotations types
275        that should make up the experimental factors of the experiment.
276      </para>
277     
278      <para>
279        Use the <guibutton>Add annotation types</guibutton> button to
280        select the annotation types that should be used as experimental
281        factors. The &gbRemove; button removes the
282        selected annotation types.
283      </para>
284
285      <para>
286        Click on the &gbSave; button to save the
287        changes or on &gbCancel; to abort.
288      </para>
289     
290      <para>
291        To be able to use the values of the experimental factors
292        in the analysis of your data the values must be accessible
293        from the <guilabel>root raw bioassays</guilabel>. A root raw bioassay
294        is a wrapper around a raw bioassay that is part of the experiment and
295        it has two purposes:
296      </para>
297     
298      <itemizedlist>
299        <listitem>
300          <para>
301          Hold experimental factor values for the raw bioassay in the
302          context of the current experiment without affecting other
303          experiments were the same raw bioassay is used.
304          </para>
305        </listitem>
306        <listitem>
307          <para>
308          Give the owner of the experiment control over the experimental factor
309          values used. In a multi-project setting this is important since the
310          owner of the raw bioassay may not permit changes to the raw bioassay.
311          Use the <guilabel>clone</guilabel> feature when inheriting
312          annotations to the root raw bioassay to make sure that downstream
313          analysis is not affected by changes made to the original parent
314          annotations (unless you do a manual <guilabel>resync</guilabel>).
315          </para>
316        </listitem>
317      </itemizedlist>
318       
319      <para>
320        Since most of your annotations are probably made at the sample or biosource
321        level the root raw bioassays must inherit or clone those annotations.
322        The experiment view page lists all experimental factors and their current
323        values for each root raw bioassay.
324      </para>
325
326      <para>
327        There is a quick access to the <link linkend="annotations.batch-inherit">batch inherit</link>
328        function that makes it easy to inherit any annotations that are missing.
329        <nohelp>See also <xref linkend="annotations.inheriting" /> for more information about inheriting annotations.</nohelp>
330      </para>
331     
332      <nohelp>
333      <figure id="experiments_analysis.figures.experiment_factor_values">
334        <title>Experimental factor values</title>
335        <screenshot>
336          <mediaobject>
337            <imageobject><imagedata 
338              fileref="figures/experiment_factor_values.png" format="PNG"
339              /></imageobject>
340          </mediaobject>
341        </screenshot>
342      </figure>
343      </nohelp>
344
345      <tip>
346        <para>
347        Use the <guilabel>Item overview</guilabel> function to
348        verify that all your raw bioassays has been annotated or
349        inherited values for all experimental factors. If not, you
350        should do that before starting with the analysis.
351        </para>
352      </tip>
353     
354      <seeother>
355        <other external_id="experiment.edit">Experiment properties</other>
356        <other external_id="experiment.edit.publication">Publication</other>
357        <other external_id="item.overview">Item overview</other>
358        <other external_id="annotations.edit.inerited">Inherit annotations</other>
359      </seeother>
360     
361    </helptext>
362  </sect2>
363
364</sect1>
Note: See TracBrowser for help on using the repository browser.