spcore 0.1.9 → 0.2.0

data/ChangeLog.rdoc

@@ -48,4 +48,10 @@ Add Envelope and Extrema classes, for signal analysis.
 === 0.1.9 / 2013-05-06
 
 Add TukeyWindow.
-Add Signal#keep_frequences, Signal#remove_frequencies, and Plotter#plot_signals.
+Add Signal#keep_frequences, Signal#remove_frequencies, and Plotter#plot_signals.
+
+=== 0.2.0 / 2013-05-21
+
+Add instance methods to Signal class: #duration, #normalize, #derivative, #lowpass, #highpass, #bandpass, #bandstop, #plot_1d, and #plot_2d.
+Add Correlation class to find similarity between signals (used to find a feature in an image).
+Make envelopes smoother with polynomial upsampling. In Signal#envelope and Signal, always return a Signal object (so also remove make_signal flag).

data/README.rdoc

@@ -25,6 +25,9 @@ A library of signal processing methods and classes.
 * Oscillator with selectable wave type (sine, square, triangle, sawtooth)
 * Signal abstraction class
 * Extrema & Envelope measurement
+* Normalization
+* Derivatives
+* Correlation
 
 == Examples
 

data/lib/spcore.rb

@@ -41,6 +41,7 @@ require 'spcore/resampling/discrete_resampling'
 require 'spcore/resampling/polynomial_resampling'
 require 'spcore/resampling/hybrid_resampling'
 
+require 'spcore/analysis/correlation'
 require 'spcore/analysis/extrema'
 require 'spcore/analysis/envelope'
 require 'spcore/analysis/signal'

data/lib/spcore/analysis/correlation.rb

@@ -0,0 +1,55 @@
+module SPCore
+# Determines the normalized cross-correlation of a feature with an image.
+# Normalization is from -1 to +1, where +1 is high correlation, -1 is high
+# correlation (of inverse), and 0 is no correlation.
+#
+# For autocorrelation, just cross-correlate a signal with itself.
+#
+# @author James Tunnell
+class Correlation
+  attr_reader :data
+
+  # @param [Array] image The values which are actually recieved/measured.
+  # @param [Array] feature The values to be searched for in the image. Size must not be greater than size of image.
+  # @param [Fixnum] zero_padding Number of zeros to surround the image with.
+  def initialize image, feature, zero_padding = 0
+    raise ArgumentError, "feature size is > image size" if feature.size > image.size
+    
+    unless zero_padding == 0
+      image = Array.new(zero_padding, 0) + image + Array.new(zero_padding, 0)
+    end
+    
+    feature_mean = feature.inject(0){ |s, x| s + x } / feature.size.to_f
+    feature_diff = feature.map {|x| x - feature_mean }
+    sx = feature_diff.inject(0){ |s, x| s + x**2 }
+    
+    @data = []
+    for i in 0...(1 + image.size - feature.size)
+      region = image[i...(i + feature.size)]
+      region_mean = region.inject(0){|s,x| s + x } / feature.size.to_f
+      region_diff = region.map {|x| x - region_mean }
+      sy = region_diff.inject(0){ |s, x| s + x**2 }
+      
+      if sx == 0 || sy == 0
+        if sx == 0 && sy == 0
+          @data.push 1.0
+        else
+          @data.push 0.0
+        end
+        
+        next
+      end
+        
+      denom = Math.sqrt(sx*sy)
+      
+      sum = 0
+      feature.size.times do |j|
+        sum += (region_diff[j] * feature_diff[j])
+      end
+      
+      r = sum / denom
+      @data.push(r)
+    end    
+  end
+end
+end

data/lib/spcore/analysis/envelope.rb

@@ -11,47 +11,65 @@ class Envelope
   def initialize samples
     # combine absolute values of positive maxima and negative minima
     extrema = Extrema.new(samples)
-    points = {}
+    starting_outline = {}
     extrema.minima.each do |idx,val|
       if val <= 0.0
-        points[idx] = val.abs
+        starting_outline[idx] =val.abs
       end
     end
     
     extrema.maxima.each do |idx,val|
       if val >= 0.0
-        points[idx] = val.abs
+        starting_outline[idx] = val.abs
       end
     end
     
     # add in first and last samples so the envelope follows entire signal
-    points[0] = samples[0].abs
-    points[samples.count - 1] = samples[samples.count - 1].abs
+    starting_outline[0] = samples[0].abs
+    starting_outline[samples.count - 1] = samples[samples.count - 1].abs
     
-    indices = points.keys.sort
-    @data = Array.new(samples.count, 0)
+    # the extrema we have now are probably not spaced evenly. Upsampling at
+    # this point would lead to a time-distorted signal. So the next step is to
+    # interpolate between all the extrema to make a crude but properly sampled
+    # envelope.
+    
+    proper_outline = Array.new(samples.count, 0)
+    indices = starting_outline.keys.sort
     
-    # interpolate between all the extrema for the rest of the values. We
-    # manually added first/last index so the whole signal should be covered
-    # by this
     for i in 1...indices.count
       l_idx = indices[i-1]
       r_idx = indices[i]
       
-      l_val = points[l_idx]
-      r_val = points[r_idx]
+      l_val = starting_outline[l_idx]
+      r_val = starting_outline[r_idx]
       
-      @data[l_idx] = l_val
-      @data[r_idx] = r_val
+      proper_outline[l_idx] = l_val
+      proper_outline[r_idx] = r_val
       
       idx_span = r_idx - l_idx
       
       for j in (l_idx + 1)...(r_idx)
         x = (j - l_idx).to_f / idx_span
         y = Interpolation.linear l_val, r_val, x
-        @data[j] = y
+        proper_outline[j] = y
       end
     end
+    
+    # Now downsample by dropping samples, back to the number of starting_outline we had
+    # with just the extrema, but this time with samples properly spaced so as
+    # to avoid time distortion after upsampling.
+    
+    downsample_factor = (samples.count / starting_outline.count).to_i
+    downsampled_outline = []
+
+    (0...proper_outline.count).step(downsample_factor) do |n|
+      downsampled_outline.push proper_outline[n]
+    end
+    
+    # finally, use polynomial interpolation to upsample to the original sample rate.
+    
+    upsample_factor = samples.count / downsampled_outline.count.to_f
+    @data = PolynomialResampling.upsample(downsampled_outline, upsample_factor)
   end
 
 end

data/lib/spcore/analysis/signal.rb

@@ -37,22 +37,107 @@ class Signal
   def size
     @data.size
   end
+
+  # Size of the signal data.
+  def count
+    @data.size
+  end
+  
+  # Signal duration in seconds.
+  def duration
+    return @data.size.to_f / @sample_rate
+  end
   
   # Access signal data.
   def [](arg)
     @data[arg]
   end
+
+  # Plot the signal data against sample numbers.
+  def plot_1d
+    plotter = Plotter.new(:title => "Signal: values vs. sample number", :xtitle => "sample number", :ytitle => "sample value")
+    plotter.plot_1d "signal data" => @data
+  end
+  
+  # Plot the signal data against time.
+  def plot_2d
+    plotter = Plotter.new(:title => "Signal: values vs. time", :xtitle => "time (sec)", :ytitle => "sample value")
+    
+    data_vs_time = {}
+    sp = 1.0 / @sample_rate
+    @data.each_index do |i|
+      data_vs_time[i * sp] = @data[i]
+    end
+      
+    plotter.plot_2d "signal data" => data_vs_time
+  end
+  
+  # Run a discrete lowpass filter over the signal data (using SincFilter).
+  # Modifies current object.
+  def lowpass! cutoff_freq, order
+    filter = SincFilter.new(:sample_rate => @sample_rate, :order => order, :cutoff_freq => cutoff_freq)
+    @data = filter.lowpass(@data)
+    return self
+  end
+  
+  # Run a discrete lowpass filter over the signal data (using SincFilter).
+  # Return result in a new Signal object.
+  def lowpass cutoff_freq, order
+    self.clone.lowpass! cutoff_freq, order
+  end
+
+  # Run a discrete highpass filter over the signal data (using SincFilter).
+  # Modifies current object.
+  def highpass! cutoff_freq, order
+    filter = SincFilter.new(:sample_rate => @sample_rate, :order => order, :cutoff_freq => cutoff_freq)
+    @data = filter.highpass(@data)
+    return self
+  end
+  
+  # Run a discrete highpass filter over the signal data (using SincFilter).
+  # Return result in a new Signal object.
+  def highpass cutoff_freq, order
+    self.clone.highpass! cutoff_freq, order
+  end
+  
+  # Run a discrete bandpass filter over the signal data (using DualSincFilter).
+  # Modifies current object.
+  def bandpass! left_cutoff, right_cutoff, order
+    filter = DualSincFilter.new(
+      :sample_rate => @sample_rate,
+      :order => order,
+      :left_cutoff_freq => left_cutoff,
+      :right_cutoff_freq => right_cutoff
+    )
+    @data = filter.bandpass(@data)
+    return self
+  end
   
-  # Plot the signal data, either against sample numbers or fraction of total samples.
-  # @param plot_against_fraction If false, plot data against sample number. If true,
-  #                              plot against fraction of total samples.
-  def plot_data plot_against_fraction
-    xtitle = (plot_against_fraction ? "fraction of total samples" : "sample numbers")
-    plotter = Plotter.new(:title => "signal data sequence", :xtitle => xtitle, :ytitle => "sample values")
-    titled_sequence = {"signal data" => @data}
-    plotter.plot_1d titled_sequence, plot_against_fraction
+  # Run a discrete bandpass filter over the signal data (using DualSincFilter).
+  # Return result in a new Signal object.
+  def bandpass left_cutoff, right_cutoff, order
+    self.clone.bandpass! left_cutoff, right_cutoff, order
+  end
+
+  # Run a discrete bandstop filter over the signal data (using DualSincFilter).
+  # Modifies current object.
+  def bandstop! left_cutoff, right_cutoff, order
+    filter = DualSincFilter.new(
+      :sample_rate => @sample_rate,
+      :order => order,
+      :left_cutoff_freq => left_cutoff,
+      :right_cutoff_freq => right_cutoff
+    )
+    @data = filter.bandstop(@data)
+    return self
   end
   
+  # Run a discrete bandstop filter over the signal data (using DualSincFilter).
+  # Return result in a new Signal object.
+  def bandstop left_cutoff, right_cutoff, order
+    self.clone.bandstop! left_cutoff, right_cutoff, order
+  end
+
   # Increase the sample rate of signal data by the given factor using
   # discrete upsampling method. Modifies current object.
   # @param [Fixnum] upsample_factor Increase the sample rate by this factor.
@@ -181,21 +266,43 @@ class Signal
     Math.sqrt(energy / size)
   end
   
+  # Compute the mean of signal data.
+  def mean
+    sum = @data.inject(0){ |s, x| s + x }
+    return sum.to_f / size
+  end
+  
   # Find extrema (maxima, minima) within signal data.
   def extrema
     return Extrema.new(@data)
   end
   
+  # Operate on the signal data (in place) with the absolute value function.
+  def abs!
+    @data = @data.map {|x| x.abs }
+    return self
+  end
+  
+  # Operate on copy of the Signal object with the absolute value function.
+  def abs
+    self.clone.abs!
+  end
+  
+  def normalize! level = 1.0
+    self.divide!(@data.max / level)
+  end
+  
+  # reduce all samples to 
+  def normalize level = 1.0
+    self.clone.normalize! level
+  end
+  
   # Determine the envelope of the current Signal and return either a Envelope
   # or a new Signal object as a result.
   # @param [True/False] make_signal If true, return envelope data in a new
   #                     Otherwise, return an Envelope object.
-  def envelope make_signal = false
-    if make_signal
-      return Signal.new(:sample_rate => @sample_rate, :data => Envelope.new(@data).data)
-    else
-      return Envelope.new(@data)
-    end
+  def envelope
+    Signal.new(:sample_rate => @sample_rate, :data => Envelope.new(@data).data)
   end
   
   # Add data in array or other signal to the beginning of current data.
@@ -437,7 +544,26 @@ class Signal
     end
     
     return cross_correlation
-  end  
+  end
+  
+  # Differentiates the signal data.
+  # @param [true/false] make_signal If true, return the result as a new
+  #                                 Signal object. Otherwise, return result
+  #                                 as an array.
+  def derivative
+    raise "Signal does not have at least 2 samples" unless @data.size > 2
+    
+    derivative = Array.new(@data.size)
+    sample_period = 1.0 / @sample_rate
+    
+    for i in 1...@data.count
+      derivative[i] = (@data[i] - @data[i-1]) / sample_period
+    end
+    
+    derivative[0] = derivative[1]
+    
+    return Signal.new(:sample_rate => @sample_rate, :data => derivative)
+  end
 
   # Removes all but the given range of frequencies from the signal, using
   # frequency domain filtering. Modifes and returns the current object.

data/lib/spcore/util/plotter.rb

@@ -25,11 +25,12 @@ class Plotter
   end
   
   # Plot XY datapoints.
-  # @param [Hash] titled_hashes A hash that maps dataset titles to data. The data itself
-  #                             is a hash also, that maps x values to y values.
+  # @param [Hash] titled_hashes A hash that maps title strings to 2d datasets.
+  #                             The dataset itself is a hash also, that maps
+  #                             x values to y values.
   #
   # @example
-  #   Plotter.plot_2d "somedata" => {0.0 => 4.0, 1.0 => 2.0}
+  #   Plotter.new.plot_2d "somedata" => {0.0 => 4.0, 1.0 => 2.0}
   def plot_2d titled_hashes
     datasets = []
     titled_hashes.each do |title, hash|
@@ -51,24 +52,34 @@ class Plotter
     plot_datasets datasets
   end
 
+  # Plot XY datapoints.
+  # @param [Hash] titled_hashes A hash that maps title strings to 2d datasets.
+  #                             The dataset itself is a hash also, that maps
+  #                             x values to y values.
+  #
+  # @example
+  #   Plotter.plot_2d "somedata" => {0.0 => 4.0, 1.0 => 2.0}
+  def self.plot_2d titled_hashes
+    return Plotter.new.plot_2d titled_hashes
+  end
+  
   # Plot a sequence of values.
-  # @param [Hash] titled_sequences A hash that maps sequence titles to data. The data itself
-  #                             is an array of values. In the plot, values will be mapped to
-  #                             their index in the sequence.
-  # @param plot_against_fraction If true, instead of plotting samples against sample number, plot
-  #                              them against the fraction (sample_number / total_samples).
+  # @param [Hash] titled_sequences A hash that maps title strings to data
+  #                               sequences. The data itself is an array of
+  #                               values. In the plot, values will be mapped to
+  #                               their index in the sequence.
   #
   # @example
-  #   Plotter.plot_1d "somedata" => [0,2,3,6,3,-1]
-  def plot_1d titled_sequences, plot_against_fraction = false
+  #   Plotter.new.plot_1d "somedata" => [0,2,3,6,3,-1]
+  def plot_1d titled_sequences
     datasets = []
     titled_sequences.each do |title, sequence|
       indices = Array.new(sequence.size)
       sequence.each_index do |i|
         indices[i] = i
-        if plot_against_fraction
-          indices[i] /= sequence.size.to_f
-        end
+        #if plot_against_fraction
+        #  indices[i] /= sequence.size.to_f
+        #end
       end
       
       dataset = Gnuplot::DataSet.new( [indices, sequence] ){ |ds|
@@ -82,6 +93,18 @@ class Plotter
     plot_datasets datasets
   end
 
+  # Plot a sequence of values.
+  # @param [Hash] titled_sequences A hash that maps title strings to data
+  #                               sequences. The data itself is an array of
+  #                               values. In the plot, values will be mapped to
+  #                               their index in the sequence.
+  #
+  # @example
+  #   Plotter.plot_1d "somedata" => [0,2,3,6,3,-1]
+  def self.plot_1d titled_sequences
+    return Plotter.new.plot_1d titled_sequences
+  end
+
   # Plot Gnuplot::DataSet objects.
   # @param [Array] datasets An array of Gnuplot::DataSet objects.
   def plot_datasets datasets
@@ -98,7 +121,15 @@ class Plotter
       end
     end
   end
+
+  # Plot Gnuplot::DataSet objects.
+  # @param [Array] datasets An array of Gnuplot::DataSet objects.
+  def self.plot_datasets datasets
+    Plotter.new.plot_datasets datasets
+  end
   
+  # Plot data from Signal objects.
+  # @param [Hash] signals_hash A hash that maps title strings Signal objects
   def plot_signals signals_hash
     data_hash = {}
     signals_hash.each do |name, signal|
@@ -106,5 +137,11 @@ class Plotter
     end
     plot_1d data_hash
   end
+
+  # Plot data from Signal objects.
+  # @param [Hash] signals_hash A hash that maps title strings Signal objects
+  def self.plot_signals signals_hash
+    Plotter.new.plot_signals signals_hash
+  end
 end
 end

data/lib/spcore/version.rb

@@ -1,5 +1,5 @@
 # A library of signal processing methods and classes.
 module SPCore
   # spcore version
-  VERSION = "0.1.9"
+  VERSION = "0.2.0"
 end

data/spec/analysis/correlation_spec.rb

@@ -0,0 +1,28 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe SPCore::Correlation do
+  context 'image => triangular window' do
+    before :all do
+      @size = size = 48
+      @triangle = TriangularWindow.new(size * 2).data
+    end
+    
+    context 'feature => rising ramp (half size of triangular window)' do
+      it 'should have maximum correlation at beginning' do
+        rising_ramp = Array.new(@size){|i| i / @size.to_f }
+        correlation = Correlation.new(@triangle, rising_ramp)
+        correlation.data.first.should eq(correlation.data.max)
+      end
+    end
+    
+    context 'feature => falling ramp (half size of triangular window)' do
+      it 'should have maximum correlation at end' do
+        falling_ramp = Array.new(@size){|i| (@size - i) / @size.to_f }
+        correlation = Correlation.new(@triangle, falling_ramp)
+        correlation.data.last.should eq(correlation.data.max)
+        
+        #Plotter.plot_1d "correlate falling ramp" => correlation.data
+      end
+    end
+  end  
+end

data/spec/analysis/envelope_spec.rb

@@ -1,22 +1,27 @@
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 
 describe SPCore::Envelope do
-  it 'should produce an output that follows the amplitude of the input' do
+  before :all do
     sample_rate = 1000
-    sample_count = 512
+    sample_count = 512 * 2
     generator = SignalGenerator.new(:size => sample_count, :sample_rate => sample_rate)
     
-    modulation_signal = generator.make_signal [4.0]
-    modulation_signal.multiply! BlackmanWindow.new(sample_count).data
+    @modulation_signal = generator.make_signal [4.0], :amplitude => 0.1
+    @modulation_signal.multiply! BlackmanWindow.new(sample_count).data
 
-    base_signal = generator.make_signal [64.0]
-    base_signal.multiply! modulation_signal
-    
-    envelope = base_signal.envelope(true)
-    
+    @base_signal = generator.make_signal [64.0]
+    @base_signal.multiply! @modulation_signal
+  end
+
+  it 'should produce an output that follows the amplitude of the input' do
+    envelope = @base_signal.envelope
+    check_envelope(envelope)
+  end
+  
+  def check_envelope envelope    
     #signals = {
-    #  "signal" => base_signal,
-    #  "modulation" => modulation_signal,
+    #  "signal" => @base_signal,
+    #  "modulation (abs)" => @modulation_signal.abs,
     #  "envelope" => envelope,
     #}
     #
@@ -26,15 +31,17 @@ describe SPCore::Envelope do
     #  :ylabel => "values",
     #).plot_signals(signals)
     
+    #Plotter.new().plot_2d("envelop freq magnitudes" => envelope.freq_magnitudes)
+    
     begin
-      ideal = modulation_signal.energy
+      ideal = @modulation_signal.energy
       actual = envelope.energy
       error = (ideal - actual).abs / ideal
       error.should be_within(0.1).of(0.0)
     end
     
     begin
-      ideal = modulation_signal.rms
+      ideal = @modulation_signal.rms
       actual = envelope.rms
       error = (ideal - actual).abs / ideal
       error.should be_within(0.1).of(0.0)

data/spec/analysis/signal_spec.rb

@@ -1,6 +1,74 @@
 require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 
 describe SPCore::Signal do
+  describe '#duration' do
+    it 'should produce duration in seconds, according to sample_rate' do
+      sample_rate = 2000
+      [5,50,100,1500].each do |count|
+        zeros = Array.new(count, 0)
+        signal = SPCore::Signal.new(:data => zeros, :sample_rate => sample_rate)
+        expected_duration = count.to_f / sample_rate
+        signal.duration.should eq expected_duration
+      end      
+    end
+  end
+  
+  describe '#derivative' do
+    before :all do
+      sample_rate = 200
+      sample_period = 1.0 / sample_rate
+      sample_count = sample_rate
+      
+      range = -Math::PI..Math::PI
+      delta = (range.max - range.min) / sample_count
+      
+      sin = []
+      cos = []
+      
+      range.step(delta) do |x|
+        sin << Math::sin(x)
+        cos << (Math::PI * 2 * Math::cos(x))
+      end
+      
+      @sin = SPCore::Signal.new(:sample_rate => sample_count, :data => sin)
+      @expected = SPCore::Signal.new(:sample_rate => sample_count, :data => cos)
+      @actual = @sin.derivative
+    end
+    
+    it 'should produce a signal of same size' do
+      @actual.size.should eq @expected.size
+    end
+    
+    it 'should produce a signal matching the 1st derivative' do
+      @actual.data.each_index do |i|
+        @actual[i].should be_within(0.1).of(@expected[i])
+      end
+    end
+  end
+  
+  describe '#normalize' do
+    before :all do
+      generator = SignalGenerator.new(:sample_rate => 2000, :size => 256)
+      @signal = generator.make_signal([40.0, 160.0]).multiply(HannWindow.new(256).data)
+      @max = @signal.data.max
+    end
+    
+    it 'should be able to normalize to a level lower than peak value' do
+      normalized = @signal.normalize(@max * 0.75)
+      normalized.data.max.should eq(@max * 0.75)
+    end
+    
+    it 'should be able to normalize to a level higher than peak value' do
+      normalized = @signal.normalize(@max * 1.5)
+      normalized.data.max.should eq(@max * 1.5)
+    end
+
+    it 'should be able to normalize to a level equal to peak value' do
+      normalized = @signal.normalize(@max)
+      normalized.data.max.should eq(@max)
+    end
+  end
+  
   describe '#remove_frequencies' do
     before :each do
       generator = SignalGenerator.new(:sample_rate => 2000, :size => 256)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spcore
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-06 00:00:00.000000000 Z
+date: 2013-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashmake
@@ -144,6 +144,7 @@ files:
 - README.rdoc
 - Rakefile
 - lib/spcore.rb
+- lib/spcore/analysis/correlation.rb
 - lib/spcore/analysis/envelope.rb
 - lib/spcore/analysis/extrema.rb
 - lib/spcore/analysis/signal.rb
@@ -190,6 +191,7 @@ files:
 - lib/spcore/windows/triangular_window.rb
 - lib/spcore/windows/tukey_window.rb
 - spcore.gemspec
+- spec/analysis/correlation_spec.rb
 - spec/analysis/envelope_spec.rb
 - spec/analysis/extrema_spec.rb
 - spec/analysis/signal_spec.rb
@@ -228,7 +230,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -94862182169118755
+      hash: 688071795
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -237,7 +239,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -94862182169118755
+      hash: 688071795
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -245,6 +247,7 @@ signing_key:
 specification_version: 3
 summary: A library of signal processing methods and classes.
 test_files:
+- spec/analysis/correlation_spec.rb
 - spec/analysis/envelope_spec.rb
 - spec/analysis/extrema_spec.rb
 - spec/analysis/signal_spec.rb