red_amber 0.3.0 → 0.4.0

data/lib/red_amber/vector_updatable.rb

@@ -4,17 +4,114 @@
 # reference: https://arrow.apache.org/docs/cpp/compute.html
 
 module RedAmber
-  # mix-in for class Vector
+  # Mix-in for class Vector
   # Functions to make up some data (especially missing) for new data.
   module VectorUpdatable
     # Add properties to Arrow::Array and Arrow::ChunkedArray
     using RefineArrayLike
 
-    # Replace data
-    # @param specifier [Array, Vector, Arrow::Array] index or booleans.
-    # @param replacer [Scalar, Array, Vector, Arrow::Array] new data to replace for.
-    # @return [Vector] Replaced new Vector.
-    #   If specifier has no true, return self.
+    # Replace data in self by position specifier and replacer.
+    #
+    # - Scalar value may be broadcasted.
+    # - Returned value type may be automatically up-casted by replacer.
+    #
+    # @overload replace(booleans, replacer_by_scalar)
+    #   Replace the value where true in boolean specifier to scalar replacer.
+    #
+    #   @param booleans [Array, Vector, Arrow::Array]
+    #     boolean position specifier to specify the position to be replaced by true.
+    #   @param replacer_by_scalar [Scalar]
+    #     new data to replace for.
+    #   @return [Vector]
+    #     a new replaced Vector.
+    #     If specifier has no true, returns self.
+    #   @example Replace with boolean specifier and scalar replacer
+    #     Vector.new([1, 2, 3]).replace([true, false, true], 0)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
+    #     [0, 2, 0]
+    #
+    #   @example Type of result is up-casted by replacer.
+    #     ector.new([1, 2, 3]).replace([true, false, true], -1.0)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:double, size=3):0x0000000000025d78>
+    #     [-1.0, 2.0, -1.0]
+    #
+    #   @example Position of nil in booleans is replaced with nil
+    #     Vector.new([1, 2, 3]).replace([true, false, nil], -1)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
+    #     [-1, 2, nil]
+    #
+    #   @example Replace 'NA' to nil
+    #     vector = Vector.new(['A', 'B', 'NA'])
+    #     vector.replace(vector == 'NA', nil)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:string, size=3):0x000000000000f8ac>
+    #     ["A", "B", nil]
+    #
+    # @overload replace(indices, replacer_by_scalar)
+    #   Replace the value at the index specifier to scalar replacer.
+    #
+    #   @param indices [Array, Vector, Arrow::Array]
+    #     index specifier to specify the position to be replaced.
+    #   @param replacer_by_scalar [Scalar]
+    #     new data to replace for.
+    #   @return [Vector]
+    #     a new replaced Vector.
+    #     If specifier is empty, returns self.
+    #   @example Replace with index specifier and scalar replacer
+    #     Vector.new([1, 2, 3]).replace([0, 2], 0)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:uint8, size=3):0x000000000000c15c>
+    #     [0, 2, 0]
+    #
+    # @overload replace(booleans, replacer_array)
+    #   Replace the value where true in boolean specifier to replacer array.
+    #
+    #   @param booleans [Array, Vector, Arrow::Array]
+    #     boolean position specifier to specify the position to be replaced by true.
+    #   @param replacer_array [Vector, Array, Arrow::Array]
+    #     new data to replace for.
+    #     The number of true in booleans must be equal to the length of replacer array.
+    #   @return [Vector]
+    #     a new replaced Vector.
+    #     If specifier has no true, returns self.
+    #   @example Replace with boolean specifier and replacer array
+    #     vector = Vector.new([1, 2, 3])
+    #     booleans = [true, false, true]
+    #     replacer = [4, 5]
+    #     vector.replace(booleans, replacer)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
+    #     [4, 2, 5]
+    #
+    # @overload replace(indices, replacer_array)
+    #   Replace the value at the index specifier to replacer array.
+    #
+    #   @param indices [Array, Vector, Arrow::Array]
+    #     index specifier to specify the position to be replaced.
+    #   @param replacer_array [Vector, Array, Arrow::Array]
+    #     new data to replace for.
+    #     The length of index specifier must be equal to the length of replacer array.
+    #   @return [Vector]
+    #     a new replaced Vector.
+    #     If specifier is empty, returns self.
+    #   @example Replace with index specifier and replacer array
+    #     vector = Vector.new([1, 2, 3])
+    #     indices = [0, 2]
+    #     replacer = [4, 5]
+    #     vector.replace(indices, replacer)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
+    #     [4, 2, 5]
     #
     def replace(specifier, replacer)
       vector = Vector.new(parse_args(Array(specifier), size))
@@ -37,7 +134,7 @@ module RedAmber
         in nil | [nil]
           return replace_to_nil(booleans.data)
         in Arrow::Array
-        # nop
+          replacer
         in Vector
           replacer.data
         in Array
@@ -52,10 +149,59 @@ module RedAmber
       replace_with(booleans.data, replacer_array)
     end
 
-    # (related functions)
-    # fill_null_backward, fill_null_forward
-
-    # [Ternary element-wise]: boolean_vector.func(if_true, else) => vector
+    # Choose values based on self.
+    #
+    # [Ternary element-wise function] Returns a Vector.
+    # - Self must be a boolean Vector.
+    # - `true_choice`, `false_choice` must be of the same type scalar / array / Vector.
+    # - `nil` values in self will be promoted to the output.
+    #
+    # @overload if_else(true_choise, false_choise)
+    #   replace with a scalar.
+    #
+    #   @param true_choice [scalar]
+    #     a value to be replaced with true.
+    #   @param false_choice [scalar]
+    #     a value to be replaced with false.
+    #   @return [Vector]
+    #     replaced result.
+    #   @example Replace with scalar choices
+    #     Vector.new(true, true, false, nil, false).if_else(1, 2)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:uint8, size=5):0x000000000000c198>
+    #     [1, 1, 2, nil, 2]
+    #
+    # @overload if_else(true_choise, false_choise)
+    #   replace with a scalar.
+    #
+    #   @param true_choice [Vector, Array, Arrow::Array]
+    #     values to be replaced with true.
+    #     The size of true_choice must be same as self.
+    #   @param false_choice [Vector, Array, Arrow::Array]
+    #     values to be replaced with false.
+    #     The size of false_choice must be same as self.
+    #   @return [Vector]
+    #     replaced result.
+    #   @example Replace with Array choices
+    #     boolean_vector = Vector.new(true, true, false, nil, false)
+    #     true_choise = Vector.new([1.1, 2.2, 3.3, 4.4, 5.5])
+    #     false_choise = -true_choise
+    #     boolean_vector.if_else(true_choise, false_choise)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:double, size=5):0x000000000000cd28>
+    #     [1.1, 2.2, -3.3, nil, -5.5]
+    #
+    #   @example Normalize negative indices to positive ones
+    #     indices = Vector.new([1, -1, 3, -4])
+    #     array_size = 10
+    #     normalized_indices = (indices < 0).if_else(indices + array_size, indices)
+    #
+    #     # =>
+    #     #<RedAmber::Vector(:int16, size=4):0x000000000000f85c>
+    #     [1, 9, 3, 6]
+    #
     def if_else(true_choice, false_choice)
       true_choice = true_choice.data if true_choice.is_a? Vector
       false_choice = false_choice.data if false_choice.is_a? Vector
@@ -65,21 +211,58 @@ module RedAmber
       Vector.create(datum.value)
     end
 
-    # same behavior as Ruby's invert
+    # Another #invert which is same behavior as Ruby's invert.
+    #
     # ![true, false, nil] #=> [false, true, true]
+    # @return [Vector]
+    #   follows Ruby's BasicObject#!'s behavior.
+    # @example
+    #   vector = Vector.new([true, true, false, nil])
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:boolean, size=4):0x000000000000fa8c>
+    #   [true, true, false, nil]
+    #
+    #   # nil is converted to nil by Vector#invert.
+    #   vector.invert
+    #   # or
+    #   !vector
+    #
+    #   #<RedAmber::Vector(:boolean, size=4):0x000000000000faa0>
+    #   [false, false, true, nil]
+    #
+    #   # On the other hand,
+    #   # Vector#primitive_invert follows Ruby's BasicObject#!'s behavior.
+    #   vector.primitive_invert
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:boolean, size=4):0x000000000000fab4>
+    #   [false, false, true, true]
+    #
     def primitive_invert
       raise VectorTypeError, "Not a boolean Vector: #{self}" unless boolean?
 
       is_nil.if_else(false, self).invert
     end
 
+    # Shift elements in self.
+    #
+    # @param amount [Integer]
+    #   amount of shift. Positive value will shift right, negative will shift left.
+    # @param fill [Object]
+    #   complementary element to fill the new seat.
+    # @return [Vector]
+    #   shifted Vector.
+    #
     def shift(amount = 1, fill: nil)
-      raise VectorArgumentError, 'Shift amount is too large' if amount.abs > size
+      raise VectorArgumentError, 'Shift amount is too large' if amount.abs >= size
 
       if amount.positive?
-        replace(amount..-1, self[0...-amount]).replace(0...amount, fill)
+        filler = [fill] * amount
+        Vector.new(filler.concat(Array(self[0...-amount])))
       elsif amount.negative?
-        replace(0...amount, self[-amount..]).replace(amount..-1, fill)
+        filler = [fill] * -amount
+        Vector.new(Array(self[-amount...]).concat(filler))
       else # amount == 0
         self
       end
@@ -87,13 +270,18 @@ module RedAmber
 
     # Split string Vector and returns Array of columns.
     #
-    # @param sep [nil, String, Regexp] separater.
-    #   If separator is nil (or no argeument given), the column will be splitted by
-    #   Arrow's split function using any ASCII whitespace.
-    #   Otherwise sep will passed to String#split.
-    # @param limit [Integer] maximum number to limit separation. Passed to String#split.
-    # @return [Array<Vector>] an Array of Vectors.
-    # @note nil will separated as nil's at same row. ex) `nil => [nil, nil]`
+    # @param sep [nil, String, Regexp]
+    #   separator.
+    #   If separator is nil (or no argeument given),
+    #   the column will be splitted by Arrow's split function
+    #   using any ASCII whitespace.
+    #   Otherwise, sep will passed to String#split.
+    # @param limit [Integer]
+    #   maximum number to limit separation. Passed to String#split.
+    # @return [Array<Vector>]
+    #   an Array of Vectors.
+    # @note nil will separated as nil's at same row.
+    #   ex) `nil => [nil, nil]`
     #
     def split_to_columns(sep = nil, limit = 0)
       l = split(sep, limit)
@@ -102,20 +290,25 @@ module RedAmber
 
     # Split string Vector and flatten into rows.
     #
-    # @param sep [nil, String, Regexp] separater.
-    #   If separator is nil (or no argeument given), the column will be splitted by
-    #   Arrow's split function using any ASCII whitespace.
-    #   Otherwise sep will passed to String#split.
-    # @param limit [Integer] maximum number to limit separation. Passed to String#split.
-    # @return [Vector] a flatten Vector.
-    # @note nil will separated as nil's at same row. ex) `nil => [nil, nil]`
+    # @param sep [nil, String, Regexp]
+    #   separater.
+    #   If separator is nil (or no argeument given),
+    #   the column will be splitted by Arrow's split function
+    #   using any ASCII whitespace.
+    #   Otherwise, sep will passed to String#split.
+    # @param limit [Integer]
+    #   maximum number to limit separation. Passed to String#split.
+    # @return [Vector]
+    #   a flatten Vector.
+    # @note nil will separated as nil's at same row.
+    #   ex) `nil => [nil, nil]`
     #
     def split_to_rows(sep = nil, limit = 0)
       l = split(sep, limit)
       l.list_flatten
     end
 
-    # return element size Array for list Vector.
+    # Return element size Array for list Vector.
     #
     # @api private
     #
@@ -179,8 +372,10 @@ module RedAmber
     #
     # @param other [String, Vector]
     #   merger from right. It will be broadcasted if it is a scalar String.
-    # @param sep [String] separator.
-    # @return [Vector] merged Vector
+    # @param sep [String]
+    #   separator.
+    # @return [Vector]
+    #   merged Vector
     #
     def merge(other, sep: ' ')
       if empty? || !string?
@@ -207,6 +402,53 @@ module RedAmber
       Vector.create(datum.value)
     end
 
+    # Concatenate other array-like to self.
+    #
+    # @param other [Vector, Array, Arrow::Array, Arrow::ChunkedArray]
+    #   other array-like to concatenate.
+    # @return [Vector]
+    #   concatenated Vector.
+    # @example Concatenate to string
+    #   string_vector
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:string, size=2):0x00000000000037b4>
+    #   ["A", "B"]
+    #
+    #   string_vector.concatenate([1, 2])
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:string, size=4):0x0000000000003818>
+    #   ["A", "B", "1", "2"]
+    #
+    # @example Concatenate to integer
+    #   integer_vector
+    #
+    #   # =>
+    #   #<RedAmber::Vector(:uint8, size=2):0x000000000000382c>
+    #   [1, 2]
+    #
+    #   integer_vector.concatenate(["A", "B"])
+    #   # =>
+    #   #<RedAmber::Vector(:uint8, size=4):0x0000000000003840>
+    #   [1, 2, 65, 66]
+    #
+    # @since 0.4.0
+    #
+    def concatenate(other)
+      concatenated_array =
+        case other
+        when Vector
+          data + other.data
+        when Arrow::ChunkedArray
+          data + other.pack
+        else
+          data + other
+        end
+      Vector.create(concatenated_array)
+    end
+    alias_method :concat, :concatenate
+
     private
 
     # Replace elements selected with a boolean mask
@@ -222,7 +464,8 @@ module RedAmber
     #   - `replacer.size` must be equal to `mask.count(true)`.
     #   - Types of self and replacer must be same
     #
-    # @return [Vector] Replaced vector.
+    # @return [Vector]
+    #   replaced vector.
     #   Type of returned Vector is upcasted if needed.
     #
     def replace_with(boolean_mask, replacer)
@@ -241,7 +484,8 @@ module RedAmber
     #   Boolean mask which indicates the position to be replaced.
     #   - Position with true will be replaced by nil
     #   - Position with nil will remain as nil.
-    # @return [Vector] Replaced vector.
+    # @return [Vector]
+    #   replaced vector.
     #
     def replace_to_nil(boolean_mask)
       nil_array = data.class.new([nil] * size) # Casted nil Array

data/lib/red_amber/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module RedAmber
-  VERSION = '0.3.0'
+  # Library version
+  VERSION = '0.4.0'
 end

data/lib/red_amber.rb

@@ -14,20 +14,32 @@ require_relative 'red_amber/data_frame_selectable'
 require_relative 'red_amber/data_frame_variable_operation'
 require_relative 'red_amber/data_frame'
 require_relative 'red_amber/group'
-require_relative 'red_amber/vector_functions'
+require_relative 'red_amber/subframes'
+require_relative 'red_amber/vector_aggregation'
+require_relative 'red_amber/vector_binary_element_wise'
+require_relative 'red_amber/vector_unary_element_wise'
 require_relative 'red_amber/vector_updatable'
 require_relative 'red_amber/vector_selectable'
 require_relative 'red_amber/vector'
 require_relative 'red_amber/version'
 
 module RedAmber
+  # Generic error
   class Error < StandardError; end
 
+  # Argument error in DataFrame
   class DataFrameArgumentError < ArgumentError; end
+  # Data type error in DataFrame
   class DataFrameTypeError < TypeError; end
 
+  # Argument error in Vector
   class VectorArgumentError < ArgumentError; end
+  # Data type error in DataFrame
   class VectorTypeError < TypeError; end
 
+  # Argument error in Group
   class GroupArgumentError < ArgumentError; end
+
+  # Argument error in SubFrames
+  class SubFramesArgumentError < ArgumentError; end
 end

data/red_amber.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ['heronshoes877@gmail.com']
 
   spec.summary = 'Simple dataframe library for Ruby'
-  spec.description = 'RedAmber is a simple dataframe library' \
+  spec.description = 'RedAmber is a simple dataframe library ' \
                      'inspired by Rover-df and powered by Red Arrow.'
   spec.homepage = 'https://github.com/heronshoes/red_amber'
   spec.license = 'MIT'
@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'red-arrow', '~> 10.0.0'
+  spec.add_dependency 'red-arrow', '~> 11.0.0'
 
   # Development dependency has gone to the Gemfile (rubygems/bundler#7237)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: red_amber
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hirokazu SUZUKI (heronshoes)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-17 00:00:00.000000000 Z
+date: 2023-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: red-arrow
@@ -16,15 +16,15 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.0.0
+        version: 11.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 10.0.0
-description: RedAmber is a simple dataframe libraryinspired by Rover-df and powered
+        version: 11.0.0
+description: RedAmber is a simple dataframe library inspired by Rover-df and powered
   by Red Arrow.
 email:
 - heronshoes877@gmail.com
@@ -54,6 +54,8 @@ files:
 - benchmark/vector.yml
 - doc/CODE_OF_CONDUCT.md
 - doc/DataFrame.md
+- doc/DataFrame_Comparison.md
+- doc/SubFrames.md
 - doc/Vector.md
 - doc/image/arrow_table_new.png
 - doc/image/basic_verbs.png
@@ -66,7 +68,6 @@ files:
 - doc/image/dataframe/remove.png
 - doc/image/dataframe/rename.png
 - doc/image/dataframe/rename_operation.png
-- doc/image/dataframe/reshaping_DataFrames.png
 - doc/image/dataframe/set_and_bind.png
 - doc/image/dataframe/slice.png
 - doc/image/dataframe/slice_operation.png
@@ -85,6 +86,7 @@ files:
 - doc/image/vector/unary_element_wise.png
 - doc/tdr.md
 - doc/tdr_ja.md
+- doc/yard-templates/default/fulldoc/html/css/common.css
 - lib/red-amber.rb
 - lib/red_amber.rb
 - lib/red_amber/data_frame.rb
@@ -98,9 +100,12 @@ files:
 - lib/red_amber/group.rb
 - lib/red_amber/helper.rb
 - lib/red_amber/refinements.rb
+- lib/red_amber/subframes.rb
 - lib/red_amber/vector.rb
-- lib/red_amber/vector_functions.rb
+- lib/red_amber/vector_aggregation.rb
+- lib/red_amber/vector_binary_element_wise.rb
 - lib/red_amber/vector_selectable.rb
+- lib/red_amber/vector_unary_element_wise.rb
 - lib/red_amber/vector_updatable.rb
 - lib/red_amber/version.rb
 - red_amber.gemspec
@@ -128,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Simple dataframe library for Ruby