hierclust 0.1.0

data/spec/hierclust/cluster_spec.rb

@@ -0,0 +1,52 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper.rb')
+
+module Hierclust
+  describe Cluster, " with no points" do
+    before do
+      @c = Cluster.new([])
+    end
+
+    it "should have nil x-coordinate" do
+      @c.x.should be_nil
+    end
+
+    it "should have nil y-coordinate" do
+      @c.y.should be_nil
+    end
+  end
+
+  describe Cluster, " with one point" do
+    before do
+      @x = 123
+      @y = 234
+      @p = Point.new(@x, @y)
+      @c = Cluster.new([@p])
+    end
+
+    it "should have the same x-coordinate as the point" do
+      @c.x.should == @p.x
+    end
+
+    it "should have the same y-coordinate as the point" do
+      @c.y.should == @p.y
+    end
+  end
+
+  describe Cluster, " with two points" do
+    before do
+      @x_1, @x_2 = 5, 15
+      @y_1, @y_2 = 4, 8
+      @p_1 = Point.new(@x_1, @y_1)
+      @p_2 = Point.new(@x_2, @y_2)
+      @c = Cluster.new([@p_1, @p_2])
+    end
+
+    it "should have x-coordinate at average of point's x-coordinates" do
+      @c.x.should == 10
+    end
+
+    it "should have y-coordinate at average of point's y-coordinates" do
+      @c.y.should == 6
+    end
+  end
+end

data/spec/hierclust/clusterer_spec.rb

@@ -0,0 +1,167 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper.rb')
+
+module Hierclust
+  describe Clusterer, " with no data" do
+    before do
+      @c = Clusterer.new([])
+    end
+
+    it "should return no clusters" do
+      @c.clusters.should == []
+    end
+  end
+
+  describe Clusterer, " with one point" do
+    before do
+      @x = 1
+      @y = 2
+      @p = Point.new(@x, @y)
+      @c = Clusterer.new([@p])
+    end
+
+    it "should return the point" do
+      @c.clusters.should == [@p]
+    end
+  end
+
+  describe Clusterer, " with two points" do
+    before do
+      @x_1, @x_2 = 1, 5
+      @y_1, @y_2 = 2, 8
+      @p_1 = Point.new(@x_1, @y_1)
+      @p_2 = Point.new(@x_2, @y_2)
+      @c = Clusterer.new([@p_1, @p_2])
+    end
+
+    it "should return one cluster" do
+      @c.clusters.size.should == 1
+    end
+
+    it "should have two points in the cluster" do
+      @c.clusters.first.size.should == 2
+    end
+
+    it "should have the first point in the cluster" do
+      @c.clusters.first.should include(@p_1)
+    end
+
+    it "should have the second point in the cluster" do
+      @c.clusters.first.should include(@p_2)
+    end
+  end
+
+  describe Clusterer, " with three points" do
+    before do
+      @x_1, @x_2, @x_3 = 1, 5, 2
+      @y_1, @y_2, @y_3 = 2, 6, 3
+      @p_1 = Point.new(@x_1, @y_1)
+      @p_2 = Point.new(@x_2, @y_2)
+      @p_3 = Point.new(@x_3, @y_3)
+      @c = Clusterer.new([@p_1, @p_2, @p_3])
+      @cluster = @c.clusters.first
+      @clusters = @cluster.items.sort_by{|c|c.size}
+    end
+
+    it "should return one cluster" do
+      @c.clusters.size.should == 1
+    end
+
+    it "containing two items" do
+      @cluster.items.size.should == 2
+    end
+
+    it "should have one Cluster" do
+      @clusters[1].class.should == Cluster
+    end
+
+    it "and one Point" do
+      @clusters[0].class.should == Point
+    end
+
+    it "should have the first and third points in the bigger cluster" do
+      @clusters[1].should include(@p_1, @p_3)
+    end
+
+    it "should have the second point in the smaller cluster" do
+      @clusters[0].should == @p_2
+    end
+  end
+
+  FOUR_P = [
+    Point.new(0, 1),
+    Point.new(1, 0),
+    Point.new(3, 4),
+    Point.new(4, 3),
+  ]
+  
+  describe Clusterer, " with four points and no separation" do
+    before do
+      @c = Clusterer.new(FOUR_P)
+    end
+
+    it "should return one cluster" do
+      @c.clusters.size.should == 1
+    end
+  end
+
+  describe Clusterer, " with four points and separation 1" do
+    before do
+      @c = Clusterer.new(FOUR_P, 1)
+    end
+
+    it "should return all four individual points" do
+      @c.clusters.size.should == 4
+    end
+  end
+
+  describe Clusterer, " with four points and separation 2" do
+    before do
+      @c = Clusterer.new(FOUR_P, 2)
+    end
+
+    it "should return two clusters" do
+      @c.clusters.size.should == 2
+    end
+  end
+
+  EIGHT_P = [
+    Point.new(0, 1),
+    Point.new(1, 0),
+    Point.new(3, 4),
+    Point.new(4, 3),
+    Point.new(7, 8),
+    Point.new(8, 7),
+    Point.new(8, 9),
+    Point.new(9, 8),
+  ]
+  
+  describe Clusterer, " with eight points and no separation" do
+    before do
+      @c = Clusterer.new(EIGHT_P)
+    end
+
+    it "should return one cluster when no minimum separation is given" do
+      @c.clusters.size.should == 1
+    end
+  end
+
+  describe Clusterer, " with eight points and separation 1" do
+    before do
+      @c = Clusterer.new(EIGHT_P, 1)
+    end
+
+    it "should return all eight individual points" do
+      @c.clusters.size.should == 8
+    end
+  end
+
+  describe Clusterer, " with eight points and separation 2" do
+    before do
+      @c = Clusterer.new(EIGHT_P, 2)
+    end
+
+    it "should return three clusters" do
+      @c.clusters.size.should == 3
+    end
+  end
+end

data/spec/hierclust/distances_spec.rb

@@ -0,0 +1,52 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper.rb')
+
+module Hierclust
+  describe Distances, " with two points" do
+    before do
+      @x_1, @x_2 = 1, 5
+      @y_1, @y_2 = 2, 8
+      @p_1 = Point.new(@x_1, @y_1)
+      @p_2 = Point.new(@x_2, @y_2)
+      @d = Distances.new([@p_1, @p_2])
+      @dist = Math.sqrt((@x_1 - @x_2) ** 2 + (@y_1 - @y_2) ** 2)
+    end
+
+    it "should tell us the distance between those points" do
+      @d[@p_1, @p_2].should == @dist
+    end
+
+    it "should tell us the distance between those points backwards" do
+      @d[@p_1, @p_2].should == @dist
+    end
+
+    it "should have separation equal to distance between those points" do
+      @d.separation.should == @dist
+    end
+  end
+
+  describe Distances, " with three points" do
+    before do
+      @x_1, @x_2, @x_3 = 1, 5, 3
+      @y_1, @y_2, @y_3 = 2, 8, 4
+      @p_1 = Point.new(@x_1, @y_1)
+      @p_2 = Point.new(@x_2, @y_2)
+      @p_3 = Point.new(@x_3, @y_3)
+      @d = Distances.new([@p_1, @p_2, @p_3])
+      @dist_1_2 = Math.sqrt((@x_1 - @x_2) ** 2 + (@y_1 - @y_2) ** 2)
+      @dist_2_3 = Math.sqrt((@x_2 - @x_3) ** 2 + (@y_2 - @y_3) ** 2)
+      @dist_3_1 = Math.sqrt((@x_3 - @x_1) ** 2 + (@y_3 - @y_1) ** 2)
+    end
+
+    it "should tell us the nearest points" do
+      @d.nearest.should include(@p_1, @p_3)
+    end
+
+    it "should tell us the outliers" do
+      @d.outliers.should == [@p_2]
+    end
+
+    it "should have separation equal to distance between nearest points" do
+      @d.separation.should == @dist_3_1
+    end
+  end
+end

data/spec/hierclust/point_spec.rb

@@ -0,0 +1,12 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper.rb')
+
+module Hierclust
+  describe Point do
+    before do
+      @p = Point.new(1, 1)
+    end
+
+    it "should return no clusters" do
+    end
+  end
+end

data/spec/hierclust_spec.rb

@@ -0,0 +1,4 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+describe Hierclust do
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  gem 'rspec'
+  require 'spec'
+end
+
+require File.dirname(__FILE__) + '/../lib/hierclust'

data/tasks/deployment.rake

@@ -0,0 +1,34 @@
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+desc 'Install the package as a gem, without generating documentation(ri/rdoc)'
+task :install_gem_no_doc => [:clean, :package] do
+  sh "#{'sudo ' unless Hoe::WINDOZE }gem install pkg/*.gem --no-rdoc --no-ri"
+end
+
+namespace :manifest do
+  desc 'Recreate Manifest.txt to include ALL files'
+  task :refresh do
+    `rake check_manifest | patch -p0 > Manifest.txt`
+  end
+end

data/tasks/environment.rake

@@ -0,0 +1,7 @@
+task :ruby_env do
+  RUBY_APP = if RUBY_PLATFORM =~ /java/
+    "jruby"
+  else
+    "ruby"
+  end unless defined? RUBY_APP
+end

data/tasks/rspec.rake

@@ -0,0 +1,20 @@
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  begin
+    require 'rubygems'
+    require 'spec/rake/spectask'
+  rescue LoadError
+    puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+    exit(0)
+  end
+end
+
+desc "Run the specs under spec/"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/*_spec.rb']
+end

data/tasks/website.rake

@@ -0,0 +1,17 @@
+desc 'Generate website files'
+task :website_generate => :ruby_env do
+  (Dir['website/**/*.txt'] - Dir['website/version*.txt']).each do |txt|
+    sh %{ #{RUBY_APP} script/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{PATH}/"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]

data/website/index.html

@@ -0,0 +1,147 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>
+      Simple Hierarchical Clustering
+  </title>
+  <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
+<style>
+
+</style>
+  <script type="text/javascript">
+    window.onload = function() {
+      settings = {
+          tl: { radius: 10 },
+          tr: { radius: 10 },
+          bl: { radius: 10 },
+          br: { radius: 10 },
+          antiAlias: true,
+          autoPad: true,
+          validTags: ["div"]
+      }
+      var versionBox = new curvyCorners(settings, document.getElementById("version"));
+      versionBox.applyCornersToAll();
+    }
+  </script>
+</head>
+<body>
+<div id="main">
+
+    <h1>Simple Hierarchical Clustering</h1>
+    <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/hierclust"; return false'>
+      <p>Get Version</p>
+      <a href="http://rubyforge.org/projects/hierclust" class="numbers">0.1.0</a>
+    </div>
+    <h1>&#x2192; &#8216;hierclust&#8217;</h1>
+
+
+	<h2>What</h2>
+
+
+	<p>Given a set of points, organizes them into clusters. You can either have it continue clustering until all the clusters are organized into larger clusters, or tell it to stop once a certain minimum level of separation between clusters has been reached.</p>
+
+
+	<p>Useful for taking a large set of points to be plotted on a map, and reducing them to a smaller number of clusters, separated enough so that the map remains legible.</p>
+
+
+	<h2>Installing</h2>
+
+
+	<p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">hierclust</span></pre></p>
+
+
+	<h2>The basics</h2>
+
+
+	<p><pre class='syntax'><span class="ident">points</span> <span class="punct">=</span> <span class="punct">(</span><span class="number">1</span><span class="punct">..</span><span class="number">6</span><span class="punct">).</span><span class="ident">map</span> <span class="punct">{</span> <span class="constant">Hierclust</span><span class="punct">::</span><span class="constant">Point</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span><span class="ident">rand</span><span class="punct">(</span><span class="number">10</span><span class="punct">),</span> <span class="ident">rand</span><span class="punct">(</span><span class="number">10</span><span class="punct">))</span> <span class="punct">}</span>
+<span class="ident">clusterer</span> <span class="punct">=</span> <span class="constant">Hierclust</span><span class="punct">::</span><span class="constant">Clusterer</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span><span class="ident">points</span><span class="punct">)</span>
+<span class="ident">puts</span> <span class="ident">clusterer</span><span class="punct">.</span><span class="ident">clusters</span> <span class="comment"># =&gt; [[[(4, 9), (4, 8)], (9, 6)], [[(1, 4), (3, 1)], (6, 3)]]</span></pre></p>
+
+
+	<h2>Demonstration of usage</h2>
+
+
+	<p>Let&#8217;s say you have an existing set of objects with latitudes and longitudes, and you want to organize them into clusters that are separated by at least 5 degrees (for simplicity&#8217;s sake we&#8217;ll pretend that latitudes and longitude form a rectangular grid).</p>
+
+
+	<p><pre class='syntax'><span class="ident">require</span> <span class="punct">'</span><span class="string">hierclust</span><span class="punct">'</span></pre></p>
+
+
+	<p>Start by extending the built-in Point class so that it can maintain a reference
+to your data:</p>
+
+
+	<p><pre class='syntax'><span class="keyword">class </span><span class="class">Hierclust::Point</span>
+  <span class="ident">attr_accessor</span> <span class="symbol">:data</span>
+<span class="keyword">end</span></pre></p>
+
+
+	<p>Then turn your data into a set of points:</p>
+
+
+	<p><pre class='syntax'><span class="ident">dataset</span> <span class="punct">=</span> <span class="constant">MyGeocodedThing</span><span class="punct">.</span><span class="ident">find</span><span class="punct">(</span><span class="symbol">:all</span><span class="punct">)</span>
+<span class="ident">points</span> <span class="punct">=</span> <span class="ident">dataset</span><span class="punct">.</span><span class="ident">map</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">thing</span><span class="punct">|</span>
+  <span class="ident">point</span> <span class="punct">=</span> <span class="constant">Hierclust</span><span class="punct">::</span><span class="constant">Point</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span><span class="ident">thing</span><span class="punct">.</span><span class="ident">lon</span><span class="punct">,</span> <span class="ident">thing</span><span class="punct">.</span><span class="ident">lat</span><span class="punct">)</span>
+  <span class="ident">point</span><span class="punct">.</span><span class="ident">data</span> <span class="punct">=</span> <span class="ident">thing</span>
+  <span class="ident">point</span>
+<span class="keyword">end</span></pre></p>
+
+
+	<p>Then tell Hierclust to cluster those points to at least 5 degrees separation:</p>
+
+
+	<p><pre class='syntax'><span class="ident">clusterer</span> <span class="punct">=</span> <span class="constant">Hierclust</span><span class="punct">::</span><span class="constant">Clusterer</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span><span class="ident">points</span><span class="punct">,</span> <span class="number">5</span><span class="punct">)</span>
+<span class="ident">clusters</span> <span class="punct">=</span> <span class="ident">clusterer</span><span class="punct">.</span><span class="ident">clusters</span></pre></p>
+
+
+	<p>Then do what you will with your clusters:</p>
+
+
+	<p><pre class='syntax'><span class="ident">map</span> <span class="punct">=</span> <span class="constant">MapThing</span><span class="punct">.</span><span class="ident">new</span>
+<span class="ident">clusters</span><span class="punct">.</span><span class="ident">each</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">cluster</span><span class="punct">|</span>
+  <span class="ident">map</span><span class="punct">.</span><span class="ident">add_point</span><span class="punct">(</span>
+    <span class="ident">x</span> <span class="punct">=&gt;</span> <span class="ident">cluster</span><span class="punct">.</span><span class="ident">x</span><span class="punct">,</span>
+    <span class="ident">y</span> <span class="punct">=&gt;</span> <span class="ident">cluster</span><span class="punct">.</span><span class="ident">y</span><span class="punct">,</span>
+    <span class="ident">label</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string"><span class="expr">#{cluster.size}</span> Things</span><span class="punct">&quot;</span>
+  <span class="punct">)</span>
+<span class="keyword">end</span></pre></p>
+
+
+	<h2>Forum</h2>
+
+
+	<p><a href="http://groups.google.com/group/hierclust">http://groups.google.com/group/hierclust</a></p>
+
+
+	<h2>How to submit patches</h2>
+
+
+	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
+
+
+	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/hierclust/trunk</code> for anonymous access.</p>
+
+
+	<h2>License</h2>
+
+
+	<p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
+
+
+	<h2>Contact</h2>
+
+
+	<p>Comments are welcome. Send an email to <a href="mailto:FIXME"><span class="caps">FIXME</span> full name</a> email via the <a href="http://groups.google.com/group/hierclust">forum</a></p>
+    <p class="coda">
+      <a href="FIXME email">FIXME full name</a>, 2nd February 2008<br>
+      Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
+    </p>
+</div>
+
+<!-- insert site tracking codes here, like Google Urchin -->
+
+</body>
+</html>

data/website/index.txt

@@ -0,0 +1,76 @@
+h1. Simple Hierarchical Clustering
+
+h1. → 'hierclust'
+
+h2. What
+
+Given a set of points, organizes them into clusters. You can either have it continue clustering until all the clusters are organized into larger clusters, or tell it to stop once a certain minimum level of separation between clusters has been reached.
+
+Useful for taking a large set of points to be plotted on a map, and reducing them to a smaller number of clusters, separated enough so that the map remains legible.
+
+h2. Installing
+
+<pre syntax="ruby">sudo gem install hierclust</pre>
+
+h2. The basics
+
+<pre syntax="ruby">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)]]</pre>
+
+h2. Demonstration of usage
+
+Let's say you have an existing set of objects with latitudes and longitudes, and you want to organize them into clusters that are separated by at least 5 degrees (for simplicity's sake we'll pretend that latitudes and longitude form a rectangular grid).
+
+<pre syntax="ruby">require 'hierclust'</pre>
+
+Start by extending the built-in Point class so that it can maintain a reference
+to your data:
+
+<pre syntax="ruby">class Hierclust::Point
+  attr_accessor :data
+end</pre>
+
+Then turn your data into a set of points:
+
+<pre syntax="ruby">dataset = MyGeocodedThing.find(:all)
+points = dataset.map do |thing|
+  point = Hierclust::Point.new(thing.lon, thing.lat)
+  point.data = thing
+  point
+end</pre>
+
+Then tell Hierclust to cluster those points to at least 5 degrees separation:
+
+<pre syntax="ruby">clusterer = Hierclust::Clusterer.new(points, 5)
+clusters = clusterer.clusters</pre>
+
+Then do what you will with your clusters:
+
+<pre syntax="ruby">map = MapThing.new
+clusters.each do |cluster|
+  map.add_point(
+    x => cluster.x,
+    y => cluster.y,
+    label => "#{cluster.size} Things"
+  )
+end</pre>
+
+h2. Forum
+
+"http://groups.google.com/group/hierclust":http://groups.google.com/group/hierclust
+
+h2. How to submit patches
+
+Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
+
+The trunk repository is <code>svn://rubyforge.org/var/svn/hierclust/trunk</code> for anonymous access.
+
+h2. License
+
+This code is free to use under the terms of the MIT license. 
+
+h2. Contact
+
+Comments are welcome. Send an email to "FIXME full name":mailto:FIXME email via the "forum":http://groups.google.com/group/hierclust
+