From 012ce7b27090ab309678b930b802fb5e49a89637 Mon Sep 17 00:00:00 2001
From: Sanuj <sanuj.sharma.in@gmail.com>
Date: Mon, 18 Jul 2016 12:52:10 +0530
Subject: [PATCH] add cookbook for euclidean distance

---
 .../source/examples/distance/euclidean.rst    | 43 +++++++++++++++++++
 examples/meta/src/distance/euclidean.sg       | 24 +++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 doc/cookbook/source/examples/distance/euclidean.rst
 create mode 100644 examples/meta/src/distance/euclidean.sg

diff --git a/doc/cookbook/source/examples/distance/euclidean.rst b/doc/cookbook/source/examples/distance/euclidean.rst
new file mode 100644
index 00000000000..f83808a02c9
--- /dev/null
+++ b/doc/cookbook/source/examples/distance/euclidean.rst
@@ -0,0 +1,43 @@
+==================
+Euclidean Distance
+==================
+
+The Euclidean distance for real valued features is the square root of the sum of squared disparity between the corresponding feature dimensions of two data points.
+
+.. math::
+
+    d({\bf x},{\bf x'})= \sqrt{\sum_{i=0}^{d}|{\bf x_i}-{\bf x'_i}|^2}
+
+where :math:`\bf x` and :math:`\bf x'` are :math:`d` dimensional feature vectors.
+
+-------
+Example
+-------
+
+Imagine we have files with data. We create CDenseFeatures (here 64 bit floats aka RealFeatures) as
+
+.. sgexample:: euclidean.sg:create_features
+
+We create an instance of :sgclass:`CEuclideanDistance` by passing it :sgclass:`CDenseFeatures`.
+
+.. sgexample:: euclidean.sg:create_instance
+
+Distance matrix can be extracted as follows:
+
+.. sgexample:: euclidean.sg:extract_distance
+
+We can use the same instance with new :sgclass:`CDenseFeatures` to compute distance.
+
+.. sgexample:: euclidean.sg:refresh_distance
+
+If desired, squared distance can be extracted like:
+
+.. sgexample:: euclidean.sg:extract_sq_distance
+
+----------
+References
+----------
+:wiki:`Euclidean_distance`
+
+.. bibliography:: ../../references.bib
+    :filter: docname in docnames
diff --git a/examples/meta/src/distance/euclidean.sg b/examples/meta/src/distance/euclidean.sg
new file mode 100644
index 00000000000..289dabedfd9
--- /dev/null
+++ b/examples/meta/src/distance/euclidean.sg
@@ -0,0 +1,24 @@
+CSVFile f_feats_a("../../data/fm_train_real.dat")
+CSVFile f_feats_b("../../data/fm_test_real.dat")
+
+#![create_features]
+RealFeatures features_a(f_feats_a)
+RealFeatures features_b(f_feats_b)
+#![create_features]
+
+#![create_instance]
+EuclideanDistance distance(features_a, features_a)
+#![create_instance]
+
+#![extract_distance]
+RealMatrix distance_matrix_aa = distance.get_distance_matrix()
+#![extract_distance]
+
+#![refresh_distance]
+distance.init(features_a, features_b)
+#![refresh_distance]
+
+#![extract_sq_distance]
+distance.set_disable_sqrt(True)
+RealMatrix distance_matrix_ab = distance.get_distance_matrix()
+#![extract_sq_distance]