flock 0.4.1 → 0.5.0

data/ext/cluster.h

@@ -55,7 +55,7 @@ void getclustermedoids(int nclusters, int nelements, double** distance,
   int clusterid[], int centroids[], double errors[]);
 void kcluster (int nclusters, int ngenes, int ndata, double** data,
   int** mask, double weight[], int transpose, int npass, char method, char dist,
-  int clusterid[], double* error, int* ifound);
+  int clusterid[], double* error, int* ifound, int assign);
 void kmedoids (int nclusters, int nelements, double** distance,
   int npass, int clusterid[], double* error, int* ifound);
 

data/ext/flock.c

@@ -3,41 +3,60 @@
 
 #define ID_CONST_GET rb_intern("const_get")
 #define CONST_GET(scope, constant) (rb_funcall(scope, ID_CONST_GET, 1, rb_str_new2(constant)))
+#define DEFAULT_ITERATIONS 100
 
-static VALUE mFlock;
+static VALUE mFlock, scFlock;
 typedef double (*distance_fn)(int, double**, double**, int**, int**, const double [], int, int, int);
 
-int opt_int_value(VALUE option, char *key, int def) {
-  if (NIL_P(option)) return def;
+int get_int_option(VALUE option, char *key, int default_value) {
+    if (NIL_P(option)) return default_value;
 
-  VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
-  return NIL_P(value) ? def : NUM2INT(value);
+    VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
+    return NIL_P(value) ? default_value : NUM2INT(value);
 }
 
-int opt_double_value(VALUE option, char *key, double def) {
-  if (NIL_P(option)) return def;
+int get_bool_option(VALUE option, char *key, int default_value) {
+    if (NIL_P(option)) return default_value;
+    VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
+    return (TYPE(value) == T_FALSE || TYPE(value) == T_NIL) ? 0 : 1;
+}
+
+double get_dbl_option(VALUE option, char *key, double default_value) {
+    if (NIL_P(option)) return default_value;
 
-  VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
-  return NIL_P(value) ? def : NUM2DBL(value);
+    VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
+    return NIL_P(value) ? default_value : NUM2DBL(value);
 }
 
-VALUE rb_kmeans(int argc, VALUE *argv, VALUE self) {
+VALUE get_value_option(VALUE option, char *key, VALUE default_value) {
+    if (NIL_P(option)) return default_value;
+
+    VALUE value = rb_hash_aref(option, ID2SYM(rb_intern(key)));
+    return NIL_P(value) ? default_value : value;
+}
+
+/* @api private */
+VALUE rb_do_kcluster(int argc, VALUE *argv, VALUE self) {
     VALUE size, data, mask, weights, options;
-    rb_scan_args(argc, argv, "22", &size, &data, &mask, &options);
+    rb_scan_args(argc, argv, "21", &size, &data, &options);
 
     if (TYPE(data) != T_ARRAY)
         rb_raise(rb_eArgError, "data 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");
+
+    mask = get_value_option(options, "mask", Qnil);
+
     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 = get_bool_option(options, "transpose", 0);
+    int npass     = get_int_option(options, "iterations", DEFAULT_ITERATIONS);
 
-    int transpose = opt_int_value(options, "transpose", 0);
-    int npass     = opt_int_value(options, "iterations", 1000);
     // a = average, m = means
-    int method    = opt_int_value(options, "method", 'a');
+    int method    = get_int_option(options, "method", 'a');
+
     // e = euclidian,
     // b = city-block distance
     // c = correlation
@@ -46,7 +65,10 @@ VALUE rb_kmeans(int argc, VALUE *argv, VALUE self) {
     // x = absolute uncentered correlation
     // s = spearman's rank correlation
     // k = kendall's tau
-    int dist      = opt_int_value(options, "metric", 'e');
+    int dist      = get_int_option(options, "metric", 'e');
+
+    // initial assignment
+    int assign    = get_int_option(options, "seed",    0);
 
     int i,j;
     int nrows = RARRAY_LEN(data);
@@ -94,7 +116,7 @@ VALUE rb_kmeans(int argc, VALUE *argv, VALUE self) {
     double error;
 
     kcluster(nsets,
-        nrows, ncols, cdata, cmask, cweights, transpose, npass, method, dist, ccluster, &error, &ifound);
+        nrows, ncols, cdata, cmask, cweights, transpose, npass, method, dist, ccluster, &error, &ifound, assign);
     getclustercentroids(nsets,
         nrows, ncols, cdata, cmask, ccluster, ccentroid, ccentroid_mask, transpose, method);
 
@@ -137,13 +159,16 @@ VALUE rb_kmeans(int argc, VALUE *argv, VALUE self) {
     return result;
 }
 
-VALUE rb_som(int argc, VALUE *argv, VALUE self) {
+/* @api private */
+VALUE rb_do_self_organizing_map(int argc, VALUE *argv, VALUE self) {
     VALUE nx, ny, data, mask, weights, options;
-    rb_scan_args(argc, argv, "32", &nx, &ny, &data, &mask, &options);
+    rb_scan_args(argc, argv, "31", &nx, &ny, &data, &options);
 
     if (TYPE(data) != T_ARRAY)
         rb_raise(rb_eArgError, "data should be an array of arrays");
 
+    mask = get_value_option(options, "mask", Qnil);
+
     if (!NIL_P(mask) && TYPE(mask) != T_ARRAY)
         rb_raise(rb_eArgError, "mask should be an array of arrays");
 
@@ -155,8 +180,8 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
 
     int nxgrid    = NUM2INT(rb_Integer(nx));
     int nygrid    = NUM2INT(rb_Integer(ny));
-    int transpose = opt_int_value(options, "transpose", 0);
-    int npass     = opt_int_value(options, "iterations", 1000);
+    int transpose = get_int_option(options, "transpose", 0);
+    int npass     = get_int_option(options, "iterations", DEFAULT_ITERATIONS);
 
     // e = euclidian,
     // b = city-block distance
@@ -166,8 +191,8 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
     // x = absolute uncentered correlation
     // s = spearman's rank correlation
     // k = kendall's tau
-    int dist      = opt_int_value(options, "metric", 'e');
-    double tau    = opt_double_value(options, "tau", 1.0);
+    int dist      = get_int_option(options, "metric", 'e');
+    double tau    = get_dbl_option(options, "tau", 1.0);
 
     int i, j, k;
     int nrows = RARRAY_LEN(data);
@@ -211,8 +236,7 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
             ccelldata[i][j] = (double *)malloc(sizeof(double)*dimy);
     }
 
-    somcluster(nrows, ncols, cdata, cmask, cweights, transpose,
-        nxgrid, nygrid, tau, npass, dist, ccelldata, ccluster);
+    somcluster(nrows, ncols, cdata, cmask, cweights, transpose, nxgrid, nygrid, tau, npass, dist, ccelldata, ccluster);
 
     VALUE result   = rb_hash_new();
     VALUE cluster  = rb_ary_new();
@@ -260,22 +284,30 @@ VALUE rb_som(int argc, VALUE *argv, VALUE self) {
     return result;
 }
 
-VALUE rb_treecluster(int argc, VALUE *argv, VALUE self) {
+/* @api private */
+VALUE rb_do_treecluster(int argc, VALUE *argv, VALUE self) {
     VALUE size, data, mask, weights, options;
-    rb_scan_args(argc, argv, "22", &size, &data, &mask, &options);
+    rb_scan_args(argc, argv, "21", &size, &data, &options);
 
     if (TYPE(data) != T_ARRAY)
         rb_raise(rb_eArgError, "data should be an array of arrays");
 
+    mask = get_value_option(options, "mask", Qnil);
+
     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');
+    int transpose = get_int_option(options, "transpose", 0);
+
+    // s: pairwise single-linkage clustering
+    // m: pairwise maximum- (or complete-) linkage clustering
+    // a: pairwise average-linkage clustering
+    // c: pairwise centroid-linkage clustering
+    int method    = get_int_option(options, "method", 'a');
+
     // e = euclidian,
     // b = city-block distance
     // c = correlation
@@ -284,7 +316,7 @@ VALUE rb_treecluster(int argc, VALUE *argv, VALUE self) {
     // x = absolute uncentered correlation
     // s = spearman's rank correlation
     // k = kendall's tau
-    int dist      = opt_int_value(options, "metric", 'e');
+    int dist      = get_int_option(options, "metric", 'e');
 
     int i,j;
     int nrows = RARRAY_LEN(data);
@@ -346,15 +378,25 @@ VALUE rb_treecluster(int argc, VALUE *argv, VALUE self) {
     if (tree)
         free(tree);
     else
-        rb_raise(rb_eNoMemError, "tree cluster ran out of memory");
+        rb_raise(rb_eNoMemError, "treecluster ran out of memory");
 
     return result;
 }
 
-VALUE rb_distance(VALUE vec1, VALUE vec2, distance_fn fn) {
+void inline copy_mask(VALUE src, int *dst, int size, int def) {
+    int i;
+    if (NIL_P(src))
+        for (i = 0; i < size; i++)
+            dst[i] = def;
+    else
+        for (i = 0; i < size; i++)
+            dst[i] = NUM2INT(rb_ary_entry(src, i));
+}
+
+VALUE rb_distance(VALUE vec1, VALUE m1, VALUE vec2, VALUE m2, distance_fn fn) {
     uint32_t size;
     double *data1, *data2, *weight, dist;
-    int *mask, i;
+    int *mask1, *mask2, i;
 
     if (TYPE(vec1) != T_ARRAY)
         rb_raise(rb_eArgError, "vector1 should be an array");
@@ -373,17 +415,21 @@ VALUE rb_distance(VALUE vec1, VALUE vec2, distance_fn fn) {
     data1  = (double *)malloc(sizeof(double)*size);
     data2  = (double *)malloc(sizeof(double)*size);
     weight = (double *)malloc(sizeof(double)*size);
-    mask   = (int *)malloc(sizeof(int)*size);
+    mask1  = (int *)malloc(sizeof(int)*size);
+    mask2  = (int *)malloc(sizeof(int)*size);
 
     for (i = 0; i < size; i++) {
-        mask[i]   = 1;
         weight[i] = 1;
         data1[i]  = NUM2DBL(rb_ary_entry(vec1, i));
         data2[i]  = NUM2DBL(rb_ary_entry(vec2, i));
     }
 
-    dist = fn(size, &data1, &data2, &mask, &mask, weight, 0, 0, 0);
-    free(mask);
+    copy_mask(m1, mask1, size, 1);
+    copy_mask(m2, mask2, size, 1);
+
+    dist = fn(size, &data1, &data2, &mask1, &mask2, weight, 0, 0, 0);
+    free(mask1);
+    free(mask2);
     free(weight);
     free(data2);
     free(data1);
@@ -391,48 +437,155 @@ VALUE rb_distance(VALUE vec1, VALUE vec2, distance_fn fn) {
     return DBL2NUM(dist);
 }
 
-VALUE rb_euclid(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, euclid);
+/*
+  Euclidian distance measure
+
+  @example
+    Flock.euclidian_distance([0, 0], [1, 1])
+    Flock.euclidian_distance([0, 0, 0], [1, 1, 1], [1, 1, 0], [1, 1, 0]) # with mask
+
+  @overload euclidian_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_euclid(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, euclid);
 }
 
-VALUE rb_cityblock(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, cityblock);
+/*
+  Cityblock distance measure
+
+  @overload cityblock_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_cityblock(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, cityblock);
 }
 
-VALUE rb_correlation(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, correlation);
+/*
+  Correlation distance measure
+
+  @overload correlation_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_correlation(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, correlation);
 }
 
-VALUE rb_ucorrelation(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, ucorrelation);
+/*
+  Uncentered correlation distance measure
+
+  @overload uncentered_correlation_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_ucorrelation(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, ucorrelation);
 }
 
-VALUE rb_acorrelation(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, acorrelation);
+/*
+  Absolute correlation distance measure
+
+  @overload absolute_correlation_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_acorrelation(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, acorrelation);
 }
 
-VALUE rb_uacorrelation(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, uacorrelation);
+/*
+  Absolute uncentered correlation distance measure
+
+  @overload absolute_uncentered_correlation_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_uacorrelation(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, uacorrelation);
 }
 
-VALUE rb_spearman(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, spearman);
+/*
+  Spearman distance measure
+
+  @overload spearman_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_spearman(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, spearman);
 }
 
-VALUE rb_kendall(VALUE self, VALUE vec1, VALUE vec2) {
-    return rb_distance(vec1, vec2, kendall);
+/*
+  Kendall distance measure
+
+  @overload kendall_distance(vector1, vector2, mask1 = identity, mask2 = identity)
+    @param [Array]  vector1     Numeric vector
+    @param [Array]  vector2     Numeric vector
+    @param [Array]  mask1       Optional mask for vector1
+    @param [Array]  mask2       Optional mask for vector2
+*/
+VALUE rb_kendall(int argc, VALUE *argv, VALUE self) {
+    VALUE v1, v2, m1, m2;
+    rb_scan_args(argc, argv, "22", &v1, &v2, &m1, &m2);
+    return rb_distance(v1, m1, v2, m2, kendall);
 }
 
 
 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);
+    mFlock  = rb_define_module("Flock");
+    scFlock = rb_singleton_class(mFlock);
+
+    rb_define_private_method(scFlock, "do_kcluster",            RUBY_METHOD_FUNC(rb_do_kcluster),            -1);
+    rb_define_private_method(scFlock, "do_self_organizing_map", RUBY_METHOD_FUNC(rb_do_self_organizing_map), -1);
+    rb_define_private_method(scFlock, "do_treecluster",         RUBY_METHOD_FUNC(rb_do_treecluster),         -1);
 
+    /* kcluster method - K-Means */
     rb_define_const(mFlock, "METHOD_AVERAGE", INT2NUM('a'));
+
+    /* kcluster method - K-Medians */
     rb_define_const(mFlock, "METHOD_MEDIAN",  INT2NUM('m'));
 
+    /* treecluster method - pairwise single-linkage clustering */
+    rb_define_const(mFlock, "METHOD_SINGLE_LINKAGE",   INT2NUM('s'));
+    /* treecluster method - pairwise maximum- (or complete-) linkage clustering */
+    rb_define_const(mFlock, "METHOD_MAXIMUM_LINKAGE",  INT2NUM('m'));
+    /* treecluster method - pairwise average-linkage clustering */
+    rb_define_const(mFlock, "METHOD_AVERAGE_LINKAGE",  INT2NUM('a'));
+    /* treecluster method - pairwise centroid-linkage clustering */
+    rb_define_const(mFlock, "METHOD_CENTROID_LINKAGE", INT2NUM('c'));
+
+
     rb_define_const(mFlock, "METRIC_EUCLIDIAN",                       INT2NUM('e'));
     rb_define_const(mFlock, "METRIC_CITY_BLOCK",                      INT2NUM('b'));
     rb_define_const(mFlock, "METRIC_CORRELATION",                     INT2NUM('c'));
@@ -442,12 +595,27 @@ void Init_flock(void) {
     rb_define_const(mFlock, "METRIC_SPEARMAN",                        INT2NUM('s'));
     rb_define_const(mFlock, "METRIC_KENDALL",                         INT2NUM('k'));
 
-    rb_define_module_function(mFlock, "euclidian_distance", RUBY_METHOD_FUNC(rb_euclid), 2);
-    rb_define_module_function(mFlock, "cityblock_distance", RUBY_METHOD_FUNC(rb_cityblock), 2);
-    rb_define_module_function(mFlock, "correlation_distance", RUBY_METHOD_FUNC(rb_correlation), 2);
-    rb_define_module_function(mFlock, "absolute_correlation_distance", RUBY_METHOD_FUNC(rb_acorrelation), 2);
-    rb_define_module_function(mFlock, "uncentered_correlation_distance", RUBY_METHOD_FUNC(rb_ucorrelation), 2);
-    rb_define_module_function(mFlock, "absolute_uncentered_correlation_distance", RUBY_METHOD_FUNC(rb_uacorrelation), 2);
-    rb_define_module_function(mFlock, "spearman_distance", RUBY_METHOD_FUNC(rb_spearman), 2);
-    rb_define_module_function(mFlock, "kendall_distance", RUBY_METHOD_FUNC(rb_kendall), 2);
+    /* Randomly assign data points to clusters using a uniform distribution. */
+    rb_define_const(mFlock, "SEED_RANDOM",          INT2NUM(0));
+
+    /*
+        K-Means++ style initialization where data points are probabilistically assigned to clusters
+        based on their distance from closest cluster.
+    */
+    rb_define_const(mFlock, "SEED_KMEANS_PLUSPLUS", INT2NUM(1));
+
+    /*
+        Deterministic cluster assignment by spreading out initial clusters as far away from each other
+        as possible.
+    */
+    rb_define_const(mFlock, "SEED_SPREADOUT",       INT2NUM(2));
+
+    rb_define_module_function(mFlock, "euclidian_distance", RUBY_METHOD_FUNC(rb_euclid), -1);
+    rb_define_module_function(mFlock, "cityblock_distance", RUBY_METHOD_FUNC(rb_cityblock), -1);
+    rb_define_module_function(mFlock, "correlation_distance", RUBY_METHOD_FUNC(rb_correlation), -1);
+    rb_define_module_function(mFlock, "absolute_correlation_distance", RUBY_METHOD_FUNC(rb_acorrelation), -1);
+    rb_define_module_function(mFlock, "uncentered_correlation_distance", RUBY_METHOD_FUNC(rb_ucorrelation), -1);
+    rb_define_module_function(mFlock, "absolute_uncentered_correlation_distance", RUBY_METHOD_FUNC(rb_uacorrelation), -1);
+    rb_define_module_function(mFlock, "spearman_distance", RUBY_METHOD_FUNC(rb_spearman), -1);
+    rb_define_module_function(mFlock, "kendall_distance", RUBY_METHOD_FUNC(rb_kendall), -1);
 }