flock 0.3.1 → 0.4.0

data/README.rdoc

@@ -4,11 +4,15 @@ Ruby bindings to {Cluster 3.0}[http://bonsai.hgc.jp/~mdehoon/software/cluster/so
 
 == Description
 
-Provides bindings to K-Means clustering in Cluster 3.0
+Provides bindings to clustering methods in Cluster 3.0.
+
+ * K-Means
+ * Kohonen Self-Organizing Maps
+ * Tree Cluster or Hierarchical Clustering
 
 == Synopsis
 
-=== Numeric Data
+=== Specify vectors explicitly
 
   require 'pp'
   require 'flock'
@@ -69,8 +73,18 @@ Provides bindings to K-Means clustering in Cluster 3.0
     weights:   Array.new(13) {1.0},
   )
 
+  pp Flock.treecluster(
+    6,
+    data,
+    mask,
+    method:    Flock::METHOD_AVERAGE,
+    metric:    Flock::METRIC_EUCLIDIAN,
+    transpose: 0,
+    weights:   Array.new(13) {1.0},
+  )
+
 
-=== Sparse and Non-Numeric data
+=== Sparse data and clustering string labels
 
   require 'pp'
   require 'flock'
@@ -88,7 +102,7 @@ Provides bindings to K-Means clustering in Cluster 3.0
 
   data = []
 
-  # a much simpler way to cluster text
+  # a much simpler way to cluster text labels.
   data << %w(apple orange)
   data << %w(black white)
   data << %w(white cyan)
@@ -97,9 +111,15 @@ Provides bindings to K-Means clustering in Cluster 3.0
 
   # additional options such as metric, iterations can be passed in a hash.
   pp Flock.sparse_kmeans(2, data)
+  pp Flock.sparse_treecluster(2, data)
+
 
 === Self-Organizing Map
 
+Self-Organizing Maps (SOM) require that you specify a 2D grid on which data points can cluster. Some of the
+grid points may be empty and others might have clusters mapped to them. There is no need to provide
+a fixed cluster size like K-Means or Tree Cluster.
+
   require 'pp'
   require 'flock'
 
@@ -116,11 +136,13 @@ Provides bindings to K-Means clustering in Cluster 3.0
   # additional options such as metric, iterations can be passed in a hash.
   pp Flock.sparse_self_organizing_map(2, 2, data)
 
-== TODO
+Note: SOM clustering provides the 2D grid coordinate for each vector instead of an integer cluster value
+for each vector like K-Means and Tree Cluster methods do.
 
-Bindings to,
+== TODO
 
-* Hierarchical clustering (treecluster)
+* {K-Tree clustering}[http://arxiv.org/pdf/1001.0827v1]
+* Use Sparse Matrix instead of converting sparse data into dense matrices.
 
 = License
 

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0

data/examples/treecluster.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/ruby
+
+require 'pp'
+require 'flock'
+
+data = []
+data << %w(apple orange)
+data << %w(black white)
+data << %w(white cyan)
+data << %w(orange)
+data << %w(apple)
+
+pp Flock.sparse_treecluster(2, data)

data/ext/flock.c

@@ -218,8 +218,12 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
     VALUE cluster  = rb_ary_new();
     VALUE centroid = rb_ary_new();
 
-    for (i = 0; i < dimx; i++)
-        rb_ary_push(cluster, INT2NUM(ccluster[i][0] * nxgrid + ccluster[i][1]));
+    for (i = 0; i < dimx; i++) {
+        VALUE gridpoint = rb_ary_new();
+        rb_ary_push(gridpoint, INT2NUM(ccluster[i][0]));
+        rb_ary_push(gridpoint, INT2NUM(ccluster[i][1]));
+        rb_ary_push(cluster, gridpoint);
+    }
 
     for (i = 0; i < nxgrid; i++) {
         for (j = 0; j < nygrid; j++) {
@@ -256,6 +260,96 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
     return result;
 }
 
+VALUE rb_treecluster(int argc, VALUE *argv, VALUE self) {
+    VALUE size, data, mask, weights, options;
+    rb_scan_args(argc, argv, "22", &size, &data, &mask, &options);
+
+    if (TYPE(data) != T_ARRAY)
+        rb_raise(rb_eArgError, "data should be an array of arrays");
+
+    if (!NIL_P(mask) && TYPE(mask) != T_ARRAY)
+        rb_raise(rb_eArgError, "mask should be an array of arrays");
+
+    if (NIL_P(size) || NUM2INT(rb_Integer(size)) > RARRAY_LEN(data))
+        rb_raise(rb_eArgError, "size should be > 0 and <= data size");
+
+    int transpose = opt_int_value(options, "transpose", 0);
+    // a = average, m = means
+    int method    = opt_int_value(options, "method", 'a');
+    // e = euclidian,
+    // b = city-block distance
+    // c = correlation
+    // a = absolute value of the correlation
+    // u = uncentered correlation
+    // x = absolute uncentered correlation
+    // s = spearman's rank correlation
+    // k = kendall's tau
+    int dist      = opt_int_value(options, "metric", 'e');
+
+    int i,j;
+    int nrows = RARRAY_LEN(data);
+    int ncols = RARRAY_LEN(rb_ary_entry(data, 0));
+    int nsets = NUM2INT(rb_Integer(size));
+
+    double **cdata    = (double**)malloc(sizeof(double*)*nrows);
+    int    **cmask    = (int   **)malloc(sizeof(int   *)*nrows);
+    double *cweights  = (double *)malloc(sizeof(double )*ncols);
+
+    int *ccluster, dimx = nrows, dimy = ncols;
+
+    for (i = 0; i < nrows; i++) {
+        cdata[i]          = (double*)malloc(sizeof(double)*ncols);
+        cmask[i]          = (int   *)malloc(sizeof(int   )*ncols);
+        for (j = 0; j < ncols; j++) {
+            cdata[i][j] = NUM2DBL(rb_Float(rb_ary_entry(rb_ary_entry(data, i), j)));
+            cmask[i][j] = NIL_P(mask) ? 1 : NUM2INT(rb_Integer(rb_ary_entry(rb_ary_entry(mask, i), j)));
+        }
+    }
+
+    weights = NIL_P(options) ? Qnil : rb_hash_aref(options, ID2SYM(rb_intern("weights")));
+    for (i = 0; i < ncols; i++) {
+        cweights[i] = NIL_P(weights) ? 1.0 : NUM2DBL(rb_Float(rb_ary_entry(weights, i)));
+    }
+
+    if (transpose) {
+        dimx  = ncols;
+        dimy  = nrows;
+    }
+
+    ccluster = (int *)malloc(sizeof(int)*dimx);
+
+    Node *tree   = treecluster(nrows, ncols, cdata, cmask, cweights, transpose, dist, method, 0);
+    VALUE result = Qnil, cluster;
+
+    if (tree) {
+        cuttree(dimx, tree, nsets, ccluster);
+
+        result  = rb_hash_new();
+        cluster = rb_ary_new();
+
+        for (i = 0; i < dimx; i++)
+            rb_ary_push(cluster, INT2NUM(ccluster[i]));
+
+        rb_hash_aset(result, ID2SYM(rb_intern("cluster")),   cluster);
+    }
+
+    for (i = 0; i < nrows; i++) {
+        free(cdata[i]);
+        free(cmask[i]);
+    }
+
+    free(cdata);
+    free(cmask);
+    free(cweights);
+    free(ccluster);
+
+    if (tree)
+        free(tree);
+    else
+        rb_raise(rb_eNoMemError, "tree cluster ran out of memory");
+
+    return result;
+}
 
 VALUE rb_distance(VALUE vec1, VALUE vec2, distance_fn fn) {
     uint32_t size;
@@ -334,6 +428,7 @@ void Init_flock(void) {
     mFlock = rb_define_module("Flock");
     rb_define_module_function(mFlock, "kmeans", RUBY_METHOD_FUNC(rb_kmeans), -1);
     rb_define_module_function(mFlock, "self_organizing_map", RUBY_METHOD_FUNC(rb_som), -1);
+    rb_define_module_function(mFlock, "treecluster", RUBY_METHOD_FUNC(rb_treecluster), -1);
 
     rb_define_const(mFlock, "METHOD_AVERAGE", INT2NUM('a'));
     rb_define_const(mFlock, "METHOD_MEDIAN",  INT2NUM('m'));

data/flock.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{flock}
-  s.version = "0.3.1"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Bharanee Rathna"]
-  s.date = %q{2011-04-24}
+  s.date = %q{2011-04-27}
   s.description = %q{A thin ruby binding to Cluster 3.0}
   s.email = ["deepfryed@gmail.com"]
   s.extensions = ["ext/extconf.rb"]
@@ -35,7 +35,8 @@ Gem::Specification.new do |s|
   s.test_files = [
     "examples/sparse.rb",
      "examples/som.rb",
-     "examples/dense.rb"
+     "examples/dense.rb",
+     "examples/treecluster.rb"
   ]
 
   if s.respond_to? :specification_version then

data/lib/flock.rb

@@ -21,27 +21,30 @@ module Flock
     [dims,data]
   end
 
-  def self.sparse_kmeans size, sparse_data, options = {}
+  def self.densify sparse_data, weights = nil
     dims, data = sparse_data[0].kind_of?(Array) ? sparse_array_to_data(sparse_data) : sparse_hash_to_data(sparse_data)
 
-    if options.key?(:weights)
-      weights = Array.new(dims.size) {1}
-      options[:weights].each {|k,v| weights[dims[k]] = v }
-      options[:weights] = weights
+    if weights
+      resampled = Array.new(dims.size) {1}
+      weights.each {|k,v| resampled[dims[k]] = v }
+      weights   = resampled
     end
 
+    [data, weights]
+  end
+
+  def self.sparse_kmeans size, sparse_data, options = {}
+    data, options[:weights] = densify(sparse_data, options[:weights])
     kmeans(size, data, nil, options)
   end
 
   def self.sparse_self_organizing_map nx, ny, sparse_data, options = {}
-    dims, data = sparse_data[0].kind_of?(Array) ? sparse_array_to_data(sparse_data) : sparse_hash_to_data(sparse_data)
-
-    if options.key?(:weights)
-      weights = Array.new(dims.size) {1}
-      options[:weights].each {|k,v| weights[dims[k]] = v }
-      options[:weights] = weights
-    end
-
+    data, options[:weights] = densify(sparse_data, options[:weights])
     self_organizing_map(nx, ny, data, nil, options)
   end
+
+  def self.sparse_treecluster size, sparse_data, options = {}
+    data, options[:weights] = densify(sparse_data, options[:weights])
+    treecluster(size, data, nil, options)
+  end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 1
-  version: 0.3.1
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Bharanee Rathna
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-24 00:00:00 +10:00
+date: 2011-04-27 00:00:00 +10:00
 default_executable: 
 dependencies: []
 
@@ -40,6 +40,7 @@ files:
 - examples/sparse.rb
 - examples/som.rb
 - examples/dense.rb
+- examples/treecluster.rb
 has_rdoc: true
 homepage: http://github.com/deepfryed/flock
 licenses: []
@@ -76,3 +77,4 @@ test_files:
 - examples/sparse.rb
 - examples/som.rb
 - examples/dense.rb
+- examples/treecluster.rb