red_amber 0.3.0 → 0.4.0

data/lib/red_amber/vector_aggregation.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+# Available functions in Arrow are shown by `Arrow::Function.all.map(&:name)`
+# reference: https://arrow.apache.org/docs/cpp/compute.html
+
+module RedAmber
+  # Representing a series of data.
+  class Vector
+    class << self
+      private
+
+      # @!macro [attach] define_unary_aggregation
+      #   [Unary aggregation function] Returns a scalar.
+      #
+      def define_unary_aggregation(function)
+        define_method(function) do |**options|
+          datum = exec_func_unary(function, options)
+          get_scalar(datum)
+        end
+      end
+    end
+
+    # Not implemented in red-arrow yet:
+    # Arrow::Indexoptions, Arrow::ModeOptions, Arrow::TDigestOptions
+
+    # @!macro scalar_aggregate_options
+    #   @param skip_nulls [true, false]
+    #     If true, nil values are ignored.
+    #     Otherwise, if any value is nil, emit nil.
+    #   @param min_count [Integer]
+    #     if less than this many non-nil values are observed, emit nil.
+    #     If skip_nulls is false, this option is not respected.
+
+    # @!macro count_options
+    #   @param mode [:only_valid, :only_null, :all]
+    #     control count aggregate kernel behavior.
+    #     - only_valid: count only non-nil values.
+    #     - only_null: count only nil.
+    #     - all: count both.
+
+    # @!macro variance_options
+    #   @param ddof [0, 1]
+    #     Control Delta Degrees of Freedom (ddof) of Variance and Stddev kernel.
+    #     The divisor used in calculations is N - ddof, where N is the number
+    #     of elements. By default, ddof is zero, and population variance or stddev
+    #     is returned.
+    #   @macro scalar_aggregate_options
+
+    # Test whether all elements in self are evaluated to true.
+    #
+    # @!method all(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [true, false]
+    #   `all` result of self.
+    # @example Default.
+    #   Vector.new(true, true, nil).all # => true
+    #
+    # @example Skip nils.
+    #   Vector.new(true, true, nil).all(skip_nulls: false) # => false
+    #
+    define_unary_aggregation :all
+    alias_method :all?, :all
+
+    # Test whether any elements in self are evaluated to true.
+    #
+    # @!method any(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [true, false]
+    #   `any` result of self.
+    # @example Default.
+    #   Vector.new(true, false, nil).any # => true
+    #
+    define_unary_aggregation :any
+    alias_method :any?, :any
+
+    # Approximate median of a numeric Vector with T-Digest algorithm.
+    #
+    # @!method approximate_median(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Float]
+    #   median of self.
+    #   A nil is returned if there is no valid data point.
+    #
+    define_unary_aggregation :approximate_median
+    alias_method :median, :approximate_median
+
+    # Count the number of nil / non-nil values.
+    #
+    # @!method count(mode: :non_null)
+    # @macro count_options
+    # @return [Integer] count of self.
+    # @example Count only non-nil (default)
+    #   Vector.new(1.0, -2.0, Float::NAN, nil).count # => 3
+    #
+    # @example Count nil only.
+    #   Vector.new(1.0, -2.0, Float::NAN, nil).count(mode: :only_null) # => 1
+    #
+    # @example Count both non-nil and nil.
+    #   Vector.new(1.0, -2.0, Float::NAN, nil).count(mode: :all) # => 4
+    #
+    define_unary_aggregation :count
+
+    # Count the number of unique values.
+    #
+    # @!method count_distinct(mode: :only_valid)
+    # @macro count_options
+    # @return [Integer]
+    #   unique count of self.
+    # @example
+    #   vector = Vector.new(1, 1.0, nil, nil, Float::NAN, Float::NAN)
+    #   vector
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=6):0x000000000000d390>
+    #   [1.0, 1.0, nil, nil, NaN, NaN]
+    #
+    #   # Float::NANs are counted as 1.
+    #   vector.count_uniq # => 2
+    #
+    #   # nils are counted as 1.
+    #   vector.count_uniq(mode: :only_null) # => 1
+    #
+    #   vector.count_uniq(mode: :all) # => 3
+    #
+    define_unary_aggregation :count_distinct
+    alias_method :count_uniq, :count_distinct
+
+    # Compute maximum value of self.
+    #
+    # @!method max(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Numeric]
+    #   maximum value of self.
+    #
+    define_unary_aggregation :max
+
+    # Compute mean value of self.
+    #
+    # @!method mean(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Numeric]
+    #   mean of self.
+    #
+    define_unary_aggregation :mean
+
+    # Compute minimum value of self.
+    #
+    # @!method min(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Numeric]
+    #   minimum of self.
+    #
+    define_unary_aggregation :min
+
+    # Compute the min and max value of self.
+    #
+    # @!method min_max(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Array<min, max>]
+    #   min and max of self in an Array.
+    #
+    define_unary_aggregation :min_max
+
+    # Compute product value of self.
+    #
+    # @note Self must be a numeric Vector.
+    # @!method product(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Numeric]
+    #   product of self.
+    #
+    define_unary_aggregation :product
+
+    # Calculate standard deviation of self.
+    #
+    # @note Self must be a numeric Vector.
+    # @!method stddev(ddof: 0, skip_nulls: true, min_count: 1)
+    # @macro variance_options
+    # @return [Float]
+    #   standard deviation of self. Biased (ddof=0) by default.
+    #
+    define_unary_aggregation :stddev
+
+    # Calculate unbiased standard deviation of self.
+    #
+    # @note Self must be a numeric Vector.
+    # @!method sd(ddof: 1, skip_nulls: true, min_count: 1)
+    # @macro variance_options
+    # @return [Float]
+    #   standard deviation of self. Unviased (ddof=1)by default.
+    #
+    def sd
+      stddev(ddof: 1)
+    end
+    alias_method :std, :sd
+
+    # Compute sum of self.
+    #
+    # @note Self must be a numeric Vector.
+    # @!method sum(skip_nulls: true, min_count: 1)
+    # @macro scalar_aggregate_options
+    # @return [Numeric]
+    #   sum of self.
+    #
+    define_unary_aggregation :sum
+
+    # Calculate variance of self.
+    #
+    # @note Self must be a numeric Vector.
+    # @!method variance(ddof: 0, skip_nulls: true, min_count: 1)
+    # @macro variance_options
+    #
+    # @return [Float]
+    #   unviased (ddof=1) standard deviation of self by default.
+    #
+    # @return [Float]
+    #   variance of self. Biased (ddof=0) by default.
+    #
+    define_unary_aggregation :variance
+
+    # Calculate unbiased variance of self.
+    #
+    # @note self must be a numeric Vector.
+    # @!method unbiased_variance(ddof: 1, skip_nulls: true, min_count: 1)
+    # @macro variance_options
+    # @return [Float]
+    #   variance of self. Unviased (ddof=1) by default.
+    #
+    def unbiased_variance
+      variance(ddof: 1)
+    end
+    alias_method :var, :unbiased_variance
+
+    # @!macro quantile_interpolation
+    #   @param interpolation [Symbol]
+    #     specifies interpolation method to use,
+    #     when the quantile lies between the data i and j.
+    #     - Default value is :linear, which returns i + (j - i) * fraction.
+    #     - lower: returns i.
+    #     - higher: returns j.
+    #     - nearest: returns i or j, whichever is closer.
+    #     - midpoint: returns (i + j) / 2.
+
+    # Returns a quantile value.
+    # - 0.5 quantile (median) is returned by default.
+    # - Or return quantile for specified probability (prob).
+    # - If quantile lies between two data points, interpolated value is
+    #   returned based on selected interpolation method.
+    # - Nils and NaNs are ignored.
+    # - Nil is returned if there are no valid data point.
+    #
+    # @param prob [Float]
+    #   probability.
+    # @macro quantile_interpolation
+    # @macro scalar_aggregate_options
+    # @return [Float]
+    #   quantile of self.
+    # @example
+    #   penguins[:bill_depth_mm].quantile
+    #
+    #   # =>
+    #   17.3 # defaultis prob = 0.5
+    #
+    def quantile(prob = 0.5, interpolation: :linear, skip_nulls: true, min_count: 0)
+      unless (0..1).cover? prob
+        raise VectorArgumentError,
+              "Invalid: probability #{prob} must be between 0 and 1"
+      end
+
+      datum = find(:quantile).execute([data],
+                                      q: prob,
+                                      interpolation: interpolation,
+                                      skip_nulls: skip_nulls,
+                                      min_count: min_count)
+      datum.value.to_a.first
+    end
+
+    # Return quantiles in a DataFrame
+    #
+    # @param probs [Array]
+    #   Array of probabilities. Default probabilities are 0.0, 0.25, 0.5 0.75, 1.0 .
+    # @macro quantile_interpolation
+    # @macro scalar_aggregate_options
+    # @return [DataFrame]
+    #   quantiles of self.
+    # @example
+    #   penguins[:bill_depth_mm].quantiles([0.05, 0.95])
+    #
+    #   # =>
+    #   #<RedAmber::DataFrame : 2 x 2 Vectors, 0x000000000000fb2c>
+    #        probs quantiles
+    #     <double>  <double>
+    #   0     0.05      13.9
+    #   1     0.95      20.0
+    #
+    def quantiles(probs = [0.0, 0.25, 0.5, 0.75, 1.0],
+                  interpolation: :linear, skip_nulls: true, min_count: 0)
+      if probs.empty? || !probs.all? { |q| (0..1).cover?(q) }
+        raise VectorArgumentError, "Invarid probavilities #{probs}"
+      end
+
+      DataFrame.new(
+        probs: probs,
+        quantiles: probs.map do |q|
+          quantile(q,
+                   interpolation: interpolation, skip_nulls: skip_nulls,
+                   min_count: min_count)
+        end
+      )
+    end
+  end
+end

data/lib/red_amber/vector_binary_element_wise.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+# Available functions in Arrow are shown by `Arrow::Function.all.map(&:name)`
+# reference: https://arrow.apache.org/docs/cpp/compute.html
+
+module RedAmber
+  # Representing a series of data.
+  class Vector
+    class << self
+      # Compute the inverse tangent of y/x.
+      #
+      # [Binary element-wise function] Returns a Vector.
+      # The return value is in the range [-pi, pi].
+      # @param y [Vector, array-like]
+      #   numeric array-like.
+      # @param x [Vector, array-like]
+      #   numeric array-like.
+      # @return [Vector]
+      #   inverse tangent of y/x.
+      #
+      def atan2(y, x) # rubocop:disable Naming/MethodParameterName
+        y = y.data if y.is_a? Vector
+        x = x.data if x.is_a? Vector
+
+        datum = Arrow::Function.find(:atan2).execute([y, x])
+        Vector.create(datum.value)
+      end
+
+      private
+
+      # @!macro [attach] define_binary_element_wise
+      #   [Binary element-wise function] Returns a Vector.
+      #
+      def define_binary_element_wise(function)
+        define_method(function) do |other, **options|
+          datum = exec_func_binary(function, other, options)
+          Vector.create(datum.value)
+        end
+      end
+
+      # @!macro [attach] define_binary_element_wise_logical
+      #   [Binary element-wise function] Returns a Vector.
+      #
+      def define_binary_element_wise_logical(method, function)
+        define_method(method) do |other, **options|
+          datum = exec_func_binary(function, other, options)
+          Vector.create(datum.value)
+        end
+      end
+    end
+
+    # @!macro kleene_logic_and
+    #   This function behaves as follows with nils:
+    #   - true and nil = nil
+    #   - nil and true = nil
+    #   - false and nil = false
+    #   - nil and false = false
+    #   - nil and nil = nil
+    #   In other words, in this context a nil value really means "unknown",
+    #   and an unknown value 'and' false is always false.
+
+    # @!macro kleene_logic_and_not
+    #   This function behaves as follows with nils:
+    #   - true and not nil = nil
+    #   - nil and not false = nil
+    #   - false and not nil = false
+    #   - nil and not true = false
+    #   - nil and not nil = nil
+    #   In other words, in this context a nil value really means "unknown",
+    #   and an unknown value 'and not' true is always false,
+    #   as is false 'and not' an unknown value.
+
+    # @!macro kleene_logic_or
+    #   This function behaves as follows with nils:
+    #   - true or nil = true
+    #   - nil or true = true
+    #   - false or nil = nil
+    #   - nil or false = nil
+    #   - nil or nil = nil
+    #   In other words, in this context a nil value really means "unknown",
+    #   and an unknown value 'or' true is always true.
+
+    # rubocop:disable Lint/SymbolConversion)
+
+    # Logical 'and' boolean values with Kleene logic.
+    #
+    # @macro kleene_logic_and
+    # For a different nil behavior, see function {#and_org}.
+    # @!method and_kleene(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   and_kleene of self and other.
+    define_binary_element_wise :and_kleene
+    alias_method :'&', :and_kleene
+
+    # Logical 'and not' boolean values.
+    #
+    # When a nil is encountered in either input, a nil is output.
+    # For a different nil behavior, see function {#and_not_kleene}.
+    # @!method and_not(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   and not of self and other.
+    #
+    define_binary_element_wise :and_not
+
+    # Logical 'and not' boolean values with Kleene logic.
+    #
+    # @macro kleene_logic_and_not
+    # For a different nil behavior, see function {#and_not}.
+    # @!method and_not_kleene(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   and not kleene of self and other.
+    #
+    define_binary_element_wise :and_not_kleene
+
+    # Logical 'and' boolean values.
+    #
+    # When a nil is encountered in either input, a nil is output.
+    # For a different nil behavior, see function {#and_kleene}.
+    # @!method and_org(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   evacuated `and` of self and other.
+    #
+    define_binary_element_wise_logical(:and_org, :and)
+
+    # Bit-wise AND of self and other by element-wise.
+    #
+    # Nil values return nil.
+    # @!method bit_wise_and(other)
+    # @param other [Vector, array-like]
+    #   integer array-like.
+    # @return [Vector]
+    #   bit wise and of self and other.
+    #
+    define_binary_element_wise :bit_wise_and
+
+    # Bit-wise OR of self and other by element-wise.
+    #
+    # Nil values return nil.
+    # @!method bit_wise_or(other)
+    # @param other [Vector, array-like]
+    #   integer array-like.
+    # @return [Vector]
+    #   bit wise or of self and other.
+    #
+    define_binary_element_wise :bit_wise_or
+
+    # Bit-wise XOR of self and other by element-wise.
+    #
+    # Nil values return nil.
+    # @!method bit_wise_xor(other)
+    # @param other [Vector, array-like]
+    #   integer array-like.
+    # @return [Vector]
+    #   bit wise xor of self and other.
+    #
+    define_binary_element_wise :bit_wise_xor
+
+    # Compute base `b` logarithm of self.
+    #
+    # Non positive values return -inf or NaN. Nil values return nil.
+    # @!method logb(b)
+    # @param b [Integer]
+    #   base.
+    # @return [Vector]
+    #   logb of self and other.
+    #
+    define_binary_element_wise :logb
+
+    # Logical 'or' boolean values with Kleene logic.
+    #
+    # @macro kleene_logic_or
+    # For a different nil behavior, see function {#or_org}.
+    # @!method or_kleene(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   or_kleene of self and other.
+    #
+    define_binary_element_wise :or_kleene
+    alias_method :'|', :or_kleene
+
+    # Logical 'or' boolean values.
+    #
+    # When a nil is encountered in either input, a nil is output.
+    # For a different nil behavior, see function {#or_kleene}.
+    # @!method or_org(other)
+    # @param other [Vector, array-like]
+    #   boolean array-like.
+    # @return [Vector]
+    #   evacuated `or` of self and other.
+    #
+    define_binary_element_wise_logical(:or_org, :or)
+
+    # Add the arguments element-wise.
+    #
+    # Results will wrap around on integer overflow.
+    # @!method add(other)
+    # @param other [Vector, Numeric]
+    #   other numeric Vector or numeric scalar.
+    # @return [Vector]
+    #   adddition of self and other.
+    #
+    define_binary_element_wise :add
+    alias_method :'+', :add
+
+    # Divide the arguments element-wise.
+    #
+    # Integer division by zero returns an error. However, integer overflow
+    # wraps around, and floating-point division by zero returns an infinite.
+    # @!method divide(divisor)
+    # @param divisor [Vector, Numeric]
+    #   numeric vector or numeric scalar as divisor.
+    # @return [Vector]
+    #   division of self and other.
+    #
+    define_binary_element_wise :divide
+    alias_method :'/', :divide
+
+    # Multiply the arguments element-wise.
+    #
+    # Results will wrap around on integer overflow.
+    # @!method multiply(other)
+    # @param other [Vector, Numeric]
+    #   other numeric vector or numeric scalar.
+    # @return [Vector]
+    #   multiplication of self and other.
+    #
+    define_binary_element_wise :multiply
+    alias_method :'*', :multiply
+
+    # Raise arguments to power element-wise.
+    #
+    # Integer to negative integer power returns an error.
+    # However, integer overflow wraps around.
+    # If either self or exponent is nil the result will be nil.
+    # @!method power(exponent)
+    # @param exponent [Vector, Numeric]
+    #   numeric vector or numeric scalar as exponent.
+    # @return [Vector]
+    #   power operation of self and other.
+    #
+    define_binary_element_wise :power
+    alias_method :'**', :power
+
+    # Subtract the arguments element-wise.
+    #
+    # Results will wrap around on integer overflow.
+    # @!method subtract(other)
+    # @param other [Vector, Numeric]
+    #   other numeric vector or numeric scalar.
+    # @return [Vector]
+    #   subtraction of self and other.
+    #
+    define_binary_element_wise :subtract
+    alias_method :'-', :subtract
+
+    # Left shift of self by other.
+    #
+    # The shift operates as if on the two's complement representation of the number.
+    # In other words, this is equivalent to multiplying self by 2 to the power 'amount',
+    # even if overflow occurs.
+    # self is returned if 'amount' (the amount to shift by) is negative or
+    # greater than or equal to the precision of self.
+    # @!method shift_left(amount)
+    # @param amount [integer]
+    #   the amount to shift by.
+    # @return [Vector]
+    #  shift_left of self by amount.
+    #
+    define_binary_element_wise :shift_left
+    alias_method :'<<', :shift_left
+
+    # Right shift of self by other.
+    #
+    # This is equivalent to dividing `x` by 2 to the power `y`.
+    # Self is returned if 'amount' (the amount to shift by) is: negative or
+    # greater than or equal to the precision of self.
+    # @!method shift_right(amount)
+    # @param amount [integer]
+    #   the amount to shift by.
+    # @return [Vector]
+    #   shift_right of self by amount.
+    #
+    define_binary_element_wise :shift_right
+    alias_method :'>>', :shift_right
+
+    # Logical 'xor' boolean values
+    #
+    # When a nil is encountered in either input, a nil is output.
+    # @!method xor(other)
+    # @param other [Vector]
+    #   other boolean vector or boolean scalar.
+    # @return [Vector]
+    #   eq of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :xor
+    alias_method :'^', :xor
+
+    # Compare values for equality (self == other)
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method equal(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   eq of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :equal
+    alias_method :'==', :equal
+    alias_method :eq, :equal
+
+    # Compare values for ordered inequality (self > other).
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method greater(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   gt of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :greater
+    alias_method :'>', :greater
+    alias_method :gt, :greater
+
+    # Compare values for ordered inequality (self >= other).
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method greater_equal(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   ge of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :greater_equal
+    alias_method :'>=', :greater_equal
+    alias_method :ge, :greater_equal
+
+    # Compare values for ordered inequality (self < other).
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method less(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   lt of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :less
+    alias_method :'<', :less
+    alias_method :lt, :less
+
+    # Compare values for ordered inequality (self <= other).
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method less_equal(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   le of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :less_equal
+    alias_method :'<=', :less_equal
+    alias_method :le, :less_equal
+
+    # Compare values for inequality (self != other).
+    #
+    # A nil on either side emits a nil comparison result.
+    # @!method not_equal(other)
+    # @param other [Vector]
+    #   other vector or scalar.
+    # @return [Vector]
+    #   ne of self and other by a boolean Vector.
+    #
+    define_binary_element_wise :not_equal
+    alias_method :'!=', :not_equal
+    alias_method :ne, :not_equal
+
+    # rubocop:enable Lint/SymbolConversion)
+  end
+end