rmds 0.2

data/LICENSE.md

@@ -0,0 +1,27 @@
+License
+=====================================
+
+RMDS - Ruby Multidimensional Scaling Library
+Copyright (c) 2010, Christoph Heindl
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, 
+are permitted provided that the following conditions are met:
+- Redistributions of source code must retain the above copyright notice, this list 
+  of conditions and the following disclaimer.
+- Redistributions in binary form must reproduce the above copyright notice, this list 
+  of conditions and the following disclaimer in the documentation and/or other materials 
+  provided with the distribution.
+- Neither the name of the Christoph Heindl nor the names of its contributors may be 
+  used to endorse or promote products derived from this software without specific prior 
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,157 @@
+# Ruby Multidimensional Scaling Library
+
+## Introduction
+
+RMDS is a library for performing multidimensional scaling. 
+
+[Wikipedia][wiki_mds] describes multidimensional scaling (MDS) as
+> [...] a set of related statistical techniques often used in information 
+> visualization for exploring similarities or dissimilarities in data.
+
+In essence, multidimensional scaling takes a matrix of similarities or dissimilarities between pairwise observations as input and outputs a matrix of observations in Cartesian coordinates that preserve the similarities/dissimilarities given. The dimensionality of the output is a parameter to the algorithm.
+
+## Metric Multidimensional Scaling
+
+RMDS implements metric multidimensional scaling in which dissimilarities are assumed to be distances. The result of this multidimensional scaling variant are coordinates in the Euclidean space that explain the given distances. In general, the embedding found is not unique. Any rotation or translation applied to found embedding does not change the pairwise distances.
+
+## Linear Algebra Backends
+
+RMDS makes heavy use of linear algebra routines, but does not ship with linear algebra algorithms. Instead, RMDS has a non-intrusive adapter architecture to connect existing linear algebra packages to RMDS. For how-to details on providing new adapters for RMDS see {MDS::MatrixInterface}.
+
+Note that the performance of most RMDS algorithms is dominated by the algorithms and performance of the linear algebra backend used. 
+
+Currently the following linear algebra backends are supported
+
+- {MDS::StdlibInterface} - Connects Ruby's core matrix class to RMDS.
+- {MDS::GSLInterface} - Connects the GNU Scientific Library to RMDS.
+- {MDS::LinalgInterface} - Connects LAPACK and BLAS via Linalg to RMDS.
+
+## Examples
+
+The following successfully calculates a two dimensional Cartesian embedding for a given distance matrix.
+  
+    require 'mds'
+    require 'mds/interfaces/gsl_interface'
+    
+    # Tell RMDS the linear algebra backend to be used.
+    MDS::Backend.interface = MDS::GSLInterface
+    
+    # The squared Euclidean distance matrix.
+    d2 = MDS::Matrix.create_rows(
+      [0.0, 10.0, 2.0], 
+      [10.0, 0.0, 20.0], 
+      [2.0, 20.0, 0.0]
+    )
+    
+    # Find a Cartesian embedding in two dimensions
+    # that approximates the distances in two dimensions.
+    x = MDS::Metric.projectd(d2, 2)
+    
+The result, *x*, of the above example is shown in the following image. In red the coordinates that yield the input matrix *d2*. In green, the resulting embedding *x* which preserves distances between individual observations and is unique up to rigid transformations.
+
+![Result of MDS](http://github.com/cheind/rmds/raw/master/docs/readme_example.png)
+
+The following example works on a distance matrix which originates from air distances between european cities. It does not require a concrete linear algebra backend, but rather chooses an available one. The results are diagrammed graphically using Gnuplot and compared to the result from a mapping tool.
+
+    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 distance 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 # we use squared distances
+      rescue ArgumentError
+        cities << entry
+        nil
+      end
+    end
+    
+    # Invoke MDS
+
+    d2 = MDS::Matrix.create_rows(*rows)      
+    # Find a projection that preserves 90 percent of the variance of the distances.
+    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
+
+The following image show the result of the above script. A map is shown in a separate image for comparison. 
+
+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.
+
+![Result of MDS](http://github.com/cheind/rmds/raw/master/docs/readme_mds_cities.png) 
+
+![Result of Mapping](http://github.com/cheind/rmds/raw/master/docs/readme_cities.png)
+    
+## Benchmarks
+The following tables show the results of benchmarking different linear algebra packages against three test scenarios. They were generated by invoking 'rake test:bench:all' on a QuadCore 2.4 GHz machine, running Ubuntu 10.4 inside a virtual machine.
+
+Note that the each test involves creation of the observations randomly, calculating the squared euclidean distance matrix of observations and invoking MDS. The first two steps are not listed explicitely since they only take roughly 5 percent of the total runtime.
+
+    Benchmarking RMDS for 10 observations in 2-dimensional space
+                    user     system      total        real
+    stdlib:     3.710000   1.220000   4.930000 (  5.195076)
+    gsl:        0.000000   0.000000   0.000000 (  0.067544)
+    linalg:     0.000000   0.000000   0.000000 (  0.005462)
+    
+    Benchmarking RMDS for 100 observations in 5-dimensional space
+                    user     system      total        real
+    stdlib:          inf        inf        inf (       inf)
+    gsl:        0.030000   0.010000   0.040000 (  0.043115)
+    linalg:     0.020000   0.010000   0.030000 (  0.043157)
+    
+    Benchmarking RMDS for 1000 observations in 10-dimensional space
+                    user     system      total        real
+    stdlib:          inf        inf        inf (       inf)
+    gsl:       34.070000   1.390000  35.460000 ( 39.013276)
+    linalg:    12.750000   0.340000  13.090000 ( 13.645427)
+    
+Because of documented limitations of {MDS::StdlibInterface} timings for this interface are shown only for the smallest of the three scenarios. Neither GSL nor LAPACK/BLAS was re-compiled for optimal performance.
+
+## Requirements
+
+RMDS itself does not have any dependencies except Ruby. Each matrix interface is likley to depend on one or more external projects, such as bindings and native libraries.
+
+RMDS is tested against Ruby 1.8.7 and Ruby 1.9.1.
+
+## Documentation
+
+An up-to-date documentation of the current master branch can be found [here](http://rdoc.info/github/cheind/rmds/master/frames).
+
+## License
+
+*RMDS* is copyright 2010 Christoph Heindl. It is free software, and may be redistributed under the terms specified in the {file:LICENSE.md} file.
+
+[wiki_mds]: http://en.wikipedia.org/wiki/Multidimensional_scaling "Wikipedia - Multidimensional Scaling"

data/Rakefile

@@ -0,0 +1,77 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+require 'lib/mds'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+task :default => ['test:unit:all']
+
+namespace 'test' do
+
+  namespace 'unit' do
+  
+    desc 'Run all unit tests'
+    Rake::TestTask.new('all') do |t|
+      t.pattern = FileList['test/unit/**/test_*.rb']
+      t.verbose = false
+      t.warning = false
+    end
+  
+    desc 'Run unit tests for GSL interface'
+    Rake::TestTask.new('gsl') do |t|
+      t.pattern = FileList['test/unit/**/test_*gsl_*.rb']
+      t.verbose = false
+      t.warning = false
+    end
+    
+    desc 'Run unit tests for Stdlib interface'
+    Rake::TestTask.new('std') do |t|
+      t.pattern = FileList['test/unit/**/test_*stdlib_*.rb']
+      t.verbose = false
+      t.warning = false
+    end
+    
+    desc 'Run unit tests for Linalg interface'
+    Rake::TestTask.new('linalg') do |t|
+      t.pattern = FileList['test/unit/**/test_*linalg_*.rb']
+      t.verbose = false
+      t.warning = false
+    end
+  end
+  
+  namespace 'bench' do
+  
+    desc 'Run all benchmarks'
+    task('all') do |t|
+      require 'test/benchmark/benchmark_metric'
+    end
+    
+  end
+  
+end
+
+namespace 'docs' do
+
+  desc "Generate rdoc documentation"
+  Rake::RDocTask.new do |rd|
+    rd.rdoc_dir = "doc"
+    rd.main = 'README.md'
+    rd.options << '--title' << "RMDS #{MDS::VERSION} Documentation"
+    rd.rdoc_files.include('README.md', 'LICENSE.md', 'lib/**/*.rb', 'examples/**/*.rb')
+  end
+  
+  begin
+    require 'yard'
+    YARD::Rake::YardocTask.new do |t|
+      t.files   = ['lib/**/*.rb', 'examples/**/*.rb', '-', 'LICENSE.md'] 
+      t.options = ['--no-cache', '--title', "RMDS #{MDS::VERSION} Documentation"]
+    end
+  rescue LoadError
+    warn '**YARD is missing, disabling docs:yard task'
+  end
+end

data/examples/adaptive_backend.rb

@@ -0,0 +1,61 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  #
+  # Examples for RMDS
+  #
+  module Examples
+
+    #
+    # Illustrates advanced usage of {MDS::Backend}.
+    #
+    def Examples.adaptive_backend(argv)
+      require 'mds'
+      
+      # Try adding interfaces from command line arguments
+      # Make sure that at least the standard RMDS interfaces
+      # are included
+      argv << './lib/mds/interfaces/*.rb'
+      
+      while !argv.empty?
+        MDS::Backend.try_require(argv.shift)
+      end
+      
+      # Select the first available interface.
+      # Additionally pass an array of interace names that are preferred.
+      interface = MDS::Backend.first(['MDS::GSLInterface', 'MDS::LinalgInterface'])
+      raise 'No interface found' unless interface
+      puts "Using interface #{interface}"
+      
+      MDS::Backend.active = interface
+
+      # The squared Euclidean distance matrix.
+      d2 = MDS::Matrix.create_rows(
+        [0.0, 10.0, 2.0], 
+        [10.0, 0.0, 20.0], 
+        [2.0, 20.0, 0.0]
+      )
+
+      # Find a Cartesian embedding in two dimensions
+      # that approximates the distances in d2.
+      x = MDS::Metric.projectd(d2, 2) 
+
+      puts x.matrix
+      # x => -0.6037  0.2828
+      #       2.5370 -0.0841
+      #      -1.9330 -0.1987
+    end
+  end
+  
+end
+
+if __FILE__ == $0
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  MDS::Examples.adaptive_backend(ARGV)
+end
+
+

data/examples/extended_metric.rb

@@ -0,0 +1,82 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+
+  #
+  # Examples for RMDS
+  #
+  module Examples
+    #
+    # Illustrates usage of {MDS::Metric}
+    #
+    def Examples.extended_metric
+      require 'mds'
+      
+      # Prepare the linear algebra backend to be used.
+      require 'mds/interfaces/stdlib_interface'
+      MDS::Backend.active = MDS::StdlibInterface
+    
+      # Observations, usually unknown
+      x = MDS::Matrix.create_rows(
+        [1.0, 2.0], # Point A
+        [4.0, 3.0], # Point B
+        [0.0, 1.0]  # Point C
+      )
+
+      # Calculate the squared Euclidean distance matrix of observations,
+      # which is usually the only given input for MDS.
+
+      d = MDS::Metric.squared_distances(x)
+         
+      # Find an Cartesian embedding of D, such that 99 percent
+      # of the variances of distances in D are preserved. 
+
+      x_proj = MDS::Metric.projectk(d, 0.99) 
+        # => [[-0.60   0.28],
+        #     [ 2.53  -0.08],
+        #     [-1.93  -0.19]]
+
+      # Since distances are preserved it should hold
+      # that the squared Euclidean distance matrix of 
+      # x_proj equals D upto a certain delta.
+
+      diff = MDS::Metric.squared_distances(x_proj) - d
+        # => [[0.0 0.0 0.0],
+        #     [0.0 0.0 0.0],
+        #     [0.0 0.0 0.0]]
+        
+      puts "Deviation from input"
+      puts diff.matrix
+        
+      # If less accuracy of preserved distances is needed,
+      # one may lower the percentage. In our case, 80% are
+      # reflected in an embedding with just one dimension.
+      #
+      # If you look at the original input, X, this is true,
+      # since all points are close be colinear.
+
+      x_proj = MDS::Metric.projectk(d, 0.8) 
+        # => [[-0.60],
+        #     [ 2.53],
+        #     [-1.93]]
+
+      # Therefore, the distance matrix yields a reduced
+      # degree of accuracy.
+
+      diff = MDS::Metric.squared_distances(x_proj) - d
+        # => [[ 0.0  -0.13 -0.23],
+        #     [-0.13  0.0  -0.01],
+        #     [-0.23 -0.01  0.0]]
+    end
+  end
+end
+  
+  
+if __FILE__ == $0
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  MDS::Examples.extended_metric
+end

data/examples/minimal_metric.rb

@@ -0,0 +1,52 @@
+#
+# RMDS - Ruby Multidimensional Scaling Library
+# Copyright (c) Christoph Heindl, 2010
+# http://github.com/cheind/rmds
+#
+
+module MDS
+  #
+  # Examples for RMDS
+  #
+  module Examples
+
+    #
+    # Illustrates usage of {MDS::Metric}.
+    #
+    # Given a matrix of squared Euclidean distances, find
+    # a two-dimensional Cartesian embedding.
+    #
+    def Examples.minimal_metric
+      # Load RMDS
+      require 'mds'
+
+      # Prepare the linear algebra backend to be used.
+      require 'mds/interfaces/gsl_interface'
+      MDS::Backend.active = MDS::GSLInterface
+
+      # The squared Euclidean distance matrix.
+      d2 = MDS::Matrix.create_rows(
+        [0.0, 10.0, 2.0], 
+        [10.0, 0.0, 20.0], 
+        [2.0, 20.0, 0.0]
+      )
+
+      # Find a Cartesian embedding in two dimensions
+      # that approximates the distances in d2.
+      x = MDS::Metric.projectd(d2, 2) 
+
+      puts x.matrix
+      # x => -0.6037  0.2828
+      #       2.5370 -0.0841
+      #      -1.9330 -0.1987
+    end
+  end
+  
+end
+
+if __FILE__ == $0
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  MDS::Examples.minimal_metric
+end
+
+