From 1ec702a1e5478b36b8009cba67e29adcdc53e7e3 Mon Sep 17 00:00:00 2001
From: Bert Chang <jrweizhang@gmail.com>
Date: Sat, 3 May 2014 23:05:24 +0800
Subject: [PATCH] Add documents.

---
 metrics/pairwise/euclidean.go       | 4 +++-
 metrics/pairwise/manhattan.go       | 2 ++
 metrics/pairwise/pairwise.go        | 1 +
 metrics/pairwise/poly_kernel.go     | 4 ++++
 metrics/pairwise/rbf_kernel.go      | 5 ++++-
 metrics/pairwise/rbf_kernel_test.go | 4 ++--
 6 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/metrics/pairwise/euclidean.go b/metrics/pairwise/euclidean.go
index 30f8df3..e61eae6 100644
--- a/metrics/pairwise/euclidean.go
+++ b/metrics/pairwise/euclidean.go
@@ -12,13 +12,15 @@ func NewEuclidean() *Euclidean {
 	return &Euclidean{}
 }
 
+// Compute usual inner product in the sense of euclidean.
 func (self *Euclidean) InnerProduct(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	result := vectorX.Dot(vectorY)
 
 	return result
 }
 
-// We may need to create Metrics / Vector interface for this
+// Compute usual distance in the sense of euclidean.
+// Also known as L2 distance.
 func (self *Euclidean) Distance(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	subVector := mat64.NewDense(0, 0, nil)
 	subVector.Sub(vectorX, vectorY)
diff --git a/metrics/pairwise/manhattan.go b/metrics/pairwise/manhattan.go
index c734f31..20b319a 100644
--- a/metrics/pairwise/manhattan.go
+++ b/metrics/pairwise/manhattan.go
@@ -12,6 +12,8 @@ func NewManhattan() *Manhattan {
 	return &Manhattan{}
 }
 
+// Manhattan distance, also known as L1 distance.
+// Compute sum of absolute values of elements.
 func (self *Manhattan) Distance(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	var length int
 	subVector := mat64.NewDense(0, 0, nil)
diff --git a/metrics/pairwise/pairwise.go b/metrics/pairwise/pairwise.go
index adecc13..6c6a5dc 100644
--- a/metrics/pairwise/pairwise.go
+++ b/metrics/pairwise/pairwise.go
@@ -1 +1,2 @@
+// Package pairwise implements utilities to evaluate pairwise distances or inner product (via kernel).
 package pairwise
diff --git a/metrics/pairwise/poly_kernel.go b/metrics/pairwise/poly_kernel.go
index 5ddaa12..03e9ef3 100644
--- a/metrics/pairwise/poly_kernel.go
+++ b/metrics/pairwise/poly_kernel.go
@@ -10,10 +10,13 @@ type PolyKernel struct {
 	degree int
 }
 
+// Return a d-degree polynomial kernel
 func NewPolyKernel(degree int) *PolyKernel {
 	return &PolyKernel{degree: degree}
 }
 
+// Compute inner product through kernel trick
+// K(x, y) = (x^T y + 1)^d
 func (self *PolyKernel) InnerProduct(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	result := vectorX.Dot(vectorY)
 	result = math.Pow(result+1, float64(self.degree))
@@ -21,6 +24,7 @@ func (self *PolyKernel) InnerProduct(vectorX *mat64.Dense, vectorY *mat64.Dense)
 	return result
 }
 
+// Compute distance under the polynomial kernel, maybe no need.
 func (self *PolyKernel) Distance(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	subVector := mat64.NewDense(0, 0, nil)
 	subVector.Sub(vectorX, vectorY)
diff --git a/metrics/pairwise/rbf_kernel.go b/metrics/pairwise/rbf_kernel.go
index 29c9c17..af02463 100644
--- a/metrics/pairwise/rbf_kernel.go
+++ b/metrics/pairwise/rbf_kernel.go
@@ -10,15 +10,18 @@ type RBFKernel struct {
 	gamma float64
 }
 
+// Radial Basis Function Kernel
 func NewRBFKernel(gamma float64) *RBFKernel {
 	return &RBFKernel{gamma: gamma}
 }
 
+// Compute inner product through kernel trick
+// K(x, y) = exp(-gamma * ||x - y||^2)
 func (self *RBFKernel) InnerProduct(vectorX *mat64.Dense, vectorY *mat64.Dense) float64 {
 	euclidean := NewEuclidean()
 	distance := euclidean.Distance(vectorX, vectorY)
 
-	result := math.Exp(self.gamma * math.Pow(distance, 2))
+	result := math.Exp(-self.gamma * math.Pow(distance, 2))
 
 	return result
 }
diff --git a/metrics/pairwise/rbf_kernel_test.go b/metrics/pairwise/rbf_kernel_test.go
index dd43082..5cb6f48 100644
--- a/metrics/pairwise/rbf_kernel_test.go
+++ b/metrics/pairwise/rbf_kernel_test.go
@@ -18,8 +18,8 @@ func TestRBFKernel(t *testing.T) {
 		Convey("When doing inner product", func() {
 			result := rbfKernel.InnerProduct(vectorX, vectorY)
 
-			Convey("The result should be 2.45960311115695", func() {
-				So(result, ShouldEqual, 2.45960311115695)
+			Convey("The result should be 0.4065696597405991", func() {
+				So(result, ShouldEqual, 0.4065696597405991)
 
 			})
 		})