doc/Vector.md in red_amber-0.1.5 vs doc/Vector.md in red_amber-0.1.6
- old
+ new
@@ -16,10 +16,17 @@
### New from an Array
```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]
```
@@ -27,12 +34,28 @@
### `to_s`
### `values`, `to_a`, `entries`
+### `indices`, `indexes`, `indeces`
+
+ Return indices in an Array
+
+### `to_ary`
+ Vector has `#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`
@@ -47,10 +70,14 @@
### `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.
```ruby
@@ -58,20 +85,61 @@
# =>
#<RedAmber::Vector(:uint8, size=50):0x000000000000f528>
[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`
| 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`|
|[ ]`index` | [ ] | [ ] | [ ] |[ ] Index | |
| ✓ `max` | ✓ | ✓ | ✓ | ✓ ScalarAggregate| |
@@ -201,11 +269,14 @@
vector = RedAmber::Vector.new(array)
vector.tally #=> {NaN=>2}
vector.value_counts #=> {NaN=>2}
```
+### `index(element)`
+ Returns index of specified element.
+
### `sort_indexes`, `sort_indices`, `array_sort_indices`
### [ ] `sort`, `sort_by`
### [ ] argmin, argmax
### [ ] (array functions)
@@ -216,90 +287,106 @@
### [ ] (other functions)
## Coerce (not impremented)
## 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]
```
- Position of nil in booleans is replaced with nil.
```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]
```
- An example to replace 'NA' to nil.
```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).
Or preserve nil if all previous values are nil or at the end.
@@ -312,6 +399,51 @@
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]
```