spcore 0.2.0 → 0.2.1

data/ChangeLog.rdoc

@@ -54,4 +54,8 @@ Add Signal#keep_frequences, Signal#remove_frequencies, and Plotter#plot_signals.
 
 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).
+Make envelopes smoother with polynomial upsampling. In Signal#envelope and Signal, always return a Signal object (so also remove make_signal flag).
+
+=== 0.2.1 / 2013-07-03
+
+Update for compatibility with hashmake-0.2.0.

data/lib/spcore.rb

@@ -4,7 +4,6 @@ require 'spcore/version'
 require 'spcore/core/circular_buffer'
 require 'spcore/core/constants'
 require 'spcore/core/delay_line'
-require 'spcore/core/oscillator'
 
 require 'spcore/windows/bartlett_hann_window'
 require 'spcore/windows/bartlett_window'
@@ -41,15 +40,19 @@ 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'
+require 'spcore/analysis/calculus'
+require 'spcore/analysis/features'
+require 'spcore/analysis/statistics'
+require 'spcore/analysis/frequency_domain'
 
 require 'spcore/util/gain'
 require 'spcore/util/limiters'
 require 'spcore/util/plotter'
 require 'spcore/util/saturation'
 require 'spcore/util/scale'
-require 'spcore/util/signal_generator'
+require 'spcore/util/signal'
 require 'spcore/util/envelope_detector'
+
+require 'spcore/generation/oscillator'
+require 'spcore/generation/signal_generator'
+require 'spcore/generation/comb_filter'

data/lib/spcore/analysis/calculus.rb

@@ -0,0 +1,38 @@
+module SPCore
+# Calculus analysis methods.
+class Calculus
+  # Differentiates the given values.
+  #
+  # @param [Array] values The input value series.
+  # @param [Numeric] dt The time differential (i.e. the sample period)
+  def self.derivative values, dt
+    raise "values.size is <= 2" if values.size <= 2
+    
+    derivative = Array.new(values.size)
+    
+    for i in 1...values.count
+      derivative[i] = (values[i] - values[i-1]) / dt
+    end
+    
+    derivative[0] = derivative[1]
+    return derivative
+  end
+  
+  # Integrates the given values.
+  #
+  # @param [Array] values The input value series.
+  # @param [Numeric] dt The time differential (i.e. the sample period)
+  def self.integral values, dt
+    raise "values.size is <= 2" if values.size <= 2
+    
+    integral = Array.new(values.size)
+    
+    integral[0] = values[0] * dt
+    for i in 1...values.count
+      integral[i] = (values[i] * dt) + integral[i-1]
+    end
+    
+    return integral
+  end
+end
+end

data/lib/spcore/analysis/features.rb

@@ -0,0 +1,186 @@
+module SPCore
+# Features analysis methods.
+class Features  
+  # Returns all minima and maxima (including positive minima and negative maxima).
+  def self.extrema samples
+    remove_inner = false
+    self.extrema_hash(samples, remove_inner)[:extrema]
+  end
+
+  # Returns outer minima and maxima (excludes positive minima and negative maxima).
+  def self.outer_extrema samples
+    remove_inner = true
+    self.extrema_hash(samples, remove_inner)[:extrema]
+  end
+
+  # Returns all minima (including positive minima).
+  def self.minima samples
+    remove_inner = false
+    self.extrema_hash(samples, remove_inner)[:minima]
+  end
+
+  # Returns all minima (excludes positive minima).
+  def self.negative_minima samples
+    remove_inner = true
+    self.extrema_hash(samples, remove_inner)[:minima]
+  end
+  
+  # Returns maxima (includes negative maxima).
+  def self.maxima samples
+    remove_inner = false
+    self.extrema_hash(samples, remove_inner)[:maxima]
+  end
+
+  # Returns maxima (excludes negative maxima).
+  def self.positive_maxima samples
+    remove_inner = true
+    self.extrema_hash(samples, remove_inner)[:maxima]
+  end
+  
+  # return the n greatest values of the given array of values.
+  def self.top_n values, n
+    top_n = []
+    values.each do |value|
+      if top_n.count < n
+        top_n.push value
+      else
+        smaller = top_n.select {|x| x < value}
+        if smaller.any?
+          top_n.delete smaller.min
+          top_n.push value
+        end
+      end
+    end
+    return top_n.sort
+  end
+  
+  def self.outline samples
+    starting_outline = make_starting_outline samples
+    filled_in_outline = fill_in_starting_outline starting_outline, samples.count
+    dropsample_factor = (samples.count / starting_outline.count).to_i
+    return dropsample_filled_in_outline filled_in_outline, dropsample_factor
+  end
+  
+  def self.envelope samples
+    outline = self.outline samples
+    upsample_factor = samples.count / outline.count.to_f
+    return PolynomialResampling.upsample(outline, upsample_factor)
+  end
+
+  private
+  
+  def self.make_starting_outline samples
+    starting_outline = self.outer_extrema(samples)
+    
+    # add in first and last samples so the envelope follows entire signal
+    starting_outline[0] = samples[0].abs
+    starting_outline[samples.count - 1] = samples[samples.count - 1].abs
+    
+    # the envelope is only concerned with absolute values
+    starting_outline.keys.each do |key|
+      starting_outline[key] = starting_outline[key].abs
+    end
+    
+    return starting_outline
+  end
+  
+  def self.fill_in_starting_outline starting_outline, tgt_count
+    # 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(tgt_count, 0)
+    indices = starting_outline.keys.sort
+    
+    for i in 1...indices.count
+      l_idx = indices[i-1]
+      r_idx = indices[i]
+      
+      l_val = starting_outline[l_idx]
+      r_val = starting_outline[r_idx]
+      
+      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
+        proper_outline[j] = y
+      end
+    end
+    
+    return proper_outline
+  end
+  
+  # This properly spaces samples in the filled in outline, so as to avoid time
+  # distortion after upsampling.
+  def self.dropsample_filled_in_outline filled_in_outline, dropsample_factor
+    dropsampled_outline = []
+
+    (0...filled_in_outline.count).step(dropsample_factor) do |n|
+      dropsampled_outline.push filled_in_outline[n]
+    end
+    
+    return dropsampled_outline
+  end
+  
+  # Finds extrema (minima and maxima), return :extrema, :minima, and :maxima
+  # seperately in a hash.
+  def self.extrema_hash samples, remove_inner = false
+    minima = {}
+    maxima = {}
+    
+    global_min_idx = 0
+    global_min_val = samples[0]
+    global_max_idx = 0
+    global_max_val = samples[0]
+    
+    diffs = []
+    for i in (1...samples.count)
+      diffs.push(samples[i] - samples[i-1])
+      
+      if samples[i] < global_min_val
+        global_min_idx = i
+        global_min_val = samples[i]
+      end
+      
+      if samples[i] > global_max_val
+        global_max_idx = i
+        global_max_val = samples[i]
+      end
+    end
+    minima[global_min_idx] = global_min_val
+    maxima[global_max_idx] = global_max_val
+    
+    is_positive = diffs.first > 0.0 # starting off with positive difference?
+    
+    # at zero crossings there is a local maxima/minima    
+    for i in (1...diffs.count)
+      if is_positive
+        # at positive-to-negative transition there is a local maxima
+        if diffs[i] <= 0.0
+          maxima[i] = samples[i]
+          is_positive = false
+        end
+      else
+        # at negative-to-positive transition there is a local minima
+        if diffs[i] > 0.0
+          minima[i] = samples[i]
+          is_positive = true
+        end
+      end
+    end
+    
+    if remove_inner
+      minima.keep_if {|idx,val| val <= 0 }
+      maxima.keep_if {|idx,val| val >= 0 }
+    end
+        
+    return :minima => minima, :maxima => maxima, :extrema => minima.merge(maxima)
+  end
+
+end
+end

data/lib/spcore/analysis/frequency_domain.rb

@@ -0,0 +1,191 @@
+module SPCore
+# Frequency domain analysis class. On instantiation a forware FFT is performed
+# on the given time series data, and the results are stored in full and half form.
+# The half-FFT form cuts out the latter half of the FFT results. Also, for the
+# half-FFT the complex values will be converted to magnitude (linear or decibel)
+# if specified in :fft_format (see FFT_FORMATS for valid values).
+class FrequencyDomain
+  include Hashmake::HashMakeable
+  
+  FFT_COMPLEX_VALUED = :complexValued
+  FFT_MAGNITUDE_LINEAR = :magnitudeLinear
+  FFT_MAGNITUDE_DECIBEL = :magnitudeDecibel
+  
+  # valid values to give for the :fft_format key.
+  FFT_FORMATS = [
+    FFT_COMPLEX_VALUED,
+    FFT_MAGNITUDE_LINEAR,
+    FFT_MAGNITUDE_DECIBEL
+  ]
+  
+  # define how the class is to be instantiated by hash.
+  ARG_SPECS = {
+    :time_data => arg_spec_array(:reqd => true, :type => Numeric),
+    :sample_rate => arg_spec(:reqd => true, :type => Numeric, :validator => ->(a){ a > 0 }),
+    :fft_format => arg_spec(:reqd => false, :type => Symbol, :default => FFT_MAGNITUDE_DECIBEL, :validator => ->(a){FFT_FORMATS.include?(a)})
+  }
+  
+  attr_reader :time_data, :sample_rate, :fft_format, :fft_full, :fft_half
+  
+  def initialize args
+    hash_make args, FrequencyDomain::ARG_SPECS
+    @fft_full = FFT.forward @time_data
+    @fft_half = @fft_full[0...(@fft_full.size / 2)]
+    
+    case(@fft_format)
+    when FFT_MAGNITUDE_LINEAR
+      @fft_half = @fft_half.map {|x| x.magnitude }
+    when FFT_MAGNITUDE_DECIBEL
+      @fft_half = @fft_half.map {|x| Gain.linear_to_db x.magnitude }  # in decibels
+    end
+  end
+  
+  # Convert an FFT output index to the corresponding frequency bin
+  def idx_to_freq(idx)
+    return (idx * @sample_rate.to_f) / @fft_full.size
+  end
+  
+  # Convert an FFT frequency bin to the corresponding FFT output index
+  def freq_to_idx(freq)
+    return (freq * @fft_full.size) / @sample_rate.to_f
+  end
+  
+  # Find frequency peak values.
+  def peaks
+    # map positive maxima to indices
+    positive_maxima = Features.positive_maxima(@fft_half)
+
+    freq_peaks = {}
+    positive_maxima.keys.sort.each do |idx|
+      freq = idx_to_freq(idx)
+      freq_peaks[freq] = positive_maxima[idx]
+    end
+    
+    return freq_peaks
+  end
+  
+  GCD = :gcd
+  WINDOW = :window
+  HARMONIC_SERIES_APPROACHES = [ GCD, WINDOW ]
+  
+  # Find the strongest harmonic series among the given peak data.
+  def harmonic_series opts = {}
+    defaults = { :n_peaks => 8, :min_freq => 40.0, :approach => WINDOW }
+    opts = defaults.merge(opts)
+    
+    n_peaks = opts[:n_peaks]
+    min_freq = opts[:min_freq]
+    approach = opts[:approach]
+    
+    raise ArgumentError, "n_peaks is < 1" if n_peaks < 1
+    peaks = self.peaks
+    
+    if peaks.empty?
+      return []
+    end
+    
+    max_freq = peaks.keys.max
+    max_idx = freq_to_idx(max_freq)
+    
+    sorted_pairs = peaks.sort_by {|f,m| m}
+    top_n_pairs = sorted_pairs.reverse[0, n_peaks]
+    
+    candidate_series = []
+    
+    case approach
+    when GCD
+      for n in 1..n_peaks
+        combinations = top_n_pairs.combination(n).to_a
+        combinations.each do |combination|
+          freq_indices = combination.map {|pair| freq_to_idx(pair[0]) }
+          fund_idx = multi_gcd freq_indices
+          
+          if fund_idx >= freq_to_idx(min_freq)
+            series = []
+            idx = fund_idx
+            while idx <= max_idx
+              freq = idx_to_freq(idx)
+              #if peaks.has_key? freq
+                series.push freq
+              #end
+              idx += fund_idx
+            end
+            candidate_series.push series
+          end
+        end
+      end
+    when WINDOW
+      # look for a harmonic series
+      top_n_pairs.each do |pair|
+        f_base = pair[0]
+        
+        min_idx_base = freq_to_idx(f_base) - 0.5
+        max_idx_base = min_idx_base + 1.0
+        
+        harmonic_series = [ f_base ]
+        target = 2 * f_base
+        min_idx = 2 * min_idx_base
+        max_idx = 2 * max_idx_base
+        
+        while target < max_freq
+          f_l = idx_to_freq(min_idx.floor)
+          f_h = idx_to_freq(max_idx.ceil)
+          window = f_l..f_h
+          candidates = peaks.select {|actual,magn| window.include?(actual) }
+          
+          if candidates.any?
+            min = candidates.min_by {|actual,magn| (actual - target).abs }
+            harmonic_series.push min[0]
+          else
+            break
+          end
+          
+          target += f_base
+          min_idx += min_idx_base
+          max_idx += max_idx_base
+        end
+        
+        candidate_series.push harmonic_series
+      end
+    else
+      raise ArgumentError, "#{approach} approach is not supported"
+    end
+    
+    strongest_series = candidate_series.max_by do |harmonic_series|
+      sum = 0
+      harmonic_series.each do |f|
+        if peaks.has_key?(f)
+          sum += peaks[f]**2
+        else
+          m = @fft_half[freq_to_idx(f)].magnitude
+          sum += m**2
+        end
+      end
+      sum
+    end
+    
+    return strongest_series
+  end
+  
+  private
+  
+  def gcd a,b
+    if b == 0
+      return a
+    else
+      return gcd(b, a % b)
+    end
+  end
+  
+  def multi_gcd nums
+    if nums.count == 1
+      return nums[0]
+    elsif nums.count == 2
+      return gcd nums[0], nums[1]
+    else
+      return multi_gcd [gcd(nums[0], nums[1])] + nums[2..-1]
+    end
+  end
+  
+end
+end