spliner 1.0.1 → 1.0.2

data/README.markdown

@@ -19,7 +19,7 @@ Spliner requires Ruby 1.9 or later. Install with rubygems:
 Quick Start
 -----------
 
-require 'spliner'
+    require 'spliner'
 
     # Initialize a spline interpolation with x range 0.0..2.0
     my_spline = Spliner::Spliner.new({0.0 => 0.0, 1.0 => 1.0, 2.0 => 0.5})
@@ -37,6 +37,14 @@ require 'spliner'
     ex_spline = Spliner::Spliner.new({0.0 => 0.0, 1.0 => 1.0, 2.0 => 0.5}, :extrapolate => '10%', :emethod => :hold)
     xx = ex_spline[2.1] # returns 0.5
 
+    # Alternative intialization using X and Y arrays
+    ar_spline = Spliner::Spliner.new [1.0, 2.0, 3.0], [0.0, 3.0, 1.0]
+
+    # When duplicate X values are encountered, two or more discontinuous curves are used
+    two_spline = Spliner::Spliner.new [1.0, 2.0, 2.0, 3.0], [0.0, 3.0, 0.0, 1.0]
+    puts two_spline.sections # prints 2
+    
+
 Spliner is based on the interpolation described on this page
 http://en.wikipedia.org/wiki/Spline_interpolation
  
@@ -48,6 +56,12 @@ Feel free to fork the project on GitHub and send fork requests. Please
 try to have each feature separated in commits.
 
 
+Home page
+---------
+
+http://www.github.com/tallakt/spliner
+
+http://rubygems.org/gems/spliner
 
 License
 -------

data/lib/spliner.rb

@@ -1,154 +1,5 @@
-#
-# Spliner::Spliner
-#
-require 'matrix'
+require 'spliner/spliner'
 
 module Spliner
-  VERSION = '1.0.1'
-
-  # Spliner::Spliner provides cubic spline interpolation based on provided 
-  # key points on a X-Y curve.
-  #
-  # == Example
-  # require 'spliner'
-  # # Initialize a spline interpolation with x range 0.0..2.0
-  # my_spline = Spliner::Spliner.new({0.0 => 0.0, 1.0 => 1.0, 2.0 => 0.5})
-  # # Perform interpolation on 31 values ranging from 0..2.0
-  # x_values = (0..30).map {|x| x / 30.0 * 2.0 }
-  # y_values = x_values.map {|x| my_spline[x] }
-  #
-  # http://en.wikipedia.org/wiki/Spline_interpolation
-  #
-  class Spliner
-    attr_reader :range
-
-    # Creates a new Spliner::Spliner object to interpolate between
-    # the supplied key points. The key points are provided in a hash where
-    # the key is the X value, and the value is the Y value. The X values
-    # mush be increasing and not duplicate. You must provide at least 
-    # two values.
-    #
-    # options may take the following keys:
-    #
-    #   :extrapolate
-    #   Specify an area outside the given X values provided that should return
-    #   a valid number. The value may be either a range (eg. -10..110) or a
-    #   percentage value written as a string (eg '10%'). Default is no
-    #   extrapolation.
-    #
-    #   :emethod
-    #   Specify a method of extrapolation, one of :linear (continue curve as 
-    #   a straigt line, default), or :hold (use Y values at the curve endpoints)
-    #
-    def initialize(key_points, options = {})
-
-      @points = key_points
-      @x = @points.keys
-      @y = @points.values
-
-      check_points_increasing
-      raise 'Interpolation needs at least two points' unless @points.size >= 2
-
-      @x_pairs = @points.keys.each_cons(2).map {|pair| pair.first..pair.last }
-
-      inv_diff = @x.each_cons(2).map {|x1, x2| 1 / (x2 - x1) }
-      a_diag = 2.0 * Matrix::diagonal(*vector_helper(inv_diff))
-      a_non_diag = Matrix::build(@points.size) do |row, col|
-        if row == col+ 1
-          inv_diff[col]
-        elsif col == row + 1
-          inv_diff[row]
-        else
-          0.0
-        end
-      end
-
-      a = a_diag + a_non_diag
-
-      tmp = @points.each_cons(2).map do |p1, p2|
-        x1, y1 = p1
-        x2, y2 = p2
-        3.0 * (y2 - y1) / (x2 - x1) ** 2.0
-      end
-      b = vector_helper(tmp)
-
-      @k = a.inv * b
-
-      options[:extrapolate].tap do |ex|
-        case ex
-        when /^\d+(\.\d+)?\s?%$/
-          percentage = ex[/\d+(\.\d+)?/].to_f
-          span = @x.last - @x.first
-          extra = span * percentage * 0.01
-          @range = (@x.first - extra)..(@x.last + extra)
-        when Range
-          @range = ex
-        when nil
-          @range = @x.first..@x.last
-        else
-          raise 'Unable to use extrapolation parameter'
-        end
-      end
-
-      @extrapolation_method = options[:emethod] || :linear
-    end
-
-    # returns an interpolated value
-    def get(v)
-      i = @x_pairs.find_index {|pair| pair.member? v }
-      if i
-        dx = @x[i + 1] - @x[i]
-        dy = @y[i + 1] - @y[i]
-        t = (v - @x[i]) / dx
-        a = @k[i] * dx - dy
-        b = -(@k[i + 1] * dx - dy)
-        (1 - t) * @y[i] + t * @y[i + 1] + t * (1 - t) * (a * (1 - t) + b * t)
-      elsif range.member? v
-        extrapolate(v)
-      else
-        nil
-      end
-    end
-
-    alias :'[]' :get 
-
-
-    # for a vector [a, b, c] returns [a, a + b, b + c, c]
-    # :nodoc:
-    def vector_helper(a)
-      Vector[*([0.0] + a)] + Vector[*(a + [0.0])]
-    end
-    private :vector_helper
-
-
-
-    # :nodoc:
-    def check_points_increasing
-      @x.each_cons(2) do |x1, x2|
-        raise 'Points must form a series of x and y values where x is increasing' unless x2 > x1
-      end
-    end
-    private :check_points_increasing
-
-    # :nodoc:
-    def extrapolate(v)
-      case @extrapolation_method
-      when :hold
-        if v < @x.first
-          @y.first
-        else
-          @y.last
-        end
-      else
-        x, y, k = if v < @x.first
-                    [@x.first, @y.first, @k.first]
-                  else
-                    [@x.last, @y.last, @k[-1]]
-                  end
-        y + k * (v - x)
-      end
-    end
-    private :extrapolate
-
-  end
+  VERSION = '1.0.2'
 end

data/lib/spliner/spliner.rb

@@ -0,0 +1,135 @@
+require 'matrix'
+require 'spliner/spliner_section'
+
+module Spliner
+  # Spliner::Spliner provides cubic spline interpolation based on provided 
+  # key points on a X-Y curve.
+  #
+  # == Example
+  #
+  #    require 'spliner'
+  #    # Initialize a spline interpolation with x range 0.0..2.0
+  #    my_spline = Spliner::Spliner.new [0.0, 1.0, 2.0], [0.0, 1.0, 0.5]
+  #    # Perform interpolation on 31 values ranging from 0..2.0
+  #    x_values = (0..30).map {|x| x / 30.0 * 2.0 }
+  #    y_values = x_values.map {|x| my_spline[x] }
+  #
+  # Algorithm based on http://en.wikipedia.org/wiki/Spline_interpolation
+  #
+  class Spliner
+    attr_reader :range
+
+    # Creates a new Spliner::Spliner object to interpolate between
+    # the supplied key points. 
+    #
+    # The key points shoul be in increaing X order. When duplicate X 
+    # values are encountered, the spline is split into two or more 
+    # discontinuous sections.
+    #
+    # The extrapolation method may be :linear by default, using a linear 
+    # extrapolation at the curve ends using the curve derivative at the 
+    # end points. The :hold method will use the Y value at the nearest end 
+    # point of the curve.
+    #
+    # @overload initialize(key_points, options)
+    #   @param key_points [Hash{Float => Float}] keys are X values in increasing order, values Y
+    #   @param options [Hash]
+    #   @option options [Range,String] :extrapolate ('0%') either a range or percentage, eg '10.0%'
+    #   @option options [Symbol] :emethod (:linear) extrapolation method
+    #
+    # @overload initialize(x, y, options)
+    #   @param x [Array(Float),Vector] the X values of the key points
+    #   @param y [Array(Float),Vector] the Y values of the key points
+    #   @param options [Hash]
+    #   @option options [Range,String] :extrapolate ('0%') either a range or percentage, eg '10.0%'
+    #   @option options [Symbol] :emethod (:linear) extrapolation method
+    #
+    def initialize(*param)
+      # sort parameters from two alternative initializer signatures
+      x, y = nil
+      case param.first
+      when Array, Vector
+        xx,yy, options = param
+        x = xx.to_a
+        y = yy.to_a
+      else
+        points, options = param
+        x = points.keys
+        y = points.values
+      end
+      options ||= {}
+
+      @sections = split_at_duplicates(x).map {|slice| SplinerSection.new x[slice], y[slice] }
+
+      # Handle extrapolation option parameter
+      options[:extrapolate].tap do |ex|
+        case ex
+        when /^\d+(\.\d+)?\s?%$/
+          percentage = ex[/\d+(\.\d+)?/].to_f
+          span = x.last - x.first
+          extra = span * percentage * 0.01
+          @range = (x.first - extra)..(x.last + extra)
+        when Range
+          @range = ex
+        when nil
+          @range = x.first..x.last
+        else
+          raise 'Unable to use extrapolation parameter'
+        end
+      end
+      @extrapolation_method = options[:emethod] || :linear
+    end
+
+    # returns the ranges at each slice between duplicate X values
+    def split_at_duplicates(x)
+      # find all indices with duplicate x values
+      dups = x.each_cons(2).map{|a,b| a== b}.each_with_index.select {|b,i| b }.map {|b,i| i}
+      ([-1] + dups + [x.size - 1]).each_cons(2).map {|end0, end1| (end0 + 1)..end1 }
+    end
+    private :split_at_duplicates
+
+
+    # returns an interpolated value
+    def get(v)
+      i = @sections.find_index {|section| section.range.member? v }
+      if i
+        @sections[i].get v
+      elsif range.member? v
+        extrapolate(v)
+      else
+        nil
+      end
+    end
+
+    alias :'[]' :get 
+
+    # The number of non-continuous sections used
+    def sections
+      @sections.size
+    end
+
+
+
+    def extrapolate(v)
+      x, y, k = if v < first_x
+                  [@sections.first.x.first, @sections.first.y.first, @sections.first.k.first]
+                else
+                  [@sections.last.x.last, @sections.last.y.last, @sections.last.k[-1]]
+                end
+
+      case @extrapolation_method
+      when :hold
+        y
+      else
+        y + k * (v - x)
+      end
+    end
+    private :extrapolate
+
+    def first_x
+      @sections.first.x.first
+    end
+    private :first_x
+  end
+end
+

data/lib/spliner/spliner_section.rb

@@ -0,0 +1,86 @@
+require 'matrix'
+require 'spliner/spliner_section'
+
+module Spliner
+
+  # Spliner::SplinerSection is only used via Spliner::Spliner
+  #
+  # As the spline algorithm does not handle duplicate X values well, the 
+  # curve is split into two non continuous parts where duplicate X values 
+  # appear. Each such part is represented by a SplinerSection
+  class SplinerSection
+    attr_reader :k, :x, :y
+
+    def initialize(x, y)
+      @x, @y = x, y
+      @x_pairs = @x.each_cons(2).map {|pair| pair.first..pair.last }
+      check_points_increasing
+      calculate_a_k
+    end
+
+    def range
+      @x.first..@x.last
+    end
+
+    def calculate_a_k
+      if @x.size > 1
+        inv_diff = @x.each_cons(2).map {|x1, x2| 1 / (x2 - x1) }
+        a_diag = 2.0 * Matrix::diagonal(*vector_helper(inv_diff))
+        a_non_diag = Matrix::build(@x.size) do |row, col|
+          if row == col+ 1
+            inv_diff[col]
+          elsif col == row + 1
+            inv_diff[row]
+          else
+            0.0
+          end
+        end
+
+        a = a_diag + a_non_diag
+
+        tmp = @x.zip(@y).each_cons(2).map do |p1, p2|
+          x1, y1 = p1
+          x2, y2 = p2
+          3.0 * (y2 - y1) / (x2 - x1) ** 2.0
+        end
+        b = vector_helper(tmp)
+
+        @k = a.inv * b
+      else
+        @k = Vector[0.0]
+      end
+    end
+    private :calculate_a_k
+
+    # returns an interpolated value
+    def get(v)
+      i = @x_pairs.find_index {|pair| pair.member? v }
+      if i
+        dx = @x[i + 1] - @x[i]
+        dy = @y[i + 1] - @y[i]
+        t = (v - @x[i]) / dx
+        a = @k[i] * dx - dy
+        b = -(@k[i + 1] * dx - dy)
+        (1 - t) * @y[i] + t * @y[i + 1] + t * (1 - t) * (a * (1 - t) + b * t)
+      elsif @x.size == 1 && @x.first == v
+        @y.first
+      else
+        nil
+      end
+    end
+
+    # for a vector [a, b, c] returns [a, a + b, b + c, c]
+    def vector_helper(a)
+      Vector[*([0.0] + a)] + Vector[*(a + [0.0])]
+    end
+    private :vector_helper
+
+    def check_points_increasing
+      @x.each_cons(2) do |x1, x2|
+        raise 'Key point\'s X values should be in increasing order' unless x2 > x1
+      end
+    end
+    private :check_points_increasing
+  end
+end
+

data/spec/spliner_spec.rb

@@ -6,11 +6,38 @@ describe Spliner::Spliner do
 
 
   it 'should not accept x values that are not increasing' do
-    expect(lambda { Spliner::Spliner.new({0 => 0, 0 => 10})}).to raise_exception
+    expect(lambda { Spliner::Spliner.new [0.0, -1.0], [0.0, 1.0] }).to raise_exception
   end
 
-  it 'should not accept less than two values' do 
-    expect(lambda { Spliner::Spliner.new({0 => 0})}).to raise_exception
+  it 'should support key points with a single value' do
+    s1 = Spliner::Spliner.new Hash[0.0, 0.0]
+    expect(s1.get 0.0).to be_within(0.0001).of(0.0)
+    expect(s1.get 1.5).to be_nil
+
+    s2 = Spliner::Spliner.new Hash[0.0, 0.0], :extrapolate => -1..1
+    expect(s2.get 0.0).to be_within(0.0001).of(0.0)
+    expect(s2.get 0.5).to be_within(0.0001).of(0.0)
+  end
+
+  it 'supports the Hash initializer' do
+    s1 = Spliner::Spliner.new Hash[0.0, 0.0, 1.0, 1.0]
+    expect(s1[0.5]).to be_within(0.0001).of(0.5)
+
+    s2 = Spliner::Spliner.new Hash[0.0, 0.0, 1.0, 1.0], :extrapolate => '100%'
+    expect(s2[0.5]).to be_within(0.0001).of(0.5)
+    expect(s2.range.first).to be_within(0.0001).of(-1.0)
+  end
+
+  it 'supports the x-y array/vector initializer' do
+    s1 = Spliner::Spliner.new [0.0, 1.0], [0.0, 1.0]
+    expect(s1[0.5]).to be_within(0.0001).of(0.5)
+
+    s2= Spliner::Spliner.new [0.0, 1.0], [0.0, 1.0], :extrapolate => '100%'
+    expect(s2[0.5]).to be_within(0.0001).of(0.5)
+    expect(s2.range.first).to be_within(0.0001).of(-1.0)
+
+    s3 = Spliner::Spliner.new Vector[0.0, 1.0], Vector[0.0, 1.0]
+    expect(s3[0.5]).to be_within(0.0001).of(0.5)
   end
 
   it 'should return the data points themselves' do
@@ -71,4 +98,15 @@ describe Spliner::Spliner do
     expect(s3.range.first).to be_within(0.0001).of(-10.0)
     expect(s3.range.last).to be_within(0.0001).of(110.0)
   end
+
+  it 'splits data points with duplicate X values into separate sections' do
+    s = Spliner::Spliner.new [0.0, 1.0, 1.0, 2.0, 2.0, 3.0], [0.0, 0.0, 1.0, 1.0, 2.0, 2.0], :extrapolate => 3.0..4.0
+    expect(s.sections).to eq(3)
+    expect(s[-1.0]).to be_nil
+    expect(s[0.5]).to be_within(0.0001).of(0.0)
+    expect(s[1.5]).to be_within(0.0001).of(1.0)
+    expect(s[2.5]).to be_within(0.0001).of(2.0)
+    expect(s[3.5]).to be_within(0.0001).of(2.0)
+    expect(s[5.0]).to be_nil
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spliner
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-21 00:00:00.000000000 Z
+date: 2012-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -57,6 +57,8 @@ files:
 - README.markdown
 - Rakefile
 - lib/spliner.rb
+- lib/spliner/spliner.rb
+- lib/spliner/spliner_section.rb
 - spec/spliner_spec.rb
 - spliner.gemspec
 homepage: http://www.github.com/tallakt/spliner
@@ -84,3 +86,4 @@ signing_key:
 specification_version: 3
 summary: Cubic spline interpolation library
 test_files: []
+has_rdoc: