daru 0.1.5 → 0.3

data/lib/daru/maths/statistics/dataframe.rb

@@ -22,7 +22,7 @@ module Daru
         #   Calculate the minimum value of each numeric vector
         # @!method product
         #   Compute the product of each numeric vector
-        [:mean, :variance_sample, :range, :median, :mode, :std, :sum, :count, :min, :product].each do |meth|
+        %i[mean variance_sample range median mode std sum count min product].each do |meth|
           define_method(meth) do
             compute_stats meth
           end
@@ -41,38 +41,38 @@ module Daru
         #   Calculate cumulative sum of each numeric Vector
         # @!method standardize
         #   Standardize each Vector
-        # @!method acf
+        # @!method acf(max_lags)
         #   Calculate Autocorrelation coefficient
-        #   @param [Integer] max_lags (nil) Number of initial lags
-        # @!method ema
+        #   @param max_lags [Integer] (nil) Number of initial lags
+        # @!method ema(n,wilder)
         #   Calculate exponential moving average.
-        #   @param [Integer] n (10) Loopback length.
-        #   @param [TrueClass, FalseClass, NilClass] wilder (false) If true,
+        #   @param n [Integer] (10) Loopback length.
+        #   @param wilder [TrueClass, FalseClass, NilClass] (false) If true,
         #     1/n value is  used for smoothing; if false, uses 2/(n+1) value.
-        # @!method rolling_mean
+        # @!method rolling_mean(n)
         #   Calculate moving averages
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_median
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_median(n)
         #   Calculate moving median
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_max
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_max(n)
         #   Calculate moving max
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_min
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_min(n)
         #   Calculate moving min
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_count
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_count(n)
         #   Calculate moving non-missing count
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_std
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_std(n)
         #   Calculate moving standard deviation
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        # @!method rolling_variance
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        # @!method rolling_variance(n)
         #   Calculate moving variance
-        #   @param [Integer] n (10) Loopback length. Default to 10.
-        [
-          :cumsum,:standardize,:acf,:ema,:rolling_mean,:rolling_median,:rolling_max,
-          :rolling_min,:rolling_count,:rolling_std,:rolling_variance, :rolling_sum
+        #   @param n [Integer] (10) Loopback length. Default to 10.
+        %i[
+          cumsum standardize acf ema rolling_mean rolling_median rolling_max
+          rolling_min rolling_count rolling_std rolling_variance rolling_sum
         ].each do |meth|
           define_method(meth) do |*args|
             apply_method_to_numerics meth, *args
@@ -88,7 +88,7 @@ module Daru
         # be applied to numeric vectors. Default is [:count, :mean, :std, :max,
         # :min]. Methods will be applied in the specified order.
         def describe methods=nil
-          methods ||= [:count, :mean, :std, :min, :max]
+          methods ||= %i[count mean std min max]
 
           description_hash = {}
           numeric_vectors.each do |vec|
@@ -133,17 +133,15 @@ module Daru
         # Calculate sample variance-covariance between the numeric vectors.
         def covariance
           cache = Hash.new do |h, (col, row)|
-            h[[col, row]] = vector_cov(self[row],self[col])
+            value = vector_cov(self[row],self[col])
+            h[[col, row]] = value
+            h[[row, col]] = value
           end
           vectors = numeric_vectors
 
           mat_rows = vectors.collect do |row|
             vectors.collect do |col|
-              if row == col
-                self[row].variance
-              else
-                cache[[col,row]]
-              end
+              row == col ? self[row].variance : cache[[col,row]]
             end
           end
 

data/lib/daru/maths/statistics/vector.rb

@@ -19,10 +19,6 @@ module Daru
           @data.product
         end
 
-        def min
-          @data.min
-        end
-
         def range
           max - min
         end
@@ -45,7 +41,7 @@ module Daru
         # be applied to vectors. Default is [:count, :mean, :std, :max,
         # :min]. Methods will be applied in the specified order.
         def describe methods=nil
-          methods ||= [:count, :mean, :std, :min, :max]
+          methods ||= %i[count mean std min max]
           description = methods.map { |m| send(m) }
           Daru::Vector.new(description, index: methods, name: :statistics)
         end
@@ -70,24 +66,280 @@ module Daru
           reject_values(*Daru::MISSING_VALUES).uniq.reset_index!
         end
 
-        # Maximum element of the vector.
-        #
-        # @param return_type [Symbol] Data type of the returned value. Defaults
-        #   to returning only the maximum number but passing *:vector* will return
-        #   a Daru::Vector with the index of the corresponding maximum value.
-        def max return_type=:stored_type
-          max_value = @data.max
-          if return_type == :vector
-            Daru::Vector.new({index_of(max_value) => max_value}, name: @name, dtype: @dtype)
-          else
-            max_value
+        if RUBY_VERSION >= '2.2'
+          # Returns the maximum value(s) present in the vector, with an optional comparator block.
+          #
+          # @param size [Integer] Number of maximum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.max
+          #   #=> "Tyrion"
+          #
+          #   dv.max(2) { |a,b| a.size <=> b.size }
+          #   #=> ["Jon Starkgaryen","Daenerys"]
+          def max(size=nil, &block)
+            reject_values(*Daru::MISSING_VALUES).to_a.max(size, &block)
+          end
+
+          # Returns the maximum value(s) present in the vector, with a compulsory object block.
+          #
+          # @param size [Integer] Number of maximum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.max_by(2) { |i| i.size }
+          #   #=> ["Jon Starkgaryen","Daenerys"]
+          def max_by(size=nil, &block)
+            raise ArgumentError, 'Expected compulsory object block in max_by method' unless block_given?
+            reject_values(*Daru::MISSING_VALUES).to_a.max_by(size, &block)
+          end
+
+          # Returns the minimum value(s) present in the vector, with an optional comparator block.
+          #
+          # @param size [Integer] Number of minimum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.min
+          #   #=> "Daenerys"
+          #
+          #   dv.min(2) { |a,b| a.size <=> b.size }
+          #   #=> ["Tyrion","Daenerys"]
+          def min(size=nil, &block)
+            reject_values(*Daru::MISSING_VALUES).to_a.min(size, &block)
+          end
+
+          # Returns the minimum value(s) present in the vector, with a compulsory object block.
+          #
+          # @param size [Integer] Number of minimum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.min_by(2) { |i| i.size }
+          #   #=> ["Tyrion","Daenerys"]
+          def min_by(size=nil, &block)
+            raise ArgumentError, 'Expected compulsory object block in min_by method' unless block_given?
+            reject_values(*Daru::MISSING_VALUES).to_a.min_by(size, &block)
+          end
+        else
+          # Returns the maximum value(s) present in the vector, with an optional comparator block.
+          #
+          # @param size [Integer] Number of maximum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.max
+          #   #=> "Tyrion"
+          #
+          #   dv.max(2) { |a,b| a.size <=> b.size }
+          #   #=> ["Jon Starkgaryen","Daenerys"]
+          def max(size=nil, &block)
+            range = size.nil? ? 0 : (0..size-1)
+            reject_values(*Daru::MISSING_VALUES).to_a.sort(&block).reverse[range]
+          end
+
+          # Returns the maximum value(s) present in the vector, with a compulsory object block.
+          #
+          # @param size [Integer] Number of maximum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.max_by(2) { |i| i.size }
+          #   #=> ["Jon Starkgaryen","Daenerys"]
+          def max_by(size=nil, &block)
+            raise ArgumentError, 'Expected compulsory object block in max_by method' unless block_given?
+            reject_values(*Daru::MISSING_VALUES).to_a.sort_by(&block).reverse[size.nil? ? 0 : (0..size-1)]
           end
+
+          # Returns the minimum value(s) present in the vector, with an optional comparator block.
+          #
+          # @param size [Integer] Number of minimum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.min
+          #   #=> "Daenerys"
+          #
+          #   dv.min(2) { |a,b| a.size <=> b.size }
+          #   #=> ["Tyrion","Daenerys"]
+          def min(size=nil, &block)
+            range = size.nil? ? 0 : (0..size-1)
+            reject_values(*Daru::MISSING_VALUES).to_a.sort(&block)[range]
+          end
+
+          # Returns the minimum value(s) present in the vector, with a compulsory object block.
+          #
+          # @param size [Integer] Number of minimum values to return. Defaults to nil.
+          #
+          # @example
+          #
+          #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+          #   #=>
+          #   #   #<Daru::Vector(3)>
+          #   #       t   Tyrion
+          #   #       d   Daenerys
+          #   #       j   Jon Starkgaryen
+          #
+          #   dv.min_by
+          #   #=> "Daenerys"
+          #
+          #   dv.min_by(2) { |i| i.size }
+          #   #=> ["Tyrion","Daenerys"]
+          def min_by(size=nil, &block)
+            raise ArgumentError, 'Expected compulsory object block in min_by method' unless block_given?
+            reject_values(*Daru::MISSING_VALUES).to_a.sort_by(&block)[size.nil? ? 0 : (0..size-1)]
+          end
+        end
+
+        # Returns the index of the maximum value(s) present in the vector, with an optional
+        # comparator block.
+        #
+        # @param size [Integer] Number of maximum indices to return. Defaults to nil.
+        #
+        # @example
+        #
+        #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+        #   #=>
+        #   #   #<Daru::Vector(3)>
+        #   #       t   Tyrion
+        #   #       d   Daenerys
+        #   #       j   Jon Starkgaryen
+        #
+        #   dv.index_of_max
+        #   #=> :t
+        #
+        #   dv.index_of_max(2) { |a,b| a.size <=> b.size }
+        #   #=> [:j, :d]
+        def index_of_max(size=nil,&block)
+          vals = max(size, &block)
+          dv   = reject_values(*Daru::MISSING_VALUES)
+          vals.is_a?(Array) ? (vals.map { |x| dv.index_of(x) }) : dv.index_of(vals)
+        end
+
+        # Returns the index of the maximum value(s) present in the vector, with a compulsory
+        # object block.
+        #
+        # @param size [Integer] Number of maximum indices to return. Defaults to nil.
+        #
+        # @example
+        #
+        #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+        #   #=>
+        #   #   #<Daru::Vector(3)>
+        #   #       t   Tyrion
+        #   #       d   Daenerys
+        #   #       j   Jon Starkgaryen
+        #
+        #   dv.index_of_max_by(2) { |i| i.size }
+        #   #=> [:j, :d]
+        def index_of_max_by(size=nil,&block)
+          vals = max_by(size, &block)
+          dv   = reject_values(*Daru::MISSING_VALUES)
+          vals.is_a?(Array) ? (vals.map { |x| dv.index_of(x) }) : dv.index_of(vals)
+        end
+
+        # Returns the index of the minimum value(s) present in the vector, with an optional
+        # comparator block.
+        #
+        # @param size [Integer] Number of minimum indices to return. Defaults to nil.
+        #
+        # @example
+        #
+        #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+        #   #=>
+        #   #   #<Daru::Vector(3)>
+        #   #       t   Tyrion
+        #   #       d   Daenerys
+        #   #       j   Jon Starkgaryen
+        #
+        #   dv.index_of_min
+        #   #=> :d
+        #
+        #   dv.index_of_min(2) { |a,b| a.size <=> b.size }
+        #   #=> [:t, :d]
+        def index_of_min(size=nil,&block)
+          vals = min(size, &block)
+          dv   = reject_values(*Daru::MISSING_VALUES)
+          vals.is_a?(Array) ? (vals.map { |x| dv.index_of(x) }) : dv.index_of(vals)
+        end
+
+        # Returns the index of the minimum value(s) present in the vector, with a compulsory
+        # object block.
+        #
+        # @param size [Integer] Number of minimum indices to return. Defaults to nil.
+        #
+        # @example
+        #
+        #   dv = Daru::Vector.new (["Tyrion", "Daenerys", "Jon Starkgaryen"]), index: Daru::Index.new([:t, :d, :j])
+        #   #=>
+        #   #   #<Daru::Vector(3)>
+        #   #       t   Tyrion
+        #   #       d   Daenerys
+        #   #       j   Jon Starkgaryen
+        #
+        #   dv.index_of_min(2) { |i| i.size }
+        #   #=> [:t, :d]
+        def index_of_min_by(size=nil,&block)
+          vals = min_by(size, &block)
+          dv   = reject_values(*Daru::MISSING_VALUES)
+          vals.is_a?(Array) ? (vals.map { |x| dv.index_of(x) }) : dv.index_of(vals)
         end
 
-        # Return a Vector with the max element and its index.
+        # Return the maximum element present in the Vector, as a Vector.
         # @return [Daru::Vector]
         def max_index
-          max :vector
+          max_value = @data.max
+          Daru::Vector.new({index_of(max_value) => max_value}, name: @name, dtype: @dtype)
         end
 
         def frequencies
@@ -104,7 +356,7 @@ module Daru
         def proportions
           len = size - count_values(*Daru::MISSING_VALUES)
           frequencies.to_h.each_with_object({}) do |(el, count), hash|
-            hash[el] = count / len
+            hash[el] = count / len.to_f
           end
         end
 
@@ -448,29 +700,29 @@ module Daru
 
         # @!method rolling_mean
         #   Calculate rolling average
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_median
         #   Calculate rolling median
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_count
         #   Calculate rolling non-missing count
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_max
         #   Calculate rolling max value
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_min
         #   Calculate rolling min value
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_sum
         #   Calculate rolling sum
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_std
         #   Calculate rolling standard deviation
-        #   @param [Integer] n (10) Loopback length
+        #   @yieldparam [Integer] n (10) Loopback length
         # @!method rolling_variance
         #   Calculate rolling variance
-        #   @param [Integer] n (10) Loopback length
-        [:count, :mean, :median, :max, :min, :sum, :std, :variance].each do |meth|
+        #   @yieldparam [Integer] n (10) Loopback length
+        %i[count mean median max min sum std variance].each do |meth|
           define_method("rolling_#{meth}".to_sym) do |n=10|
             rolling(meth, n)
           end
@@ -581,26 +833,28 @@ module Daru
 
         # Moving Average Convergence-Divergence.
         # Calculates the MACD (moving average convergence-divergence) of the time
-        # series - this is a comparison of a fast EMA with a slow EMA.
+        # series.
+        # @see https://en.wikipedia.org/wiki/MACD
         #
-        # == Arguments
-        # * *fast*: integer, (default = 12) - fast component of MACD
-        # * *slow*: integer, (default = 26) - slow component of MACD
-        # * *signal*: integer, (default = 9) - signal component of MACD
-        #
-        # == Usage
+        # @param fast [Integer] fast period of MACD (default 12)
+        # @param slow [Integer] slow period of MACD (default 26)
+        # @param signal [Integer] signal period of MACD (default 9)
         #
+        # @example Create a series and calculate MACD values
         #   ts = Daru::Vector.new((1..100).map { rand })
         #            # => [0.69, 0.23, 0.44, 0.71, ...]
-        #   ts.macd(13)
+        #   macdseries, macdsignal, macdhist = ts.macd
+        #   macdseries, macdsignal, macdhist = ts.macd(13)
+        #   macdseries, macdsignal, macdhist = ts.macd(signal=5)
         #
-        # == Returns
+        # @return [Array<Daru::Vector>] macdseries, macdsignal and macdhist are
+        #   returned as an array of three Daru::Vectors
         #
-        # Array of two Daru::Vectors - comparison of fast EMA with slow and EMA with
-        # signal value
         def macd(fast=12, slow=26, signal=9)
-          series = ema(fast) - ema(slow)
-          [series, series.ema(signal)]
+          macdseries = ema(fast) - ema(slow)
+          macdsignal = macdseries.ema(signal)
+          macdhist = macdseries - macdsignal
+          [macdseries, macdsignal, macdhist]
         end
 
         # Calculates the autocorrelation coefficients of the series.