rmds 0.2

data/lib/mds/interfaces/stdlib_interface.rb

@@ -0,0 +1,155 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'mds/matrix_interface'
+
+begin
+  require 'rubygems'
+  require 'extendmatrix'
+rescue LoadError
+  warn "\n**Notice: RubyAdapter requires \'extendmatrix\' which was not found."
+  warn "You can install the extension as follows: \n gem install extendmatrix \n"
+  raise $!
+end
+
+module MDS
+  
+  #
+  # Matrix interface for Ruby's standard library Matrix class.
+  #
+  # To succesfully use this interface 'extendmatrix' is required.
+  # For more information and installation instructions see 
+  # http://github.com/clbustos/extendmatrix
+  #
+  # The algorithm/implementation of the eigen-decomposition is 
+  # sub-optimal. It is therefore suitable only for small-scale problems.
+  # Timings are illustrated in the benchmark section of the {file:README}.
+  # 
+  # The reason this interface is still included in RMDS is the fact
+  # that it only depends on Ruby code and no native extensions.
+  #
+  # Compatible with 'extendmatrix >= 0.3.1'
+  #
+  class StdlibInterface < MatrixInterface
+    
+    #
+    # Create a new matrix with equal elements.
+    #
+    # @param (see MatrixInterface#create)
+    # @return (see MatrixInterface#create)
+    #
+    def StdlibInterface.create(n, m, s)
+      ::Matrix.build(n, m, s)
+    end
+
+    #
+    # Return the number of matrix rows
+    #
+    # @param (see MatrixInterface#nrows)
+    # @return (see MatrixInterface#nrows)
+    #
+    def StdlibInterface.nrows(m)
+      m.row_size
+    end
+    
+    #
+    # Return the number of matrix columns
+    #
+    # @param (see MatrixInterface#ncols)
+    # @return (see MatrixInterface#ncols)
+    #
+    def StdlibInterface.ncols(m)
+      m.column_size
+    end
+   
+    #
+    # Set matrix element.
+    #
+    # @param (see MatrixInterface#set)
+    #
+    def StdlibInterface.set(m, i, j, s)
+      m[i,j] = s
+    end
+    
+    #
+    # Get matrix element.
+    #
+    # @param (see MatrixInterface#get)
+    # @return (see MatrixInterface#get)
+    #
+    def StdlibInterface.get(m, i, j)
+      m[i,j]
+    end
+    
+    #
+    # Calculate the product of two matrices or
+    # the product of a matrix and a scalar.
+    #
+    # @param (see MatrixInterface#prod)
+    # @return (see MatrixInterface#prod)
+    #
+    def StdlibInterface.prod(m, n)
+      m * n
+    end
+    
+    #
+    # Transpose a matrix.
+    #
+    # @param (see MatrixInterface#t)
+    # @return (see MatrixInterface#t)
+    #
+    def StdlibInterface.t(m)
+      m.t
+    end
+    
+    #
+    # Componentwise addition of two matrices.
+    #
+    # @param (see MatrixInterface#add)
+    # @return (see MatrixInterface#add)
+    #
+    def StdlibInterface.add(m, n)
+      m + n
+    end
+    
+    #
+    # Componentwise subtraction of two matrices.
+    #
+    # @param (see MatrixAdapter#sub)
+    # @return (see MatrixAdapter#sub)
+    #
+    def StdlibInterface.sub(m, n)
+      m - n
+    end
+    
+    #
+    # Compute the eigen-decomposition of a real symmetric matrix.
+    #
+    # The Ruby version uses Jacobi iterations to calculate the 
+    # eigen-decomposition of a matrix. Although comfortable as all
+    # third-party dependencies can be installed via gem, the method is
+    # not suited for matrices bigger than 10x10.
+    #
+    # @param (see MatrixInterface#ed)
+    # @return (see MatrixInterface#ed)
+    #
+    def StdlibInterface.ed(m)
+      eigen_values = m.cJacobiA
+      eigen_vectors = m.cJacobiV
+
+      ranks = (0..(m.row_size-1)).sort{|i,j| eigen_values[j,j] <=> eigen_values[i,i]}
+      
+      s_eigen_values = []
+      s_eigen_vectors = []
+      ranks.each do |r|
+        s_eigen_values << eigen_values[r,r]
+        s_eigen_vectors << eigen_vectors.column(r)
+      end    
+      [::Matrix.diagonal(*s_eigen_values), ::Matrix.columns(s_eigen_vectors)]
+    end
+    
+  end
+end

data/lib/mds/io.rb

@@ -0,0 +1,29 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  module IO
+
+    #
+    # Read matrix from CSV file
+    # Each feature corresponds to a single row.
+    # All rows are assumed to have an equal column count.
+    #
+    def IO.read_csv(path, sep = ' ')
+      rows = []
+      File.foreach(path) do |line|
+        cells = line.chop.split(sep)
+        if block_given?
+          rows << cells.map{|c| yield c}.compact
+        else
+          rows << cells
+        end
+      end
+      rows
+    end
+    
+  end
+end

data/lib/mds/matrix.rb

@@ -0,0 +1,258 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  
+  #
+  # A matrix adapter.
+  #
+  # RMDS does not implement matrices or linear algebra routines itself, 
+  # instead RMDS offers a non-intrusive adapter architecture to interop 
+  # with third party linear algebra packages.
+  #
+  # The RMDS adapter architecture consists of two layers
+  #
+  # * {MDS::MatrixInterface} defines a minimal common interface of 
+  #   required interop methods.
+  # * {MDS::Matrix} is a matrix adapter that binds to data provided by 
+  #   a specialized {MDS::MatrixInterface} class and carries out all
+  #   computations through methods defined in {MDS::MatrixInterface}.
+  #
+  # @see MDS::MatrixInterface
+  #
+  class Matrix 
+    # Wrapped matrix
+    attr_reader :m
+    alias :matrix :m
+    
+    #
+    # Initialize from matrix instance and interface class.
+    #
+    # @param matrix the matrix to be wrapped
+    #
+    def initialize(matrix)
+      @m = matrix
+    end
+    
+    # 
+    # Create a new matrix setting all elements to equal values.
+    #
+    # @param (see MatrixInterface#create)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create(n, m, s)
+      Matrix.new(Backend.active.create(n, m, s))
+    end
+    
+    #
+    # Create a new matrix and assign each element as the
+    # result of invoking the given block.
+    #
+    # @param (see MatrixInterface#create_block)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create_block(n, m, &block)
+      Matrix.new(Backend.active.create_block(n, m, &block))
+    end
+    
+    #
+    # Create a new matrix from uniform random distribution.
+    #
+    # @param (see MatrixInterface#create_random)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create_random(n, m, smin = -1.0, smax = 1.0)
+      Matrix.new(Backend.active.create_random(n, m, smin, smax))
+    end
+    
+    #
+    # Create a new identity matrix.
+    #
+    # @param (see MatrixInterface#create_identity)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create_identity(n)
+      Matrix.new(Backend.active.create_identity(n))
+    end  
+
+    #
+    # Create a new diagonal matrix.
+    #
+    # @param (see MatrixInterface#create_diagonal)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create_diagonal(*elements)
+      Matrix.new(Backend.active.create_diagonal(*elements))
+    end
+    
+    #
+    # Create matrix from rows.
+    #
+    # @param (see MatrixInterface#create_rows)
+    # @return [Matrix] the newly created matrix.
+    #
+    def Matrix.create_rows(*rows)
+      Matrix.new(Backend.active.create_rows(*rows))
+    end
+    
+    #
+    # Return the number of matrix rows
+    #
+    # @return number of rows in matrix
+    #
+    def nrows
+      Backend.active.nrows(@m)
+    end
+    
+    #
+    # Return the number of matrix columns
+    #
+    # @return number of columns in matrix
+    #
+    def ncols
+      Backend.active.ncols(@m)
+    end
+    
+    #
+    # Set value of matrix element.
+    #
+    # @param [Integer] i the i-th row, zero-based indexing
+    # @param [Integer] j the j-th column, zero-based indexing
+    # @param [Float] s scalar value to set
+    # 
+    def []=(i, j, s)
+      Backend.active.set(@m, i, j, s)
+    end
+    
+    #
+    # Get value of matrix element.
+    #
+    # @param [Integer] i the i-th row, zero-based indexing
+    # @param [Integer] j the j-th column, zero-based indexing
+    # @return [Float] value of element
+    #
+    def [](i,j)
+      Backend.active.get(@m, i, j)
+    end
+    
+    #
+    # Calculate the product of two matrices or
+    # the product of a matrix and a scalar.
+    #
+    # @param [Matrix, Float] other matrix to multiply with, or scalar
+    # @return [Matrix] the matrix.
+    #
+    def *(other)
+      is_ma = other.instance_of?(Matrix)
+      Matrix.new(
+        Backend.active.prod(@m, is_ma ? other.matrix : other)
+      )
+    end
+    
+    #
+    # Componentwise addition of two matrices.
+    #
+    # @param [Matrix] other matrix to add to this matrix
+    # @return [Matrix] the matrix.
+    #
+    def +(other)
+      Matrix.new(Backend.active.add(@m, other.m))
+    end
+    
+    #
+    # Componentwise subtraction of two matrices.
+    #
+    # @param [Matrix] other matrix to subtract from this matrix.
+    # @return [Matrix] the matrix.
+    #
+    def -(other)
+      Matrix.new(Backend.active.sub(@m, other.m))
+    end
+    
+    #
+    # Transpose a matrix.
+    #
+    # @return [Matrix] the transposed matrix.
+    #
+    def t
+      Matrix.new(Backend.active.t(@m))
+    end
+    
+    #
+    # Compute the eigen-decomposition of a real symmetric matrix.
+    #
+    # The eigen-decomposition consists of a diagonal matrix +D+ containing
+    # the eigen values and a square matrix +N+ having the normalized eigenvectors
+    # in columns. 
+    #
+    # @return [Array] the array containing the matrix of eigen-values and eigen-vector
+    #
+    def ed
+      Backend.active.ed(@m).map {|m| Matrix.new(m) }
+    end
+    
+    #
+    # Retrieve the diagonal elements as an array.
+    #
+    # @return [Array] diagonal elements as array.
+    #
+    def diagonals
+      Backend.active.diagonals(@m)
+    end
+    
+    #
+    # Calculate the sum of diagonal matrix elements.
+    #
+    # @return [Float] trace of matrix
+    #
+    def trace
+      Backend.active.trace(@m)
+    end
+    
+    #
+    # Calculate minor matrix.
+    #
+    # @param [Range] row_range row range
+    # @param [Range] col_range column range
+    # @return [Matrix] minor matrix
+    #
+    def minor(row_range, col_range)
+      Matrix.new(
+        Backend.active.minor(@m, row_range, col_range)
+      )
+    end
+    
+    #
+    # Returns matrix as array of columns.
+    # 
+    # @return [Array<Array>] the array of columns where each column is an array
+    #
+    def columns
+      Backend.active.columns(@m) 
+    end
+    
+    #
+    # Returns matrix as array of rows.
+    # 
+    # @return [Array<Array>] the array of rows where each row is an array
+    #
+    def rows
+      Backend.active.rows(@m) 
+    end
+    
+    #
+    # Convert to string.
+    #
+    # Invokes #to_s from wrapped matrix.
+    #
+    # @return wrapped matrix as string.
+    #
+    def to_s
+      Backend.active.to_s(@m) 
+    end
+    
+  end
+end

data/lib/mds/matrix_interface.rb

@@ -0,0 +1,358 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  
+  #
+  # Provides a common interface to matrix operations.
+  #
+  # RMDS does not implement any linear algebra routine itself,
+  # but rather provides a non intrusive mechanism to plugin third party 
+  # linear algebra packages. {MDS::MatrixInterface} defines a minimal 
+  # set of required methods to be implemented for any linear algebra packages
+  # which are to be used with RMDS.
+  #
+  # Making linear algebra backends compatible with RMDS is easy:
+  # simply subclass from {MDS::MatrixInterface} and implement all abstract
+  # methods. Not all of {MDS::MatrixInterface} methods are abstract, some
+  # come with a default implementation. If your linear algebra package
+  # does better at some of those methods, you should override them in your
+  # interface subclass.
+  #
+  # RMDS helps you in testing your matrix interfaces through test bundles
+  # that ship with RMDS. Each test bundle contains a set of tests that work 
+  # independently of the matrix interface chosen. The following file unit
+  # tests a matrix interface.
+  #
+  #  require 'test/unit'
+  #  require 'mds/test/bundles/bundle_matrix_interface.rb'
+  #  require 'mds/interfaces/linalg_interface'
+  #  
+  #  class TestLinalgInteface < Test::Unit::TestCase
+  #    include MDS::Test::BundleMatrixInterface
+  #    
+  #    def setup
+  #      MDS::Backend.push_active(MDS::LinalgInterface)
+  #    end
+  #    
+  #    def teardown
+  #      MDS::Backend.pop_active
+  #    end
+  #    
+  #  end
+  #
+  # Finally, tell RMDS to use your matrix interface by setting the 
+  # default matrix interface, like so
+  #  
+  #  # Set active interface
+  #  MDS::Backend.active = YourMatrixInterface
+  #
+  #  # Push onto interface stack and set active interface
+  #  MDS::Backend.push_active(YourMatrixInterface)
+  #
+  #  # Restore the previously active interface
+  #  MDS::Backend.pop_active
+  #
+  # @see MDS::Matrix, MDS::Backend
+  class MatrixInterface
+  
+    #
+    # Record creation of a subclass of this class at the MDS::Backend
+    #
+    def MatrixInterface.inherited(subclass)
+      MDS::Backend.add(subclass)
+    end
+  
+    #---------------------------------------
+    # Required
+    # Abstract methods
+    #---------------------------------------
+    
+    # 
+    # Create a new matrix having all elements equal values.
+    #
+    # @param [Integer] n the number of rows
+    # @param [Integer] m the number of columns
+    # @param [Float] s the scalar value of each matrix component
+    # @return the newly created matrix.
+    # @abstract
+    #
+    def MatrixInterface.create(n, m, s)
+      raise NotImplementedError
+    end
+    
+    #
+    # Return the number of matrix rows
+    #
+    # @param m the matrix
+    # @return number of rows in matrix
+    # @abstract
+    #
+    def MatrixInterface.nrows(m)
+      raise NotImplementedError
+    end
+    
+    #
+    # Return the number of matrix columns
+    #
+    # @param m the matrix
+    # @return number of columns in matrix
+    # @abstract
+    #
+    def MatrixInterface.ncols(m)
+      raise NotImplementedError
+    end
+    
+    #
+    # Set value of matrix element.
+    #
+    # @param m the matrix
+    # @param [Integer] i the i-th row, zero-based indexing
+    # @param [Integer] j the j-th column, zero-based indexing
+    # @param [Float] s scalar value to set
+    # @abstract
+    def MatrixInterface.set(m, i, j, s)
+      raise NotImplementedError
+    end
+    
+    #
+    # Get value of matrix element.
+    #
+    # @param m the matrix
+    # @param [Integer] i the i-th row, zero-based indexing
+    # @param [Integer] j the j-th column, zero-based indexing
+    # @return [Float] value of element
+    # @abstract
+    #
+    def MatrixInterface.get(m, i, j)
+      raise NotImplementedError
+    end
+    
+    #
+    # Calculate the product of two matrices or
+    # the product of a matrix and a scalar.
+    #
+    # @param m first matrix
+    # @param n second matrix or scalar
+    # @return the matrix product as newly allocated matrix
+    # @abstract
+    #
+    def MatrixInterface.prod(m, n)
+      raise NotImplementedError
+    end
+    
+    #
+    # Componentwise addition of two matrices.
+    #
+    # @param m first matrix
+    # @param n second matrix
+    # @return the matrix addition as newly allocated matrix
+    # @abstract
+    def MatrixInterface.add(m, n)
+      raise NotImplementedError
+    end
+    
+    #
+    # Componentwise subtraction of two matrices.
+    #
+    # @param m first matrix
+    # @param n second matrix
+    # @return the matrix subtraction as newly allocated matrix
+    # @abstract
+    #
+    def MatrixInterface.sub(m, n)
+      raise NotImplementedError
+    end
+    
+    #
+    # Transpose a matrix.
+    #
+    # @param m the matrix to transpose
+    # @return the transposed matrix as newly allocated matrix
+    # @abstract
+    #
+    def MatrixInterface.t(m)
+      raise NotImplementedError
+    end
+    
+    #
+    # Compute the eigen-decomposition of a real symmetric matrix.
+    #
+    # The eigen-decomposition consists of a diagonal matrix +D+ containing
+    # the eigen values and a square matrix +N+ having the normalized eigenvectors
+    # in columns. It is assumed that the result of MatrixInterface#ed yields the 
+    # matrices as an array and that the eigen-vectors and values are sorted in 
+    # descending order of importance.
+    #
+    # @param m the matrix to decompose
+    # @return [Array] the array containing the matrix of eigen-values and eigen-vector
+    # @abstract
+    #
+    def MatrixInterface.ed(m)
+      raise NotImplementedError
+    end
+    
+    #---------------------------------------
+    # Optional
+    # Methods having default implementations.
+    #---------------------------------------
+    
+    #
+    # Create a new matrix and assign each element as the
+    # result of invoking the given block.
+    #
+    # @param [Integer] n the number of rows
+    # @param [Integer] m the number of columns.
+    # @return the newly created matrix.
+    #
+    def MatrixInterface.create_block(n, m, &block)
+      mat = self.create(n, m, 0.0)
+      for i in 0..self.nrows(mat)-1
+        for j in 0..self.ncols(mat)-1
+          self.set(mat, i, j, block.call(i,j))
+        end
+      end
+      mat
+    end
+    
+    #
+    # Create a new matrix with uniform random elements.
+    #
+    # @param [Integer] n the number of rows
+    # @param [Integer] m the number of columns
+    # @param [Float] smin the minimum element value (inclusive).
+    # @param [Float] smax the maximum element value (inclusive).
+    # @return the newly created matrix.
+    #
+    def MatrixInterface.create_random(n, m, smin = -1.0, smax = 1.0)
+      range = smax - smin
+      self.create_block(n, m) do |i,j|
+        smin + range*rand()
+      end
+    end
+    
+    #
+    # Create a new identity matrix.
+    # 
+    # @param [Integer] n matrix dimension
+    # @return the newly created matrix.
+    #
+    def MatrixInterface.create_identity(n)
+      self.create_diagonal(*[1.0]*n)
+    end
+    
+    # 
+    # Create a new diagonal matrix.
+    # 
+    # @param *elements the diagonal elements
+    # @return the newly created matrix
+    #
+    def MatrixInterface.create_diagonal(*elements)
+      n = elements.length
+      m = self.create(n, n, 0.0)
+      for i in 0..self.nrows(m)-1
+        self.set(m, i, i, elements[i])
+      end
+      m
+    end
+    
+    #
+    # Create matrix from rows.
+    #
+    # @param [Array] rows the rows
+    # @return the newly created matrix
+    #
+    def MatrixInterface.create_rows(*rows)
+      nrows = rows.length
+
+      ncols = rows.first.length
+      self.create_block(nrows, ncols) do |i,j|
+        rows[i][j]
+      end
+    end
+    
+    #
+    # Retrieve the diagonal elements as an array.
+    #
+    # The number of diagonals of an NxM matrix is 
+    # defined as min(N,M).
+    #
+    # @param m the matrix
+    # @return diagonals of matrix as array.
+    #
+    def MatrixInterface.diagonals(m)
+      size = [self.nrows(m), self.ncols(m)].min
+      (0..size-1).map{|i| self.get(m,i,i)}
+    end
+    
+    #
+    # Calculate the sum of diagonal matrix elements.
+    #
+    # @param m the matrix
+    # @return trace of matrix
+    #
+    def MatrixInterface.trace(m)
+      self.diagonals(m).inject(0) {|sum,e| sum += e}
+    end
+    
+    #
+    # Returns matrix as array of columns.
+    # 
+    # @return [Array<Array>] the array of columns where each column is an array
+    #
+    def MatrixInterface.columns(m)
+      a = Array.new(self.ncols(m)) {Array.new(self.nrows(m))}
+      for i in 0..self.nrows(m)-1 do
+        for j in 0..self.ncols(m)-1 do
+          a[j][i] = self.get(m, i, j)
+        end
+      end
+      a
+    end
+    
+    #
+    # Returns matrix as array of rows.
+    # 
+    # @return [Array<Array>] the array of rows where each rows is an array
+    #
+    def MatrixInterface.rows(m)
+      a = Array.new(self.nrows(m)) {Array.new(self.ncols(m))}
+      for i in 0..self.nrows(m)-1 do
+        for j in 0..self.ncols(m)-1 do
+          a[i][j] = self.get(m, i, j)
+        end
+      end
+      a
+    end
+    
+    #
+    # Calculate minor matrix.
+    #
+    # @param m matrix to calculate minor from
+    # @param [Range] row_range linear row range with step size equal to one.
+    # @param [Range] col_range linear column range with step size equal to one.
+    #
+    def MatrixInterface.minor(m, row_range, col_range)
+      nrows = (row_range.last - row_range.first) + 1
+      ncols = (col_range.last - col_range.first) + 1
+      self.create_block(nrows, ncols) do |i,j|
+        self.get(m, i + row_range.first, j + col_range.first)
+      end
+    end
+    
+    #
+    # Convert to string.
+    #
+    # Invokes #to_s from wrapped matrix.
+    #
+    # @return wrapped matrix as string.
+    #
+    def to_s(m)
+      m.to_s
+    end
+    
+  end
+end