Empact-hierclust 0.2.0

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/Empact-hierclust.gemspec

@@ -0,0 +1,82 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{Empact-hierclust}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brandt Kurowski", "Ben Woosley"]
+  s.date = %q{2010-11-01}
+  s.description = %q{performs hierarchical clustering on points in Euclidian space}
+  s.email = %q{ben.woosley@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "Empact-hierclust.gemspec",
+     "History.txt",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "examples/visualize.rb",
+     "lib/hierclust.rb",
+     "lib/hierclust/cluster.rb",
+     "lib/hierclust/clusterer.rb",
+     "lib/hierclust/distances.rb",
+     "lib/hierclust/point.rb",
+     "log/debug.log",
+     "script/destroy",
+     "script/generate",
+     "script/txt2html",
+     "spec/hierclust/cluster_spec.rb",
+     "spec/hierclust/clusterer_spec.rb",
+     "spec/hierclust/distances_spec.rb",
+     "spec/hierclust/point_spec.rb",
+     "spec/hierclust_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "tasks/deployment.rake",
+     "tasks/environment.rake",
+     "tasks/rspec.rake",
+     "tasks/website.rake",
+     "website/index.txt",
+     "website/javascripts/rounded_corners_lite.inc.js",
+     "website/stylesheets/screen.css",
+     "website/template.rhtml"
+  ]
+  s.homepage = %q{http://github.com/Empact/hierclust}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{hierclust}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{performs hierarchical clustering in N dimensions}
+  s.test_files = [
+    "spec/hierclust/cluster_spec.rb",
+     "spec/hierclust/clusterer_spec.rb",
+     "spec/hierclust/distances_spec.rb",
+     "spec/hierclust/point_spec.rb",
+     "spec/hierclust_spec.rb",
+     "spec/spec_helper.rb",
+     "examples/visualize.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  end
+end
+

data/History.txt

@@ -0,0 +1,47 @@
+== 0.2.0 2010-11-01
+
+* 1 major enhancement:
+  * Clustering & Points now support N dimensions (up from 2)
+* 1 minor enhancement:
+  * Switch to jeweler
+
+== 0.1.5 2008-03-21
+
+* 1 minor enhancement:
+  * added cluster radius
+* 1 new example script:
+  * demonstrates SVG rendering of points and clusters
+
+== 0.1.4 2008-02-13
+
+* 1 minor enhancement:
+  * gave linear-time preclustering an independent "resolution" parameter
+* 1 bugfix:
+  * corrected cluster coordinate calculation
+
+== 0.1.3 2008-02-10
+
+* 1 performance improvement
+  * added linear-time preclustering based on minimum separation distance
+* 1 major change:
+  * when minimum separation is given, the clusterer will no longer calculate
+    and return clusters smaller than "separation / 2.0"
+
+== 0.1.2 2008-02-07
+
+* 1 performance improvement
+  * refactored Distances to be more intelligent about precalculated values
+* 1 bugfix:
+  * correct degenerate case of Hierclust::Point.points
+
+== 0.1.1 2008-02-04
+
+* 1 minor enhancement:
+  * add method for returning flattened list of points in a cluster
+* 1 bugfix:
+  * correct intermittent failure of Clusterer spec
+
+== 0.1.0 2008-02-01
+
+* 1 major enhancement:
+  * Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Brandt Kurowski <brandt@kurowski.net>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,28 @@
+= Hierclust
+
+A simple hierarchical clustering library for spatial data.
+
+== Example
+
+  require 'hierclust'
+  points = (1..6).map { Hierclust::Point.new(rand(10), rand(10)) }
+  clusterer = Hierclust::Clusterer.new(points)
+  puts clusterer.clusters => [[[(4, 9), (4, 8)], (9, 6)], [[(1, 4), (3, 1)], (6, 3)]]
+
+== Contact for this fork
+
+Ben Woosley <ben.woosley@gmail.com>
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Brandt Kurowski. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "Empact-hierclust"
+    gem.summary = %Q{performs hierarchical clustering in N dimensions}
+    gem.description = %Q{performs hierarchical clustering on points in Euclidian space}
+    gem.email = "ben.woosley@gmail.com"
+    gem.homepage = "http://github.com/Empact/hierclust"
+    gem.authors = ["Brandt Kurowski", "Ben Woosley"]
+    gem.rubyforge_project = "hierclust"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "hierclust #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/examples/visualize.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+begin
+  $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+  require 'hierclust'
+rescue LoadError
+  require 'rubygems'
+  require 'hierclust'
+end
+
+points = (1..20).map { Hierclust::Point.new(rand(800), rand(600)) }
+clusterer = Hierclust::Clusterer.new(points)
+
+print %Q{<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
+  "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="800" height="600" version="1.1"
+     xmlns="http://www.w3.org/2000/svg">
+}
+
+def plot(cluster)
+  if cluster.kind_of? Hierclust::Cluster
+    print %Q{
+      <circle cx="#{cluster.coordinates[0]}" cy="#{cluster.coordinates[1]}" r="#{cluster.radius}"
+              fill="none" stroke="black" stroke-width="#{cluster.items}"/>
+    }
+    cluster.items.each {|item| plot(item)}
+  else
+    print %Q{
+      <circle cx="#{cluster.coordinates[0]}" cy="#{cluster.coordinates[1]}" r="2"
+              fill="red" stroke="none"/>
+    }
+  end
+end
+
+clusterer.clusters.each {|cluster| plot cluster}
+
+print %Q{
+  <rect x="1" y="1" width="798" height="598"
+        fill="none" stroke="grey" stroke-width="2" />
+</svg>
+}

data/lib/hierclust.rb

@@ -0,0 +1,6 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'hierclust/point'
+require 'hierclust/cluster'
+require 'hierclust/distances'
+require 'hierclust/clusterer'

data/lib/hierclust/cluster.rb

@@ -0,0 +1,61 @@
+module Hierclust
+  # A Cluster represents a collection of Points. A Cluster has it's own
+  # coordinates that are the mean of the coordinates of it's points.
+  # Because a Cluster has coordinates, it can act as a Point and therefore
+  # be included in other Clusters.
+  class Cluster < Point
+    # An array of items in this cluster
+    attr_accessor :items
+    
+    # Create a Cluster for the given set of +items+.
+    def initialize(items)
+      @items = items
+    end
+    
+    # Returns the average coordinates of all items in this Cluster.
+    def coordinates
+      return nil if size == 0
+      @coordinates ||= begin
+        coords = self.points.map {|p| p.coordinates }
+        coords = coords.shift.zip(*coords)
+        coords.map {|points| points.inject(0.0) {|sum, p| sum + p } / points.size }
+      end
+    end
+
+    # Add an +item+ to this Cluster.
+    def <<(item)
+      @coordinates = nil
+      @items << item
+    end
+    
+    # Returns the number of items in this Cluster.
+    def size
+      @items.size
+    end
+    
+    # Returns the distance from the center of this Cluster to the edge.
+    def radius
+      return nil if @items.empty?
+      return 0 if @items.size == 1
+      return (@items[0].distance_to(@items[1]) + @items[0].radius + @items[1].radius) / 2.0
+      raise "radius not implemented for clusters with more than two items"
+    end
+    
+    # Returns a flat list of all the points contained in either this cluster
+    # or any of the clusters it contains.
+    def points
+      @items.map {|item| item.points}.flatten
+    end
+    
+    # Returns +true+ if this Cluster includes the given +item+, otherwise
+    # returns +false+.
+    def include?(item)
+      @items.include? item
+    end
+    
+    # Returns a legible representation of this Cluster and it's items.
+    def to_s
+      "[#{@items.join(', ')}]"
+    end
+  end
+end

data/lib/hierclust/clusterer.rb

@@ -0,0 +1,70 @@
+module Hierclust
+  # Clusters a set of Points using Hierarchical Clustering, stopping either
+  # when the hierarchy is complete or the clusters are separated by a given
+  # minimum distance.
+  class Clusterer
+    # The Distances for the items being clustered
+    attr_reader :distances
+
+    # Create a new Clusterer for the given data.
+    # 
+    # Specify +separation+ to stop the clustering process once all the
+    # items are at least +separation+ units apart.
+    # 
+    # Specify +resolution+ to give a minimum size for clusters. Points that
+    # are within this distance from each other will not be hierarchically
+    # clustered, but will be put into clusters based strictly on coordinates.
+    # The clusters generated by this "pre-clustering" will then be
+    # hierarchically clustered as normal.
+    def initialize(data, separation = nil, resolution = nil)
+      @separation = separation
+      @resolution = resolution
+      @data = precluster(data)
+      @distances = Distances.new(@data)
+    end
+
+    # Calculates and returns the set of clusters.
+    def clusters
+      return @data if @separation && @distances.separation > @separation
+      while @data.length > 1
+        @distances = Distances.new(@data)
+        return @data if @separation && @distances.separation > @separation
+        @data = find_cluster
+      end
+      @data
+    end
+
+    private
+    
+    def find_cluster
+      case @data.length
+      when 0
+        []
+      when 1, 2
+        [Cluster.new(@data)]
+      else
+        nearest = @distances.nearest
+        outliers = @distances.outliers
+        [Cluster.new(nearest), *outliers]
+      end
+    end
+    
+    def precluster(points)
+      unless @resolution && @separation
+        # preclustering is only applicable given lower bound on resolution
+        # can't precluster w/ no min separation given
+        return points.dup
+      end
+      if @separation == 0
+        # if no separation is asked for, it's all one cluster
+        return [Cluster.new(points)]
+      end
+      points.inject({}) do |grid_clusters, point|
+        grid_coordinates = point.coordinates.map {|coord| (coord / @resolution).floor }
+        grid_clusters[grid_coordinates] ||= Cluster.new([])
+        grid_clusters[grid_coordinates] << point
+        grid_clusters
+      end.values
+    end
+  end
+end

data/lib/hierclust/distances.rb

@@ -0,0 +1,47 @@
+module Hierclust
+  # Represents the pair-wise distances between a set of items.
+  class Distances
+    attr_reader :nearest, :outliers, :separation
+
+    # Create a new Distances for the given +items+
+    def initialize(items)
+      @items = items
+      @separation = 0
+      @nearest = []
+      items = @items.dup
+      while !items.empty?
+        origin = items.shift
+        items.each do |other|
+          distance = origin.distance_to(other)
+          if @separation == 0 or distance < @separation
+            @separation = distance
+            @nearest = [origin, other]
+          end
+        end
+      end
+      @outliers = @items - @nearest
+    end
+
+=begin
+
+old idea
+
+1 calculate all distances
+2 update distances when a new cluster is created from two existing points
+3 keep distances sorted by separation so that we always know which is shortest
+
+new idea
+
+don't worry about the lower level clusters
+don't worry about the higher level clusters
+just form clusters of the desired separation
+start by dividing the points into a grid of 0.5 * sep
+and put all points in the same grid cells together
+...
+and then do regular hierarchical clustering! we should be fine at that point.
+sweet....
+
+=end
+
+  end
+end