rmds 0.2

data/lib/mds/metric.rb

@@ -0,0 +1,150 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+
+  #
+  # In metric MDS dissimilarities are interpreted as distances und 
+  # the goal is to find an embedding in an Euclidean space that best preserves
+  # the given distances.
+  #
+  # This implementation gives an analytical solution and avoids iterative
+  # optimization. The performance of the algorithm highly depends on the 
+  # implementation of the eigen-decomposition provided via {MDS::MatrixInterface}.
+  #
+  # *Examples*
+  # - {Examples.minimal_metric}
+  # - {Examples.extended_metric}
+  #
+  class Metric
+    
+    #
+    # Find a Cartesian embedding for the given distances.
+    #
+    # Instead of a fixed dimensionality for the resulting embedding, this
+    # method determines the dimensionality based on the variances of distances
+    # in its input matrix and the parameter passed. The parameter specifies
+    # the percent of variance of distance to preserve in the Cartesian embedding.
+    #
+    # @param [MDS::Matrix] d squared Eulcidean distance matrix of observations
+    # @param [Float] k the percent of variance of distances 
+    # to preserve in embedding in the range [0..1].
+    # @return [MDS::Matrix] the matrix containing the cartesian embedding.
+    #
+    def Metric.projectk(d, k)
+      b = Metric.shift(d)
+      eval, evec = b.ed
+      dims = Metric.find_dimensionality(eval, k)
+      Metric.project(eval, evec, dims)      
+    end
+    
+    #
+    # Find a Cartesian embedding for the given distances.
+    #
+    # @param [MDS::Matrix] d squared Eulcidean distance matrix of observations
+    # @param [Integer] dims the number of dimensions of the embedding.
+    # @return [MDS::Matrix] the matrix containing the cartesian embedding.
+    #
+    def Metric.projectd(d, dims)
+      b = Metric.shift(d)
+      eval, evec = b.ed
+      Metric.project(eval, evec, dims)
+    end
+    
+    #
+    # Calculates the squared Euclidean distances for all
+    # pairwise observations in the given matrix. Each observation 
+    # corresponds to a matrix row and is provided in Cartesian coordinates.
+    #
+    # The result is a real symmetric matrix of size +NxN+, where +N+ is the
+    # number of observations in the input. Each element +(i,j)+ in this matrix
+    # corresponds to the squared distance between the i-th and j-th observation
+    # in the input matrix.
+    #
+    # @param [MDS::Matrix] x the matrix of observations.
+    # @return [MDS::Matrix] the squared Euclidean distance matrix
+    #
+    def Metric.squared_distances(x)
+      # Product of x with transpose of x
+      xxt = x * x.t
+      # 1xN matrix of ones, where N size of xxt
+      ones = Matrix.create(1, xxt.nrows, 1.0)
+      # Nx1 matrix containing diagonal elements of x
+      diagonals = xxt.diagonals
+      c = Matrix.create_block(xxt.nrows, 1) do |i, j|
+        diagonals[i]
+      end
+      c * ones + (c * ones).t - xxt * 2
+    end
+    
+    
+    protected 
+    
+    #
+    # Transform the squared distance matrix into a matrix of Cartesian 
+    # coordinates by projecting the distances onto the basis formed by
+    # the eigen-decomposition of the initial matrix. 
+    #
+    # @param [MDS::Matrix] d squared Euclidean distance matrix
+    # @param [Float] k percent [0..1] of variances in distances to keep in embedding.
+    # @return [MDS::Matrix] containing the Cartesian embedding.
+    #
+    def Metric.project(eval, evec, dims)     
+      lam = eval.minor(0..eval.nrows-1, 0..dims-1)
+      for i in 0..lam.ncols-1
+        v = lam[i,i]
+        if v > 0.0
+          lam[i,i] = Math.sqrt(v)
+        end
+      end
+      evec * lam
+    end
+    
+    #
+    # Transforms the distance matrix into an equivalent scalar product
+    # matrix.
+    # 
+    # @param [MDS::Matrix] d the squared Euclidean distance matrix
+    # @return [MDS::Matrix] the equivalent scalar product matrix.
+    #
+    def Metric.shift(d)
+      # Nx1 matrix of ones
+      ones = Matrix.create(d.nrows, 1, 1.0)
+      # 1xN weight vector
+      m = Matrix.create(1, d.nrows, 1.0/d.nrows)
+      # NxN centering matrix
+      xi = Matrix.create_identity(d.nrows) - ones * m
+      # NxN shifted distances matrix, B
+      (xi * d * xi.t) * -0.5
+    end
+
+    
+    #
+    # Find the dimensionality of the resulting coordinate space so that
+    # at least +k+ percent of the variance of the distances is preserved.
+    #
+    # @param [MDS::Matrix] eval the diagonal matrix of sorted eigen-values.
+    # @param [Float] k percent of variance to keep.
+    # @return [Integer] minimum number of dimensions to use, to keep k-percent
+    # of variances of distances in embedding.
+    #
+    def Metric.find_dimensionality(eval, k)
+      sum_ev = eval.trace
+      n = eval.nrows
+      
+      i = 0
+      sum = 0
+      while ((i < n) && 
+             (eval[i,i] > 0.0) && 
+             (sum / sum_ev) < k)
+        sum += eval[i,i]
+        i += 1
+      end
+      i
+    end
+  end
+  
+end

data/lib/mds/test/bundles/bundle_matrix_interface.rb

@@ -0,0 +1,199 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'mds/test/matrix_assertions.rb'
+
+module MDS
+  module Test
+  
+    #
+    # Module containing standarized tests for matrix interfaces.
+    #
+    module BundleMatrixInterface
+      include MDS::Test::MatrixAssertions
+
+      #----------------------------
+      # Matrix creators
+      #----------------------------
+
+      def test_create
+        m = MDS::Matrix.create(2, 3, 0.0)
+        assert_equal(2, m.nrows)
+        assert_equal(3, m.ncols)
+        
+        for i in 0..m.nrows-1 do
+          for j in 0..m.ncols-1 do
+            assert_instance_of(Float, m[i,j])
+            assert_equal(0.0, m[i,j])
+          end
+        end
+      end
+      
+      def test_create_identity
+        m = MDS::Matrix.create_identity(3)
+        r = MDS::Matrix.create(3, 3, 0.0)
+        r[0,0] = 1.0; r[1,1] = 1.0; r[2,2] = 1.0;
+        assert_equal_matrices(m, r)
+      end
+      
+      def test_create_diagonal
+        m = MDS::Matrix.create_diagonal(1.0, 2.0, 3.0)
+        r = MDS::Matrix.create(3, 3, 0.0)
+        r[0,0] = 1.0; r[1,1] = 2.0; r[2,2] = 3.0;
+        assert_equal_matrices(m, r)
+      end
+      
+      def test_create_block
+        m = MDS::Matrix.create_block(2,2) do |i,j|
+          i == j ? 0.0 : 1.0
+        end
+        r = MDS::Matrix.create(3, 3, 1.0)
+        r[0,0] = 0.0; r[1,1] = 0.0;
+        assert_equal_matrices(m, r)
+      end
+      
+      def test_create_rows
+        m = MDS::Matrix.create_rows([1.0, 2.0, 3.0], [4.0, 5.0, 6.0])
+        r = MDS::Matrix.create_block(2,3) do |i,j|
+          (i*3 + j + 1).to_f
+        end
+        assert_equal_matrices(m, r)
+      end
+      
+      #----------------------------
+      # Matrix element accessors
+      #----------------------------
+      
+      def test_get_set
+        a = MDS::Matrix.create(2, 2, 1.0)
+
+        a[0,0] = 1.0
+        a[0,1] = 2.0
+        a[1,0] = 3.0
+        a[1,1] = 4.0
+            
+        assert_equal(1.0, a[0,0])
+        assert_equal(2.0, a[0,1])
+        assert_equal(3.0, a[1,0])
+        assert_equal(4.0, a[1,1])
+      end
+      
+      #----------------------------
+      # Matrix views
+      #----------------------------
+      
+      def test_transpose
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 2.0, 3.0])
+        r = MDS::Matrix.create_rows([2.0, 1.0], [3.0, 2.0], [4.0, 3.0])
+        m = a.t
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_diagonals
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 4.0, 3.0])
+        r = MDS::Matrix.create_rows([2.0, 4.0])
+        m = MDS::Matrix.create_rows(a.diagonals)
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_minor
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 4.0, 3.0])
+        r = MDS::Matrix.create_rows([4.0],[3.0])
+        m = a.minor(0..1, 2..2)
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_trace
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 4.0, 3.0])
+        assert_equal(6.0, a.trace)
+      end
+      
+      def test_columns
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 4.0, 3.0])
+        assert_equal([[2.0, 1.0], [3.0, 4.0], [4.0, 3.0]], a.columns)
+      end
+      
+      def test_rows
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 4.0, 3.0])
+        assert_equal([[2.0, 3.0, 4.0], [1.0, 4.0, 3.0]], a.rows)
+      end
+      
+      #----------------------------
+      # Matrix operations
+      #----------------------------
+      
+      def test_product
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 2.0, 3.0])
+        b = MDS::Matrix.create_rows([3.0, 1.0], [1.0, 2.0], [3.0, -4.0])
+        r = MDS::Matrix.create_rows([21.0, -8.0], [14.0, -7.0])
+        
+        m = a * b
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_product_scalar
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 2.0, 3.0])
+        r = MDS::Matrix.create_rows([4.0, 6.0, 8.0], [2.0, 4.0, 6.0])
+        m = a * 2.0
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_add
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 2.0, 3.0])
+        b = MDS::Matrix.create_rows([1.0, 2.0, 3.0], [0.0, 0.0, 2.0])
+        r = MDS::Matrix.create_rows([3.0, 5.0, 7.0], [1.0, 2.0, 5.0])
+        m = a + b
+        assert_delta_matrices(r, m)
+      end
+      
+      def test_sub
+        a = MDS::Matrix.create_rows([2.0, 3.0, 4.0], [1.0, 2.0, 3.0])
+        b = MDS::Matrix.create_rows([1.0, 2.0, 2.0], [0.0, 0.0, 2.0])
+        r = MDS::Matrix.create_rows([1.0, 1.0, 2.0], [1.0, 2.0, 1.0])
+        m = a - b
+        assert_delta_matrices(r, m)
+      end
+        
+      def test_ed
+        a = MDS::Matrix.create_rows(
+          [0.0, 10.0, 2.0], 
+          [10.0, 0.0, 20.0],
+          [2.0, 20.0, 0.0]
+        )
+                
+        eval_a, evec_a = a.ed
+        
+        assert_in_delta(23.2051, eval_a[0,0], 1e-3)
+        assert_in_delta(-1.5954, eval_a[1,1], 1e-3)
+        assert_in_delta(-21.6097, eval_a[2,2], 1e-3)
+          
+        r0 = MDS::Matrix.create_rows([0.3529, 0.6934, 0.6281])
+        r1 = MDS::Matrix.create_rows([0.8948, -0.0541, -0.4430])
+        r2 = MDS::Matrix.create_rows([-0.2732, 0.7184, -0.6396])
+        
+        v0 = evec_a.minor(0..2, 0..0)
+        v1 = evec_a.minor(0..2, 1..1)
+        v2 = evec_a.minor(0..2, 2..2)
+        
+        # Norm of vectors
+        assert_in_delta(1.0, (v0.t * v0)[0,0], 1e-3)
+        assert_in_delta(1.0, (v1.t * v1)[0,0], 1e-3)
+        assert_in_delta(1.0, (v2.t * v2)[0,0], 1e-3)
+        
+        # Orthogonality of basis vectors
+        assert_in_delta(0.0, (v0.t * v1)[0,0], 1e-3)
+        assert_in_delta(0.0, (v0.t * v2)[0,0], 1e-3)
+        assert_in_delta(0.0, (v1.t * v2)[0,0], 1e-3)
+        
+        # Orientation of basis vectors (up to 180° ambiguity)
+        assert_in_delta(1.0, (r0 * v0)[0,0].abs, 1e-3)
+        assert_in_delta(1.0, (r1 * v1)[0,0].abs, 1e-3)
+        assert_in_delta(1.0, (r2 * v2)[0,0].abs, 1e-3)
+      end
+    end
+    
+  end
+end

data/lib/mds/test/bundles/bundle_metric.rb

@@ -0,0 +1,82 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'mds/test/matrix_assertions.rb'
+
+module MDS
+  module Test
+  
+    #
+    # Module containing standarized tests for MDS::Metric.
+    #
+    module BundleMetric
+      include MDS::Test::MatrixAssertions
+      
+      def test_squared_distances
+        input = MDS::Matrix.create_rows(
+          [1.0, 2.0], 
+          [4.0, 3.0],
+          [0.0, 1.0]
+        )
+        
+        output = MDS::Matrix.create_rows(
+          [0.0, 10.0, 2.0], 
+          [10.0, 0.0, 20.0], 
+          [2.0, 20.0, 0.0]
+        )
+        
+        d = MDS::Metric.squared_distances(input)
+        assert_equal_matrices(output, d)
+      end
+      
+      def test_k_2d
+        x = MDS::Matrix.create_rows(
+          [1.0, 2.0], 
+          [4.0, 3.0],
+          [0.0, 1.0]
+        )
+        d = MDS::Metric::squared_distances(x)
+        proj = MDS::Metric.projectk(d, 0.99)   
+        dd = MDS::Metric.squared_distances(proj)    
+        assert_delta_matrices(d, dd, 1e-5)
+      end
+      
+      def test_d_2d
+        x = MDS::Matrix.create_rows(
+          [1.0, 2.0], 
+          [4.0, 3.0],
+          [0.0, 1.0]
+        )
+        d = MDS::Metric.squared_distances(x)
+        
+        proj = MDS::Metric.projectd(d, 2)   
+        dd = MDS::Metric.squared_distances(proj)    
+        assert_delta_matrices(d, dd, 1e-5)
+      end
+      
+      def test_k_5d
+        x = MDS::Matrix.create_random(10, 5, -10, 10)   
+        d = MDS::Metric.squared_distances(x)
+        
+        proj = MDS::Metric.projectk(d, 1.0)   
+        dd = MDS::Metric.squared_distances(proj)    
+        assert_delta_matrices(d, dd, 1e-5)
+        
+        proj = MDS::Metric.projectk(d, 0.8)   
+        dd = MDS::Metric.squared_distances(proj)    
+        assert_delta_matrices(d, dd, 5e2)
+      end
+      
+      def test_d_5d
+        x = MDS::Matrix.create_random(10, 5, -10, 10)   
+        d = MDS::Metric.squared_distances(x)
+        proj = MDS::Metric.projectd(d, 10)   
+        dd = MDS::Metric.squared_distances(proj)    
+        assert_delta_matrices(d, dd, 1e-5)
+      end
+    end
+  end
+end

data/lib/mds/test/matrix_assertions.rb

@@ -0,0 +1,54 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  module Test
+
+    #
+    # Addition assertions for comparing matrices.
+    #
+    module MatrixAssertions
+
+      #
+      # Assert that two matrices are equal
+      #
+      # @param [MDS::Matrix] a first matrix
+      # @param [MDS::Matrix] b second matrix
+      #
+      def assert_equal_matrices(a, b)
+        assert_instance_of(a.matrix.class, b.matrix)
+        assert(a.nrows, b.nrows)
+        assert(a.ncols, b.ncols)
+        
+        for i in 0..a.nrows-1 do
+          for j in 0..a.ncols-1 do
+            assert_equal(a[i,j], b[i,j])
+          end
+        end
+      end
+      
+      #
+      # Assert that two matrices are equal up to delta
+      #
+      # @param [MDS::Matrix] first matrix
+      # @param [MDS::Matrix] second matrix
+      # @param [Float] delta delta
+      #
+      def assert_delta_matrices(a, b, delta = 1e-10)
+        assert_instance_of(a.matrix.class, b.matrix)
+        assert(a.nrows, b.nrows)
+        assert(a.ncols, b.ncols)
+        
+        for i in 0..a.nrows-1 do
+          for j in 0..a.ncols-1 do
+            assert_in_delta(a[i,j], b[i,j], delta)
+          end
+        end
+      end
+    end
+    
+  end
+end