plugins/base1/se.lu.onk.Center/trunk/README

Code
Comments
Other
Rev Date Author Line
766 16 Sep 08 jari 1 $Id$
766 16 Sep 08 jari 2
875 05 Dec 08 jari 3 = About `se.lu.onk.Center` =
766 16 Sep 08 jari 4
879 05 Dec 08 jari 5 The `se.lu.onk.Center` plug-in is a normalisation method where
2118 05 Nov 13 jari 6 expression values are centred around the data median or mean. See
879 05 Dec 08 jari 7 ``Documentation`` below for further information about the plug-in.
766 16 Sep 08 jari 8
2118 05 Nov 13 jari 9 `se.lu.onk.Center` is open source software. See the file `license.txt`
2118 05 Nov 13 jari 10 for copying conditions.
766 16 Sep 08 jari 11
2118 05 Nov 13 jari 12 The package was created by Johan Enell.
766 16 Sep 08 jari 13
766 16 Sep 08 jari 14
766 16 Sep 08 jari 15 == Downloading ==
766 16 Sep 08 jari 16
875 05 Dec 08 jari 17 `se.lu.onk.Center` can be obtained from
766 16 Sep 08 jari 18
766 16 Sep 08 jari 19   http://baseplugins.thep.lu.se/wiki/PluginDownload
766 16 Sep 08 jari 20
766 16 Sep 08 jari 21
772 18 Sep 08 jari 22 == Installation and upgrade ==
766 16 Sep 08 jari 23
2118 05 Nov 13 jari 24 ''This plug-in is only tested in BASE through the Base1PluginExecuter
2118 05 Nov 13 jari 25 and may work also in BASE 1.2.17. Please report failure or success in
2118 05 Nov 13 jari 26 BASE 1.2 through http://baseplugins.thep.lu.se. These installation
2118 05 Nov 13 jari 27 instructions only describe how to get the plug-in to work with the
2118 05 Nov 13 jari 28 Base1PluginExecuter in the latest BASE 3.x version.''
766 16 Sep 08 jari 29
766 16 Sep 08 jari 30 If you downloaded a binary package you only need to follow these
766 16 Sep 08 jari 31 instructions. If you prefer to compile the package yourself, read the
766 16 Sep 08 jari 32 instructions about compiling and creating a distribution before doing
766 16 Sep 08 jari 33 the installation steps described here.
766 16 Sep 08 jari 34
766 16 Sep 08 jari 35 You need to understand how to install plug-ins in BASE, please refer
766 16 Sep 08 jari 36 to BASE documentation at http://base.thep.lu.se for general
766 16 Sep 08 jari 37 instructions on plug-in installation. The BASE documentation contains
772 18 Sep 08 jari 38 a chapter on plug-ins. If you have read the plug-in information you
772 18 Sep 08 jari 39 should be able to follow this path
766 16 Sep 08 jari 40 {{{
766 16 Sep 08 jari 41   # cd /path/to/base/plugins
875 05 Dec 08 jari 42   # download Center-version.tgz
875 05 Dec 08 jari 43   # untar Center-version.tgz
875 05 Dec 08 jari 44   # ln -s Center-version Center
766 16 Sep 08 jari 45 }}}
776 18 Sep 08 jari 46 The symbolic link in the last line above allows for easier change to
766 16 Sep 08 jari 47 future version of the plug-in.
766 16 Sep 08 jari 48 {{{
766 16 Sep 08 jari 49   # Log in to your BASE as admin
879 05 Dec 08 jari 50   # Upload the configuration file misc/plugin_Transformation_Center.base`
776 18 Sep 08 jari 51   # Create/update a configuration for the plug-in where you select the
879 05 Dec 08 jari 52     plug-in definition file `plugin_Transformation_Center.base`. BASE
879 05 Dec 08 jari 53     will respond that plug-ins where configured but ...
776 18 Sep 08 jari 54   # Re-configure the plug-in without selecting a file, set the `Plugin
2118 05 Nov 13 jari 55     executable path` and proceed to next window by clicking
772 18 Sep 08 jari 56     `Next`. This is explained in the BASE documentation and needs to
772 18 Sep 08 jari 57     be done even when you update your plug-in.
766 16 Sep 08 jari 58   # In this parameter window set the `Name of executable`. The value
766 16 Sep 08 jari 59     of this parameter and `Plugin executables path` should add up to
776 18 Sep 08 jari 60     the absolute path to the binary `run`, i.e.,
875 05 Dec 08 jari 61     /path/to/base/plugins/Center/run. How this string looks
766 16 Sep 08 jari 62     like depends on your plug-in directory structure.
766 16 Sep 08 jari 63   # Test the plug-ins and when you are satisfied, share it to your
766 16 Sep 08 jari 64     users.
766 16 Sep 08 jari 65 }}}
766 16 Sep 08 jari 66
766 16 Sep 08 jari 67
766 16 Sep 08 jari 68 == Compiling ==
766 16 Sep 08 jari 69
2118 05 Nov 13 jari 70 You must check out the `se.lu.onk.Center` from the repository and
766 16 Sep 08 jari 71 follow the instructions below. Then download and untar the
766 16 Sep 08 jari 72 `se.lu.onk.BaseFile` package available from
766 16 Sep 08 jari 73 http://baseplugins.thep.lu.se/wiki/PluginDownload. This package is
766 16 Sep 08 jari 74 known to work with `se.lu.onk.BaseFile` version 1.0.
766 16 Sep 08 jari 75 {{{
2118 05 Nov 13 jari 76   check out project, see instructions below in section "Subversion Access"
875 05 Dec 08 jari 77   # cd /path/to/se.lu.onk.Center
804 01 Oct 08 jari 78   # wget http://baseplugins.thep.lu.se/attachment/wiki/se.lu.onk.BaseFile/BaseFile-1.0.tgz?format=raw -O BaseFile-1.0.tgz
804 01 Oct 08 jari 79   # wget http://baseplugins.thep.lu.se/attachment/wiki/se.lu.onk.BaseFile/BaseFile-1.0.tgz.MD5?format=raw -O BaseFile-1.0.tgz.MD5
788 18 Sep 08 jari 80   # optionally compare the MD5 sum of the downloaded file and the MD5-file
766 16 Sep 08 jari 81   # tar zxpf BaseFile-1.0.tgz
766 16 Sep 08 jari 82   # ln -s BaseFile-1.0 BaseFile
766 16 Sep 08 jari 83     or
766 16 Sep 08 jari 84   # mv BaseFile-1.0 BaseFile
766 16 Sep 08 jari 85 }}}
766 16 Sep 08 jari 86 It is important that the `BaseFile` package is located in directory
766 16 Sep 08 jari 87 `BaseFile`. Now simple issue `ant`. This will create a jar file
875 05 Dec 08 jari 88 `dist/Center.jar`.
766 16 Sep 08 jari 89
766 16 Sep 08 jari 90
766 16 Sep 08 jari 91 == Creating a distribution ==
766 16 Sep 08 jari 92
776 18 Sep 08 jari 93 Update the version number in `build.xml`, and issue `ant
776 18 Sep 08 jari 94 package`. This creates a distribution package with all required
2118 05 Nov 13 jari 95 components, including `BaseFile.jar` and associated files.
766 16 Sep 08 jari 96
766 16 Sep 08 jari 97
766 16 Sep 08 jari 98 == Bug Reporting ==
766 16 Sep 08 jari 99
875 05 Dec 08 jari 100 You can report `se.lu.onk.Center` bugs on
766 16 Sep 08 jari 101
766 16 Sep 08 jari 102   http://baseplugins.thep.lu.se/newticket
766 16 Sep 08 jari 103
766 16 Sep 08 jari 104 Use user `base` and password `base`.
766 16 Sep 08 jari 105
766 16 Sep 08 jari 106
766 16 Sep 08 jari 107 == Subversion Access ==
766 16 Sep 08 jari 108
875 05 Dec 08 jari 109 The `se.lu.onk.Center` source repository is available via anonymous
766 16 Sep 08 jari 110 subversion access, issue:
766 16 Sep 08 jari 111
875 05 Dec 08 jari 112   `svn co http://baseplugins.thep.lu.se/svn/plugins/base1/se.lu.onk.Center/trunk se.lu.onk.Center`
766 16 Sep 08 jari 113
766 16 Sep 08 jari 114 There is no guarantees about the contents or quality of the latest
766 16 Sep 08 jari 115 code in the subversion repository: it is not unheard of for code that
766 16 Sep 08 jari 116 is known to be broken to be committed to the repository. Use at your
766 16 Sep 08 jari 117 own risk. You may prefer to check out a released version instead, then
776 18 Sep 08 jari 118 replace `trunk` with `tags/version` in the above example.
766 16 Sep 08 jari 119
766 16 Sep 08 jari 120
788 18 Sep 08 jari 121 == Documentation ==
766 16 Sep 08 jari 122
2118 05 Nov 13 jari 123 To centre your data means that data values are adjusted to reflect
879 05 Dec 08 jari 124 their variation from some property of the data such as the mean or
2118 05 Nov 13 jari 125 median. The centre plug-in allows the user to centre the expression
879 05 Dec 08 jari 126 levels either per gene or per array.
788 18 Sep 08 jari 127
879 05 Dec 08 jari 128 Consider a common experimental design where you are looking at a large
879 05 Dec 08 jari 129 number of samples all compared to a common reference. For each gene,
879 05 Dec 08 jari 130 you have a series of ratio values that are relative to the expression
879 05 Dec 08 jari 131 level of that gene in the reference sample. Since the reference sample
879 05 Dec 08 jari 132 really has nothing to do with your experiment, you want your analysis
879 05 Dec 08 jari 133 to be independent of the amount of a gene present in the reference
2118 05 Nov 13 jari 134 sample. This is achieved by cent-er your data on genes. Centring makes
879 05 Dec 08 jari 135 less sense in experiments where the reference sample is part of the
879 05 Dec 08 jari 136 experiment.
788 18 Sep 08 jari 137
2118 05 Nov 13 jari 138 Centring the data for arrays can also be used to remove certain types
2118 05 Nov 13 jari 139 of bias and can be seen as a crude normalisation. The results of many
2118 05 Nov 13 jari 140 two-colour fluorescent hybridisation experiments are not corrected for
879 05 Dec 08 jari 141 systematic biases in ratios that are the result of differences in RNA
2118 05 Nov 13 jari 142 amounts, labelling efficiency, and image acquisition parameters. Such
879 05 Dec 08 jari 143 bias have the effect of multiplying ratios for all genes by a fixed
2118 05 Nov 13 jari 144 scalar. Mean or median centring the data in log-space has the effect
879 05 Dec 08 jari 145 of correcting this bias, although it should be noted that an
879 05 Dec 08 jari 146 assumption is being made in correcting this bias, which is that the
879 05 Dec 08 jari 147 average gene in a given experiment is expected to have a ratio of 1.0
879 05 Dec 08 jari 148 (or log-ratio of 0).
788 18 Sep 08 jari 149
2118 05 Nov 13 jari 150 In general, it is recommended that median rather than mean centring
879 05 Dec 08 jari 151 is used since it is more robust against outliers.
788 18 Sep 08 jari 152
788 18 Sep 08 jari 153 === Parameters ===
788 18 Sep 08 jari 154
2118 05 Nov 13 jari 155 ''Center on genes/assays'' - Whether centring should be done on
2118 05 Nov 13 jari 156 genes, assays, or both. If both is chosen then the centring will
2118 05 Nov 13 jari 157 first be done on genes then on assays, this is called a cycle.
788 18 Sep 08 jari 158
2118 05 Nov 13 jari 159 ''Assay groups for centering'' - If the centring should be based on
2118 05 Nov 13 jari 160 data in one or more assay groups. If `Default` is selected, centring
2118 05 Nov 13 jari 161 on assays is made with each assay in its own group, while centring on
2118 05 Nov 13 jari 162 genes is made with all assays in one group. Selecting `Single assay
2118 05 Nov 13 jari 163 group` centres all data based on values in a single assay
2118 05 Nov 13 jari 164 group. `Assay groups` centres each assay group separately.
2118 05 Nov 13 jari 165
2118 05 Nov 13 jari 166 ''Center group(s) assay names'' - Comma-separated list of names of
2118 05 Nov 13 jari 167 assays in groups to use for centring, with each group separated by a
2118 05 Nov 13 jari 168 `|` character. This option is only used when `Single assay group` or
2118 05 Nov 13 jari 169 `Assay groups` has been selected under ''Assay groups for centering''.
2118 05 Nov 13 jari 170
879 05 Dec 08 jari 171 ''Number of centering cycles'' - How many cycles should be done during
879 05 Dec 08 jari 172 centering. This value is only relevant if the centering should be done
2118 05 Nov 13 jari 173 on both genes and assays.
788 18 Sep 08 jari 174
879 05 Dec 08 jari 175 ''Centering using median or mean'' - Whether median or mean should be
879 05 Dec 08 jari 176 used for the centering.
788 18 Sep 08 jari 177
2118 05 Nov 13 jari 178 ''Normalise on gene/assays using median or mean'' - Whether
2118 05 Nov 13 jari 179 normalisation should be done on genes, assays, or both.
788 18 Sep 08 jari 180
2118 05 Nov 13 jari 181 ''Number of normalization cycles'' - How many cycles should be done
2118 05 Nov 13 jari 182 during normalisation.
2118 05 Nov 13 jari 183
2118 05 Nov 13 jari 184 ''Create debug files'' - If debug data should be stored in `data`
2118 05 Nov 13 jari 185 directory.
2118 05 Nov 13 jari 186
766 16 Sep 08 jari 187 ----------------------------------------------------------------------
766 16 Sep 08 jari 188 {{{
2118 05 Nov 13 jari 189 Copyright (C) 2008, 2013 Jari Häkkinen
766 16 Sep 08 jari 190
875 05 Dec 08 jari 191 This file is part of the se.lu.onk.Center plug-in for BASE. Available
875 05 Dec 08 jari 192 at http://baseplugins.thep.lu.se/ and BASE web site is
766 16 Sep 08 jari 193 http://base.thep.lu.se
766 16 Sep 08 jari 194
766 16 Sep 08 jari 195 This is free software; you can redistribute it and/or modify it under
766 16 Sep 08 jari 196 the terms of the GNU General Public License as published by the Free
766 16 Sep 08 jari 197 Software Foundation; either version 3 of the License, or (at your
766 16 Sep 08 jari 198 option) any later version.
766 16 Sep 08 jari 199
766 16 Sep 08 jari 200 This package is distributed in the hope that it will be useful, but
766 16 Sep 08 jari 201 WITHOUT ANY WARRANTY; without even the implied warranty of
766 16 Sep 08 jari 202 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
766 16 Sep 08 jari 203 General Public License for more details.
766 16 Sep 08 jari 204
766 16 Sep 08 jari 205 You should have received a copy of the GNU General Public License
766 16 Sep 08 jari 206 along with this package. If not, see <http://www.gnu.org/licenses/>.
766 16 Sep 08 jari 207 }}}