plugins/base1/se.lu.thep.wenni/trunk/README

Code
Comments
Other
Rev Date Author Line
69 11 Feb 06 jari 1 $Id$
69 11 Feb 06 jari 2
317 28 May 07 peter 3 ----------------------------------------------------------------------
317 28 May 07 peter 4 {{{
95 05 Apr 06 jari 5 Copyright (C) 2005, 2006 Jari Häkkinen, Peter Johansson
317 28 May 07 peter 6 Copyright (C) 2007 Peter Johansson
665 16 Apr 08 jari 7 Copyright (C) 2008 Jari Häkkinen
95 05 Apr 06 jari 8
95 05 Apr 06 jari 9 This file is part of WeNNI,
825 26 Nov 08 jari 10 http://baseplugins.thep.lu.se/wiki/se.lu.thep.WeNNI
95 05 Apr 06 jari 11
95 05 Apr 06 jari 12 WeNNI is free software; you can redistribute it and/or modify it under
95 05 Apr 06 jari 13 the terms of the GNU General Public License as published by the Free
824 26 Nov 08 jari 14 Software Foundation; either version 3 of the License, or (at your
95 05 Apr 06 jari 15 option) any later version.
95 05 Apr 06 jari 16
95 05 Apr 06 jari 17 WeNNI is distributed in the hope that it will be useful, but WITHOUT
95 05 Apr 06 jari 18 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
95 05 Apr 06 jari 19 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
95 05 Apr 06 jari 20 for more details.
95 05 Apr 06 jari 21
95 05 Apr 06 jari 22 You should have received a copy of the GNU General Public License
824 26 Nov 08 jari 23 along with WeNNI. If not, see <http://www.gnu.org/licenses/>.
317 28 May 07 peter 24 }}}
317 28 May 07 peter 25 ----------------------------------------------------------------------
95 05 Apr 06 jari 26
95 05 Apr 06 jari 27
824 26 Nov 08 jari 28 = License =
824 26 Nov 08 jari 29
824 26 Nov 08 jari 30 WeNNI is free software released under therms of GPL3. See `COPYING`
824 26 Nov 08 jari 31 for the GPL3 license text.
824 26 Nov 08 jari 32
824 26 Nov 08 jari 33
824 26 Nov 08 jari 34 = Feedback =
824 26 Nov 08 jari 35
69 11 Feb 06 jari 36 Send comments, suggestion, complaints, or questions about this
69 11 Feb 06 jari 37 document to jari@thep.lu.se
69 11 Feb 06 jari 38
69 11 Feb 06 jari 39
824 26 Nov 08 jari 40 = How to cite WeNNI =
824 26 Nov 08 jari 41
115 22 Jun 06 jari 42 Please use the below reference if you use WeNNI in connection with
115 22 Jun 06 jari 43 scientific publications:
115 22 Jun 06 jari 44
115 22 Jun 06 jari 45 "Improving missing value imputation of microarray data by using spot
115 22 Jun 06 jari 46 quality weights", P. Johansson and J. Häkkinen. BMC Bioinformatics 7,
115 22 Jun 06 jari 47 306 (2006)
115 22 Jun 06 jari 48
115 22 Jun 06 jari 49
824 26 Nov 08 jari 50 = Installation =
824 26 Nov 08 jari 51
828 27 Nov 08 jari 52 For installation and compilation instructions please read `INSTALL`.
69 11 Feb 06 jari 53
69 11 Feb 06 jari 54
824 26 Nov 08 jari 55 = Comments on WeNNI =
115 22 Jun 06 jari 56
828 27 Nov 08 jari 57  1. WeNNI is presented in the article referenced above.
115 22 Jun 06 jari 58
828 27 Nov 08 jari 59  2. The notion of weights becomes obsolete after running WeNNI, i.e.,
828 27 Nov 08 jari 60     do not use the weight fed into WeNNI in any subsequent analysis
828 27 Nov 08 jari 61     because all weights are now strictly 1.
115 22 Jun 06 jari 62
828 27 Nov 08 jari 63  3. Running WeNNI as a BASE plug-in makes WeNNI destined to impute log
828 27 Nov 08 jari 64     ratios of channel 1 and channel 2 (M values in BASE world). A
828 27 Nov 08 jari 65     consequence of imputing log ratios is that a change in ratio
828 27 Nov 08 jari 66     cannot be assigned to a specific channel. This implies that
828 27 Nov 08 jari 67     log(channel1*channel2) (A values in BASE world) become undefined
828 27 Nov 08 jari 68     and useless. However, on request from BASE users it was decided
828 27 Nov 08 jari 69     that A values should not be affected by the transformation in
828 27 Nov 08 jari 70     cases where the A value is well defined before imputation. In
828 27 Nov 08 jari 71     cases when an A value do not exist before transformation
828 27 Nov 08 jari 72     (i.e. channel1<=0 or channel2<=0) it was decided that A should be
828 27 Nov 08 jari 73     set to 0. NOTE, this does not change the underlying WeNNI
828 27 Nov 08 jari 74     algorithm in any way but is rather conventions needed for BASE
828 27 Nov 08 jari 75     plug-in usage.
115 22 Jun 06 jari 76
828 27 Nov 08 jari 77  4. Remember, if you installed the software as a BASE plug-in, please
828 27 Nov 08 jari 78     log on to the server and make the server aware of the plug-in. The
828 27 Nov 08 jari 79     BASE1 plug-in definition file can be found in directory
828 27 Nov 08 jari 80     `base/base1/base_plugin_script` as file `plugin_WeNNI.base`. BASE2
828 27 Nov 08 jari 81     users should follow the plug-in installation instructions in the
828 27 Nov 08 jari 82     BASE2 manual available at http://base.thep.lu.se.
115 22 Jun 06 jari 83
69 11 Feb 06 jari 84
828 27 Nov 08 jari 85 = WeNNI package details =
69 11 Feb 06 jari 86
828 27 Nov 08 jari 87 If you installed the software as a stand alone package two binaries
828 27 Nov 08 jari 88 where created `NNIFileConverter` and `nni`. If your input file is a
828 27 Nov 08 jari 89 BASEfile you probably want to compile this package in BASE1 mode
828 27 Nov 08 jari 90 instead (see `INSTALL` for compilation instructions).
69 11 Feb 06 jari 91
828 27 Nov 08 jari 92 The three programs will take you from a BASEfile to an imputed matrix
828 27 Nov 08 jari 93 by running them in the order below (examples 1 to 3). There is no need
828 27 Nov 08 jari 94 to run all steps, i.e., you can generate a data (matrix) file with an
828 27 Nov 08 jari 95 associated weights matrix file and just run `nni` to impute missing
828 27 Nov 08 jari 96 values.
69 11 Feb 06 jari 97
828 27 Nov 08 jari 98 There is a 4th example below where the `wenni.pl` script (found in
828 27 Nov 08 jari 99 directory `./base/base1/base_plugin_script/`) is used to run all
828 27 Nov 08 jari 100 examples 1 through 3. `wenni.pl` also generates a result BASEfile that
828 27 Nov 08 jari 101 a BASE1 server would accept as a result file (and import it into the
828 27 Nov 08 jari 102 database) when running `wenni.pl` as a plug-in from within BASE1.
69 11 Feb 06 jari 103
828 27 Nov 08 jari 104 {{{
69 11 Feb 06 jari 105 1) BaseFileConverter.
69 11 Feb 06 jari 106
69 11 Feb 06 jari 107    Extracts columns from a file exported from BASE, and writes the
69 11 Feb 06 jari 108    extracted data into files in matrix form. What data should be
828 27 Nov 08 jari 109    extracted from the BASEfile is set by command line options.
69 11 Feb 06 jari 110
69 11 Feb 06 jari 111    Command syntax:
69 11 Feb 06 jari 112
69 11 Feb 06 jari 113       BaseFileConverter <basefile> <string> -<fieldtype> <fieldname> ...
69 11 Feb 06 jari 114
69 11 Feb 06 jari 115      or
69 11 Feb 06 jari 116
69 11 Feb 06 jari 117       BaseFileConverter <basefile> -show
69 11 Feb 06 jari 118
69 11 Feb 06 jari 119    where
69 11 Feb 06 jari 120
69 11 Feb 06 jari 121       <basefile> is the file exported from BASE.
69 11 Feb 06 jari 122       <string> is a string added to the beginning of all matrix files created.
828 27 Nov 08 jari 123       <fieldtype> defines which field should be extracted from the BASEfile.
69 11 Feb 06 jari 124       <fieldname> the name of the column to extract.
69 11 Feb 06 jari 125       ... means that the two last option can be defined several times. This to
70 13 Feb 06 jari 126           facilitate export of several fields in one run.
69 11 Feb 06 jari 127
828 27 Nov 08 jari 128       -show will output available fieldtypes and fieldnames in the BASEfile.
69 11 Feb 06 jari 129
69 11 Feb 06 jari 130    Example
69 11 Feb 06 jari 131  
828 27 Nov 08 jari 132    a) This is an example on how to extract data from a sample BASEfile
828 27 Nov 08 jari 133       available in the data directory (data/basefile_in.data)
69 11 Feb 06 jari 134
69 11 Feb 06 jari 135       ./BaseFileConverter basefile_in.data wenni_ -assayFields FCh1Mean \
69 11 Feb 06 jari 136                                                   -assayFields BCh1Mean \
69 11 Feb 06 jari 137                                                   -assayFields FCh2Mean \
69 11 Feb 06 jari 138                                                   -assayFields BCh2Mean \
69 11 Feb 06 jari 139                                                   -assayFields BCh1SD   \
69 11 Feb 06 jari 140                                                   -assayFields BCh2SD
69 11 Feb 06 jari 141
69 11 Feb 06 jari 142       Six files will be created: wenni_BCh1Mean.data, wenni_BCh1SD.data,
69 11 Feb 06 jari 143                                  wenni_BCh2Mean.data, wenni_BCh2SD.data,
69 11 Feb 06 jari 144                                  wenni_FCh1Mean.data, wenni_FCh2Mean.data
69 11 Feb 06 jari 145
828 27 Nov 08 jari 146    b) Another example on how to extract data from a sample BASEfile
69 11 Feb 06 jari 147       available in the data directory (data/basefile_in.data)
69 11 Feb 06 jari 148
69 11 Feb 06 jari 149       ./BaseFileConverter basefile_in.data wenni_ -assayFields intensity1 \
69 11 Feb 06 jari 150                                                   -assayFields intensity2 \
69 11 Feb 06 jari 151                                                   -assayFields BCh1SD     \
69 11 Feb 06 jari 152                                                   -assayFields BCh2SD
69 11 Feb 06 jari 153
69 11 Feb 06 jari 154       Four files will be created: wenni_intensity1.data, wenni_BCh1SD.data,
69 11 Feb 06 jari 155                                   wenni_intensity2.data, wenni_BCh2SD.data
69 11 Feb 06 jari 156
69 11 Feb 06 jari 157
69 11 Feb 06 jari 158 2) NNIFileConverter
69 11 Feb 06 jari 159
69 11 Feb 06 jari 160    This program merges the six files created in with BaseFileConverter
69 11 Feb 06 jari 161    into two files: a logratio matrix file and a weight matrix file.
69 11 Feb 06 jari 162
69 11 Feb 06 jari 163    Command syntax:
69 11 Feb 06 jari 164
69 11 Feb 06 jari 165       NNIFilerConverter -o option
69 11 Feb 06 jari 166
69 11 Feb 06 jari 167    with the following available options
69 11 Feb 06 jari 168
69 11 Feb 06 jari 169       -beta     the beta parameter of the snr to weight calculation.
69 11 Feb 06 jari 170       -datatype Values 'raw' or 'derived' . When 'derived' is given,
69 11 Feb 06 jari 171                 only foreground files are expected, and background
69 11 Feb 06 jari 172                 files ignored (cf. options -fg1, -fg2, -bg1, and -bg2.
69 11 Feb 06 jari 173       -fg1      input file first foreground
69 11 Feb 06 jari 174       -bg1      input file first background
69 11 Feb 06 jari 175       -bgstd1   input file first background standard deviation
69 11 Feb 06 jari 176       -fg2      input file second foreground
69 11 Feb 06 jari 177       -bg2      input file second background
69 11 Feb 06 jari 178       -bgstd2   input file second background standard deviation
69 11 Feb 06 jari 179       -logratio output file logratio (first/second)
69 11 Feb 06 jari 180       -weight   output file weight
69 11 Feb 06 jari 181
69 11 Feb 06 jari 182    Example
69 11 Feb 06 jari 183  
69 11 Feb 06 jari 184    c) This is an example on how to merge the files created in the
69 11 Feb 06 jari 185       BaseFileConverter example a) above.
69 11 Feb 06 jari 186
69 11 Feb 06 jari 187       ./NNIFileConverter -beta 0.6 \
69 11 Feb 06 jari 188                          -bg1 wenni_BCh1Mean.data \
69 11 Feb 06 jari 189                          -bg2 wenni_BCh2Mean.data \
69 11 Feb 06 jari 190                          -bgstd1 wenni_BCh1SD.data \
69 11 Feb 06 jari 191                          -bgstd2 wenni_BCh2SD.data \
69 11 Feb 06 jari 192                          -fg1 wenni_FCh1Mean.data \
69 11 Feb 06 jari 193                          -fg2 wenni_FCh2Mean.data \
69 11 Feb 06 jari 194                          -logratio wenni_logratio.data \
69 11 Feb 06 jari 195                          -weight wenni_weight.data
69 11 Feb 06 jari 196
69 11 Feb 06 jari 197       Two files will be created: wenni_logratio.data wenni_weight.data
69 11 Feb 06 jari 198
69 11 Feb 06 jari 199    d) Another example on how to merge the files created in the
69 11 Feb 06 jari 200       BaseFileConverter example b) above.
69 11 Feb 06 jari 201
69 11 Feb 06 jari 202       ./NNIFileConverter -beta 0.6 \
69 11 Feb 06 jari 203                          -bgstd1 wenni_BCh1SD.data \
69 11 Feb 06 jari 204                          -bgstd2 wenni_BCh2SD.data \
70 13 Feb 06 jari 205                          -datatype derived \
69 11 Feb 06 jari 206                          -fg1 wenni_intensity1.data \
69 11 Feb 06 jari 207                          -fg2 wenni_intensity2.data \
69 11 Feb 06 jari 208                          -logratio wenni_logratio.data \
69 11 Feb 06 jari 209                          -weight wenni_weight.data
69 11 Feb 06 jari 210
69 11 Feb 06 jari 211       Two files will be created: wenni_logratio.data
70 13 Feb 06 jari 212       wenni_weight.data. If you followed the examples carefully,
69 11 Feb 06 jari 213       using provided sample files, these result files should be the
69 11 Feb 06 jari 214       same as the ones produced in example c).
69 11 Feb 06 jari 215
69 11 Feb 06 jari 216
69 11 Feb 06 jari 217 3) nni
69 11 Feb 06 jari 218
70 13 Feb 06 jari 219    Perform missing value imputation on a data matrix with associated
74 15 Feb 06 jari 220    weights. Weights may be SNR, see options.
69 11 Feb 06 jari 221
70 13 Feb 06 jari 222    The input matrices are read from files and the resulting matrix is
70 13 Feb 06 jari 223    written to stdout.
69 11 Feb 06 jari 224
69 11 Feb 06 jari 225    Command syntax:
69 11 Feb 06 jari 226
69 11 Feb 06 jari 227       nni -o option
69 11 Feb 06 jari 228
69 11 Feb 06 jari 229    with the following available options
69 11 Feb 06 jari 230
74 15 Feb 06 jari 231       -beta:          set the beta value for weight calculation
74 15 Feb 06 jari 232                       This option is only used if the weights are SNR
74 15 Feb 06 jari 233                       rather than weights. See the WeNNI paper for
74 15 Feb 06 jari 234                       details on this parameter.
69 11 Feb 06 jari 235       -data           data file name
70 13 Feb 06 jari 236       -neighbours     number of nearest neighbours
69 11 Feb 06 jari 237                       This sets the number of contributions to use in
69 11 Feb 06 jari 238                       the imputation. For binary weights this
69 11 Feb 06 jari 239                       corresponds directly to closest neighbours,
69 11 Feb 06 jari 240                       whereas For non-binary weights the accumulated
69 11 Feb 06 jari 241                       weights are compared against the cutoff.
69 11 Feb 06 jari 242       -nni_algorithm  the algorithm to use
69 11 Feb 06 jari 243                       Available algorithms are kNNI and WeNNI and a
69 11 Feb 06 jari 244                       string is expected as the option
69 11 Feb 06 jari 245       -weight         weight file name
69 11 Feb 06 jari 246                       Weights must be within [0,1].
159 11 Aug 06 jari 247                       See -weight_cutoff parameter if kNNI algorithm is used.
74 15 Feb 06 jari 248       -weight_cutoff  set the cutoff value for weights
74 15 Feb 06 jari 249                       kNNI requires binary weights. All values larger than
74 15 Feb 06 jari 250                       the cutoff will be treated as 1s, and 0s otherwise.
74 15 Feb 06 jari 251       -weight_is_snr  weight file contains snr values rather than weights
74 15 Feb 06 jari 252                       Use -beta to tune the weights.
69 11 Feb 06 jari 253
74 15 Feb 06 jari 254
74 15 Feb 06 jari 255
69 11 Feb 06 jari 256    Example
69 11 Feb 06 jari 257  
69 11 Feb 06 jari 258    e) This is an example on how to (WeNNI) impute the data file using the
69 11 Feb 06 jari 259       associated weights file created by NNIFileConverter above:
69 11 Feb 06 jari 260
69 11 Feb 06 jari 261       ./nni -data wenni_logratio.data \
69 11 Feb 06 jari 262             -neighbours 10 \
69 11 Feb 06 jari 263             -nni_algorithm WeNNI \
70 13 Feb 06 jari 264             -weight wenni_weight.data > wenni_imputed.data
69 11 Feb 06 jari 265
70 13 Feb 06 jari 266       One file will be created: wenni_imputed.data
69 11 Feb 06 jari 267
74 15 Feb 06 jari 268    f) This is an example on how to (WeNNI) impute the data file using
74 15 Feb 06 jari 269       an SNR file instead of weights:
69 11 Feb 06 jari 270
74 15 Feb 06 jari 271       ./nni -beta 0.6 \
74 15 Feb 06 jari 272             -data wenni_logratio.data \
74 15 Feb 06 jari 273             -neighbours 10 \
74 15 Feb 06 jari 274             -nni_algorithm WeNNI \
74 15 Feb 06 jari 275             -weight wenni_snr.data \
159 11 Aug 06 jari 276             -weight_is_snr > wenni_imputed.data
74 15 Feb 06 jari 277
74 15 Feb 06 jari 278       One file will be created: wenni_imputed.data
83 04 Apr 06 jari 279       This file may differ slightly from the file generated in
74 15 Feb 06 jari 280       example e) above due to limited floating point precision.
74 15 Feb 06 jari 281
74 15 Feb 06 jari 282    g) This is an example on how to (KNNimpute) impute the data file
74 15 Feb 06 jari 283       using the associated weights file created by NNIFileConverter
74 15 Feb 06 jari 284       above:
74 15 Feb 06 jari 285
74 15 Feb 06 jari 286       ./nni -data wenni_logratio.data \
74 15 Feb 06 jari 287             -neighbours 10 \
74 15 Feb 06 jari 288             -nni_algorithm kNNI \
74 15 Feb 06 jari 289             -weight wenni_weight.data \
159 11 Aug 06 jari 290             -weight_cutoff 0.5 > knni_imputed.data
74 15 Feb 06 jari 291
74 15 Feb 06 jari 292       One file will be created: knni_imputed.data
74 15 Feb 06 jari 293
74 15 Feb 06 jari 294
69 11 Feb 06 jari 295 4) wenni.pl
69 11 Feb 06 jari 296
828 27 Nov 08 jari 297    Performs missing value imputation on data in a BASEfile. The
828 27 Nov 08 jari 298    BASEfile is read from stdin, and the resulting BASEfile is written
828 27 Nov 08 jari 299    to stdout. This is how a plug-in is expected to behave to make the
69 11 Feb 06 jari 300    BASE job runner happy.
69 11 Feb 06 jari 301
70 13 Feb 06 jari 302    Command syntax:
69 11 Feb 06 jari 303
665 16 Apr 08 jari 304       wenni.pl --option value < basefile_in.data > basefile_out.data
69 11 Feb 06 jari 305
70 13 Feb 06 jari 306    wenni.pl will read options from basefile_in.data, but the settings
70 13 Feb 06 jari 307    may be changed by corresponding command line options. The available
70 13 Feb 06 jari 308    command line options are
69 11 Feb 06 jari 309
69 11 Feb 06 jari 310       --beta       the beta parameter (cf. text to example 2).
69 11 Feb 06 jari 311       --datatype   string that defines data exported from BASE.
69 11 Feb 06 jari 312                    Allowed string values for datatype is 'raw' or
69 11 Feb 06 jari 313                    'derived' (without '' characters). When 'derived'
69 11 Feb 06 jari 314                    is given, the user defined intensity1 and
828 27 Nov 08 jari 315                    intensity2 will be used from the BASEfile. When
69 11 Feb 06 jari 316                    'raw' is used, intensity1 will be calculated as
69 11 Feb 06 jari 317                    FCh1Mean-BCh1Mean (intensity2 is defined
69 11 Feb 06 jari 318                    correspondingly).
70 13 Feb 06 jari 319       --neighbours number of nearest neighbours (cf. text to example 3).
69 11 Feb 06 jari 320       --nodelete   Do not clean up, i.e. temporary files will not be
69 11 Feb 06 jari 321                    deleted.
69 11 Feb 06 jari 322
69 11 Feb 06 jari 323    Example
69 11 Feb 06 jari 324
74 15 Feb 06 jari 325    h) wenni.pl will basically run through examples 1a, 2c, and 3e
828 27 Nov 08 jari 326       sequentially, and produce a BASEfile with the imputed
70 13 Feb 06 jari 327       values. 'raw' type of input data is demanded by the command line
828 27 Nov 08 jari 328       options --datatype. Other options are read from the input
828 27 Nov 08 jari 329       BASEfile. Intermediate files will not be deleted
69 11 Feb 06 jari 330
69 11 Feb 06 jari 331       ./wenni.pl --datatype raw --nodelete < basefile_in.data > basefile_out.data
69 11 Feb 06 jari 332
74 15 Feb 06 jari 333    i) wenni.pl will basically run through examples 1b, 2d, and 3e
828 27 Nov 08 jari 334       sequentially, and produce a BASEfile with the imputed
70 13 Feb 06 jari 335       values. 'derived' type of data is expected ('derived' type is
828 27 Nov 08 jari 336       default). Options are read from the input BASEfile.
828 27 Nov 08 jari 337       Intermediate files are deleted.
69 11 Feb 06 jari 338
69 11 Feb 06 jari 339       ./wenni.pl < basefile_in.data > basefile_out.data
828 27 Nov 08 jari 340 }}}

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