red_amber 0.1.5 → 0.1.8

data/doc/Vector.md

@@ -18,6 +18,13 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
 
   ```ruby
   vector = RedAmber::Vector.new([1, 2, 3])
+  # or
+  vector = RedAmber::Vector.new(1, 2, 3)
+  # or
+  vector = RedAmber::Vector.new(1..3)
+  # or
+  vector = RedAmber::Vector.new(Arrow::Array([1, 2, 3])
+
   # =>
   #<RedAmber::Vector(:uint8, size=3):0x000000000000f514>
   [1, 2, 3]
@@ -29,29 +36,46 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
 
 ### `values`, `to_a`, `entries`
 
+### `indices`, `indexes`, `indeces`
+
+  Return indices in an Array.
+
+### `to_ary`
+
+  It implicitly converts a Vector to an Array when required.
+
+  ```ruby
+  [1, 2] + Vector.new([3, 4])
+
+  # =>
+  [1, 2, 3, 4]
+  ```
+
 ### `size`, `length`, `n_rows`, `nrow`
 
+### `empty?`
+
 ### `type`
 
 ### `boolean?`, `numeric?`, `string?`, `temporal?`
 
 ### `type_class`
 
-### [ ] `each` (not impremented yet)
-
-### [ ] `chunked?` (not impremented yet)
+### `each`
 
-### [ ] `n_chunks` (not impremented yet)
-
-### [ ] `each_chunk` (not impremented yet)
+  If block is not given, returns Enumerator.
 
 ### `n_nils`, `n_nans`
 
   - `n_nulls` is an alias of `n_nils`
 
+### `has_nil?`
+
+  Returns `true` if self has any `nil`. Otherwise returns `false`.
+
 ### `inspect(limit: 80)`
 
-  - `limit` sets size limit to display long array.
+  - `limit` sets size limit to display a long array.
 
     ```ruby
     vector = RedAmber::Vector.new((1..50).to_a)
@@ -60,6 +84,47 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, ... ]
     ```
 
+## Selecting Values
+
+### `take(indices)`, `[](indices)`
+
+- Acceptable class for indices:
+  - Integer, Float
+  - Vector of integer or float
+  - Arrow::Arry of integer or float
+- Negative index is also OK like the Ruby's primitive Array.
+
+```ruby
+array = RedAmber::Vector.new(%w[A B C D E])
+indices = RedAmber::Vector.new([0.1, -0.5, -5.1])
+array.take(indices)
+# or
+array[indices]
+
+# =>
+#<RedAmber::Vector(:string, size=3):0x000000000000f820>
+["A", "E", "A"]
+```
+
+### `filter(booleans)`, `[](booleans)`
+
+- Acceptable class for booleans:
+  - An array of true, false, or nil
+  - Boolean Vector
+  - Arrow::BooleanArray
+
+```ruby
+array = RedAmber::Vector.new(%w[A B C D E])
+booleans = [true, false, nil, false, true]
+array.filter(booleans)
+# or
+array[booleans]
+
+# =>
+#<RedAmber::Vector(:string, size=2):0x000000000000f21c>
+["A", "E"]
+```
+
 ## Functions
 
 ### Unary aggregations: `vector.func => scalar`
@@ -68,8 +133,8 @@ Class `RedAmber::Vector` represents a series of data in the DataFrame.
 
 | Method    |Boolean|Numeric|String|Options|Remarks|
 | ----------- | --- | --- | --- | --- | --- |
-| ✓ `all`     |  ✓  |     |     | ✓ ScalarAggregate|     |
-| ✓ `any`     |  ✓  |     |     | ✓ ScalarAggregate|     |
+| ✓ `all?`     |  ✓  |     |     | ✓ ScalarAggregate| alias `all` |
+| ✓ `any?`     |  ✓  |     |     | ✓ ScalarAggregate| alias `any` |
 | ✓ `approximate_median`|  |✓|  | ✓ ScalarAggregate| alias `median`|
 | ✓ `count`   |  ✓  |  ✓  |  ✓  | ✓  Count  |     |
 | ✓ `count_distinct`| ✓ | ✓ | ✓ | ✓  Count  |alias `count_uniq`|
@@ -99,9 +164,9 @@ double = RedAmber::Vector.new([1, 0/0.0, -1/0.0, 1/0.0, nil, ""])
 [1.0, NaN, -Infinity, Infinity, nil, 0.0]
 
 double.count #=> 5
-double.count(opts: {mode: :only_valid}) #=> 5, default
-double.count(opts: {mode: :only_null}) #=> 1
-double.count(opts: {mode: :all}) #=> 6
+double.count(mode: :only_valid) #=> 5, default
+double.count(mode: :only_null) #=> 1
+double.count(mode: :all) #=> 6
 
 boolean = RedAmber::Vector.new([true, true, nil])
 #=>
@@ -109,8 +174,8 @@ boolean = RedAmber::Vector.new([true, true, nil])
 [true, true, nil]
 
 boolean.all #=> true
-boolean.all(opts: {skip_nulls: true}) #=> true
-boolean.all(opts: {skip_nulls: false}) #=> false
+boolean.all(skip_nulls: true) #=> true
+boolean.all(skip_nulls: false) #=> false
 ```
 
 ### Unary element-wise: `vector.func => vector`
@@ -144,6 +209,37 @@ boolean.all(opts: {skip_nulls: false}) #=> false
 | ✓ `tan`      |     |  ✓  |     |     |       |
 | ✓ `trunc`    |     |  ✓  |     |     |       |
 
+Examples of options for `#round`;
+
+- `:n-digits` The number of digits to show.
+- `round_mode` Specify rounding mode.
+
+```ruby
+double = RedAmber::Vector.new([15.15, 2.5, 3.5, -4.5, -5.5])
+# => [15.15, 2.5, 3.5, -4.5, -5.5]
+double.round
+# => [15.0, 2.0, 4.0, -4.0, -6.0]
+double.round(mode: :half_to_even)
+# => Default. Same as double.round
+double.round(mode: :towards_infinity)
+# => [16.0, 3.0, 4.0, -5.0, -6.0]
+double.round(mode: :half_up)
+# => [15.0, 3.0, 4.0, -4.0, -5.0]
+double.round(mode: :half_towards_zero)
+# => [15.0, 2.0, 3.0, -4.0, -5.0]
+double.round(mode: :half_towards_infinity)
+# => [15.0, 3.0, 4.0, -5.0, -6.0]
+double.round(mode: :half_to_odd)
+# => [15.0, 3.0, 3.0, -5.0, -5.0]
+
+double.round(n_digits: 0)
+# => Default. Same as double.round
+double.round(n_digits: 1)
+# => [15.2, 2.5, 3.5, -4.5, -5.5]
+double.round(n_digits: -1)
+# => [20.0, 0.0, 0.0, -0.0, -10.0]
+```
+
 ### Binary element-wise: `vector.func(vector) => vector`
 
   ![binary element-wise](doc/image/../../image/vector/binary_element_wise.png)
@@ -203,6 +299,9 @@ boolean.all(opts: {skip_nulls: false}) #=> false
   vector.tally #=> {NaN=>2}
   vector.value_counts #=> {NaN=>2}
   ```
+### `index(element)`
+
+  Returns index of specified element.
 
 ### `sort_indexes`, `sort_indices`, `array_sort_indices`
 
@@ -215,42 +314,68 @@ boolean.all(opts: {skip_nulls: false}) #=> false
 ### [ ] (index functions)
 ### [ ] (other functions)
 
-## Coerce (not impremented)
+## Coerce
+
+```ruby
+vector = RedAmber::Vector.new(1,2,3)
+# => 
+#<RedAmber::Vector(:uint8, size=3):0x00000000000decc4>            
+[1, 2, 3]                                                         
+
+# Vector's `#*` method
+vector * -1
+# =>
+#<RedAmber::Vector(:int16, size=3):0x00000000000e3698>            
+[-1, -2, -3]                                                      
+
+# coerced calculation
+-1 * vector
+# => 
+#<RedAmber::Vector(:int16, size=3):0x00000000000ea4ac>            
+[-1, -2, -3]
+
+# `@-` operator
+-vector
+# =>
+#<RedAmber::Vector(:uint8, size=3):0x00000000000ee7b4>
+[255, 254, 253]
+```
 
 ## Update vector's value
-### `replace_with(booleans, replacements)` => vector
+### `replace(specifier, replacer)` => 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
+- Accepts Scalar, Range  of Integer, Vector, Array, Arrow::Array as a specifier
+- Accepts Scalar, Vector, Array and Arrow::Array as a replacer.
+- Boolean specifiers specify the position of replacer in true.
+- Index specifiers specify the position of replacer in indices.
+- replacer specifies the values to be replaced.
+  - The number of true in booleans must be equal to the length of replacer
 
 ```ruby
 vector = RedAmber::Vector.new([1, 2, 3])
 booleans = [true, false, true]
-replacemants = [4, 5]
-vector.replace_with(booleans, replacemants)
+replacer = [4, 5]
+vector.replace(booleans, replacer)
 # => 
 #<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
 [4, 2, 5] 
 ```
 
-- Scalar value in replacements can be broadcasted.
+- Scalar value in replacer can be broadcasted.
 
 ```ruby
-replacemant = 0
-vector.replace_with(booleans, replacement)
+replacer = 0
+vector.replace(booleans, replacer)
 # => 
 #<RedAmber::Vector(:uint8, size=3):0x000000000001ee10>
 [0, 2, 0] 
 ```
 
-- Returned data type is automatically up-casted by replacement.
+- Returned data type is automatically up-casted by replacer.
 
 ```ruby
-replacement = 1.0
-vector.replace_with(booleans, replacement)
+replacer = 1.0
+vector.replace(booleans, replacer)
 # => 
 #<RedAmber::Vector(:double, size=3):0x0000000000025d78>
 [1.0, 2.0, 1.0]
@@ -260,29 +385,29 @@ vector.replace_with(booleans, replacement)
 
 ```ruby
 booleans = [true, false, nil]
-replacemant = -1
-vec.replace_with(booleans, replacement)
+replacer = -1
+vec.replace(booleans, replacer)
 => 
 #<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
 [-1, 2, nil]
 ```
 
-- Replacemants can have nil in it.
+- replacer can have nil in it.
 
 ```ruby
 booleans = [true, false, true]
-replacemants = [nil]
-vec.replace_with(booleans, replacemants)
+replacer = [nil]
+vec.replace(booleans, replacer)
 => 
 #<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
 [nil, 2, nil]
 ```
 
-- If no replacemants specified, it is same as to specify nil.
+- If no replacer specified, it is same as to specify nil.
 
 ```ruby
 booleans = [true, false, true]
-vec.replace_with(booleans)
+vec.replace(booleans)
 => 
 #<RedAmber::Vector(:int8, size=3):0x00000000000304d0>
 [nil, 2, nil]
@@ -292,12 +417,27 @@ vec.replace_with(booleans)
 
 ```ruby
 vector = RedAmber::Vector.new(['A', 'B', 'NA'])
-vector.replace_with(vector == 'NA', nil)
+vector.replace(vector == 'NA', nil)
 # =>
 #<RedAmber::Vector(:string, size=3):0x000000000000f8ac>
 ["A", "B", nil]
 ```
 
+- Specifier in indices.
+
+Specified indices are used 'as sorted'. Position in indices and replacer may not have correspondence.
+
+```ruby
+vector = RedAmber::Vector.new([1, 2, 3])
+indices = [2, 1]
+replacer = [4, 5]
+vector.replace(indices, replacer)
+# =>
+#<RedAmber::Vector(:uint8, size=3):0x000000000000f244>
+[1, 4, 5] # not [1, 5, 4]
+```
+
+
 ### `fill_nil_forward`, `fill_nil_backward` => vector
 
 Propagate the last valid observation forward (or backward).
@@ -315,3 +455,73 @@ integer.fill_nil_backward
 #<RedAmber::Vector(:uint8, size=5):0x000000000000f974>
 [0, 1, 3, 3, nil]
 ```
+
+### `boolean_vector.if_else(true_choice, false_choice)` => vector
+
+Choose values based on self. Self must be a boolean Vector.
+
+`true_choice`, `false_choice` must be of the same type scalar / array / Vector.
+`nil` values in `cond` will be promoted to the output.
+
+This example will normalize negative indices to positive ones.
+
+```ruby
+indices = RedAmber::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]
+```
+
+### `is_in(values)` => boolean vector
+
+For each element in self, return true if it is found in given `values`, false otherwise.
+By default, nulls are matched against the value set. (This will be changed in SetLookupOptions: not impremented.)
+
+```ruby
+vector = RedAmber::Vector.new %W[A B C D]
+values = ['A', 'C', 'X']
+vector.is_in(values)
+
+# =>
+#<RedAmber::Vector(:boolean, size=4):0x000000000000f2a8>
+[true, false, true, false]
+```
+
+`values` are casted to the same Class of Vector.
+
+```ruby
+vector = RedAmber::Vector.new([1, 2, 255])
+vector.is_in(1, -1)
+
+# =>
+#<RedAmber::Vector(:boolean, size=3):0x000000000000f320>
+[true, false, true]
+```
+
+### `shift(amount = 1, fill: nil)`
+
+Shift vector's values by specified `amount`. Shifted space is filled by value `fill`.
+
+```ruby
+vector = RedAmber::Vector.new([1, 2, 3, 4, 5])
+vector.shift
+
+# =>
+#<RedAmber::Vector(:uint8, size=5):0x00000000000072d8>  
+[nil, 1, 2, 3, 4]
+
+vector.shift(-2)
+
+# =>
+#<RedAmber::Vector(:uint8, size=5):0x0000000000009970>  
+[3, 4, 5, nil, nil]
+
+vector.shift(fill: Float::NAN)
+
+# =>
+#<RedAmber::Vector(:double, size=5):0x0000000000011d3c>                    
+[NaN, 1.0, 2.0, 3.0, 4.0]
+```