red_amber 0.3.0 → 0.4.0

data/lib/red_amber/vector_selectable.rb

@@ -4,7 +4,7 @@
 # reference: https://arrow.apache.org/docs/cpp/compute.html
 
 module RedAmber
-  # mix-in for class Vector
+  # Mix-in for class Vector
   #   Functions to select some data.
   module VectorSelectable
     using RefineArray
@@ -12,11 +12,14 @@ module RedAmber
 
     # Select elements in the self by indices.
     #
-    # @param indices [Array<Numeric>, Vector] indices.
-    # @yield [Array<Numeric>, Vector] indices.
-    # @return [Vector] Vector by selected elements.
+    # @param indices [Array<Numeric>, Vector]
+    #   an array-like of indices.
+    # @yieldreturn [Array<Numeric>, Vector]
+    #   an array-like of indices from the block.
+    # @return [Vector]
+    #   vector by selected elements.
     #
-    #   TODO: support for the option `boundscheck: true`
+    # TODO: support for the option `boundscheck: true`
     def take(*indices, &block)
       if block
         unless indices.empty?
@@ -47,11 +50,14 @@ module RedAmber
 
     # Select elements in the self by booleans.
     #
-    # @param booleans [Array<true, false, nil>, Vector] booleans.
-    # @yield [Array<true, false, nil>, Vector] booleans.
-    # @return [Vector] Vector by selected elements.
+    # @param booleans [Array<true, false, nil>, Vector]
+    #   an array-like of booleans.
+    # @yieldreturn [Array<true, false, nil>, Vector]
+    #   an array-like of booleans from the block.
+    # @return [Vector]
+    #   vector by selected elements.
     #
-    #   TODO: support for the option `null_selection_behavior: :drop`
+    # TODO: support for the option `null_selection_behavior: :drop`
     def filter(*booleans, &block)
       if block
         unless booleans.empty?
@@ -87,9 +93,12 @@ module RedAmber
 
     # Select elements in the self by indices or booleans.
     #
-    # @param args [Array<Numeric, true, false, nil>, Vector] specifier.
-    # @yield [Array<Numeric, true, false, nil>, Vector] specifier.
-    # @return [scalar, Array] returns scalar or array.
+    # @param args [Array<Numeric, true, false, nil>, Vector]
+    #   specifier. Indices or booleans.
+    # @yieldparam [Array<Numeric, true, false, nil>, Vector]
+    #   specifier. Indices or booleans.
+    # @return [scalar, Array]
+    #   returns scalar or array.
     #
     def [](*args)
       array =
@@ -139,11 +148,207 @@ module RedAmber
       to_a.index(element)
     end
 
+    # Drop nil in self and returns a new Vector as a result.
+    #
+    # @return [Vector]
+    #   a Vector without nils.
+    #
     def drop_nil
       datum = find(:drop_null).execute([data])
       Vector.create(datum.value)
     end
 
+    # Arrange values in Vector.
+    #
+    # @param order [Symbol]
+    #   sort order.
+    #   - `:+`, `:ascending` or without argument will sort in increasing order.
+    #   - `:-` or `:descending` will sort in decreasing order.
+    # @return [Vector]
+    #   sorted Vector.
+    # @example Sort in increasing order (default)
+    #   Vector.new(%w[B D A E C]).sort
+    #   # same as #sort(:+)
+    #   # same as #sort(:ascending)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:string, size=5):0x000000000000c134>
+    #   ["A", "B", "C", "D", "E"]
+    #
+    # @example Sort in decreasing order
+    #   Vector.new(%w[B D A E C]).sort(:-)
+    #   # same as #sort(:descending)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:string, size=5):0x000000000000c148>
+    #   ["E", "D", "C", "B", "A"]
+    #
+    # @since 0.4.0
+    #
+    def sort(order = :ascending)
+      order =
+        case order.to_sym
+        when :+, :ascending, :increasing
+          :ascending
+        when :-, :descending, :decreasing
+          :descending
+        else
+          raise VectorArgumentError, "illegal order option: #{order}"
+        end
+      take(sort_indices(order: order))
+    end
+
+    # Returns numerical rank of self.
+    # - Nil values are considered greater than any value.
+    # - NaN values are considered greater than any value but smaller than nil values.
+    # - Tiebreakers are ranked in order of appearance.
+    # - `RankOptions` in C++ function is not implemented in C GLib yet.
+    #   This method is currently fixed to the default behavior.
+    #
+    # @return [Vector]
+    #   0-based rank of self (0...size in range).
+    # @example Rank of float Vector
+    #   fv = Vector.new(0.1, nil, Float::NAN, 0.2, 0.1); fv
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000c65c>
+    #   [0.1, nil, NaN, 0.2, 0.1]
+    #
+    #   fv.rank
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:uint64, size=5):0x0000000000003868>
+    #   [0, 4, 3, 2, 1]
+    #
+    # @example Rank of string Vector
+    #   sv = Vector.new("A", "B", nil, "A", "C"); sv
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:string, size=5):0x0000000000003854>
+    #   ["A", "B", nil, "A", "C"]
+    #
+    #   sv.rank
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:uint64, size=5):0x0000000000003868>
+    #   [0, 2, 4, 1, 3]
+    #
+    # @since 0.4.0
+    #
+    def rank
+      datum = Arrow::Function.find(:rank).execute([data])
+      Vector.create(datum.value) - 1
+    end
+
+    # Pick up elements at random.
+    #
+    # @overload sample()
+    #   Return a randomly selected element.
+    #   This is one of an aggregation function.
+    #
+    #   @return [scalar]
+    #     one of an element in self.
+    #   @example Sample a element
+    #     v = Vector.new('A'..'H'); v
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=8):0x0000000000011b20>
+    #     ["A", "B", "C", "D", "E", "F", "G", "H"]
+    #
+    #     v.sample
+    #
+    #     # =>
+    #     "C"
+    #
+    # @overload sample(n)
+    #   Pick up n elements at random.
+    #
+    #   @param n [Integer]
+    #     positive number of elements to pick.
+    #     If n is smaller or equal to size, elements are picked by non-repeating.
+    #     If n is greater than `size`, elements are picked repeatedly.
+    #   @return [Vector]
+    #     sampled elements.
+    #     If n == 1 (in case of `sample(1)`), it returns a Vector of size == 1
+    #     not a scalar.
+    #   @example Sample Vector in size 1
+    #     v.sample(1)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=1):0x000000000001a3b0>
+    #     ["H"]
+    #
+    #   @example Sample same size of self: every element is picked in random order
+    #     v.sample(8)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=8):0x000000000001bda0>
+    #     ["H", "D", "B", "F", "E", "A", "G", "C"]
+    #
+    #   @example Over sampling: "E" and "A" are sampled repeatedly
+    #     v.sample(9)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=9):0x000000000001d790>
+    #     ["E", "E", "A", "D", "H", "C", "A", "F", "H"]
+    #
+    # @overload sample(prop)
+    #   Pick up elements by proportion `prop` at random.
+    #
+    #   @param prop [Float]
+    #     positive proportion of elements to pick.
+    #     Absolute number of elements to pick:`prop*size` is rounded (by `half: :up``).
+    #     If prop is smaller or equal to 1.0, elements are picked by non-repeating.
+    #     If prop is greater than 1.0, some elements are picked repeatedly.
+    #   @return [Vector]
+    #     sampled elements.
+    #     If picked element is only one, it returns a Vector of size == 1
+    #     not a scalar.
+    #   @example Sample same size of self: every element is picked in random order
+    #     v.sample(1.0)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=8):0x000000000001bda0>
+    #     ["D", "H", "F", "C", "A", "B", "E", "G"]
+    #
+    #   @example 2 times over sampling
+    #     v.sample(2.0)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=16):0x00000000000233e8>
+    #     ["H", "B", "C", "B", "C", "A", "F", "A", "E", "C", "H", "F", "F", "A", ... ]
+    #
+    # @since 0.4.0
+    #
+    def sample(n_or_prop = nil)
+      require 'arrow-numo-narray'
+
+      return nil if size == 0
+
+      n_sample =
+        case n_or_prop
+        in Integer
+          n_or_prop
+        in Float
+          (n_or_prop * size).round
+        in nil
+          return to_a.sample
+        else
+          raise VectorArgumentError, "must specify Integer or Float but #{n_or_prop}"
+        end
+      if n_or_prop < 0
+        raise VectorArgumentError, '#sample does not accept negative number.'
+      end
+      return Vector.new([]) if n_sample == 0
+
+      over_sample = [8 * size, n_sample].max
+      over_size = n_sample > size ? n_sample / size * size * 2 : size
+      over_vector =
+        Vector.create(Numo::UInt32.new(over_size).rand(over_sample).to_arrow_array)
+      indices = over_vector.rank.take(*0...n_sample)
+      take(indices - ((indices / size) * size))
+    end
+
     private
 
     # Accepts indices by numeric Vector

data/lib/red_amber/vector_unary_element_wise.rb

@@ -0,0 +1,436 @@
+# 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_element_wise
+      #   [Unary element-wise function] Returns a Vector.
+      #
+      def define_unary_element_wise(function)
+        define_method(function) do |**options|
+          datum = exec_func_unary(function, options)
+          Vector.create(datum.value)
+        end
+      end
+    end
+
+    # @!macro array_sort_options
+    #   @param order [:ascending, :descending]
+    #     ascending: Arrange values in increasing order.
+    #     descending: Arrange values in decreasing order.
+
+    # rubocop:disable Layout/LineLength
+
+    # @!macro round_mode
+    #   @param round_mode [:down, :up, :towards_zero, :towards_infinity, :half_down, :half_up, :half_towards_zero, :half_towards_infinity, :half_to_even, :half_to_odd]
+    #     Rounding and tie-breaking mode.
+    #     - down: Round to nearest integer less than or equal in magnitude (aka “floor”).
+    #     - up: Round to nearest integer greater than or equal in magnitude (aka “ceil”).
+    #     - towards_zero: Get the integral part without fractional digits (aka “trunc”).
+    #     - towards_infinity: Round negative values with :down rule and positive values
+    #       with :up rule (aka “away from zero”).
+    #     - half_down: Round ties with :down rule (also called
+    #       “round half towards negative infinity”).
+    #     - half_up: Round ties with :up rule (also called
+    #       “round half towards positive infinity”).
+    #     - half_towards_zero: Round ties with :towards_zero rule (also called
+    #       “round half away from infinity”).
+    #     - half_towards_infinity: Round ties with :towards_infinity rule (also called
+    #       “round half away from zero”).
+    #     - half_to_even: Round ties to nearest even integer.
+    #     - half_to_odd: Round ties to nearest odd integer.
+
+    # rubocop:enable Layout/LineLength
+
+    # Calculate the absolute value of self element-wise.
+    #
+    # Results will wrap around on integer overflow.
+    # @return [Vector]
+    #   abs of each element of self.
+    #
+    define_unary_element_wise :abs
+
+    # Compute the inverse cosine of self element-wise.
+    #
+    # NaN is returned for invalid input values.
+    # @return [Vector]
+    #   acos of each element of self.
+    #
+    define_unary_element_wise :acos
+
+    # Compute the inverse sine of self element-wise.
+    #
+    # NaN is returned for invalid input values.
+    # @return [Vector]
+    #   asin of each element of self.
+    #
+    define_unary_element_wise :asin
+
+    # Return the indices that would sort self.
+    #
+    # Computes indices Vector that define a stable sort of self.
+    # By default, nils are considered greater than any other value
+    # and are therefore sorted at the end of the Vector.
+    # For floating-point types, NaNs are considered greater than any
+    # other non-nil value, but smaller than nil.
+    # @!method array_sort_indices(order: :ascending)
+    # @macro array_sort_options
+    # @return [Vector]
+    #   sort indices of self.
+    #
+    define_unary_element_wise :array_sort_indices
+    alias_method :sort_indexes, :array_sort_indices
+    alias_method :sort_indices, :array_sort_indices
+    alias_method :sort_index, :array_sort_indices
+
+    # Compute the inverse tangent of self element-wise.
+    #
+    # the return value is in the range [-pi/2, pi/2].
+    # For a full return range [-pi, pi], see {.atan2} .
+    # @return [Vector]
+    #   atan of each element of self.
+    #
+    define_unary_element_wise :atan
+
+    # Bit-wise negate by element-wise.
+    #
+    # nil values reeturn nil.
+    # @return [Vector]
+    #   bit wise not of each element of self.
+    #
+    define_unary_element_wise :bit_wise_not
+
+    # Round up to the nearest integer.
+    #
+    # Compute the smallest integer value not less in magnitude than each element.
+    # @return [Vector]
+    #   ceil of each element of self.
+    # @example
+    #   double = Vector.new([15.15, 2.5, 3.5, -4.5, -5.5])
+    #   double.ceil
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd00>
+    #   [16.0, 3.0, 4.0, -4.0, -5.0]
+    #
+    define_unary_element_wise :ceil
+
+    # Compute the cosine of self element-wise.
+    #
+    # NaN is returned for invalid input values.
+    # @return [Vector]
+    #   cos of each element of self.
+    #
+    define_unary_element_wise :cos
+
+    # Compute cumulative sum over the numeric Vector.
+    #
+    # @note Self must be numeric.
+    # @note Return error for integer overflow.
+    # @return [Vector]
+    #   cumulative sum of self.
+    #
+    define_unary_element_wise :cumulative_sum_checked
+
+    # Compute cumulative sum over the numeric Vector.
+    #
+    # @note Self must be numeric.
+    # @note Try to cast to Int64 if integer overflow occured.
+    # @return [Vector]
+    #   cumulative sum of self.
+    #
+    def cumsum
+      cumulative_sum_checked
+    rescue Arrow::Error::Invalid
+      Vector.create(Arrow::Int64Array.new(data)).cumulative_sum_checked
+    end
+
+    # Carry non-nil values backward to fill nil slots.
+    #
+    # Propagate next valid value backward to previous nil values.
+    # Or nothing if all next values are nil.
+    # @return [Vector]
+    #   a Vector which filled nil backward.
+    # @example
+    #   integer = Vector.new([0, 1, nil, 3, nil])
+    #   integer.fill_nil_backward
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:uint8, size=5):0x000000000000f974>
+    #   [0, 1, 3, 3, nil]
+    #
+    define_unary_element_wise :fill_null_backward
+    alias_method :fill_nil_backward, :fill_null_backward
+
+    # Carry non-nil values forward to fill nil slots.
+    #
+    # Propagate last valid value backward to next nil values.
+    # Or nothing if all previous values are nil.
+    # @return [Vector]
+    #   a Vector which filled nil forward.
+    # @example
+    #   integer = Vector.new([0, 1, nil, 3, nil])
+    #   integer.fill_nil_forward
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:uint8, size=5):0x000000000000f960>
+    #   [0, 1, 1, 3, 3]
+    #
+    define_unary_element_wise :fill_null_forward
+    alias_method :fill_nil_forward, :fill_null_forward
+
+    # Round down to the nearest integer.
+    #
+    # Compute the largest integer value not greater in magnitude than each element.
+    # @return [Vector]
+    #   floor of each element of self.
+    # @example
+    #   double = Vector.new([15.15, 2.5, 3.5, -4.5, -5.5])
+    #   double.floor
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd14>
+    #   [15.0, 2.0, 3.0, -5.0, -6.0]
+    #
+    define_unary_element_wise :floor
+
+    # Return true if value is finite.
+    #
+    # For each input value, emit true if the value is finite.
+    # (i.e. neither NaN, inf, nor -inf).
+    # @return [Vector]
+    #   boolean Vector wheather each element is finite.
+    #
+    define_unary_element_wise :is_finite
+
+    # Return true if value is infinity.
+    #
+    # For each input value, emit true if the value is infinite (inf or -inf).
+    # @return [Vector]
+    #   boolean Vector wheather each element is inf.
+    #
+    define_unary_element_wise :is_inf
+
+    # return true if value is nil or NaN.
+    #
+    # For each input value, emit true if the value is nil or NaN.
+    # @return [Vector]
+    #   boolean Vector wheather each element is na.
+    #
+    def is_na # rubocop:disable Naming/PredicateName
+      numeric? ? (is_nil | is_nan) : is_nil
+    end
+
+    # Return true if NaN.
+    #
+    # For each input value, emit true if the value is NaN.
+    # @return [Vector]
+    #   boolean Vector wheather each element is nan.
+    #
+    define_unary_element_wise :is_nan
+
+    # Return true if nil.
+    #
+    # @note Arrow::NullOptions is not supported yet.
+    # For each input value, emit true if the value is nil.
+    # @return [Vector]
+    #   boolean Vector wheather each element is null.
+    #
+    define_unary_element_wise :is_null
+    alias_method :is_nil, :is_null
+
+    # Return true if non-nil.
+    #
+    # For each input value, emit true if the value is valid (i.e. non-nil).
+    # @return [Vector]
+    #   boolean Vector wheather each element is valid.
+    #
+    define_unary_element_wise :is_valid
+
+    # Compute natural logarithm.
+    #
+    # Non-positive values return -inf or NaN. Nil values return nil.
+    # @return [Vector]
+    #   natural logarithm of each element of self.
+    #
+    define_unary_element_wise :ln
+
+    # Compute base 10 logarithm.
+    #
+    # Non-positive values return -inf or NaN. Nil values return nil.
+    # @return [Vector]
+    #   base 10 logarithm of each element of self.
+    #
+    define_unary_element_wise :log10
+
+    # Compute natural log of (1+x).
+    #
+    # Non-positive values return -inf or NaN. Nil values return nil.
+    # This function may be more precise than log(1 + x) for x close to zero.
+    # @return [Vector]
+    #   natural log of (each element + 1) of self.
+    #
+    define_unary_element_wise :log1p
+
+    # Compute base 2 logarithm.
+    #
+    # Non-positive values return -inf or NaN. Nil values return nil.
+    # @return [Vector]
+    #   base 2 logarithm of each element of self.
+    #
+    define_unary_element_wise :log2
+
+    # Round to a given precision.
+    #
+    # Options are used to control the number of digits and rounding mode.
+    # Default behavior is to round to the nearest integer and
+    # use half-to-even rule to break ties.
+    # @!method round(n_digits: 0, round_mode: :half_to_even)
+    # @param n_digits [Integer]
+    #   Rounding precision (number of digits to round to).
+    # @macro round_mode
+    # @return [Vector]
+    #   round of each element of self.
+    # @example
+    #   double = Vector.new([15.15, 2.5, 3.5, -4.5, -5.5])
+    #   double.round
+    #   # or double.round(n_digits: 0, mode: :half_to_even)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd28>
+    #   [15.0, 2.0, 4.0, -4.0, -6.0]
+    #
+    #   double.round(mode: :towards_infinity)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd3c>
+    #   [16.0, 3.0, 4.0, -5.0, -6.0]
+    #
+    #   double.round(mode: :half_up)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd50>
+    #   [15.0, 3.0, 4.0, -4.0, -5.0]
+    #
+    #   double.round(mode: :half_towards_zero)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd64>
+    #   [15.0, 2.0, 3.0, -4.0, -5.0]
+    #
+    #   double.round(mode: :half_towards_infinity)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd78>
+    #   [15.0, 3.0, 4.0, -5.0, -6.0]
+    #
+    #   double.round(mode: :half_to_odd)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cd8c>
+    #   [15.0, 3.0, 3.0, -5.0, -5.0]
+    #
+    #   double.round(n_digits: 1)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cda0>
+    #   [15.2, 2.5, 3.5, -4.5, -5.5]
+    #
+    #   double.round(n_digits: -1)
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:double, size=5):0x000000000000cdb4>
+    #   [20.0, 0.0, 0.0, -0.0, -10.0]
+    #
+    define_unary_element_wise :round
+
+    # Round to a given multiple.
+    #
+    # Options are used to control the rounding multiple and rounding mode.
+    # Default behavior is to round to the nearest integer and
+    # use half-to-even rule to break ties.
+    # @!method round_to_multiple(multiple: 1.0, round_mode: :half_to_even)
+    # @param multiple [Float, Integer]
+    #   Rounding scale (multiple to round to).
+    #   Should be a positive numeric scalar of a type compatible with the argument
+    #   to be rounded. The cast kernel is used to convert the rounding multiple
+    #   to match the result type.
+    # @macro round_mode
+    # @return [Vector]
+    #   round to multiple of each element of self.
+    #
+    def round_to_multiple(multiple: 1.0, round_mode: :half_to_even)
+      datum = exec_func_unary(:round_to_multiple,
+                              multiple: Arrow::DoubleScalar.new(multiple),
+                              round_mode: round_mode)
+      Vector.create(datum.value)
+    end
+
+    # Get the signedness of the arguments element-wise.
+    #
+    # Output is any of (-1,1) for nonzero inputs and 0 for zero input.
+    # NaN values return NaN. Integral values return signedness as Int8 and
+    # floating-point values return it with the same type as the input values.
+    # @return [Vector]
+    #   sign of each element of self.
+    #
+    define_unary_element_wise :sign
+
+    # Compute the sine of self element-wise.
+    #
+    # NaN is returned for invalid input values.
+    # @return [Vector]
+    #   sine of each element of self.
+    #
+    define_unary_element_wise :sin
+
+    # Compute the tangent of self element-wise.
+    #
+    # NaN is returned for invalid input values.
+    # @return [Vector]
+    #   tangent of each element of self.
+    #
+    define_unary_element_wise :tan
+
+    # Compute the integral part
+    #
+    # Compute the nearest integer not greater in magnitude than each element.
+    # @return [Vector]
+    #   trunc of each element of self.
+    #
+    define_unary_element_wise :trunc
+
+    # Compute unique elements
+    #
+    # Return an array with distinct values.  Nils in the input are ignored.
+    # @return [Vector]
+    #   uniq element of self.
+    #
+    define_unary_element_wise :unique
+    alias_method :uniq, :unique
+
+    # Invert boolean values
+    #
+    # @return [Vector]
+    #   not of each element of self.
+    #
+    define_unary_element_wise :invert
+    alias_method :'!', :invert # rubocop:disable Lint/SymbolConversion
+    alias_method :not, :invert
+
+    # Negate the argument element-wise
+    #
+    # Results will wrap around on integer overflow.
+    # @return [Vector]
+    #   negate of each element of self.
+    #
+    define_unary_element_wise :negate
+    alias_method :'-@', :negate # rubocop:disable Lint/SymbolConversion
+  end
+end