From 7c51fef1bc31bdcc4cd5adb8d96791bf8291e7fb Mon Sep 17 00:00:00 2001
From: Dongryeol Lee <drselee@gmail.com>
Date: Mon, 21 Jan 2008 02:26:18 +0000
Subject: [PATCH] Extensive commenting and instructions on how to run fast kde
 is completed

---
 fastlib/u/dongryel/kde/kde.h       | 21 ++++++-----
 fastlib/u/dongryel/kde/kde_main.cc | 60 +++++++++++++++++++++++++++++-
 2 files changed, 71 insertions(+), 10 deletions(-)

diff --git a/fastlib/u/dongryel/kde/kde.h b/fastlib/u/dongryel/kde/kde.h
index 520b138978..797d89d892 100644
--- a/fastlib/u/dongryel/kde/kde.h
+++ b/fastlib/u/dongryel/kde/kde.h
@@ -15,8 +15,7 @@
  * published conference papers (in chronological order):
  *
  * @inproceedings{DBLP:conf/sdm/GrayM03,
- *  author    = {Alexander G. Gray and
- *               Andrew W. Moore},
+ *  author    = {Alexander G. Gray and Andrew W. Moore},
  *  title     = {Nonparametric Density Estimation: Toward Computational 
  *               Tractability},
  *  booktitle = {SDM},
@@ -48,8 +47,7 @@
  * }
  *
  * @inproceedings{DBLP:conf/uai/LeeG06,
- *  author    = {Dongryeol Lee and
- *               Alexander G. Gray},
+ *  author    = {Dongryeol Lee and Alexander G. Gray},
  *  title     = {Faster Gaussian Summation: Theory and Experiment},
  *  booktitle = {UAI},
  *  year      = {2006},
@@ -84,12 +82,16 @@
  *
  * @code
  *   FastKde fast_kde;
- *   struct datanode* allnn_module;
- *   ArrayList<index_t> results;
+ *   struct datanode* kde_module;
+ *   Vector results;
  *
- *   allnn_module = fx_submodule(NULL, "allnn", "allnn");
- *   allnn.Init(query_set, reference_set, allnn_module);
- *   allnn.ComputeNeighbors(&results);
+ *   kde_module = fx_submodule(NULL, "kde", "kde");
+ *   fast_kde.Init(queries, references, queries_equal_references,
+ *                 kde_module);
+ *   fast_kde.Compute(); 
+ *   
+ *   // important to make sure that you don't call Init on results!
+ *   fast_kde.get_density_estimates(&results);
  * @endcode
  */
 template<typename TKernelAux>
@@ -149,6 +151,7 @@ class FastKde {
       // get bandwidth and relative error
       bandwidth_ = fx_param_double_req(module, "bandwidth");
       relative_error_ = fx_param_double(module, "relative_error", 0.1);
+      DEBUG_ASSERT(bandwidth_ > 0 && relative_error_ > 0);
 
       // temporarily initialize these to -1's
       dimension_ = reference_count_ = query_count_ = -1;
diff --git a/fastlib/u/dongryel/kde/kde_main.cc b/fastlib/u/dongryel/kde/kde_main.cc
index 4ebc80feac..57b8b2803f 100644
--- a/fastlib/u/dongryel/kde/kde_main.cc
+++ b/fastlib/u/dongryel/kde/kde_main.cc
@@ -1,10 +1,68 @@
-#include "fastlib/fastlib_int.h"
+/** @file kde_main.cc
+ *
+ *  Driver file for fast KDE algorithm.
+ *
+ *  @author Dongryeol Lee (dongryel)
+ */
+
+#include <fastlib/fastlib.h>
 #include "dataset_scaler.h"
 #include "kde.h"
 #include "naive_kde.h"
 
+/**
+ * Main function which reads parameters and determines which
+ * algorithms to run.
+ *
+ * In order to compile this driver, do:
+ * fl-build kde_bin --mode=fast
+ *
+ * In order to run this driver for the fast KDE algorithms, type the
+ * following (which consists of both required and optional arguments)
+ * in a single command line:
+ *
+ * ./kde_bin --data=name_of_the_reference_dataset
+ *           --query=name_of_the_query_dataset 
+ *           --kde/bandwidth=0.0130619
+ *           --kde/scaling=range 
+ *           --kde/multiplicative_expansion
+ *           --kde/fast_kde_output=fast_kde_output.txt
+ *           --kde/naive_kde_output=naive_kde_output.txt 
+ *           --kde/do_naive
+ *           --kde/relative_error=0.01
+ *
+ * Explanations for the arguments listed with possible values: 
+ * 1. data (required): the name of the reference dataset
+ * 2. query (optional): the name of the query dataset (if missing, the query 
+ *    dataset is assumed to be the same as the reference dataset)
+ * 3. kde/kernel (optional): kernel function to use
+ *    - gaussian: Gaussian kernel (default)
+ *    - epan: Epanechnikov kernel
+ * 4. kde/bandwidth (required): smoothing parameter used for KDE; this has
+ *    to be positive.
+ * 5. kde/scaling (optional): whether to prescale the dataset
+ *    - range: scales both the query and the reference sets to be within
+ *             the unit hypercube [0, 1]^D where D is the dimensionality.
+ *    - none: default value; no scaling
+ * 6. kde/multiplicative_expansion (optional): 
+ *    If this flag is present, the series expansion for the Gaussian kernel 
+ *    uses O(p^D) expansion. Otherwise, the Gaussian kernel uses O(D^p) 
+ *    expansion. See kde.h for details.
+ * 7. kde/do_naive (optional): run the naive algorithm after the 
+ *                             fast algorithm.
+ * 8. kde/fast_kde_output (optional): if this flag is present, the approximated
+ *    density estimates are output to the filename provided after it.
+ * 9. kde/naive_kde_output (optional): if this flag is present, the exact 
+ *    density estimates computed by the naive algorithm are output to the 
+ *    filename provided after it. This flag is not ignored if --kde/do_naive 
+ *    flag is not present.
+ * 10. kde/relative_error (optional): relative error criterion for the fast 
+ *     algorithm; default value is 0.1 (10 % relative error for all query
+ *     density estimates).
+ */
 int main(int argc, char *argv[]) {
 
+  // initialize FastExec (parameter handling stuff)
   fx_init(argc, argv);
 
   ////////// READING PARAMETERS AND LOADING DATA /////////////////////