################################################################################
# This is the README file for RVKDE (http://mbi.ee.ncku.edu.tw/rvkde/) written
# in Dokuwiki syntax (http://wiki.splitbrain.org/wiki:dokuwiki).

====== Abstract ======
RVKDE, standing for Relaxed Variable Kernel Density Estimation, is an
integrated software of classification, regression and density estimation.  This
document explains the use of RVKDE.

RVKDE is available at 'http://mbi.ee.ncku.edu.tw/rvkde/'.  Please read the
COPYRIGHT file before using RVKDE.

====== Table of contents ======
  - Quick start
  - Installation and data format
  - __kde-train.pl__ usage
  - __kde-predict.pl__ usage
  - Additional tools
  - Additional information

====== Quick start ======
If you are new to RVKDE and if the data is not large, please go to __tool__
directory and use __kde-easy.pl__ after installation.  It does everything, from
data scaling to parameter selection, automatic.

<code>
Usage: kde-easy.pl TRAINING_FILE [TESTING_FILE]
</code>

More information about parameter selection can be found in __tool/README__

====== Installation and data format ======
**On Linux systems**
  - Donwload the latest version from the official site of RVKDE.<code>
wget http://mbi.ee.ncku.edu.tw/rvkde/res/rvkde-current-linux32.tgz
</code>
  - Extract the archive.<code>
tar zxvf rvkde-current-linux32.tgz
</code>
  - Execute them without arguments to show the usages.<code>
kde-train.pl
kde-predict.pl
</code>

--------------------------------------------------------------------------------
**On Windows systems**

Before installing RVKDE, please make sure that Perl is installed.
[[http://www.activestate.com/|ActivePerl]] is a good Perl Distribution for
Windows.
  - Donwload the latest version from the official site of RVKDE.<code>
wget http://mbi.ee.ncku.edu.tw/rvkde/res/rvkde-current-win32.tgz
</code>
  - Extract the archive using a compressor (e.g. 7-zip, WinRAR or WinZip). 
  - Invoke the Windows console.<code>
[Start] -> [Run] -> Type 'cmd' -> [OK]
</code>
  - Execute them without arguments to show the usages.
  - Using __cd__ to the directory of your extracted RVKDE.
  - Execute them without arguments to show the usages.<code>
kde-train.pl
kde-predict.pl
</code>

The format of training and testing data file is:

<file>
<value> <index1>:<feature1> <index2>:<feature2> ...
.
.
.
</file>

Each line contains an instance and is ended by a '\n' character.  For
classification, <value> is an integer indicating the class label (multi-class
is supported).  For regression, <value> is the target value which can be any
real number.  <index>:<feature> gives a feature (attribute) value.  <index> is
an integer starting from 1 and <feature> is a real number.  Labels in the
testing file are only used to calculate accuracy or errors.  If they are
unknown, just fill the first column with any numbers.

A sample classification data included in this package is __satimage__.  Type
__kde-train.pl satimage.scale__, and the program will read the training data
and output the model file __satimage.scale.model__.  If you have a test set
called __satimage.scale.t__, then type __kde-predict.pl satimage.scale.t
satimage.scale.model output__ to see the prediction accuracy.  The __output__
file contains the predicted class labels.<code>
kde-train.pl satimage.scale # train
kde-predict.pl satimage.scale.t satimage.scale.model output # predict
vi output # predicted results
</code>

====== kde-train.pl usage ======
<code>
Usage: kde-train.pl [OPTION]... TRAINING_FILE [MODEL_FILE]
kde-train.pl is a Perl wrapper for RVKDE to make the using of RVKDE like
LIBSVM.  Make sure the rvkde binary executable file is in the same directory
of this script.

Options:
  -a  alpha: set alpha in kernel function (default: 1)
  -b  beta: set beta in kernel function (default: 1)
  -h  print this help, then exit
  -s  ks: set maximum ks in kernel function (default: 10)
  -t  kt: set kt in kernel function (default: 10)
  -v  n: n-fold cross validation mode

Examples:
  kde-train.pl satimage.scale # generate satimage.scale.model
  kde-train.pl satimage.scale satimage.scale.kde-model # different model name
  kde-train.pl -v 5 satimage.scale # five-fold cross validation
  kde-train.pl -s 30 satimage.scale # using different parameters

Option -v splits the data into n parts by modulo arithmetic and calculates
cross validation performance on them.

Report bugs to <darby@ee.ncku.edu.tw>.
</code>

====== kde-predict.pl usage ======
<code>
Usage: kde-predict.pl [OPTION]... TESTING_FILE MODEL_FILE OUTPUT_FILE
kde-predict.pl is a Perl wrapper for RVKDE to make the using of RVKDE like
LIBSVM.  Make sure the rvkde binary executable file is in the same directory
of this script.

Options:
  -a  alpha: set alpha in kernel function (default: 1)
  -b  beta: set beta in kernel function (default: 1)
  -h  print this help, then exit
  -s  ks: set ks in kernel function (default: 10)
  -t  kt: set kt in kernel function (default: 10)

  TESTING_FILE is the testing data you want to predict.
  MODEL_FILE is the model file generated by kde-train.pl.
  OUTPUT_FILE contains the predicted results by RVKDE.

Examples:
  kde-predict.pl satimage.scale.t satimage.scale.model output
  kde-predict.pl -s 30 -t 30 satimage.scale.t satimage.scale.model output

Unlike LIBSVM, RVKDE is a lazy-learning tool.  The model file contains only
basic information and the real prediction model is constructed right before the
prediction operation.  It means you can specify different parameters (alpha,
beta, ks and kt) for kde-predict.pl as those specified for kde-train.pl.  Only
one condition must be hold: the ks for kde-predict.pl is less than or equal to
the ks for kde-train.pl.

Report bugs to <darby@ee.ncku.edu.tw>.
</code>

====== Additional tools ======
See the README file in the tool directory.

====== Additional information ======
If you find RVKDE helpful, please cite it as

Yen-Jen Oyang, Shien-Ching Hwang, Yu-Yen Ou, Chien-Yu Chen, and Zhi-Wei Chen.
Data Classification with the Radial Basis Function Network Based on a Novel
Kernel Density Estimation Algorithm.  //IEEE Transactions on Neural Networks//,
**16**, 225-236, 2005.

Software available at 'http://mbi.ee.ncku.edu.tw/rvkde/'.

For any questions and comments, please email darby@ee.ncku.edu.tw

Acknowledgments:
This work was supported in part by the National Science Council of Taiwan via
the grant NSC 92-2213-E-002-095.  The authors thank their group members and
users for many helpful discussions and comments.
