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

Code
Comments
Other
Rev Date Author Line
766 16 Sep 08 jari 1 $Id$
766 16 Sep 08 jari 2
776 18 Sep 08 jari 3 = About `se.lu.onk.MergeBioAssay` =
766 16 Sep 08 jari 4
788 18 Sep 08 jari 5 The `se.lu.onk.MergeBioAssay` plug-in merge bioassays by grouping them
788 18 Sep 08 jari 6 according to annotation types or syntactical differences in the
788 18 Sep 08 jari 7 name. See ``Documentation`` below fo further information about the
788 18 Sep 08 jari 8 plug-in.
766 16 Sep 08 jari 9
776 18 Sep 08 jari 10 `se.lu.onk.MergeBioAssay` is free software. See the file license.txt for
766 16 Sep 08 jari 11 copying conditions.
766 16 Sep 08 jari 12
766 16 Sep 08 jari 13 The package was created by Johan Enell and is currently maintained by
766 16 Sep 08 jari 14 Jari Häkkinen.
766 16 Sep 08 jari 15
766 16 Sep 08 jari 16
766 16 Sep 08 jari 17 == Downloading ==
766 16 Sep 08 jari 18
776 18 Sep 08 jari 19 `se.lu.onk.MergeBioAssay` can be obtained from
766 16 Sep 08 jari 20
766 16 Sep 08 jari 21   http://baseplugins.thep.lu.se/wiki/PluginDownload
766 16 Sep 08 jari 22
766 16 Sep 08 jari 23
772 18 Sep 08 jari 24 == Installation and upgrade ==
766 16 Sep 08 jari 25
766 16 Sep 08 jari 26 ''This plug-in is only tested in BASE 2.8 through the
766 16 Sep 08 jari 27 Base1PluginExecuter but is expected to work also in BASE
766 16 Sep 08 jari 28 1.2.17. Please report failure or success in BASE 1.2 through
766 16 Sep 08 jari 29 http://baseplugins.thep.lu.se. These installation instructions only
766 16 Sep 08 jari 30 describe how to get the plug-in to work with the Base1PluginExecuter
776 18 Sep 08 jari 31 in the latest BASE version 2.''
766 16 Sep 08 jari 32
766 16 Sep 08 jari 33 If you downloaded a binary package you only need to follow these
766 16 Sep 08 jari 34 instructions. If you prefer to compile the package yourself, read the
766 16 Sep 08 jari 35 instructions about compiling and creating a distribution before doing
766 16 Sep 08 jari 36 the installation steps described here.
766 16 Sep 08 jari 37
766 16 Sep 08 jari 38 You need to understand how to install plug-ins in BASE, please refer
766 16 Sep 08 jari 39 to BASE documentation at http://base.thep.lu.se for general
766 16 Sep 08 jari 40 instructions on plug-in installation. The BASE documentation contains
772 18 Sep 08 jari 41 a chapter on plug-ins. If you have read the plug-in information you
772 18 Sep 08 jari 42 should be able to follow this path
766 16 Sep 08 jari 43 {{{
766 16 Sep 08 jari 44   # cd /path/to/base/plugins
776 18 Sep 08 jari 45   # download MergeBioAssay-version.tgz
776 18 Sep 08 jari 46   # untar MergeBioAssay-version.tgz
776 18 Sep 08 jari 47   # ln -s MergeBioAssay-version MergeBioAssay
766 16 Sep 08 jari 48 }}}
776 18 Sep 08 jari 49 The symbolic link in the last line above allows for easier change to
766 16 Sep 08 jari 50 future version of the plug-in.
766 16 Sep 08 jari 51 {{{
766 16 Sep 08 jari 52   # Log in to your BASE as admin
776 18 Sep 08 jari 53   # Upload the configuration file `mergebioassay.base`
776 18 Sep 08 jari 54   # Create/update a configuration for the plug-in where you select the
877 05 Dec 08 jari 55     plug-in definition file `mergebioassay.base`. BASE will respond
776 18 Sep 08 jari 56     that plug-ins where configured but ...
776 18 Sep 08 jari 57   # Re-configure the plug-in without selecting a file, set the `Plugin
776 18 Sep 08 jari 58     executables path` and proceed to next window by clicking
772 18 Sep 08 jari 59     `Next`. This is explained in the BASE documentation and needs to
772 18 Sep 08 jari 60     be done even when you update your plug-in.
766 16 Sep 08 jari 61   # In this parameter window set the `Name of executable`. The value
766 16 Sep 08 jari 62     of this parameter and `Plugin executables path` should add up to
776 18 Sep 08 jari 63     the absolute path to the binary `run`, i.e.,
776 18 Sep 08 jari 64     /path/to/base/plugins/MergeBioAssay/run. How this string looks
766 16 Sep 08 jari 65     like depends on your plug-in directory structure.
766 16 Sep 08 jari 66   # Test the plug-ins and when you are satisfied, share it to your
766 16 Sep 08 jari 67     users.
766 16 Sep 08 jari 68 }}}
766 16 Sep 08 jari 69
766 16 Sep 08 jari 70
766 16 Sep 08 jari 71 == Compiling ==
766 16 Sep 08 jari 72
776 18 Sep 08 jari 73 You must checkout the `se.lu.onk.MergeBioAssay` from the repository,
766 16 Sep 08 jari 74 follow the instructions below. Then download and untar the
766 16 Sep 08 jari 75 `se.lu.onk.BaseFile` package available from
766 16 Sep 08 jari 76 http://baseplugins.thep.lu.se/wiki/PluginDownload. This package is
766 16 Sep 08 jari 77 known to work with `se.lu.onk.BaseFile` version 1.0.
766 16 Sep 08 jari 78 {{{
766 16 Sep 08 jari 79   check out project, see instructions below
776 18 Sep 08 jari 80   # cd /path/to/se.lu.onk.MergeBioAssay
804 01 Oct 08 jari 81   # 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 82   # 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 83   # optionally compare the MD5 sum of the downloaded file and the MD5-file
766 16 Sep 08 jari 84   # tar zxpf BaseFile-1.0.tgz
766 16 Sep 08 jari 85   # ln -s BaseFile-1.0 BaseFile
766 16 Sep 08 jari 86     or
766 16 Sep 08 jari 87   # mv BaseFile-1.0 BaseFile
766 16 Sep 08 jari 88 }}}
766 16 Sep 08 jari 89 It is important that the `BaseFile` package is located in directory
766 16 Sep 08 jari 90 `BaseFile`. Now simple issue `ant`. This will create a jar file
776 18 Sep 08 jari 91 `dist/MergeBioAssay.jar`.
766 16 Sep 08 jari 92
766 16 Sep 08 jari 93
766 16 Sep 08 jari 94 == Creating a distribution ==
766 16 Sep 08 jari 95
776 18 Sep 08 jari 96 Update the version number in `build.xml`, and issue `ant
776 18 Sep 08 jari 97 package`. This creates a distribution package with all required
776 18 Sep 08 jari 98 components, including BaseFile.jar and associated files.
766 16 Sep 08 jari 99
766 16 Sep 08 jari 100
766 16 Sep 08 jari 101 == Bug Reporting ==
766 16 Sep 08 jari 102
788 18 Sep 08 jari 103 You can report `se.lu.onk.MergeBioAssay` bugs on
766 16 Sep 08 jari 104
766 16 Sep 08 jari 105   http://baseplugins.thep.lu.se/newticket
766 16 Sep 08 jari 106
766 16 Sep 08 jari 107 Use user `base` and password `base`.
766 16 Sep 08 jari 108
766 16 Sep 08 jari 109
766 16 Sep 08 jari 110 == Subversion Access ==
766 16 Sep 08 jari 111
776 18 Sep 08 jari 112 The `se.lu.onk.MergeBioAssay` source repository is available via anonymous
766 16 Sep 08 jari 113 subversion access, issue:
766 16 Sep 08 jari 114
776 18 Sep 08 jari 115   `svn co http://baseplugins.thep.lu.se/svn/plugins/base1/se.lu.onk.MergeBioAssay/trunk se.lu.onk.MergeBioAssay`
766 16 Sep 08 jari 116
766 16 Sep 08 jari 117 There is no guarantees about the contents or quality of the latest
766 16 Sep 08 jari 118 code in the subversion repository: it is not unheard of for code that
766 16 Sep 08 jari 119 is known to be broken to be committed to the repository. Use at your
766 16 Sep 08 jari 120 own risk. You may prefer to check out a released version instead, then
776 18 Sep 08 jari 121 replace `trunk` with `tags/version` in the above example.
766 16 Sep 08 jari 122
766 16 Sep 08 jari 123
788 18 Sep 08 jari 124 == Documentation ==
766 16 Sep 08 jari 125
788 18 Sep 08 jari 126 This plug-in base-users merge bioassays by grouping them according to
788 18 Sep 08 jari 127 annotation types or syntactical differences in the name. There are
788 18 Sep 08 jari 128 four different methods for calculating the merged values. They differ
788 18 Sep 08 jari 129 in what kind of mean they are using (arithmetic or geometric) and if
788 18 Sep 08 jari 130 they are merging on ratio or intensity.
788 18 Sep 08 jari 131
788 18 Sep 08 jari 132 For each group the parents are saved so the link to the raw data is
788 18 Sep 08 jari 133 preserved. Annotations for the bioassays are saved if sample1 is the
788 18 Sep 08 jari 134 same for each assay in each group.
788 18 Sep 08 jari 135
788 18 Sep 08 jari 136 === Merge methods ===
788 18 Sep 08 jari 137
788 18 Sep 08 jari 138 ''Geometric mean of ratio''::
788 18 Sep 08 jari 139   This method calculates the geometric mean of the ratios in each
788 18 Sep 08 jari 140   group per position.
788 18 Sep 08 jari 141
788 18 Sep 08 jari 142 ''Arithmetic mean of ratio''::
788 18 Sep 08 jari 143   This method calculates the arithmetic mean of the ratios in each
788 18 Sep 08 jari 144   group per position.
788 18 Sep 08 jari 145
788 18 Sep 08 jari 146 ''Arithmetic mean of intensity''::
788 18 Sep 08 jari 147   This method calculates the arithmetic mean of the intensities in
788 18 Sep 08 jari 148   each group per position.
788 18 Sep 08 jari 149
788 18 Sep 08 jari 150 ''Ratio of ratio''::
788 18 Sep 08 jari 151   This method works a little bit different from the others. It
788 18 Sep 08 jari 152   requires that each group consists of exactly two bioassays. It will
788 18 Sep 08 jari 153   then create a new ratio for each spot with one of the assays over
788 18 Sep 08 jari 154   the other, depending on what the user has specified in the ratio
788 18 Sep 08 jari 155   parameters.
788 18 Sep 08 jari 156
788 18 Sep 08 jari 157 === Parameters ===
788 18 Sep 08 jari 158
788 18 Sep 08 jari 159 ''Assayname''::
788 18 Sep 08 jari 160   This parameter specifies how the name of the assays is
877 05 Dec 08 jari 161   constructed. Use %0-%9 as wild-cards and then put any character(s)
788 18 Sep 08 jari 162   between as delimiters. For example assay name Assay_1_A can be
788 18 Sep 08 jari 163   divided into three parts. By setting the parameter to %1_%2_%3 the
877 05 Dec 08 jari 164   plug-in will read assay name assay_1_A and set %1=Assay, %2=1 and
788 18 Sep 08 jari 165   %3=A. Thus, if your assays have names constructed in the same way
788 18 Sep 08 jari 166   merge can sort the assays in groups depending on %1, %2 or %3.
788 18 Sep 08 jari 167
788 18 Sep 08 jari 168 ''Group''::
788 18 Sep 08 jari 169   This will specify how the assays will be grouped together. It can
788 18 Sep 08 jari 170   either be a %-number used in assayname or an annotation type.
788 18 Sep 08 jari 171
788 18 Sep 08 jari 172   Example 1: Assays; Assay_1_A, Assay_2_A, Assay_1_B and Assay_2_B can
788 18 Sep 08 jari 173   be sorted into groups of assays using merge.
788 18 Sep 08 jari 174
788 18 Sep 08 jari 175   A: Setting the parameter \221Assayname\222 = %1_%2_%3 and parameter
788 18 Sep 08 jari 176   \221Group\222 = %2 will sort the assays into two groups.
788 18 Sep 08 jari 177 {{{
788 18 Sep 08 jari 178 One group were %2=1  (assays Assay_1_A and Assay_1_B)
788 18 Sep 08 jari 179 One group were %2=2  (assays Assay_2_A and Assay_2_B)
788 18 Sep 08 jari 180 }}}
788 18 Sep 08 jari 181   B: Setting the parameter \221Assayname\222 = %1_%2_%3 and parameter
788 18 Sep 08 jari 182   \221Group\222 = %3 will sort the assays into two groups.
788 18 Sep 08 jari 183 {{{
788 18 Sep 08 jari 184 One group were %3=A  (assays Assay_1_A and Assay_2_A)
788 18 Sep 08 jari 185 One group were %3=B  (assays Assay_1_B and Assay_1_B)
788 18 Sep 08 jari 186 }}}
788 18 Sep 08 jari 187
788 18 Sep 08 jari 188 ''New name''::
788 18 Sep 08 jari 189   This text will be used in the name of the merged assays. The name
788 18 Sep 08 jari 190   will be this string followed by the groupname.
788 18 Sep 08 jari 191
788 18 Sep 08 jari 192 ''Merge method''::
877 05 Dec 08 jari 193   Choose one of the methods described above.
788 18 Sep 08 jari 194
788 18 Sep 08 jari 195 ''Ratio''::
788 18 Sep 08 jari 196   If merge method `ratio of ratio` is chosen the form of the ratio
788 18 Sep 08 jari 197   must be specified. This is done either in the ratio parameter or in
788 18 Sep 08 jari 198   ratio annotation type and ratio annotation value. In the ratio
788 18 Sep 08 jari 199   parameter you can choose a %-number followed by the two values it
788 18 Sep 08 jari 200   can take. The last character in the string must be the delimiter the
877 05 Dec 08 jari 201   user has chosen to use. The other way a user can specify the ratio
788 18 Sep 08 jari 202   is by choosing an annotation type in the list and specify the values
788 18 Sep 08 jari 203   in the annotation values parameter. This is done by writing the
788 18 Sep 08 jari 204   values with the delimiter used last,
788 18 Sep 08 jari 205 {{{
788 18 Sep 08 jari 206 %1|vr1|vr2|
788 18 Sep 08 jari 207 }}}
788 18 Sep 08 jari 208   This will take the values from %1 in the assayname and put the assay
788 18 Sep 08 jari 209   with value vr1 over the assay with values vr2. Notice that the final
788 18 Sep 08 jari 210   character is the delimiter (this can of course be any character).
788 18 Sep 08 jari 211
788 18 Sep 08 jari 212   Example 2: Assays; Assay_1_A, Assay_2_A, Assay_1_B and Assay_2_B can be
788 18 Sep 08 jari 213   sorted into groups of assays using merge.
788 18 Sep 08 jari 214
788 18 Sep 08 jari 215   A: Setting the parameter \221Assayname\222 = %1_%2_%3 and parameter
788 18 Sep 08 jari 216   \221Group\222 = %2 will sort the assays into two groups.
788 18 Sep 08 jari 217 {{{
788 18 Sep 08 jari 218 One group were %2=1  (assays Assay_1_A and Assay_1_B)
788 18 Sep 08 jari 219 One group were %2=2  (assays Assay_2_A and Assay_2_B)
788 18 Sep 08 jari 220 }}}
788 18 Sep 08 jari 221   B: By setting parameter \221Ratio\222 = %3|A|B| ratios of ratios
788 18 Sep 08 jari 222   will be created as:
788 18 Sep 08 jari 223 {{{
788 18 Sep 08 jari 224 Assay_1_A / Assay_1_B
788 18 Sep 08 jari 225 Assay_2_A / Assay_2_B
788 18 Sep 08 jari 226 }}}
788 18 Sep 08 jari 227
788 18 Sep 08 jari 228 === References ===
788 18 Sep 08 jari 229
788 18 Sep 08 jari 230 [http://mathworld.wolfram.com/ArithmeticMean.html Arithmetic mean] [[br]]
788 18 Sep 08 jari 231 [http://mathworld.wolfram.com/GeometricMean.html Geometric mean]
788 18 Sep 08 jari 232
788 18 Sep 08 jari 233
766 16 Sep 08 jari 234 ----------------------------------------------------------------------
766 16 Sep 08 jari 235 {{{
766 16 Sep 08 jari 236 Copyright (C) 2008 Jari Häkkinen
766 16 Sep 08 jari 237
776 18 Sep 08 jari 238 This file is part of the se.lu.onk.MergeBioAssay plug-in for
766 16 Sep 08 jari 239 BASE. Available at http://baseplugins.thep.lu.se/ and BASE web site is
766 16 Sep 08 jari 240 http://base.thep.lu.se
766 16 Sep 08 jari 241
766 16 Sep 08 jari 242 This is free software; you can redistribute it and/or modify it under
766 16 Sep 08 jari 243 the terms of the GNU General Public License as published by the Free
766 16 Sep 08 jari 244 Software Foundation; either version 3 of the License, or (at your
766 16 Sep 08 jari 245 option) any later version.
766 16 Sep 08 jari 246
766 16 Sep 08 jari 247 This package is distributed in the hope that it will be useful, but
766 16 Sep 08 jari 248 WITHOUT ANY WARRANTY; without even the implied warranty of
766 16 Sep 08 jari 249 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
766 16 Sep 08 jari 250 General Public License for more details.
766 16 Sep 08 jari 251
766 16 Sep 08 jari 252 You should have received a copy of the GNU General Public License
766 16 Sep 08 jari 253 along with this package. If not, see <http://www.gnu.org/licenses/>.
766 16 Sep 08 jari 254 }}}

Generated on Tue Nov 21 03:41:41 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)