Skip to content

Commit 4d89dc1

Browse files
headlessNodeheadlessNode
committed
feat: add ndarray/find
1 parent 6b28a8a commit 4d89dc1

File tree

15 files changed

+1729
-1199
lines changed

15 files changed

+1729
-1199
lines changed

‎lib/node_modules/@stdlib/ndarray/find/README.md‎

Lines changed: 192 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ limitations under the License.
1818
1919
-->
2020

21-
# findElement
21+
# find
2222

23-
> Return the first element in the [ndarray][@stdlib/ndarray/ctor] that passes a test implemented by a predicate function.
23+
> Return a new [ndarray][@stdlib/ndarray/ctor] containing the first elements which pass a test implemented by a predicate function along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.
2424
2525
<section class="intro">
2626

@@ -32,128 +32,235 @@ limitations under the License.
3232

3333
## Usage
3434

35+
<!-- eslint-disable no-redeclare -->
36+
3537
```javascript
36-
var findElement = require( '@stdlib/ndarray/find' );
38+
var find = require( '@stdlib/ndarray/find' );
3739
```
3840

39-
#### findElement( x\[, options], predicate\[, thisArg] )
41+
<!-- eslint-enable no-redeclare -->
42+
43+
#### find( x\[, sentinelValue]\[, options], predicate\[, thisArg] )
4044

41-
Return the first element in the [ndarray][@stdlib/ndarray/ctor] that passes a test implemented by a predicate function.
45+
Returns a new [ndarray][@stdlib/ndarray/ctor] containing the first elements which pass a test implemented by a predicate function along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.
4246

4347
<!-- eslint-disable no-invalid-this, max-len -->
4448

4549
```javascript
46-
var Float64Array = require( '@stdlib/array/float64' );
47-
var ndarray = require( '@stdlib/ndarray/ctor' );
48-
var ndarray2array = require( '@stdlib/ndarray/to-array' );
50+
var array = require( '@stdlib/ndarray/array' );
4951

50-
function predicate( z ) {
51-
return z > 6.0;
52+
function isEven( value ) {
53+
return value % 2.0 === 0.0;
5254
}
5355

54-
var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
55-
var shape = [ 2, 3 ];
56-
var strides = [ 6, 1 ];
57-
var offset = 1;
58-
59-
var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
56+
// Create an input ndarray:
57+
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
6058
// returns <ndarray>
6159

62-
var arr = ndarray2array( x );
63-
// returns [ [ 2.0, 3.0, 4.0 ], [ 8.0, 9.0, 10.0 ] ]
60+
// Perform reduction:
61+
var out = find( x, isEven );
62+
// returns <ndarray>
6463

65-
var y = findElement( x, predicate );
66-
// returns 8.0
64+
var v = out.get();
65+
// returns 2.0
6766
```
6867

6968
The function accepts the following arguments:
7069

7170
- **x**: input [ndarray][@stdlib/ndarray/ctor].
71+
- **sentinelValue**: the value to return when no element passes the test. May be either a scalar value or a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
7272
- **options**: function options _(optional)_.
7373
- **predicate**: predicate function.
7474
- **thisArg**: predicate function execution context _(optional)_.
7575

7676
The function accepts the following options:
7777

78-
- **order**: index iteration order. By default, the function iterates over elements according to the [layout order][@stdlib/ndarray/orders] of the provided [ndarray][@stdlib/ndarray/ctor]. Accordingly, for row-major input [ndarrays][@stdlib/ndarray/ctor], the last dimension indices increment fastest. For column-major input [ndarrays][@stdlib/ndarray/ctor], the first dimension indices increment fastest. To override the inferred order and ensure that indices increment in a specific manner, regardless of the input [ndarray][@stdlib/ndarray/ctor]'s layout order, explicitly set the iteration order. Note, however, that iterating according to an order which does not match that of the input [ndarray][@stdlib/ndarray/ctor] may, in some circumstances, result in performance degradation due to cache misses. Must be either `'row-major'` or `'column-major'`.
78+
- **dims**: list of dimensions over which to perform a reduction.
79+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [ndarray][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
7980

80-
By default, the output element's [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor].
81-
82-
<!-- eslint-disable max-len -->
81+
By default, the function performs reduction over all all elements in a provided [ndarray][@stdlib/ndarray/ctor]. To reduce specific dimensions, set the `dims` option.
8382

8483
```javascript
85-
var Float64Array = require( '@stdlib/array/float64' );
86-
var ndarray = require( '@stdlib/ndarray/ctor' );
84+
var array = require( '@stdlib/ndarray/array' );
8785
var ndarray2array = require( '@stdlib/ndarray/to-array' );
8886

89-
function predicate( z ) {
90-
return z > 3.0;
87+
function isEven( value ) {
88+
return value % 2.0 === 0.0;
9189
}
9290

93-
var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
94-
var shape = [ 2, 3 ];
95-
var strides = [ 6, 1 ];
96-
var offset = 1;
91+
// Create an input ndarray:
92+
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
93+
// returns <ndarray>
94+
95+
var opts = {
96+
'dims': [ 0 ]
97+
};
9798

98-
var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
99+
// Perform reduction:
100+
var out = find( x, opts, isEven );
99101
// returns <ndarray>
100102

101-
var arr = ndarray2array( x );
102-
// returns [ [ 2.0, 3.0, 4.0 ], [ 8.0, 9.0, 10.0 ] ]
103+
var v = ndarray2array( out );
104+
// returns [ NaN, 2.0, NaN, 4.0 ]
105+
```
106+
107+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a shape matching only the non-reduced dimensions of the input [ndarray][@stdlib/ndarray/ctor] (i.e., the reduced dimensions are dropped). To include the reduced dimensions as singleton dimensions in the output [ndarray][@stdlib/ndarray/ctor], set the `keepdims` option to `true`.
108+
109+
```javascript
110+
var array = require( '@stdlib/ndarray/array' );
111+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
112+
113+
function isEven( value ) {
114+
return value % 2.0 === 0.0;
115+
}
116+
117+
// Create an input ndarray:
118+
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
119+
// returns <ndarray>
103120

104121
var opts = {
105-
'order': 'column-major'
122+
'dims': [ 0 ],
123+
'keepdims': true
106124
};
107-
var y = findElement( x, opts, predicate );
108-
// returns 8.0
109125

110-
opts = {
111-
'order': 'row-major'
112-
};
113-
y = findElement( x, opts, predicate );
114-
// returns 4.0
126+
// Perform reduction:
127+
var out = find( x, opts, isEven );
128+
// returns <ndarray>
129+
130+
var v = ndarray2array( out );
131+
// returns [ [ [ NaN, 2 ], [ NaN, 4 ] ] ]
132+
```
133+
134+
For a custom sentinel value for when no element passes the test, provide a `sentinelValue` argument.
135+
136+
```javascript
137+
var array = require( '@stdlib/ndarray/array' );
138+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
139+
140+
function isEven( value ) {
141+
return value % 2.0 === 0.0;
142+
}
143+
144+
// Create an input ndarray:
145+
var x = array( [ [ [ 1.0, 3.0 ], [ 5.0, 7.0 ] ], [ [ 9.0, 11.0 ], [ 13.0, 15.0 ] ] ] );
146+
// returns <ndarray>
147+
148+
// Perform reduction:
149+
var out = find( x, NaN, isEven );
150+
// returns <ndarray>
151+
152+
var v = out.get();
153+
// returns NaN
115154
```
116155

117156
To set the `predicate` function execution context, provide a `thisArg`.
118157

119-
<!-- eslint-disable no-invalid-this, max-len -->
158+
<!-- eslint-disable no-invalid-this -->
120159

121160
```javascript
122-
var Float64Array = require( '@stdlib/array/float64' );
123-
var ndarray = require( '@stdlib/ndarray/ctor' );
161+
var array = require( '@stdlib/ndarray/array' );
124162
var ndarray2array = require( '@stdlib/ndarray/to-array' );
125163

126-
function predicate( z ) {
164+
function isEven( value ) {
127165
this.count += 1;
128-
return z > 6.0;
166+
return value % 2.0 === 0.0;
129167
}
130168

131-
var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
132-
var shape = [ 2, 3 ];
133-
var strides = [ 6, 1 ];
134-
var offset = 1;
135-
136-
var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
169+
// Create an input ndarray:
170+
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
137171
// returns <ndarray>
138172

139-
var arr = ndarray2array( x );
140-
// returns [ [ 2.0, 3.0, 4.0 ], [ 8.0, 9.0, 10.0 ] ]
141-
142173
var ctx = {
143174
'count': 0
144175
};
145-
var y = findElement( x, predicate, ctx );
146-
// returns 8.0
176+
177+
// Perform reduction:
178+
var out = find( x, isEven, ctx );
179+
// returns <ndarray>
180+
181+
var v = out.get();
182+
// returns 2.0
147183

148184
var count = ctx.count;
149-
// returns 4
185+
// returns 2
150186
```
151187

152-
The `predicate` function is provided the following arguments:
188+
#### find.assign( x, y\[, sentinelValue]\[, options], predicate\[, thisArg] )
153189

154-
- **value**: current array element.
155-
- **indices**: current array element indices.
156-
- **arr**: the input [ndarray][@stdlib/ndarray/ctor].
190+
Finds the first elements which pass a test implemented by a predicate function along one or more [ndarray][@stdlib/ndarray/ctor] dimensions and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor].
191+
192+
```javascript
193+
var array = require( '@stdlib/ndarray/array' );
194+
var empty = require( '@stdlib/ndarray/empty' );
195+
196+
function isEven( value ) {
197+
return value % 2.0 === 0.0;
198+
}
199+
200+
// Create an input ndarray:
201+
var x = array( [ [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ], [ 7.0, 8.0 ] ] ] );
202+
// returns <ndarray>
203+
204+
// Create an output ndarray:
205+
var y = empty( [], {
206+
'dtype': x.dtype
207+
});
208+
209+
// Perform reduction:
210+
var out = find.assign( x, y, isEven );
211+
// returns <ndarray>
212+
213+
var bool = ( out === y );
214+
// returns true
215+
216+
var v = y.get();
217+
// returns 2.0
218+
```
219+
220+
The function accepts the following arguments:
221+
222+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
223+
- **y**: output [ndarray][@stdlib/ndarray/ctor].
224+
- **sentinelValue**: the value to return when no element passes the test. May be either a scalar value or a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
225+
- **options**: function options _(optional)_.
226+
- **predicate**: predicate function.
227+
- **thisArg**: predicate function execution context _(optional)_.
228+
229+
The function accepts the following `options`:
230+
231+
- **dims**: list of dimensions over which to perform a reduction.
232+
233+
```javascript
234+
var array = require( '@stdlib/ndarray/array' );
235+
var empty = require( '@stdlib/ndarray/empty' );
236+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
237+
238+
function isEven( value ) {
239+
return value % 2.0 === 0.0;
240+
}
241+
242+
// Create an input ndarray:
243+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
244+
// returns <ndarray>
245+
246+
// Create an output ndarray:
247+
var y = empty( [ 4 ], {
248+
'dtype': 'bool'
249+
});
250+
251+
var opts = {
252+
'dims': [ 0 ]
253+
};
254+
255+
// Perform reduction:
256+
var out = find.assign( x, y, opts, isEven );
257+
258+
var bool = ( out === y );
259+
// returns true
260+
261+
var v = ndarray2array( y );
262+
// returns [ NaN, 2.0, NaN, 4.0 ]
263+
```
157264

158265
</section>
159266

@@ -163,7 +270,18 @@ The `predicate` function is provided the following arguments:
163270

164271
## Notes
165272

166-
- The function returns **NaN** if no element in ndarray passes test implemented by the predicate function.
273+
- By default, when no `sentinelValue` is provided, the function returns a default sentinel value based on the input [ndarray][@stdlib/ndarray/ctor] [data-type][@stdlib/ndarray/dtypes]:
274+
275+
- floating-point numbers: `NaN`.
276+
- complex numbers: `NaN + NaNj`.
277+
- integers: maximum value.
278+
- boolean: `false`.
279+
280+
- The `predicate` function is provided the following arguments:
281+
282+
- **value**: current array element.
283+
- **indices**: current array element indices.
284+
- **arr**: the input [ndarray][@stdlib/ndarray/ctor].
167285

168286
</section>
169287

@@ -176,23 +294,20 @@ The `predicate` function is provided the following arguments:
176294
<!-- eslint no-undef: "error" -->
177295

178296
```javascript
179-
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
297+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
298+
var isEven = require( '@stdlib/assert/is-even' ).isPrimitive;
180299
var ndarray2array = require( '@stdlib/ndarray/to-array' );
181-
var naryFunction = require( '@stdlib/utils/nary-function' );
182-
var array = require( '@stdlib/ndarray/array' );
183-
var isPositive = require( '@stdlib/assert/is-positive-number' ).isPrimitive;
184-
var findElement = require( '@stdlib/ndarray/find' );
300+
var fillBy = require( '@stdlib/ndarray/fill-by' );
301+
var zeros = require( '@stdlib/ndarray/zeros' );
302+
var find = require( '@stdlib/ndarray/find' );
185303

186-
var buffer = discreteUniform( 10, -100, 100, {
187-
'dtype': 'generic'
188-
});
189-
var x = array( buffer, {
190-
'shape': [ 5, 2 ],
191-
'dtype': 'generic'
304+
var x = zeros( [ 2, 4, 5 ], {
305+
'dtype': 'float64'
192306
});
307+
x = fillBy( x, discreteUniform( 0, 10 ) );
193308
console.log( ndarray2array( x ) );
194309

195-
var y = findElement( x, naryFunction( isPositive, 1 ) );
310+
var y = find( x, isEven );
196311
console.log( y );
197312
```
198313

@@ -214,8 +329,6 @@ console.log( y );
214329

215330
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
216331

217-
[@stdlib/ndarray/orders]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/orders
218-
219332
<!-- <related-links> -->
220333

221334
<!-- </related-links> -->

0 commit comments

Comments
 (0)