doc/src/docbook/user/experiments.xml

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