clustertool 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd947448c507995e271fcbb359f16a2c4d594b63
+  data.tar.gz: a472cae649f54082828137b49705a55ac6bf26ba
+SHA512:
+  metadata.gz: 41e2fcc2d1c590028cf03c9a4032003bb5425f6398cf19789378bf7d530cf61e3a381b1b83467b8d562a347f188a21d821fc92244288405245d45371e9f3ce41
+  data.tar.gz: 01cf8185ed6e7ef39d61cebfe20b37f5c37ac76fe5521bece623c240afbf7ee1180a41a67759746ce5c350400886b9f447f0baee6e3628d9da37ffcd601a67c4

data/lib/clustertool.rb

@@ -0,0 +1,48 @@
+require "sqlite3" 
+require_relative "clustertool/KMeans"
+require_relative "clustertool/DBSCAN"
+
+# The main ClusterTool driver. 
+class ClusterTool
+	# Data is retrieved from the database and passed off to the appropriate
+	# algorithm.
+	#
+	# Example:
+	# 	>> args = {
+	#	>>		:k => 3,
+	#	>>		:cycles => 10,
+	#	>> }
+	#	>> ClusterTool.cluster("test.db", "TestSimple2D", ["Field1", "Field2"],
+	#	>>		:kmeans, args)
+	#	=> [[[0, 0], [-1, 0], [1, 0], [0, -1], [0, 1]], [[0, 10], [-1, 10], [1,
+	#	10], [0, 9], [0, 11]], [[-10, 0], [-11, 0], [-9, 0], [-10, -1], [-10,
+	#	1]]]
+	#
+	# Example:
+	#   >> args = {
+	#	>>		:epsilon = 1.5,
+	#	>>		:min_points = 2,
+	#	>> }
+	#	>> ClusterTool.cluster("test.db", "TestSimple1D", ["Field"], :dbscan,
+	#	>>		args)
+	#	=> {0=>[[0, 0], [-1, 0], [1, 0], [0, -1], [0, 1]], 1=>[[0, 10], [-1,
+	#	10], [1, 10], [0, 9], [0, 11]], 2=>[[-10, 0], [-11, 0], [-9, 0], [-10,
+	#	-1], [-10, 1]]}
+	#
+	# Arguments:
+	# 	database: (String)
+	#	table: (String)
+	#	columns: [(String), ...]
+	#	algorithm: :kmeans or :dbscan
+	#	args: { (Symbol) => (Numeric), ... }
+	def self.cluster(database, table, columns, algorithm, args)
+		db = SQLite3::Database.new(database)
+		data = db.execute("select #{columns.join(", ")} from #{table};")
+
+		case algorithm
+		when :kmeans then return KMeans.cluster(data, args)
+		when :dbscan then return DBSCAN.cluster(data, args)
+		else raise ArgumentError, 'Unknown clustering algorithm' 
+		end
+	end
+end

data/lib/clustertool/DBSCAN.rb

@@ -0,0 +1,89 @@
+require_relative "Util"
+
+# Implements the DBSCAN clustering algorithm
+class DBSCAN
+
+	# Cluster data using the DBSCAN algorithm with arguments epsilon and
+	# min_points provided in args.
+	#
+	# Example:
+	# >> args = {
+	# >> 	:epsilon => 1.5,
+	# >>	:min_points => 2,
+	# >> }
+	# >> DBSCAN.cluster([[1],[2],[3],[11],[12],[13],[21],[22],[23],[100]], args)
+	# => {0 => [[1],[2],[3]], 1 => [[11],[12],[13]], 2 => [[21],[22],[23]],
+	# :noise => [[100]]}
+	#
+	# Arguments:
+	#	data: [[(Numeric), ...], ...]
+	#	args: { (Symbol) => (Numeric), ... }
+	def self.cluster(data, args)
+		unless args.include?(:epsilon)
+			raise ArgumentError, "DBSCAN algorithm requires :epsilon argument"
+		end
+		@epsilon = args[:epsilon]
+		
+		unless args.include?(:min_points)
+			raise ArgumentError, "DBSCAN algorithm requires :min_points argument"
+		end
+		@min_pts = args[:min_points]
+
+		@data = data
+		@visited = Hash.new(false)
+		@clusters = Hash.new { Array.new() }
+		@cnum = 0
+
+		@data.each do |point|
+			next if @visited[point]
+			@visited[point] = true
+			neighbor_pts = regionQuery(point)
+			if neighbor_pts.length < @min_pts
+				@clusters[:noise] = @clusters[:noise].push(point)
+			else
+				expandCluster(point, neighbor_pts)
+				@cnum += 1
+			end
+		end
+		return @clusters
+	end
+
+	private
+
+	class << self; attr_accessor :data end
+	class << self; attr_accessor :epsilon end
+	class << self; attr_accessor :min_pts end
+	class << self; attr_accessor :visited end
+	class << self; attr_accessor :clusters end
+	class << self; attr_accessor :cnum end
+
+	def self.expandCluster(point, neighbor_pts)
+		@clusters[@cnum] = @clusters[@cnum].push(point)
+		index = 0
+		while index < neighbor_pts.length do
+			neighbor = neighbor_pts[index]
+			unless @visited[neighbor]
+				@visited[neighbor] = true
+				neighbor_neighbor_pts = regionQuery(neighbor)
+				if neighbor_neighbor_pts.length >= @min_pts
+					neighbor_pts = neighbor_pts | neighbor_neighbor_pts
+				end
+			end
+
+			@clusters[:noise].delete(neighbor)
+			unless @clusters.values.any? { |cluster| cluster.include?(neighbor) }
+				@clusters[@cnum] = @clusters[@cnum].push(neighbor)
+			end
+
+			index += 1
+		end
+	end
+
+	def self.regionQuery(point)
+		neighborhood = []
+		@data.each do |p|
+			neighborhood.push(p) if Util.dist(point,p) < @epsilon
+		end
+		return neighborhood
+	end
+end

data/lib/clustertool/KMeans.rb

@@ -0,0 +1,83 @@
+require_relative "Util"
+
+# Implementation of the k-Means clustering algorithm
+class KMeans
+
+	# Cluster data using the k-Means algoritm with k specified in args. The
+	# algorithms is run multiple times (as defined in the :cycles argument) and
+	# the most common clustering is returned.
+	#
+	# Example:
+	# >> args = {
+	# >> 	:k => 3,
+	# >>	:cycles => 10,
+	# >> }
+	# >> KMeans.cluster([[1],[2],[3],[11],[12],[13],[21],[22],[23]], args)
+	# => {0 => [[1],[2],[3]], 1 => [[11],[12],[13]], 2 => [[21],[22],[23]]}
+	#
+	# Arguments:
+	#	data: [[(Numeric), ...], ...]
+	#	args: { (Symbol) => (Numeric), ... }
+
+	def self.cluster(data, args)
+		unless args.include?(:k)
+			raise ArgumentError, "KMeans algorithm requires :k arguemnt"
+		end
+		@k = args[:k]
+
+		unless args.include?(:cycles)
+			raise ArgumentError, "KMeans algorithm requires :cycles argument"
+		end
+		cycles = args[:cycles]
+
+		@data = data
+
+		results = Hash.new(0)
+		cycles.times { results[kmeans()] += 1 }
+		max = nil
+		results.each do |key, value|
+			if max.nil? or results[max] < value
+				max = key
+			end
+		end
+
+		clusters = Hash.new()
+		max.values.each_with_index { |v, i| clusters[i] = v } unless max.nil?
+		return clusters
+	end
+
+	private
+
+	class << self; attr_accessor :data end
+	class << self; attr_accessor :k end
+
+	def self.kmeans()
+		# initialize partitions with Forgy method: select random items.
+		means = data.shuffle[0...@k]
+
+		partitions = Hash.new { Array.new }
+
+		old_partitions = ""
+		until partitions.inspect.eql?(old_partitions) do
+			old_partitions = partitions.inspect
+			partitions = Hash.new { Array.new }
+			# assignment step
+			@data.each do |point|
+				min_dist = nil
+				min_index = nil
+				means.each do |mean|
+					if min_dist.nil? or Util.dist(point,mean) < min_dist
+						min_dist = Util.dist(point,mean)
+						min_index = mean
+					end
+				end
+				partitions[min_index] = partitions[min_index].push(point)
+			end
+
+			# update step
+			means = partitions.each_value.map { |points| Util.centroid(points) }
+		end
+
+		return partitions
+	end
+end

data/lib/clustertool/Util.rb

@@ -0,0 +1,46 @@
+# A few utility functions used by the clustering algorithms
+class Util
+	# Calculates the Euclidean Distance between two points of the same
+	# dimension.
+	#
+	# Example:
+	#	>> Util.dist([0,0],[3,4])
+	#	=> 5.0
+	#
+	# Arguments:
+	#	point1: [(Numeric), ...]
+	#	point2: [(Numeric), ...]
+	def self.dist(point1, point2)
+		# Start by making sure points have the same dimension
+		raise ArgumentError, "Can't calculate distance of points with different
+		dimensions" unless point1.length == point2.length
+
+		pairs = point1.zip(point2)
+		dist = 0
+		pairs.each { |pair| dist += (pair[0] - pair[1])**2 }
+		return Math.sqrt(dist)
+	end
+
+	# Caculates the centroid of a set of points
+	#
+	# Example:
+	#	>> Util.centroid([[0,0,0],[1,2,3],[2,4,0]])
+	#	=> [1,2,1]
+	#
+	# Arguments:
+	#	points: [[(Numeric), ...], ...]
+	def self.centroid(points)
+		# Check boundary conditions and make sure each point has the same
+		# dimension.
+		return Array.new unless points.length > 0
+		dim = points[0].length
+		raise ArgumentError, "Can't calculate centroid of points with different
+		dimensions" if points.any? { |p| p.length != dim }
+
+		centroid = Array.new(points[0].length, 0)
+		points.each do |point|
+			point.each_with_index { |val, idx| centroid[idx] += val }
+		end
+		return centroid.map { |val| val.to_f / points.length }
+	end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: clustertool
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- JD Nir
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-23 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Import a database and specify up to two columns of numerical
+    data as well as your choice of the K-Means or DBSCAN algorithms and their
+    respective parameters.
+email: jnir@fastorientation.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/clustertool.rb
+- lib/clustertool/DBSCAN.rb
+- lib/clustertool/KMeans.rb
+- lib/clustertool/Util.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: A tool for clustering database entries
+test_files: []