bmg 0.16.0.pre.rc1 → 0.16.0.pre.rc2

data/lib/bmg/summarizer.rb

@@ -0,0 +1,132 @@
+module Bmg
+  #
+  # Summarizer.
+  #
+  # This class provides a basis for implementing aggregation operators.
+  #
+  # Aggregation operators are made available through factory methods on the
+  # Summarizer class itself:
+  #
+  #     Summarizer.count
+  #     Summarizer.sum(:qty)
+  #     Summarizer.sum{|t| t[:qty] * t[:price] }
+  #
+  # Once built, summarizers can be used either in black-box or white-box modes.
+  #
+  #     relation = ...
+  #     agg = Summarizer.sum(:qty)
+  #
+  #     # Black box mode:
+  #     result = agg.summarize(relation)
+  #
+  #     # White box mode:
+  #     memo = agg.least
+  #     relation.each do |tuple|
+  #       memo = agg.happens(memo, tuple)
+  #     end
+  #     result = agg.finalize(memo)
+  #
+  class Summarizer
+
+    # @return Aggregation options as a Hash
+    attr_reader :options
+
+    # @return the underlying functor, either a Symbol or a Proc
+    attr_reader :functor
+
+    # Creates an Summarizer instance.
+    #
+    # Private method, please use the factory methods
+    def initialize(*args, &block)
+      @options = default_options
+      args.push(block) if block
+      args.each do |arg|
+        case arg
+        when Symbol, Proc then @functor = arg
+        when Hash         then @options = @options.merge(arg)
+        else
+          raise ArgumentError, "Unexpected `#{arg}`"
+        end
+      end
+    end
+
+    # Returns the default options to use
+    #
+    # @return the default aggregation options
+    def default_options
+      {}
+    end
+    protected :default_options
+
+    # Returns the least value, which is the one to use on an empty
+    # set.
+    #
+    # This method is intended to be overriden by subclasses; default
+    # implementation returns nil.
+    #
+    # @return the least value for this summarizer
+    def least
+      nil
+    end
+
+    # This method is called on each aggregated tuple and must return
+    # an updated _memo_ value. It can be seen as the block typically
+    # given to Enumerable.inject.
+    #
+    # The default implementation collects the pre-value on the tuple
+    # and delegates to _happens.
+    #
+    # @param memo the current aggregation value
+    # @param the current iterated tuple
+    # @return updated memo value
+    def happens(memo, tuple)
+      value = @functor.is_a?(Proc) ? @functor.call(tuple) : tuple[@functor]
+      _happens(memo, value)
+    end
+
+    # @see happens.
+    #
+    # This method is intended to be overriden and returns _value_
+    # by default, making this summarizer a "Last(...)" summarizer.
+    def _happens(memo, value)
+      value
+    end
+    protected :_happens
+
+    # This method finalizes an aggregation.
+    #
+    # Argument _memo_ is either _least_ or the result of aggregating
+    # through _happens_. The default implementation simply returns
+    # _memo_. The method is intended to be overriden for complex
+    # aggregations that need statefull information such as `avg`.
+    #
+    # @param [Object] memo the current aggregation value
+    # @return [Object] the aggregation value, as finalized
+    def finalize(memo)
+      memo
+    end
+
+    # Summarizes an enumeration of tuples.
+    #
+    # @param an enumerable of tuples
+    # @return the computed summarization value
+    def summarize(enum)
+      finalize(enum.inject(least){|m,t| happens(m, t) })
+    end
+
+    # Returns the canonical summarizer name
+    def to_summarizer_name
+      self.class.name.downcase[/::([a-z]+)$/, 1].to_sym
+    end
+
+  end # class Summarizer
+end # module Bmg
+require_relative 'summarizer/count'
+require_relative 'summarizer/sum'
+require_relative 'summarizer/min'
+require_relative 'summarizer/max'
+require_relative 'summarizer/avg'
+require_relative 'summarizer/variance'
+require_relative 'summarizer/stddev'
+require_relative 'summarizer/collect'
+require_relative 'summarizer/concat'

data/lib/bmg/summarizer/avg.rb

@@ -0,0 +1,36 @@
+module Bmg
+  class Summarizer
+    #
+    # Average summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.avg(:qty).summarize(...)
+    #
+    class Avg < Summarizer
+
+      # Returns [0.0, 0.0] as least value.
+      def least()
+        [0.0, 0.0]
+      end
+
+      # Collects one more value + the sum of all
+      def _happens(memo, val) 
+        [memo.first + val, memo.last + 1]
+      end
+
+      # Finalizes the computation.
+      def finalize(memo) 
+        memo.first / memo.last 
+      end
+
+    end # class Avg
+
+    # Factors an average summarizer
+    def self.avg(*args, &bl)
+      Avg.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/collect.rb

@@ -0,0 +1,31 @@
+module Bmg
+  class Summarizer
+    #
+    # Collects the various values as an array.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.collect(:qty).summarize(...)
+    #
+    class Collect < Summarizer
+
+      # Returns [] as least value.
+      def least()
+        []
+      end
+
+      # Adds val to the memo array
+      def _happens(memo, val) 
+        memo << val
+      end
+
+    end # class Collect
+
+    # Factors a collect summarizer
+    def self.collect(*args, &bl)
+      Collect.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/concat.rb

@@ -0,0 +1,42 @@
+module Bmg
+  class Summarizer
+    #
+    # String concatenation summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.concat(:qty).summarize(...)
+    #
+    class Concat < Summarizer
+
+      # Sets default options.
+      def default_options
+        {:before => "", :after => "", :between => ""}
+      end
+
+      # Returns least value (defaults to "")
+      def least()
+        ""
+      end
+
+      # Concatenates current memo with val.to_s
+      def _happens(memo, val) 
+        memo << options[:between].to_s unless memo.empty?
+        memo << val.to_s
+      end
+
+      # Finalizes computation
+      def finalize(memo)
+        options[:before].to_s + memo + options[:after].to_s
+      end
+
+    end # class Concat
+
+    # Factors a concatenation summarizer
+    def self.concat(*args, &bl)
+      Concat.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/count.rb

@@ -0,0 +1,31 @@
+module Bmg
+  class Summarizer
+    #
+    # Count summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.count.summarize(...)
+    #
+    class Count < Summarizer
+
+      # Returns 0 as least value.
+      def least()
+        0
+      end
+
+      # Counts one more as new memo
+      def happens(memo, tuple) 
+        memo + 1
+      end
+
+    end # class Count
+
+    # Factors a count summarizer
+    def self.count(*args, &bl)
+      Count.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/max.rb

@@ -0,0 +1,31 @@
+module Bmg
+  class Summarizer
+    #
+    # Max summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.max(:qty).summarize(...)
+    #
+    class Max < Summarizer
+
+      # Returns nil as least value.
+      def least()
+        nil
+      end
+
+      # Keeps the maximum value between memo and val, ignoring nil
+      def _happens(memo, val) 
+        memo.nil? ? val : (val.nil? ? memo : (memo > val ? memo : val))
+      end
+
+    end # class Max
+
+    # Factors a max summarizer
+    def self.max(*args, &bl)
+      Max.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/min.rb

@@ -0,0 +1,31 @@
+module Bmg
+  class Summarizer
+    #
+    # Min summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.min(:qty).summarize(...)
+    #
+    class Min < Summarizer
+
+      # Returns nil as least value.
+      def least()
+        nil
+      end
+
+      # Keep the minimum value between memo and val, ignoring nil
+      def _happens(memo, val) 
+        memo.nil? ? val : (val.nil? ? memo : (memo < val ? memo : val))
+      end
+
+    end # class Min
+
+    # Factors a min summarizer
+    def self.min(*args, &bl)
+      Min.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/stddev.rb

@@ -0,0 +1,26 @@
+module Bmg
+  class Summarizer
+    #
+    # Standard deviation summarizer
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.stddev(:qty).summarize(...)
+    #
+    class Stddev < Variance
+
+      # Finalizes the computation.
+      def finalize(memo) 
+        Math.sqrt(super(memo))
+      end
+
+    end # class Stddev
+
+    # Factors a standard deviation summarizer
+    def self.stddev(*args, &bl)
+      Stddev.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/sum.rb

@@ -0,0 +1,31 @@
+module Bmg
+  class Summarizer
+    #
+    # Sum summarizer.
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.sum(:qty).summarize(...)
+    #
+    class Sum < Summarizer
+
+      # Returns 0 as least value.
+      def least()
+        0
+      end
+
+      # Keep memo+val as new value
+      def _happens(memo, val) 
+        memo + (val.nil? ? 0 : val)
+      end
+
+    end # class Sum
+
+    # Factors a sum summarizer
+    def self.sum(*args, &bl)
+      Sum.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg

data/lib/bmg/summarizer/variance.rb

@@ -0,0 +1,42 @@
+module Bmg
+  class Summarizer
+    #
+    # Variance summarizer
+    #
+    # Example:
+    #
+    #   # direct ruby usage
+    #   Bmg::Summarizer.variance(:qty).summarize(...)
+    #
+    class Variance < Summarizer
+
+      # Returns the least value.
+      def least()
+        [0, 0.0, 0.0]
+      end
+
+      # Aggregates on a tuple occurence.
+      def _happens(memo, val) 
+        count, mean, m2 = memo
+        count += 1
+        delta = val - mean
+        mean  += (delta / count)
+        m2    += delta*(val - mean)
+        [count, mean, m2]
+      end
+
+      # Finalizes the computation.
+      def finalize(memo) 
+        count, mean, m2 = memo
+        m2 / count
+      end
+
+    end # class Variance
+
+    # Factors a variance summarizer
+    def self.variance(*args, &bl)
+      Variance.new(*args, &bl)
+    end
+
+  end # class Summarizer
+end # module Bmg