red_amber 0.1.4 → 0.1.5

data/doc/Vector.md

@@ -33,7 +33,9 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
 
 ### `type`
 
-### `data_type`
+### `boolean?`, `numeric?`, `string?`, `temporal?`
+
+### `type_class`
 
 ### [ ] `each` (not impremented yet)
 
@@ -43,8 +45,6 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
 
 ### [ ] `each_chunk` (not impremented yet)
 
-### `tally`
-
 ### `n_nils`, `n_nans`
 
   - `n_nulls` is an alias of `n_nils`
@@ -126,20 +126,23 @@ boolean.all(opts: {skip_nulls: false}) #=> false
 |[ ]`asin`     |     | [ ] |     |     |       |
 | ✓ `atan`     |     |  ✓  |     |     |       |
 | ✓ `bit_wise_not`|  | (✓) |     |     |integer only|
-|[ ]`ceil`     |     |  ✓  |     |     |       |
+| ✓ `ceil`     |     |  ✓  |     |     |       |
 | ✓ `cos`      |     |  ✓  |     |     |       |
-|[ ]`floor`    |     |  ✓  |     |     |       |
+| ✓`fill_nil_backward`| ✓ | ✓ | ✓ |    |       |
+| ✓`fill_nil_forward` | ✓ | ✓ | ✓ |    |       |
+| ✓ `floor`    |     |  ✓  |     |     |       |
 | ✓ `invert`   |  ✓  |     |     |     |`!`, alias `not`|
 |[ ]`ln`       |     | [ ] |     |     |       |
 |[ ]`log10`    |     | [ ] |     |     |       |
 |[ ]`log1p`    |     | [ ] |     |     |       |
 |[ ]`log2`     |     | [ ] |     |     |       |
-|[ ]`round`    |     | [ ] |     |[ ] Round|       |
-|[ ]`round_to_multiple`| | [ ] | |[ ] RoundToMultiple|       |
+| ✓ `round`    |     |  ✓  |     | ✓ Round (:mode, :n_digits)|    |
+| ✓ `round_to_multiple`| | ✓ |   | ✓ RoundToMultiple :mode, :multiple| multiple must be an Arrow::Scalar|
 | ✓ `sign`     |     |  ✓  |     |     |       |
 | ✓ `sin`      |     |  ✓  |     |     |       |
+| ✓`sort_indexes`| ✓  | ✓  | ✓  |:order|alias `sort_indices`|
 | ✓ `tan`      |     |  ✓  |     |     |       |
-|[ ]`trunc`    |     |  ✓  |     |     |       |
+| ✓ `trunc`    |     |  ✓  |     |     |       |
 
 ### Binary element-wise: `vector.func(vector) => vector`
 
@@ -180,8 +183,30 @@ boolean.all(opts: {skip_nulls: false}) #=> false
 | ✓ `shift_right`   |     | (✓) |     |     |`>>`, integer only|
 | ✓ `xor`           |  ✓  |     |     |     | `^`   |
 
+### `uniq`
+
+  Returns a new array with distinct elements.
+
 (Not impremented functions)
-### [ ] sort, sort_index
+
+### `tally` and `value_counts`
+
+  Compute counts of unique elements and return a Hash.
+
+  It returns almost same result as Ruby's tally. These methods consider NaNs are same.
+
+  ```ruby
+  array = [0.0/0, Float::NAN]
+  array.tally #=> {NaN=>1, NaN=>1}
+
+  vector = RedAmber::Vector.new(array)
+  vector.tally #=> {NaN=>2}
+  vector.value_counts #=> {NaN=>2}
+  ```
+
+### `sort_indexes`, `sort_indices`, `array_sort_indices`
+
+### [ ] `sort`, `sort_by`
 ### [ ] argmin, argmax
 ### [ ] (array functions)
 ### [ ] (strings functions)
@@ -192,4 +217,101 @@ boolean.all(opts: {skip_nulls: false}) #=> false
 
 ## Coerce (not impremented)
 
-## Updating (not impremented)
+## Update vector's value
+### `replace_with(booleans, replacements)` => vector
+
+- Accepts Vector, Array, Arrow::Array for booleans and replacements.
+  - Replacements can accept scalar
+- Booleans specifies the position of replacement in true.
+- Replacements specifies the vaues to be replaced.
+  - The number of true in booleans must be equal to the length of replacement
+
+```ruby
+vector = RedAmber::Vector.new([1, 2, 3])
+booleans = [true, false, true]
+replacemants = [4, 5]
+vector.replace_with(booleans, replacemants)
+# => 
+#<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
+[4, 2, 5] 
+```
+
+- Scalar value in replacements can be broadcasted.
+
+```ruby
+replacemant = 0
+vector.replace_with(booleans, replacement)
+# => 
+#<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
+[0, 2, 0] 
+```
+
+- Returned data type is automatically up-casted by replacement.
+
+```ruby
+replacement = 1.0
+vector.replace_with(booleans, replacement)
+# => 
+#<RedAmber::Vector(:double, size=3):0x0000000000025d78>
+[1.0, 2.0, 1.0]
+```
+
+- Position of nil in booleans is replaced with nil.
+
+```ruby
+booleans = [true, false, nil]
+replacemant = -1
+vec.replace_with(booleans, replacement)
+=> 
+#<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
+[-1, 2, nil]
+```
+
+- Replacemants can have nil in it.
+
+```ruby
+booleans = [true, false, true]
+replacemants = [nil]
+vec.replace_with(booleans, replacemants)
+=> 
+#<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
+[nil, 2, nil]
+```
+
+- If no replacemants specified, it is same as to specify nil.
+
+```ruby
+booleans = [true, false, true]
+vec.replace_with(booleans)
+=> 
+#<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
+[nil, 2, nil]
+```
+
+- An example to replace 'NA' to nil.
+
+```ruby
+vector = RedAmber::Vector.new(['A', 'B', 'NA'])
+vector.replace_with(vector == 'NA', nil)
+# =>
+#<RedAmber::Vector(:string, size=3):0x000000000000f8ac>
+["A", "B", nil]
+```
+
+### `fill_nil_forward`, `fill_nil_backward` => vector
+
+Propagate the last valid observation forward (or backward).
+Or preserve nil if all previous values are nil or at the end.
+
+```ruby
+integer = RedAmber::Vector.new([0, 1, nil, 3, nil])
+integer.fill_nil_forward
+# =>
+#<RedAmber::Vector(:uint8, size=5):0x000000000000f960>
+[0, 1, 1, 3, 3]
+
+integer.fill_nil_backward
+# =>
+#<RedAmber::Vector(:uint8, size=5):0x000000000000f974>
+[0, 1, 3, 3, nil]
+```

data/doc/tdr.md

@@ -36,17 +36,20 @@ The API based on TDR is draft and RedAmber is a small experiment to test the TDR
 |     |Basic Table|Transposed DataFrame|Comment for TDR|
 |-----------|---------|------------|---|
 |name in TDR|`Table`|`TDR`|**T**ransposed **D**ataFrame **R**epresentation|
-|variable   |located in a column|a key and a `Vector` in lateral|select by key|
-|observation|located in a row|intersection in a vertical axis|select by index|
-|number of rows|n_rows etc. |`size` |`n_row` is available as an alias|
-|number of columns|n_columns etc. |`n_keys`  |`n_col` is available as an alias|
-|shape      |[n_rows, n_columns]  |`[size, n_keys]` |same order as Table|
-|merge/join left| left_join(a,b)<br>merge(a, b, how='left')|`a.join(b)` |naturally join from bottom|
-|merge/join right| right_join(a,b))<br>merge(a, b, how='right')|`b.join(a)` |naturally join from bottom|
-
-## Operation example with TDR API
-
-[Operation example with TDR API](TDR_operation.pdf) (draft)
+|variable   |located in a column|a key and a `Vector` in lateral|select by keys|
+|observation|located in a row|sliced in vertical|select by indices|
+|number of variables|n_columns etc. |`n_keys`  |`n_cols` is available as an alias|
+|number of observations|n_rows etc. |`size` |`n_rows` is available as an alias|
+|shape      |[n_rows, n_columns]  |`shape`=`[size, n_keys]` |same order as Table|
+|Select variables|select, filter, [ ], etc.|`pick` or `[keys]`  |accepts arguments or a block|
+|Reject variables|drop, etc.|`drop`  |accepts arguments or a block|
+|Select observations|slice, [ ], iloc, etc.|`slice` or `[indices]` |accepts arguments or a block|
+|Reject observations|drop, etc.|`remove`  |accepts arguments or a block|
+|Add variables|mutate, assign, etc.|`assign`  |accepts arguments or a block|
+|update variables|transmute, [ ]=, etc.|`assign`  |accepts arguments or a block|
+|inner join| inner_join(a,b)<br>merge(a, b, how='inner')|`a.inner_join(b)` |with a option on:|
+|left join| left_join(a,b)<br>merge(a, b, how='left')|`a.join(b)` |naturally join from bottom<br>with a option on:|
+|right join| right_join(a,b))<br>merge(a, b, how='right')|`b.join(a)` |naturally join from bottom<br>with a option on:|
 
 ## Q and A for TDR
 

data/doc/tdr_ja.md

@@ -37,16 +37,19 @@ TDR に基づいた API はまだ暫定板の段階であり、RedAmber は TDR
 |-----------|---------|------------|---|
 |TDRでの呼称|`Table`|`TDR`|**T**ransposed **D**ataFrame **R**epresentationの略|
 |変数 |列に配置|`variables`<br>key と `Vector` として横方向に配置|key で選択|
-|観測 |行に配置|`observations`<br>縦方向に切った一つ一つは`slice`|index や `slice` メソッドで選択|
-|行の数|nrow, n_rows など |`size` |`n_row` をエイリアスとして設定|
-|列の数|ncol, n_columns など |`n_keys`  |`n_col` をエイリアスとして設定|
-|shape      |[nrow, ncol]  |`[size, n_keys]` |行, 列の順番は同じ|
-|merge/join left| left_join(a,b)<br>merge(a, b, how='left')|`a.join(b)` |自然に下にくっつける|
-|merge/join right| right_join(a,b))<br>merge(a, b, how='right')|`b.join(a)` |自然に下にくっつける|
-
-## Operation example with TDR API
-
-[TDR の操作例](TDR_operation.pdf) (暫定版)
+|観測 |行に配置|`observations`<br>縦方向に切った一つ一つはslice|index や `slice` メソッドで選択|
+|変数(列)の数|ncol, n_columns など |`n_keys`  |`n_cols` をエイリアスとして設定|
+|観測(行)の数|nrow, n_rows など |`size` |`n_rows` をエイリアスとして設定|
+|形状      |[nrow, ncol]  |`shape`=`[size, n_keys]` |行, 列の順番は同じ|
+|変数(列)の選択|select, filter, [ ], など|`pick` or `[keys]`  |引数またはブロックで指定|
+|変数(列)の削除|drop, など|`drop`  |引数またはブロックで指定|
+|観測(行)の選択|slice, [ ], iloc, など|`slice` or `[indices]` |引数またはブロックで指定|
+|観測(行)の削除|drop, など|`remove`  |引数またはブロックで指定|
+|変数(列)の追加|mutate, assign, など|`assign`  |引数またはブロックで指定|
+|変数(列)の更新|transmute, [ ]=, など|`assign`  |引数またはブロックで指定|
+|内部結合| inner_join(a,b)<br>merge(a, b, how='inner')|`a.inner_join(b)` |オプション on:|
+|左結合| left_join(a,b)<br>merge(a, b, how='left')|`a.join(b)` |自然に下にくっつける<br>オプション on:|
+|右結合| right_join(a,b))<br>merge(a, b, how='right')|`b.join(a)` |自然に下にくっつける<br>オプション on:|
 
 ## Q and A for TDR
 

data/lib/red_amber/data_frame.rb

@@ -7,20 +7,21 @@ module RedAmber
     # mix-in
     include DataFrameDisplayable
     include DataFrameHelper
+    include DataFrameIndexable
     include DataFrameSelectable
     include DataFrameObservationOperation
     include DataFrameVariableOperation
 
     def initialize(*args)
-      # DataFrame.new, DataFrame.new([]), DataFrame.new({}), DataFrame.new(nil)
-      #   returns empty DataFrame
-      @table = Arrow::Table.new({}, [])
+      @variables = @keys = @vectors = @types = @data_types = nil
       # bug in gobject-introspection: ruby-gnome/ruby-gnome#1472
       #  [Arrow::Table] == [nil] shows ArgumentError
       #  temporary use yoda condition to workaround
-      return if args.empty? || args == [[]] || args == [{}] || [nil] == args
-
-      if args.size > 1
+      if args.empty? || args == [[]] || args == [{}] || [nil] == args
+        # DataFrame.new, DataFrame.new([]), DataFrame.new({}), DataFrame.new(nil)
+        #   returns empty DataFrame
+        @table = Arrow::Table.new({}, [])
+      elsif args.size > 1
         @table = Arrow::Table.new(*args)
       else
         arg = args[0]
@@ -42,11 +43,14 @@ module RedAmber
 
     attr_reader :table
 
+    def to_arrow
+      table
+    end
+
     def save(output, options = {})
       @table.save(output, options)
     end
 
-    # Properties ===
     def size
       @table.n_rows
     end
@@ -63,8 +67,13 @@ module RedAmber
       [size, n_keys]
     end
 
+    def variables
+      @variables || @variables = init_instance_vars(:variables)
+    end
+    alias_method :vars, :variables
+
     def keys
-      @table.columns.map { |column| column.name.to_sym }
+      @keys || @keys = init_instance_vars(:keys)
     end
     alias_method :column_names, :keys
     alias_method :var_names, :keys
@@ -81,21 +90,15 @@ module RedAmber
     alias_method :index, :key_index
 
     def types
-      @table.columns.map do |column|
-        column.data.value_type.nick.to_sym
-      end
+      @types || @types = @table.columns.map { |column| column.data.value_type.nick.to_sym }
     end
 
-    def data_types
-      @table.columns.map do |column|
-        column.data_type.class
-      end
+    def type_classes
+      @data_types || @data_types = @table.columns.map { |column| column.data_type.class }
     end
 
     def vectors
-      @table.columns.map do |column|
-        Vector.new(column.data)
-      end
+      @vectors || @vectors = init_instance_vars(:vectors)
     end
 
     def indexes
@@ -104,9 +107,7 @@ module RedAmber
     alias_method :indices, :indexes
 
     def to_h
-      @table.columns.each_with_object({}) do |column, result|
-        result[column.name.to_sym] = column.entries
-      end
+      variables.transform_values(&:to_a)
     end
 
     def to_a
@@ -125,13 +126,27 @@ module RedAmber
     end
 
     def empty?
-      @table.columns.empty?
+      variables.empty?
     end
 
     def to_rover
       Rover::DataFrame.new(to_h)
     end
 
-    # def to_parquet() end
+    private
+
+    # initialize @variable, @keys, @vectors and return one of them
+    def init_instance_vars(var)
+      ary = @table.columns.each_with_object([{}, [], []]) do |column, (variables, keys, vectors)|
+        v = Vector.new(column.data)
+        k = column.name.to_sym
+        v.key = k
+        variables[k] = v
+        keys << k
+        vectors << v
+      end
+      @variables, @keys, @vectors = ary
+      ary[%i[variables keys vectors].index(var)]
+    end
   end
 end

data/lib/red_amber/data_frame_displayable.rb

@@ -73,7 +73,7 @@ module RedAmber
                 [shorthand(vector, size, max_element)].concat na_string(vector)
               end
             else
-              shorthand(vector, size, max_element)
+              [shorthand(vector, size, max_element)]
             end
         sio.printf header_format, i + 1, key, type, data_tally.size, a.join(', ')
       end
@@ -111,9 +111,10 @@ module RedAmber
     end
 
     def shorthand(vector, size, max_element)
-      a = vector.to_a.take(max_element)
+      max = vector.temporal? ? 2 : max_element
+      a = vector.to_a.take(max)
       a.map! { |e| e.nil? ? 'nil' : e.inspect }
-      a << '... ' if size > max_element
+      a << '... ' if size > max
       "[#{a.join(', ')}]"
     end
 

data/lib/red_amber/data_frame_helper.rb

@@ -6,9 +6,16 @@ module RedAmber
     private
 
     def expand_range(args)
-      args.each_with_object([]) do |e, a|
+      ary = args.each_with_object([]) do |e, a|
         e.is_a?(Range) ? a.concat(normalized_array(e)) : a.append(e)
       end
+      ary.map do |e|
+        if e.is_a?(Integer) && e.negative?
+          e + size
+        else
+          e
+        end
+      end
     end
 
     def normalized_array(range)
@@ -50,13 +57,6 @@ module RedAmber
       DataFrame.new(@table.filter(array))
     end
 
-    def select_obs_by_indeces(indeces)
-      out_of_range?(indeces) && raise(DataFrameArgumentError, "Invalid index: #{indeces} for 0..#{size - 1}")
-
-      a = indeces.map { |i| @table.slice(i).to_a }
-      DataFrame.new(@table.schema, a)
-    end
-
     def keys_by_booleans(booleans)
       keys.select.with_index { |_, i| booleans[i] }
     end

data/lib/red_amber/data_frame_indexable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RedAmber
+  # mix-ins for the class DataFrame
+  module DataFrameIndexable
+    # Common method
+    def map_indices(*indices)
+      return self if indices.empty?
+
+      indices = indices[0].data if indices[0].is_a?(Vector)
+
+      new_dataframe_by(indices)
+    end
+
+    # @param sort_keys [Arrow::SortKey]
+    #   :key, "key" or "+key" denotes ascending,
+    #   "-key" denotes descending order
+    # @return [RedAmber::Vector] Sorted indices in Vector
+    def sort_indices(*sort_keys)
+      indices = @table.sort_indices(sort_keys.flatten)
+      Vector.new(indices)
+    end
+
+    # @return [RedAmber::DataFrame] Sorted DataFrame
+    def sort(*sort_keys)
+      indices = @table.sort_indices(sort_keys.flatten)
+
+      new_dataframe_by(indices)
+    end
+
+    private
+
+    def new_dataframe_by(index_array)
+      t = Arrow::Function.find(:take).execute([@table, index_array]).value
+      RedAmber::DataFrame.new(t)
+    end
+  end
+end

data/lib/red_amber/data_frame_observation_operation.rb

@@ -25,7 +25,7 @@ module RedAmber
 
       # filter with indexes
       slicer = expand_range(slicer)
-      return select_obs_by_indeces(slicer) if integers?(slicer)
+      return map_indices(*slicer) if integers?(slicer)
 
       raise DataFrameArgumentError, "Invalid argument #{args}"
     end
@@ -57,11 +57,22 @@ module RedAmber
       # filter with indexes
       slicer = indexes.to_a - expand_range(remover)
       return remove_all_values if slicer.empty?
-      return select_obs_by_indeces(slicer) if integers?(slicer)
+      return map_indices(*slicer) if integers?(slicer)
 
       raise DataFrameArgumentError, "Invalid argument #{args}"
     end
 
+    def remove_nil
+      func = Arrow::Function.find(:drop_null)
+      DataFrame.new(func.execute([table]).value)
+    end
+    alias_method :drop_nil, :remove_nil
+
+    def group(aggregating_keys, func, target_keys)
+      t = table.group(*aggregating_keys)
+      RedAmber::DataFrame.new(t.send(func, *target_keys))
+    end
+
     private
 
     # return a DataFrame with same keys as self without values

data/lib/red_amber/data_frame_selectable.rb

@@ -27,12 +27,22 @@ module RedAmber
 
       # expand Range like [1..3, 4] to [1, 2, 3, 4]
       expanded = expand_range(args)
-      return select_obs_by_indeces(expanded) if integers?(expanded)
+      return map_indices(*expanded) if integers?(expanded)
       return select_vars_by_keys(expanded.map(&:to_sym)) if sym_or_str?(expanded)
 
       raise DataFrameArgumentError, "Invalid argument #{args}"
     end
 
+    # Select a variable by a key in String or Symbol
+    def v(key)
+      unless key.is_a?(Symbol) || key.is_a?(String)
+        raise DataFrameArgumentError, "Key is not a Symbol or String [#{key}]"
+      end
+      raise DataFrameArgumentError, "Key not exist [#{key}]" unless key?(key)
+
+      variables[key.to_sym]
+    end
+
     def head(n_rows = 5)
       raise DataFrameArgumentError, "Index is out of range #{n_rows}" if n_rows.negative?
 
@@ -57,10 +67,10 @@ module RedAmber
 
     def select_vars_by_keys(keys)
       if keys.one?
-        t = @table[*keys]
-        raise DataFrameArgumentError, "Key does not exist #{keys}" unless t
+        key = keys[0].to_sym
+        raise DataFrameArgumentError, "Key does not exist #{keys}" unless key? key
 
-        Vector.new(t.data)
+        variables[key]
       else
         DataFrame.new(@table[keys])
       end

data/lib/red_amber/vector.rb

@@ -5,10 +5,12 @@ module RedAmber
   #   @data : holds Arrow::ChunkedArray
   class Vector
     # mix-in
+    include VectorCompensable
     include VectorFunctions
 
     # chunked_array may come from column.data
     def initialize(array)
+      @key = nil # default is 'headless'
       case array
       when Vector
         @data = array.data
@@ -17,11 +19,12 @@ module RedAmber
       when Array
         @data = Arrow::Array.new(array)
       else
-        raise ArgumentError, 'Unknown array in argument'
+        raise VectorArgumentError, 'Unknown array in argument'
       end
     end
 
     attr_reader :data
+    attr_accessor :key
 
     def to_s
       @data.to_a.inspect
@@ -66,15 +69,19 @@ module RedAmber
     end
 
     def numeric?
-      %i[int8 uint8 int16 uint16 int32 uint32 int64 uint64 float double].member? type
+      type_class < Arrow::NumericDataType
     end
 
     def string?
       type == :string
     end
 
-    def data_type
-      @data.value_type
+    def temporal?
+      type_class < Arrow::TemporalDataType
+    end
+
+    def type_class
+      @data.value_data_type.class
     end
 
     # def each() end
@@ -90,7 +97,23 @@ module RedAmber
     # def each_chunk() end
 
     def tally
-      values.tally
+      hash = values.tally
+      if (type_class < Arrow::FloatingPointDataType) && is_nan.any
+        a = 0
+        hash.each do |key, value|
+          if key.is_a?(Float) && key.nan?
+            hash.delete(key)
+            a += value
+          end
+        end
+        hash[Float::NAN] = a
+      end
+      hash
+    end
+
+    def value_counts
+      values, counts = Arrow::Function.find(:value_counts).execute([data]).value.fields
+      values.zip(counts).to_h
     end
 
     def n_nulls

data/lib/red_amber/vector_compensable.rb

@@ -0,0 +1,68 @@
+# 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
+  # mix-ins for class Vector
+  # Functions to make up some data (especially missing) for new data.
+  module VectorCompensable
+    # [Ternary]: replace_with(booleans, replacements) => vector
+    # Replace items selected with a boolean mask
+    #
+    # (from Arrow C++ inline doc.)
+    # Given an array and a boolean mask (either scalar or of equal length),
+    # along with replacement values (either scalar or array),
+    # each element of the array for which the corresponding mask element is
+    # true will be replaced by the next value from the replacements,
+    # or with null if the mask is null.
+    # Hence, for replacement arrays, len(replacements) == sum(mask == true).
+
+    def replace_with(booleans, replacements = nil)
+      specifier =
+        if booleans.is_a?(Arrow::BooleanArray)
+          booleans
+        elsif booleans.is_a?(Vector) && booleans.boolean?
+          booleans.data
+        elsif booleans.is_a?(Array) && booleans?(booleans)
+          Arrow::BooleanArray.new(booleans)
+        else
+          raise VectorTypeError, 'Not a valid type'
+        end
+      raise VectorArgumentError, 'Booleans size unmatch' if specifier.length != size
+      raise VectorArgumentError, 'Booleans not have any `true`' unless specifier.any?
+
+      r = Array(replacements) # scalar to [scalar]
+      r = [nil] if r.empty?
+
+      replacer =
+        if r.size == 1
+          case replacements
+          when Arrow::Array then replacements
+          when Vector then replacements.data
+          else
+            Arrow::Array.new(r * specifier.to_a.count(true)) # broadcast
+          end
+        else
+          Arrow::Array.new(r)
+        end
+      replacer = data.class.new(replacer) if replacer.uniq == [nil]
+
+      raise VectorArgumentError, 'Replacements size unmatch' if Array(specifier).count(true) != replacer.length
+
+      values = replacer.class.new(data)
+
+      datum = find('replace_with_mask').execute([values, specifier, replacer])
+      take_out_element_wise(datum)
+    end
+
+    # (related functions)
+    # fill_null_backward, fill_null_forward
+
+    private
+
+    def booleans?(enum)
+      enum.all? { |e| e.is_a?(TrueClass) || e.is_a?(FalseClass) || e.is_a?(NilClass) }
+    end
+  end
+end