Formatted documentation

Author: mpraski

clusters.go

@@ -1,65 +1,79 @@
+// Package clusters provides abstract definitions of clusterers as well as
+// their implementations.
 package clusters
 
 import (
 	"math"
 )
 
+// DistanceFunc represents a function for measuring distance
+// between n-dimensional vectors.
 type DistanceFunc func(a, b []float64) float64
 
+// Online represents parameters important for online learning in
+// clustering algorithms.
 type Online struct {
 	Alpha     float64
 	Dimension int
 }
 
-/* Events represent intermediate results of computation of both kinds of algorithms
- * transmitted periodically to the caller */
+// HCEvent represents the intermediate result of computation of hard clustering algorithm
+// and are transmitted periodically to the caller during online learning
 type HCEvent struct {
 	Cluster     int
 	Observation []float64
 }
 
-/* TestResult represents output of a test performed to measure quality of an algorithm. */
-type TestResult struct {
-	clusters, expected int
-}
-
-/* Clusterer denotes the operation of learning
- * common for both Hard and Soft clusterers */
+// Clusterer defines the operation of learning
+// common for all algorithms
 type Clusterer interface {
 	Learn([][]float64) error
 }
 
-/* HardClusterer defines a set of operations for hard clustering algorithms */
+// HardClusterer defines a set of operations for hard clustering algorithms
 type HardClusterer interface {
 
-	/* Returns sizes of respective clusters */
+	// Sizes returns sizes of respective clusters
 	Sizes() []int
 
-	/* Returns mapping from data point indices to cluster index. Cluster indices begin at 1, not 0. */
+	// Guesses returns mapping from data point indices to cluster numbers. Clusters' numbering begins at 1.
 	Guesses() []int
 
-	/* Returns index of cluster to which the observation was assigned */
+	// Predict returns number of cluster to which the observation would be assigned
 	Predict(observation []float64) int
 
-	/* Whether algorithm supports online learning */
+	// IsOnline tells the algorithm supports online learning
 	IsOnline() bool
 
-	/* Allows to configure the algorithms for online learning */
+	// WithOnline configures the algorithms for online learning with given parameters
 	WithOnline(Online) HardClusterer
 
-	/* Provides a method to train the algorithm online and receive intermediate results of computation */
+	// Online begins the process of online training of an algorithm. Observations are sent on the observations channel,
+	// once no more are expected an empty struct needs to be sent on done channel. Caller receives intermediate results of computation via
+	// the returned channel.
 	Online(observations chan []float64, done chan struct{}) chan *HCEvent
 
+	// Implement common operation
 	Clusterer
 }
 
+// Estimator defines a computation used to determine an optimal number of clusters in the dataset
 type Estimator interface {
 
-	/* Estimates the numer of clusters */
+	// Estimate provides an expected number of clusters in the dataset
 	Estimate([][]float64) (int, error)
 }
 
+// Importer defines an operation of importing the dataset from an external file
+type Importer interface {
+
+	// Import fetches the data from a file, start and end arguments allow user
+	// to specify the span of data columns to be imported (inclusively)
+	Import(file string, start, end int) ([][]float64, error)
+}
+
 var (
+	// EuclideanDistance is one of the common distance measurement
 	EuclideanDistance = func(a, b []float64) float64 {
 		var (
 			s, t float64
@@ -73,6 +87,7 @@ var (
 		return math.Sqrt(s)
 	}
 
+	// EuclideanDistanceSquared is one of the common distance measurement
 	EuclideanDistanceSquared = func(a, b []float64) float64 {
 		var (
 			s, t float64

importer.go csv_importer.goimporter.go renamed to csv_importer.go

@@ -8,10 +8,6 @@ import (
 	"strconv"
 )
 
-type Importer interface {
-	Import(file string, start, end int) ([][]float64, error)
-}
-
 type csvImporter struct {
 }
 

importer_test.go csv_importer_test.goimporter_test.go renamed to csv_importer_test.go

@@ -29,7 +29,8 @@ type dbscanClusterer struct {
 	d [][]float64
 }
 
-/* Implementation of DBSCAN algorithm with concurrent nearest neighbour computation */
+// Implementation of DBSCAN algorithm with concurrent nearest neighbour computation. The number of goroutines acting concurrently
+// is controlled via workers argument. Passing 0 will result in this number being chosen arbitrarily.
 func DBSCAN(minpts int, eps float64, workers int, distance DistanceFunc) (HardClusterer, error) {
 	if minpts < 1 {
 		return nil, ErrZeroMinpts

dbscan.go

@@ -13,7 +13,6 @@ const (
 	CHANGES_THRESHOLD = 2
 )
 
-/* Implementation of k-means++ algorithm with online learning */
 type kmeansClusterer struct {
 	iterations, number int
 
@@ -37,6 +36,7 @@ type kmeansClusterer struct {
 	d [][]float64
 }
 
+// Implementation of k-means++ algorithm with online learning
 func KMeans(iterations, clusters int, distance DistanceFunc) (HardClusterer, error) {
 	if iterations < 1 {
 		return nil, ErrZeroIterations

kmeans.go

@@ -25,6 +25,9 @@ type kmeansEstimator struct {
 	d [][]float64
 }
 
+// Implementation of cluster number estimator using gap statistic
+// ("Estimating the number of clusters in a data set via the gap statistic", Tibshirani et al.) with k-means++ as
+// clustering algorithm
 func KMeansEstimator(iterations, clusters int, distance DistanceFunc) (Estimator, error) {
 	if iterations < 1 {
 		return nil, ErrZeroIterations

kmeans_estimator.go

@@ -46,7 +46,8 @@ type opticsClusterer struct {
 	d [][]float64
 }
 
-/* Implementation of OPTICS algorithm with concurrent nearest neighbour computation */
+// Implementation of OPTICS algorithm with concurrent nearest neighbour computation. The number of goroutines acting concurrently
+// is controlled via workers argument. Passing 0 will result in this number being chosen arbitrarily.
 func OPTICS(minpts int, eps, xi float64, workers int, distance DistanceFunc) (HardClusterer, error) {
 	if minpts < 1 {
 		return nil, ErrZeroMinpts