digiproc 0.1.0

data/lib/concerns/data_properties.rb

@@ -0,0 +1,223 @@
+## 
+# Module which can perform basic operations on 1D data arrays
+# This module extends itself so all methods can be called via:
+## Digiproc::DataProperties.method_i_want_to_call
+
+module Digiproc::DataProperties
+
+    extend self 
+    ##
+    ## all_maxima(data [Array]) => returns Array(OpenStruct<#index, #value>)
+    # returns all maximum in an array of `OpenStruct`s with #index and #value, ie:
+    ## all_maxima([1,2,3,4,5,4,3,2,6,7,8,7,6,5])   # [#<OpenStruct index=4, value=5>, #<OpenStruct index=10, value=8>] 
+    def all_maxima(data)
+        raise ArgumentError.new("Data must be an array") if not data.is_a? Array
+        slope = Slope::Positive
+        max = []
+        data.each_with_index do |n, i|
+            old_slope = slope
+            if i <= data.length - 2
+                new_slope = find_slope(data[i], data[i+1])
+                slope = new_slope.is?(:zero) ? old_slope : new_slope
+                max << OpenStruct.new(index: i, value: n) if old_slope.is? :positive and slope.is? :negative
+            else
+                max << OpenStruct.new(index: i, value: n) if slope.is? :positive
+            end
+        end
+        max
+    end
+
+    ##
+    # maxima(data [Array], num = 1 [Integer]) returns `num` number of largest maxima from the data array returned in #all_maxima
+    ## arr = [1,2,3,4,5,4,3,2,6,7,8,7,6,5]
+    ## Digiproc::DataProperties.maxima(arr, 1) # => [#<OpenStruct index=10, value=8>]
+    def maxima(data, num = 1)
+        all_maxima(data).sort{ |a, b| b.value <=> a.value }.take num
+    end
+
+    ##
+    # local_maxima(data [Array], num=1 [Integer]) => returns Array(OpenStruct(#index, #value))
+    # calculates all maxima and orders them by how much proportionally they
+    # are to any directly adjacent maxima. It then takes `num` answer and returns an array of `OpenStruct`s with #index and #value
+    # This is particularly useful to use when looking for local maxima in a FFT dB or magnitude plot.
+    ##  arr = [50,45,40,30,35,30,29,28,29,20,15,10,19,9,8,7,9,8,7,6,5,9,6,5,4,9,6,3,2,7,5,4,3,2,1,9,1,2,3,4]
+    ##  Digiproc::DataProperties.local_maxima(arr, 3)  #=> [#<OpenStruct index=35, value=9>, #<OpenStruct index=0, value=50>, #<OpenStruct index=12, value=19>]
+    def local_maxima(data, num=1)
+        all_maxima = all_maxima(data)
+        all_maxima.sort do |a, b|
+            a_upper = all_maxima.find{ |maxima| maxima.index > a.index }
+            a_lower = all_maxima.reverse.find{ |maxima| maxima.index < a.index }
+            a_adjacent = 0
+            if a_upper && a_lower
+                a_adjacent = ((a.value.to_f / a_upper.value) + (a.value.to_f / a_lower.value))  / 2.0
+            else
+                a_adjacent = !!a_upper ? (a.value.to_f / a_upper.value) : (a.value.to_f / a_lower.value)
+            end
+            b_upper = all_maxima.find{ |maxima| maxima.index > b.index }
+            b_lower = all_maxima.reverse.find{ |maxima| maxima.index < b.index }
+            b_adjacent = 0
+            if b_upper && b_lower
+                b_adjacent = ((b.value.to_f / b_upper.value) +  (b.value.to_f / b_lower.value))  / 2.0
+            else
+                b_adjacent = !!b_upper ? (b.value.to_f / b_upper.value) : (b.value.to_f / b_lower.value)
+            end
+            b_adjacent <=> a_adjacent
+        end
+        .take(num)
+    end
+
+    ##
+    # slope(a: Numeric, b: Numeric, range=1: Numeric ) => float
+    # returns the slope of these two y values, given a change in x values by `range` which defualts to 1. Returns a float
+    ## Digiproc::DataProperties.slope(0.5, 1.2, 0.5) #=> 1.4
+    def slope(a,b, range=1)
+        return (b - a) / range.to_f
+    end
+
+    ##
+    # find_slope(a: Int or Double, b: Int or Double) returns Slope::Positive, Slope::Negative, or Slope::Zero
+    # Note: Slope::Positive.is? :positive returns true, Slope::Negative.is? :negative returns true, etc.
+    def find_slope(a,b)
+        slope = nil
+        if b - a > 0
+            slope = Slope::Positive
+        elsif b - a < 0
+            slope = Slope::Negative
+        else
+            slope = Slope::Zero
+        end
+        slope
+    end
+
+    ##
+    ## Inner slope class made for pleasant syntax in the maxima methods
+    class Slope
+
+        ##
+        # returns inner class Negative
+        def self.Negative
+            Negative
+        end
+
+        ##
+        # returns inner class Positive
+        def self.Positive
+            Positive
+        end
+
+        ##
+        # returns inner class Zero
+        def self.Zero
+            Zero
+        end
+
+        ##
+        ## Used in the Slope class to indicate a negative slope. 
+        # Made for easy syntax purposes
+        class Negative
+
+            ##
+            # Used for comparison in == 
+            # returns :negative
+            def self.type
+                :negative
+            end
+
+            ##
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Negative == OpenStruct.new(type: :negative) # true
+            ## Digiproc::DataProperties::Slope::Negative == :negative # true
+            ## Digiproc::DataProperties::Slope::Negative == "negative" # true
+            def self.==(val)
+                if val.respond_to? :type
+                    return true if val.type == :negative
+                end
+                return true if val == :negative
+                if val.respond_to? :downcase
+                    return true if val.downcase == "negative"
+                end
+                false
+            end
+
+            ##
+            # Alias to ==
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Negative.is? OpenStruct.new(type: :negative) # true
+            ## Digiproc::DataProperties::Slope::Negative.is? :negative # true
+            ## Digiproc::DataProperties::Slope::Negative.is? "negative" # true, not case sensitive
+            def self.is?(val)
+                self.==(val)
+            end
+        end
+
+        ##
+        ## Used in the Slope class to indicate a positive slope. 
+        # Made for easy syntax purposes
+        class Positive
+            def self.type
+                :positive
+            end
+
+            ##
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Positive == OpenStruct.new(type: :positive) # true
+            ## Digiproc::DataProperties::Slope::Positive == :positive # true
+            ## Digiproc::DataProperties::Slope::Negative == "positive" # true, not case-sensitive
+            def self.==(val)
+                if val.respond_to? :type
+                    return true if val.type == :positive
+                end
+                return true if val == :positive
+                if val.respond_to? :downcase
+                    return true if val.downcase == "positive"
+                end
+                false
+            end
+
+            ##
+            # Alias to ==
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Piositive.is? OpenStruct.new(type: :negative) # true
+            ## Digiproc::DataProperties::Slope::Positive.is? :positive # true
+            ## Digiproc::DataProperties::Slope::Positive.is? "positive" # true, not case-sensitive
+            def self.is?(val)
+                self.==(val)
+            end
+        end
+
+        ##
+        ## Used in the Slope class to indicate a zero slope. 
+        # Made for easy syntax purposes
+        class Zero
+            def self.type
+                :zero
+            end
+
+            ##
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Zero == OpenStruct.new(type: :zero) # true
+            ## Digiproc::DataProperties::Slope::Zero == :zero # true
+            ## Digiproc::DataProperties::Slope::Zero == "zero" # true, not case sensitive
+            def self.==(val)
+                if val.respond_to? :type
+                    return true if val.type == :zero
+                end
+                return true if val == :zero
+                if val.respond_to? :downcase
+                    return true if val.downcase == "zero"
+                end
+                false
+            end
+
+            ##
+            # Alias to ==
+            # Can test equality in multiple ways:
+            ## Digiproc::DataProperties::Slope::Zero.is? OpenStruct.new(type: :zero) # true
+            ## Digiproc::DataProperties::Slope::Zero.is? :zero # true
+            ## Digiproc::DataProperties::Slope::Zero.is? "zero" # true, not case sensitive
+            def self.is?(val)
+                self.==(val)
+            end
+        end
+    end
+end

data/lib/concerns/fourier_transformable.rb

@@ -0,0 +1,178 @@
+## 
+# Module for Classes which have a property `data` which we can take the Discrete Fourier Transform of.
+# A class which wants to use methods outside of GenricMethods will also include Digiproc::Initializable, and you have to use the appropriate methods in your class constructor if you want the Digiproc::FFT class to be set up automatically
+# You could manually set it up if your class sets up its own @fft property which is an instance of Digiproc::FFT with the class' `data` passed in.
+# See an example of this in action in Digiproc::DigitalSignal initializer method. 
+module Digiproc::FourierTransformable
+
+    ## 
+    # Inner module for places where standalone functions are needed, not associated with a class which contains `data`. See Digiproc::Functions for use
+    module GenericMethods
+
+        ##
+        # Return a Fast Fourier Transform (FFT) strategy to be used for GenericMethods. Set to Digiproc::Strategies::Radix2Strategy
+        # It is important to note that the Radix2Strategy increases the size of the FFT return to the closest power of 2. 
+        def fft_strategy
+            Digiproc::Strategies::Radix2Strategy
+        end
+
+        # Return an Inverse Fast Fourier Transform (IFFT) strategy to be used for GenericMethods. Set to Digiproc::Strategies::IFFTConjugateStrategy 
+        def ifft_strategy
+            Digiproc::Strategies::IFFTConjugateStrategy
+        end
+
+        ## 
+        ## fft(data [Array of complex Numerics]) => returns Array of data corresponding to the FFT
+        # Note that for the Radix2Strategy, the only time the return size will equal the input size is if the input size is a power of 2. 
+        # Otherwise the return will be increased to the closest power of 2.
+        ## Digiproc::Functions.fft([1,2,3,4,5,6,7,8]) # => [
+        ## # 36, 
+        ## # (-4.0+9.65685424949238i),
+        ## # (-4.000000000000001+4.0i),
+        ## # (-4.000000000000002+1.6568542494923797i),
+        ## # -4,
+        ## # (-3.9999999999999996-1.6568542494923797i),
+        ## # (-3.999999999999999-4.0i),
+        ## # (-3.999999999999998-9.65685424949238i)]
+       
+        def fft(data)
+            fft_strategy.new(data.dup).calculate
+        end
+        
+        ##
+        ## ifft(data [Array of complex Numerics])
+        # Due to using the Radix2Strategy, the ifft will return the exact input if the input is a power of 2.
+        # Otherwise, there will be trailing 0s. ie: 
+        ## ft = Digiproc::Functions.fft([1,2,3,4,5,6,7,8])
+        ## Digiproc::Functions.ifft(ft) # => [(1.0-0.0i),
+        ##  # (2.0000000000000004-2.718345674301793e-16i),
+        ##  # (3.0+4.440892098500626e-16i),
+        ##  # (4.0+3.8285686989269494e-16i),
+        ##  # (5.0-0.0i),
+        ##  # (6.0-4.978996250514798e-17i),
+        ##  # (7.0-4.440892098500626e-16i),
+        ##  # (8.0-6.123233995736767e-17i)]
+        ## ft = Digiproc::Functions.fft([1,2,3,4,5])
+        ## Digiproc::Functions.ifft(ft) # => [(1.0-0.0i),
+        ##  # (2.0+3.0616169978683836e-17i),
+        ##  # (3.0-3.3306690738754696e-16i),
+        ##  # (4.0+8.040613248383182e-17i),
+        ##  # (5.0-0.0i),
+        ##  # (0.0-1.9142843494634747e-16i),
+        ##  # (0.0+3.3306690738754696e-16i),
+        ##  # (0.0+8.040613248383182e-17i)]
+        def ifft(data)
+            ifft_strategy.new(data.dup).calculate
+        end
+
+    end
+
+    ## 
+    # Include Digiproc::RequiresData when an instance is instantiated that includes Digiproc::FourierTransformable because
+    # methods require `data` (an array of Fourier Transformable data) to exist in the class
+    def self.included(base)
+        base.class_eval do 
+            include Digiproc::RequiresData, Digiproc::Initializable
+        end
+    end
+
+    attr_writer :fft
+    attr_reader :fft_strategy
+
+    ## 
+    # Initialize with (time_data: [Array(Numeric)], fft_strategy: [optional, defaults to Digiproc::Strategies::Radix2Strategy])
+    # Upon instantiation, a new Digiproc::FFT class is made with the data passed in as time_data.
+    # NOTE this does not happen automatically upon instantiation of the class which includes this module. 
+    # The class including this module will also include Digiproc::Initializable, so you can initialize this module in the class' #initialize method as follows:
+    ## class TestClass
+    ##     include Digiproc::FourierTransformable
+    ##     
+    ##     attr_accessor :data
+    ##
+    ##     def initialize(data: )
+    ##        @data = data
+    ##        initialize_modules(Digiproc::FourierTransformable => {time_data: data})
+    ##     end
+    ## end
+    ## 
+    # Note that the calculation of the FFT itself is lazy and will not be calculated unless there is an 
+    # attempt to access it or #calculate is called on @fft
+    def initialize(time_data: , fft_strategy: Digiproc::Strategies::Radix2Strategy)
+        @fft_strategy = fft_strategy
+        @fft = Digiproc::FFT.new(time_data: time_data.dup, strategy: fft_strategy)
+    end
+
+    ##
+    ## fft_db #=> Array of decible values of the magnitude of the FFT (Float, not complex)
+    # Ensures the fft is calculated, and then returns the dB vals
+    def fft_db
+        setup_fft
+        @fft.fft.db
+    end
+
+    ## fft_db #=> Array of values of the magnitude of the FFT (numeric, not complex)
+    # Ensures the fft is calculated, and then returns the magnitude
+    def fft_magnitude
+        setup_fft
+        @fft.magnitude
+    end
+
+    ##
+    ## fft(size [optional Integer]) #=> returns Digiproc::FFT instance
+    # Will calculate the FFT if it has not yet been calculated
+    # size is an optional parameter which allows you to delegate the size of the FFT to be calculated..
+    # This is useful if you want a particular resolution of the frequency domain, or if you are trying to match
+    # FFT sizes for calculation purposes. 
+    def fft(size = @fft.data.size)
+        if @fft.data.size != size
+            @fft.calculate_at_size(size)
+        end
+        @fft
+    end
+
+    ##
+    # setter for the FFT strategy
+    def fft_strategy=(strategy)
+        @fft.strategy = strategy
+    end
+
+    ##
+    ## fft_data # => Array of FFT vals (complex Numeric)
+    # Calculates the fft if not yet calculated, and returns the calculation
+    def fft_data
+        setup_fft
+        @fft.fft
+    end
+
+    ##
+    ## fft_data # => Array of angle vals (radians)
+    # Calculate the fft if not yet calculated, and returns Arra of the angle data in radians
+    def fft_angle
+        setup_fft
+        @fft.angle
+    end
+
+    ##
+    ## fft_real # => Array of real vals
+    # Calculate the fft if not yet calculated, and retun an Array of the real values
+    def fft_real
+        setup_fft
+        @fft.real
+    end
+
+    ##
+    ## fft_imaginary # => Array of imaginary vals
+    # Calculate the fft if not yet calculated, and retun an Array of the imaginary values
+    def fft_imaginary
+        setup_fft
+        @fft.fft.imaginary
+    end
+
+    private
+    ##
+    # Private method which calculates the fft 
+    def setup_fft
+        self.fft.calculate if self.fft.fft.nil?
+    end
+
+end

data/lib/concerns/initializable.rb

@@ -0,0 +1,43 @@
+
+## 
+# A module for classes which have other modules which can accept parameters from the class.
+# For example when included in a class, `Digiproc::FourierTransformable` automatically also includes
+# 'Digiproc::Initializable' because `Digiproc::FourierTransformable` needs time data (and an optional Strategy) to
+# generate the FFT for the data in the class. While another appropriate pattern could be to make the `Digiproc::FFT` generation
+# lazy, and just pull the `time_data` from the class' `data` property when any fft property is first queried, this pattern
+# allows more flexibility by allowing more customizable setup during instantiation
+module Digiproc::Initializable
+
+    ##
+    # Adds a `initialize_modules` method to the including class which allows you to call `initialize_modules(*modules)`
+    # where *modules can be Modules or a hash of Module => {params: params_values} for module initialization. 
+    # Modules which support initialization have an `initialize` method that can be called in this way
+    # See `Digiproc::DigitalSignal` for an example
+    ## initialize_modules(Module => { module_initializer_accepts_key: value, another_key: value2})
+    def self.included(base)
+        base.class_eval do 
+            def initialize_modules(*modules)
+                modules.each do |m|
+                    if verify_params(m) == :valid_hash
+                       m.keys.first.instance_method(:initialize).bind(self).call(m.values.first)
+                    elsif verify_params(m) == :valid_module
+                        m.instance_method(:initialize).bind(self).call
+                    end
+                end
+            end
+
+            private
+
+            def verify_params(item)
+                return :valid_module if item.is_a? Module
+                if item.is_a? Hash
+                    return :valid_hash if item.keys.length == 1 and item.keys.first.is_a? Module
+                end
+                raise ArgumentError.new("Each argument must either be a module or a hash of type Module => args")
+            end
+
+        end
+    end
+
+   
+end

data/lib/concerns/multipliable.rb

@@ -0,0 +1,22 @@
+##
+# Including Class instance must have a data property which is an array. Allows you to say 
+# classInstance1 * classInstance2 and the two data vectors will be multiplied on an element-by-element basis
+# Note: the data vectors must be the same length
+
+module Digiproc::Multipliable
+
+    def self.included(base)
+        base.class_eval do 
+            include RequiresData
+        end
+    end
+
+
+    ##
+    # Multiplies the instance's `data` property on an element-by-element basis with the other instance's data property
+    def * (obj)
+        raise ArgumentError.new("Object must have #data reader") if not obj.respond_to?(:data)
+        raise ArgumentError.new("Object data must respond to #times, #{obj.data.class} does not") if not obj.data.respond_to?(:times)
+        self.data.times obj.data
+    end
+end

data/lib/concerns/os.rb

@@ -0,0 +1,36 @@
+## 
+# Deternine the OS for classes which need to perform system commands
+module Digiproc::OS
+
+
+    ## 
+    # return true if in a windows env
+    def windows?
+        (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
+    end
+    
+    ## 
+    # return true if in a mac env
+    def mac?
+        (/darwin/ =~ RUBY_PLATFORM) != nil
+    end
+    
+    ## 
+    # return true if in a unix env
+    def unix?
+        !windows?
+    end
+    
+    ## 
+    # return true if in a linux env
+    def linux?
+        unix? and not mac?
+    end
+    
+    ## 
+    # return true if using jruby
+    def ruby?
+        RUBY_ENGINE == 'jruby'
+    end
+
+end