fastcluster 0.9 → 1.0

data/ext/clusterer.c

@@ -3,6 +3,18 @@
 #include <stdlib.h>
 #include <math.h>
 
+#ifndef RUBY_19
+#ifndef RFLOAT_VALUE
+#define RFLOAT_VALUE(v) (RFLOAT(v)->value)
+#endif
+#ifndef RARRAY_LEN
+#define RARRAY_LEN(v) (RARRAY(v)->len)
+#endif
+#ifndef RARRAY_PTR
+#define RARRAY_PTR(v) (RARRAY(v)->ptr)
+#endif
+#endif
+
 /*
 *
 * Algorithm:
@@ -88,11 +100,11 @@ static void fc_combine_clusters(CLUSTER * dst, CLUSTER * src) {
 */
 static long fc_get_max_grid(long resolution, CLUSTER * point_array, long num_points) {
   int i;
-  int max_grid = 0;
+  long max_grid = 0;
   for(i = 0; i < num_points; i++) {
     CLUSTER * point = &point_array[i];
-    int xg = point->x/resolution;
-    int yg = point->y/resolution;
+    long xg = point->x/resolution;
+    long yg = point->y/resolution;
     if(xg>max_grid)
       max_grid = xg;
     if(yg>max_grid)
@@ -148,9 +160,9 @@ static VALUE fc_initialize_clusterer(int argc, VALUE *argv, VALUE self) {
 static void fc_native_point_array(CLUSTER * arrayPtr, VALUE rubyArray, long num_points) {
   int i;
   for(i=0;i<num_points;i++) {
-    VALUE holdArray = RARRAY(rubyArray)->ptr[i];
-    double x = NUM2DBL(RARRAY(holdArray)->ptr[0]);
-    double y = NUM2DBL(RARRAY(holdArray)->ptr[1]);
+    VALUE holdArray = RARRAY_PTR(rubyArray)[i];
+    double x = NUM2DBL(RARRAY_PTR(holdArray)[0]);
+    double y = NUM2DBL(RARRAY_PTR(holdArray)[1]);
 
     arrayPtr[i].x = x;
     arrayPtr[i].y = y;
@@ -158,14 +170,30 @@ static void fc_native_point_array(CLUSTER * arrayPtr, VALUE rubyArray, long num_
   }
 }
 
-static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER * point_array, int num_points, long * cluster_size) {
-  int max_grid = fc_get_max_grid(resolution, &point_array[0], num_points);
+/*
+* This function does the actual clustering. It takes the following params:
+*
+* <tt>separation</tt> - The minimum distance between clusters. At 0 there will be one cluster with all the points.
+* <tt>resolution</tt> - Any points that fall within resolution distance will be clustered automatically.
+* <tt>point_array</tt> - Array of points to cluster.
+* <tt>num_points</tt> - Size of the point array.
+* <tt>cluster_size</tt> - Pointer for a variable to receive the size of the returned array.
+*
+* This function return an array of CLUSTER.
+*/
+static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER * point_array, long num_points, long * cluster_size) {
   int i, j;
   long preclust_size = 0;
 
   CLUSTER * cluster;
   CLUSTER * clusters;
 
+  // This first section does preclustering. The points are split into a grid where each
+  // grid box is of the size resolutionxresolution. When more than one point falls
+  // in a grid box they are clustered.
+  long max_grid = fc_get_max_grid(resolution, &point_array[0], num_points);
+
+  // Only precluster if a resolution is specified
   if(resolution > 0) {
     CLUSTER grid_array[max_grid][max_grid];
 
@@ -175,20 +203,24 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
       }
     }
 
+    // Add clusters to grid
     for(i = 0; i < num_points; i++) {
       cluster = &point_array[i];
 
-      int gx = floor(cluster->x/resolution);
-      int gy = floor(cluster->y/resolution);
+      long gx = floor(cluster->x/resolution);
+      long gy = floor(cluster->y/resolution);
 
       fc_add_to_cluster(&grid_array[gx][gy], cluster->x, cluster->y);
 
+      // If the grid array is holding a cluster of size 1 at this point
+      // then its a new cluster, so the preclust_size is incremented.
       if(grid_array[gx][gy].size == 1) preclust_size++;
     }
 
+    // Now the grid clusters are copied into an array
     clusters = malloc(preclust_size * sizeof(CLUSTER));
 
-    int max_grid_total = max_grid * max_grid;
+    long max_grid_total = max_grid * max_grid;
     CLUSTER * gridPtr = grid_array[0];
 
     int incr = 0;
@@ -199,6 +231,7 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
       }
     }
   } else {
+    // As there is no grid just copy the original point array into a new array
     preclust_size = num_points;
     clusters = malloc(preclust_size * sizeof(CLUSTER));
     memcpy(&clusters[0], &point_array[0], preclust_size * sizeof(CLUSTER));
@@ -207,11 +240,10 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
   double distance_sep = 0;
   long current_cluster_size = 0;
   int found;
-  long nearest_origin;
+  long nearest_origin = 0;
   long nearest_other;
 
   do {
-    // calculate distance sep
     distance_sep = 0;
     nearest_other = 0;
 
@@ -219,8 +251,6 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
       for(j=i+1;j<preclust_size;j++){
         double distance = fc_get_distance_between(&clusters[i], &clusters[j]);
 
-//        printf("distance between %f, %f and %f, %f is %f\n", clusters[i].x, clusters[i].y, clusters[j].x, clusters[j].y, distance);
-
         if(distance_sep == 0 || distance < distance_sep) {
           distance_sep = distance;
 
@@ -232,9 +262,13 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
       }
     }
 
+    // If two clusters have been identified for merging, this part merges
+    // them into the first cluster and removes the second cluster from the array
     if(nearest_other > 0) {
+      // merge into first cluster
       fc_combine_clusters(&clusters[nearest_origin], &clusters[nearest_other]);
 
+      // remove second cluster by creating temporary array without it
       CLUSTER *newarr = malloc(preclust_size * sizeof(CLUSTER));
       memcpy(&newarr[0], &clusters[0], nearest_other * sizeof(CLUSTER));
       memcpy(&newarr[nearest_other], &clusters[nearest_other+1], (preclust_size - (nearest_other + 1)) * sizeof(CLUSTER));
@@ -243,18 +277,22 @@ static CLUSTER *fc_calculate_clusters(long separation, long resolution, CLUSTER
       clusters = (CLUSTER*)_tmp;
       preclust_size = preclust_size - 1;
 
-      for(i=0;i<preclust_size;i++)
-        clusters[i] = newarr[i];
+      // and copying it back
+      memcpy(&clusters[0], &newarr[0], preclust_size * sizeof(CLUSTER));
 
       free(newarr);
     }
-
+  // keep looping until either everything is in one cluster, or all clusters are
+  // outside the separation distance.
   } while((separation == 0 || distance_sep < separation) && preclust_size > 1);
 
   *cluster_size = preclust_size;
   return clusters;
 }
 
+/*
+* Get the ruby class Cluster
+*/
 static VALUE fc_get_cluster_class() {
   ID cluster_module_id = rb_intern("Fastcluster");
   ID cluster_class_id = rb_intern("Cluster");
@@ -278,7 +316,7 @@ static VALUE fc_get_clusters(VALUE self) {
 
   // Create a native array of clusters from the ruby array of points
   VALUE pointArray = fc_get_points(self);
-  long num_points = RARRAY(pointArray)->len;
+  long num_points = RARRAY_LEN(pointArray);
   CLUSTER native_point_array[num_points];
 
   fc_native_point_array(&native_point_array[0], pointArray, num_points);
@@ -322,4 +360,4 @@ void Init_clusterer() {
 
   rb_define_method(clustererClass, "clusters", fc_get_clusters, 0);
   rb_define_method(clustererClass, "points", fc_get_points, 0);
-}
+}

data/spec/lib/fastcluster/clusterer_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
+require 'spec_helper'
 require 'benchmark'
 
 describe Fastcluster::Clusterer do
@@ -117,7 +117,7 @@ describe Fastcluster::Clusterer do
 
       describe "and separation 1" do
         before do
-          require 'lib/fastcluster'
+          require 'fastcluster'
           @clusterer = Fastcluster::Clusterer.new(1, 0, @points)
         end
 
@@ -219,4 +219,4 @@ describe Fastcluster::Clusterer do
       end
     end
   end
-end
+end

data/test.rb

@@ -1,69 +1,15 @@
 require File.dirname(__FILE__) + '/lib/fastcluster'
 require 'benchmark'
 
-points = [[815, 183], [860, 176], [793, 176], [847, 176], [813, 176], [865, 183],
-          [804, 185], [813, 181], [797, 181], [193, 133], [905, 168], [821, 173],
-          [804, 178], [799, 180], [175, 360], [880, 176], [826, 171], [843, 181],
-          [857, 171], [443, 495], [857, 174], [382, 132], [97, 1203], [218, 281],
-          [97, 1778], [814, 181], [474, 133], [797, 179], [844, 180], [812, 178],
-          [846, 18], [795, 183], [862, 182], [840, 175], [788, 176], [478, 140],
-          [860, 173], [974, 16], [833, 181], [288, 130], [831, 874], [884, 174],
-          [834, 179], [836, 182], [181, 354], [346, 46], [855, 171], [855, 180],
-          [959, 177], [792, 181], [138, 1774], [283, 783], [815, 877], [807, 178],
-          [430, 497], [819, 181], [801, 176], [836, 182], [825, 176], [873, 179],
-          [847, 182], [124, 1678], [157, 132], [835, 177], [827, 180], [532, 1191],
-          [873, 178], [174, 128], [805, 1328], [798, 178], [502, 659], [804, 180],
-          [960, 178], [886, 182], [867, 183], [875, 179], [854, 176], [849, 185],
-          [136, 1783], [800, 181], [810, 180], [312, 782], [865, 177], [745, 125],
-          [833, 178], [882, 181], [834, 177], [821, 184], [899, 182], [26, 124],
-          [859, 182], [892, 174], [172, 134], [822, 182], [396, 135], [830, 184],
-          [792, 185], [427, 488], [818, 173], [832, 177], [406, 129], [852, 181],
-          [805, 177], [820, 175], [19, 14], [839, 183], [264, 127], [800, 172],
-          [811, 176], [827, 178], [896, 177], [863, 183], [813, 177], [458, 495],
-          [808, 181], [850, 748], [810, 184], [850, 181], [886, 179], [446, 497],
-          [851, 180], [592, 132], [300, 538], [794, 180], [815, 180], [57, 1772],
-          [799, 175], [821, 182], [135, 1681], [830, 483], [796, 173], [887, 40],
-          [823, 179], [864, 179], [322, 30], [886, 182], [808, 178], [823, 189],
-          [230, 360], [224, 275], [875, 179], [133, 1773], [844, 175], [433, 495],
-          [13, 15], [856, 178], [871, 181], [658, 130], [839, 183], [822, 83],
-          [827, 175], [848, 179], [894, 184], [833, 177], [828, 176], [482, 135],
-          [841, 177], [817, 184], [470, 140], [800, 180], [857, 15], [807, 187],
-          [425, 497], [64, 131], [852, 580], [883, 183], [836, 181], [878, 177],
-          [815, 183], [860, 176], [793, 176], [847, 176], [813, 176], [865, 183],
-          [804, 185], [813, 181], [797, 181], [193, 133], [905, 168], [821, 173],
-          [804, 178], [799, 180], [175, 360], [880, 176], [826, 171], [843, 181],
-          [857, 171], [443, 495], [857, 174], [382, 132], [97, 1203], [218, 281],
-          [97, 1778], [814, 181], [474, 133], [797, 179], [844, 180], [812, 178],
-          [846, 18], [795, 183], [862, 182], [840, 175], [788, 176], [478, 140],
-          [860, 173], [974, 16], [833, 181], [288, 130], [831, 874], [884, 174],
-          [834, 179], [836, 182], [181, 354], [346, 46], [855, 171], [855, 180],
-          [959, 177], [792, 181], [138, 1774], [283, 783], [815, 877], [807, 178],
-          [430, 497], [819, 181], [801, 176], [836, 182], [825, 176], [873, 179],
-          [847, 182], [124, 1678], [157, 132], [835, 177], [827, 180], [532, 1191],
-          [873, 178], [174, 128], [805, 1328], [798, 178], [502, 659], [804, 180],
-          [960, 178], [886, 182], [867, 183], [875, 179], [854, 176], [849, 185],
-          [136, 1783], [800, 181], [810, 180], [312, 782], [865, 177], [745, 125],
-          [833, 178], [882, 181], [834, 177], [821, 184], [899, 182], [26, 124],
-          [859, 182], [892, 174], [172, 134], [822, 182], [396, 135], [830, 184],
-          [792, 185], [427, 488], [818, 173], [832, 177], [406, 129], [852, 181],
-          [805, 177], [820, 175], [19, 14], [839, 183], [264, 127], [800, 172],
-          [811, 176], [827, 178], [896, 177], [863, 183], [813, 177], [458, 495],
-          [808, 181], [850, 748], [810, 184], [850, 181], [886, 179], [446, 497],
-          [851, 180], [592, 132], [300, 538], [794, 180], [815, 180], [57, 1772],
-          [799, 175], [821, 182], [135, 1681], [830, 483], [796, 173], [887, 40],
-          [823, 179], [864, 179], [322, 30], [886, 182], [808, 178], [823, 189],
-          [230, 360], [224, 275], [875, 179], [133, 1773], [844, 175], [433, 495],
-          [13, 15], [856, 178], [871, 181], [658, 130], [839, 183], [822, 83],
-          [827, 175], [848, 179], [894, 184], [833, 177], [828, 176], [482, 135],
-          [841, 177], [817, 184], [470, 140], [800, 180], [857, 15], [807, 187],
-          [425, 497], [64, 131], [852, 580], [883, 183], [836, 181], [878, 177]]
+points = [[237, 434], [282, 435], [281, 429], [241, 427], [259, 434], [499, 218], [254, 431], [222, 433], [253, 441], [212, 440], [252, 432], [279, 433], [248, 428], [249, 202], [249, 202], [252, 202], [252, 202], [562, 402], [728, 23], [227, 424], [267, 428], [247, 438], [290, 452]]
 
 puts Benchmark.measure {
-clusterer = Fastcluster::Clusterer.new(105, 5, points)
-clusters = clusterer.clusters 
+clusterer = Fastcluster::Clusterer.new(25, 15, points)
+clusters = clusterer.clusters
+puts clusters.inspect
 
-clusters.sort{|a,b| a.size == b.size ? a.x <=> b.x : a.size <=> b.size }.each do |cluster|
-  puts cluster
-end
+#clusters.sort{|a,b| a.size == b.size ? a.x <=> b.x : a.size <=> b.size }.each do |cluster|
+#  puts cluster
+#end
 
 }

metadata

@@ -1,80 +1,70 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: fastcluster
-version: !ruby/object:Gem::Version 
-  version: "0.9"
+version: !ruby/object:Gem::Version
+  version: '1.0'
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jeremy Wells
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2009-10-24 00:00:00 +13:00
+date: 2011-07-09 00:00:00.000000000 +12:00
 default_executable: 
 dependencies: []
-
 description: A clustering library for 2 dimensional points
-email: jeremy@boost.co.nz
+email:
+- jemmyw@gmail.com
 executables: []
-
-extensions: 
+extensions:
 - ext/extconf.rb
-extra_rdoc_files: 
-- CHANGELOG
-- README.rdoc
-- ext/clusterer.c
+extra_rdoc_files: []
+files:
 - ext/extconf.rb
-- lib/fastcluster.rb
+- ext/clusterer.c
 - lib/fastcluster/cluster.rb
-files: 
+- lib/fastcluster.rb
 - CHANGELOG
-- Manifest
 - README.rdoc
-- Rakefile
-- ext/clusterer.c
-- ext/extconf.rb
-- lib/fastcluster.rb
-- lib/fastcluster/cluster.rb
 - spec/lib/fastcluster/cluster_spec.rb
 - spec/lib/fastcluster/clusterer_spec.rb
-- spec/spec.opts
 - spec/spec_helper.rb
 - spec/test_data.rb
 - test.rb
-- fastcluster.gemspec
 has_rdoc: true
 homepage: http://github.com/jemmyw/fastcluster
 licenses: []
-
 post_install_message: 
-rdoc_options: 
-- --line-numbers
-- --inline-source
-- --title
-- Fastcluster
-- --main
-- README.rdoc
-require_paths: 
+rdoc_options: []
+require_paths:
 - lib
-- ext
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "1.2"
-  version: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 716520748893881833
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 716520748893881833
 requirements: []
-
-rubyforge_project: fastcluster
-rubygems_version: 1.3.5
+rubyforge_project: 
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A clustering library for 2 dimensional points
-test_files: []
-
+test_files:
+- spec/lib/fastcluster/cluster_spec.rb
+- spec/lib/fastcluster/clusterer_spec.rb
+- spec/spec_helper.rb
+- spec/test_data.rb
+- test.rb

data/Manifest

@@ -1,14 +0,0 @@
-CHANGELOG
-Manifest
-README.rdoc
-Rakefile
-ext/clusterer.c
-ext/extconf.rb
-lib/fastcluster.rb
-lib/fastcluster/cluster.rb
-spec/lib/fastcluster/cluster_spec.rb
-spec/lib/fastcluster/clusterer_spec.rb
-spec/spec.opts
-spec/spec_helper.rb
-spec/test_data.rb
-test.rb

data/Rakefile

@@ -1,12 +0,0 @@
-require 'rubygems'
-require 'spec'
-require 'spec/rake/spectask'
-require 'echoe'
-
-Echoe.new("fastcluster") do |p|
-  p.author = "Jeremy Wells"
-  p.email = "jeremy@boost.co.nz"
-  p.summary = "A clustering library for 2 dimensional points"
-  p.description = "A clustering library for 2 dimensional points"
-  p.url = "http://github.com/jemmyw/fastcluster"
-end

data/fastcluster.gemspec

@@ -1,31 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{fastcluster}
-  s.version = "0.9"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Jeremy Wells"]
-  s.date = %q{2009-10-24}
-  s.description = %q{A clustering library for 2 dimensional points}
-  s.email = %q{jeremy@boost.co.nz}
-  s.extensions = ["ext/extconf.rb"]
-  s.extra_rdoc_files = ["CHANGELOG", "README.rdoc", "ext/clusterer.c", "ext/extconf.rb", "lib/fastcluster.rb", "lib/fastcluster/cluster.rb"]
-  s.files = ["CHANGELOG", "Manifest", "README.rdoc", "Rakefile", "ext/clusterer.c", "ext/extconf.rb", "lib/fastcluster.rb", "lib/fastcluster/cluster.rb", "spec/lib/fastcluster/cluster_spec.rb", "spec/lib/fastcluster/clusterer_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "spec/test_data.rb", "test.rb", "fastcluster.gemspec"]
-  s.homepage = %q{http://github.com/jemmyw/fastcluster}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Fastcluster", "--main", "README.rdoc"]
-  s.require_paths = ["lib", "ext"]
-  s.rubyforge_project = %q{fastcluster}
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{A clustering library for 2 dimensional points}
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
-end

data/spec/spec.opts

@@ -1,5 +0,0 @@
---colour
---format progress
---loadby mtime
---reverse
---debugger