rmds 0.2

data/examples/visualization.rb

@@ -0,0 +1,75 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  #
+  # Examples for RMDS
+  #
+  module Examples
+
+    #
+    # Visualization of {MDS::Metric} output.
+    #
+    # Visually illustrates that MDS finds an embedding 
+    # that is unique except for any rigid transformation 
+    # applied to it.
+    #
+    def Examples.visualization
+      require 'mds'
+      require 'mds/interfaces/stdlib_interface'
+      require 'gnuplot'
+      
+      MDS::Backend.active = MDS::StdlibInterface
+
+      # Input
+      x = MDS::Matrix.create_rows(
+        [1.0, 2.0], # Point A
+        [4.0, 3.0], # Point B
+        [0.0, 1.0] # Point C
+      )
+      
+      d2 = MDS::Metric.squared_distances(x)
+      
+      # Embedding in R2
+      proj = MDS::Metric.projectd(d2, 2) 
+      
+      Gnuplot.open do |gp|
+        Gnuplot::Plot.new( gp ) do |plot|
+          
+          # Uncomment the following lines to write result to image.
+          # plot.term 'png size'
+          # plot.output 'visualization.png'
+          
+          plot.title "Original Input and Result of MDS in Two Dimensions"  
+          plot.xrange "[-5:5]"
+          plot.yrange "[-5:5]"
+          
+          plot.data << Gnuplot::DataSet.new(x.columns) do |ds|
+            ds.with = "points"
+            ds.title = "Input"
+          end
+          
+          plot.data << Gnuplot::DataSet.new(proj.columns) do |ds|
+            ds.with = "points"
+            ds.title = "Output"
+          end
+   
+        end
+      end
+      
+    
+    end
+  end
+  
+end
+
+if __FILE__ == $0
+  require 'rubygems'
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  MDS::Examples.visualization
+end
+
+

data/examples/visualization_cities.rb

@@ -0,0 +1,84 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  #
+  # Examples for RMDS
+  #
+  module Examples
+  
+    #
+    # Visualization of air distances between major european cities.
+    #
+    # Compare result with http://bit.ly/bNdf0e but keep in mind that
+    #
+    # - MDS finds an embedding up to rotation and translation
+    # - The input matrix contains air-distances and the map shows correct goedesic distances.
+    #
+    def Examples.visualization_european_cities
+      require 'mds'
+      require 'gnuplot' # gem install gnuplot
+      
+      # Load backend
+      MDS::Backend.try_require
+      MDS::Backend.active = MDS::Backend.first
+      puts "Using backend #{MDS::Backend.active}"
+      
+      # Load matrix from file, contains city names in first column
+      path = File.join(File.dirname(__FILE__), 'european_city_distances.csv')
+      
+      cities = []
+      rows = MDS::IO::read_csv(path, ';') do |entry|
+        begin
+          f = Float(entry)
+          f * f
+        rescue ArgumentError
+          cities << entry
+          nil
+        end
+      end
+      
+      # Invoke MDS
+
+      d2 = MDS::Matrix.create_rows(*rows)      
+      proj = MDS::Metric.projectk(d2, 0.9) 
+      
+      # Plot results
+      
+      Gnuplot.open do |gp|
+        Gnuplot::Plot.new( gp ) do |plot|
+          
+          # Uncomment the following lines to write result to image.
+          # plot.term 'png size'
+          # plot.output 'visualization.png'
+          
+          plot.title "Air Distances between European Cities"  
+          plot.xrange "[-2000:2000]"
+          plot.yrange "[-1500:1200]"
+          
+          plot.data << Gnuplot::DataSet.new(proj.columns) do |ds|
+            ds.with = "points"
+            ds.notitle
+          end
+          
+          cities.each_with_index do |name, i|
+            plot.label "'#{name}' at #{proj[i,0] + 30}, #{proj[i,1] + 30}"
+          end
+        end
+      end
+   
+    end
+  end
+  
+end
+
+if __FILE__ == $0
+  require 'rubygems'
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  MDS::Examples.visualization_european_cities
+end
+
+

data/lib/mds.rb

@@ -0,0 +1,22 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+#
+# MDS - Ruby Multidimensional Scaling
+#
+module MDS
+  # Current version of MDS
+  VERSION = '0.2'
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'mds/matrix_interface'
+require 'mds/matrix'
+require 'mds/backend'
+require 'mds/metric'
+require 'mds/io'
+

data/lib/mds/backend.rb

@@ -0,0 +1,105 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+
+  # Defines the preferrred order of interfaces.
+  PREFERRED_INTERFACE_ORDER = ['MDS::LinalgInterface', 'MDS::GSLInterface', 'MDS::StdlibInterface']
+  
+  #
+  # Provides a common interface to matrix operations.
+  #
+  class Backend
+    # Stack of active matrix interfaces
+    @active = []
+    # Array of available interface classes
+    @available = []
+    
+    class << self; 
+      # 
+      # Access the active matrix interface.
+      #
+      def active
+        @active.first; 
+      end
+      
+      #
+      # Set the active matrix interface.
+      #
+      def active=(i)
+        @active.pop
+        @active.push(i)
+      end
+
+      #
+      # Push matrix interface onto the stack and set it active.
+      #      
+      def push_active(i)
+        @active.push(i)
+      end
+      
+      #
+      # Deactivate active matrix interface by popping it from stack.
+      #
+      def pop_active
+        @active.pop()
+      end
+      
+      # 
+      # Add available interface class.
+      #
+      # Automatically called when interface is required.
+      #
+      def add(i)
+        @available << i
+      end
+      
+      #
+      # Return available interface classes.
+      #
+      def available
+        @available
+      end
+      
+      #
+      # Return the first interface class.
+      #
+      # If no interface class matches a string in +search_order+,
+      # the first available interface is returned.
+      #
+      def first(search_order = MDS::PREFERRED_INTERFACE_ORDER)
+        c = search_order.map do |name|
+          begin
+            name.split('::').inject(Kernel) do |scope, const_name| 
+              scope.const_get(const_name)
+            end
+          rescue NameError
+            nil
+          end
+        end.compact!
+        
+        (!c || c.length == 0) ? @available.first : c.first
+      end
+      
+      #
+      # Require all interfaces from path and conceal possible errors.
+      #
+      # @param String path the path or globbing expression to pass to require
+      #
+      def try_require(path = File.join(File.dirname(__FILE__), 'interfaces', '*interface.rb'))
+        Dir.glob(File.expand_path(path)) do |path|
+          begin
+            require path
+          rescue LoadError
+          end
+        end
+      end
+            
+    end 
+    
+    
+  end
+end

data/lib/mds/interfaces/gsl_interface.rb

@@ -0,0 +1,140 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'mds/matrix_interface'
+
+begin
+  require 'rbgsl'
+rescue LoadError
+  warn "\n**Notice: GSLAdapter requires \'rb-gsl\' which was not found."
+  warn "You can install the extension from : \n http://rb-gsl.rubyforge.org/ \n"
+  raise $!
+end
+
+module MDS
+  
+  #
+  # Matrix interface for the Gnu Scientific Library.
+  #
+  # To succesfully use this interface 'rbgsl' bindings for GSL are required.
+  # For more information and installation instructions see 
+  # http://rb-gsl.rubyforge.org/
+  #
+  # Compatible with 'rb-gsl >= 1.14.3'
+  #
+  class GSLInterface < MatrixInterface
+    
+    #
+    # Create a new matrix with equal elements.
+    #
+    # @param (see MDS::MatrixInterface#create)
+    # @return (see MDS::MatrixInterface#create)
+    #
+    def GSLInterface.create(n, m, s)
+      mat = ::GSL::Matrix.alloc(n, m)
+      mat.set_all(s)
+      mat
+    end
+
+    #
+    # Return the number of matrix rows
+    #
+    # @param (see MDS::MatrixInterface#nrows)
+    # @return (see MDS::MatrixInterface#nrows)
+    #
+    def GSLInterface.nrows(m)
+      m.size1
+    end
+    
+    #
+    # Return the number of matrix columns
+    #
+    # @param (see MDS::MatrixInterface#ncols)
+    # @return (see MDS::MatrixInterface#ncols)
+    #
+    def GSLInterface.ncols(m)
+      m.size2
+    end
+   
+    #
+    # Set matrix element.
+    #
+    # @param (see MDS::MatrixInterface#set)
+    #
+    def GSLInterface.set(m, i, j, s)
+      m[i,j] = s
+    end
+    
+    #
+    # Get matrix element.
+    #
+    # @param (see MDS::MatrixInterface#get)
+    # @return (see MDS::MatrixInterface#get)
+    #
+    def GSLInterface.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 MDS::MatrixInterface#prod)
+    # @return (see MDS::MatrixInterface#prod)
+    #
+    def GSLInterface.prod(m, n)
+      m * n
+    end
+    
+    #
+    # Transpose a matrix.
+    #
+    # @param (see MDS::MatrixInterface#t)
+    # @return (see MDS::MatrixInterface#t)
+    #
+    def GSLInterface.t(m)
+      m.transpose
+    end
+    
+    #
+    # Componentwise addition of two matrices.
+    #
+    # @param (see MDS::MatrixInterface#add)
+    # @return (see MDS::MatrixInterface#add)
+    #
+    def GSLInterface.add(m, n)
+      m + n
+    end
+    
+    #
+    # Componentwise subtraction of two matrices.
+    #
+    # @param (see MDS::MatrixInterface#sub)
+    # @return (see MDS::MatrixInterface#sub)
+    #
+    def GSLInterface.sub(m, n)
+      m - n
+    end
+    
+    #
+    # Compute the eigen-decomposition of a real symmetric matrix.
+    #
+    # @param (see MDS::MatrixInterface#ed)
+    # @return (see MDS::MatrixInterface#ed)
+    #
+    def GSLInterface.ed(m)
+      eigen_values, eigen_vectors = ::GSL::Eigen::symmv(m)
+      ::GSL::Eigen::Symmv::sort(
+        eigen_values, 
+        eigen_vectors, 
+        ::GSL::Eigen::SORT_VAL_DESC
+      )
+      
+      [eigen_values.to_m_diagonal, eigen_vectors]
+    end
+    
+  end
+end

data/lib/mds/interfaces/linalg_interface.rb

@@ -0,0 +1,149 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'mds/matrix_interface'
+
+begin
+  require 'linalg'
+rescue LoadError
+  warn "\n**Notice: This matrix interface requires \'Linalg\' which was not found."
+  warn "You can install the extension from: \n http://rubyforge.org/projects/linalg/ \n"
+  raise $!
+end
+
+module MDS
+  
+  #
+  # Common matrix interface for Linalg - Ruby Bindings for LAPACK.
+  #
+  # To succesfully use this interface 'Linalg' bindings for LAPCK/BLAS 
+  # are required. For more information and installation instructions see 
+  # http://rubyforge.org/projects/linalg/
+  #
+  # Compatible with 'Linalg >= 1.0.0'
+  # 
+  class LinalgInterface < MatrixInterface
+    
+    #
+    # Create a new matrix with equal elements.
+    #
+    # @param (see MatrixInterface#create)
+    # @return (see MatrixInterface#create)
+    #
+    def LinalgInterface.create(n, m, s)
+      ::Linalg::DMatrix.new(n, m, s)
+    end
+
+    #
+    # Return the number of matrix rows
+    #
+    # @param (see MatrixInterface#nrows)
+    # @return (see MatrixInterface#nrows)
+    #
+    def LinalgInterface.nrows(m)
+      m.num_rows
+    end
+    
+    #
+    # Return the number of matrix columns
+    #
+    # @param (see MatrixInterface#ncols)
+    # @return (see MatrixInterface#ncols)
+    #
+    def LinalgInterface.ncols(m)
+      m.num_columns
+    end
+   
+    #
+    # Set matrix element.
+    #
+    # @param (see MatrixInterface#set)
+    #
+    def LinalgInterface.set(m, i, j, s)
+      m[i,j] = s
+    end
+    
+    #
+    # Get matrix element.
+    #
+    # @param (see MatrixInterface#get)
+    # @return (see MatrixInterface#get)
+    #
+    def LinalgInterface.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 LinalgInterface.prod(m, n)
+      m * n
+    end
+    
+    #
+    # Transpose a matrix.
+    #
+    # @param (see MatrixInterface#t)
+    # @return (see MatrixInterface#t)
+    #
+    def LinalgInterface.t(m)
+      m.transpose
+    end
+    
+    #
+    # Componentwise addition of two matrices.
+    #
+    # @param (see MatrixInterface#add)
+    # @return (see MatrixInterface#add)
+    #
+    def LinalgInterface.add(m, n)
+      m + n
+    end
+    
+    #
+    # Componentwise subtraction of two matrices.
+    #
+    # @param (see MatrixInterface#sub)
+    # @return (see MatrixInterface#sub)
+    #
+    def LinalgInterface.sub(m, n)
+      m - n
+    end
+    
+    #
+    # Compute the eigen-decomposition of a real symmetric matrix.
+    #
+    # @param (see MatrixInterface#ed)
+    # @return (see MatrixInterface#ed)
+    #
+    def LinalgInterface.ed(m)
+      evecs, real, img = m.eigensystem         
+      [Linalg::DMatrix.diagonal(real), evecs]
+    end
+    
+    #---------------------------------------
+    # Optional
+    # Methods having default implementations.
+    #---------------------------------------
+    
+    #
+    # Calculate minor matrix.
+    #
+    # @param (see MatrixInterface#minor)
+    # @return (see MatrixInterface#minor)
+    #
+    def LinalgInterface.minor(m, row_range, col_range)
+      nrows = (row_range.last - row_range.first) + 1
+      ncols = (col_range.last - col_range.first) + 1
+      m.minor(row_range.first, col_range.first, nrows, ncols)
+    end
+    
+  end
+end