Skip to content

Commit c5e77e6

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent d0bd8f1 commit c5e77e6

File tree

15 files changed

+2325
-1
lines changed

15 files changed

+2325
-1
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@
44
55
<section class="release" id="unreleased">
66

7-
## Unreleased (2025-06-02)
7+
## Unreleased (2025-06-03)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`cc66d3b`](https://github.com/stdlib-js/stdlib/commit/cc66d3b709812126709d2d6c8232ffc2dbd8b576) - add `ndarray/some-by` [(#7145)](https://github.com/stdlib-js/stdlib/pull/7145)
1314
- [`e05819a`](https://github.com/stdlib-js/stdlib/commit/e05819abfe0fbf982469653a85add02159e8b122) - add `someBy` to namespace
1415
- [`350203f`](https://github.com/stdlib-js/stdlib/commit/350203f7cb6419700b7b07e558b677fb177828f8) - add `ndarray/base/some-by` [(#7087)](https://github.com/stdlib-js/stdlib/pull/7087)
1516
- [`b933a8d`](https://github.com/stdlib-js/stdlib/commit/b933a8d4d5176d89e9efe541a65431275011a477) - add `countIf` to namespace
@@ -426,6 +427,7 @@ A total of 17 issues were closed in this release:
426427

427428
<details>
428429

430+
- [`cc66d3b`](https://github.com/stdlib-js/stdlib/commit/cc66d3b709812126709d2d6c8232ffc2dbd8b576) - **feat:** add `ndarray/some-by` [(#7145)](https://github.com/stdlib-js/stdlib/pull/7145) _(by Muhammad Haris, Athan Reines)_
429431
- [`b3d811d`](https://github.com/stdlib-js/stdlib/commit/b3d811d4d6ba1aed9aa1c5e012bba252c99929b6) - **refactor:** reorder expressions _(by Athan Reines)_
430432
- [`d76442e`](https://github.com/stdlib-js/stdlib/commit/d76442e623bf8b7e8e4d50b80e90315b84cbf771) - **refactor:** add missing assertion _(by Athan Reines)_
431433
- [`aec1d1b`](https://github.com/stdlib-js/stdlib/commit/aec1d1b77f2f320cf740954b3c8147b1c90aded7) - **chore:** add TODO _(by Athan Reines)_

‎some-by/README.md

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# someBy
22+
23+
> Test whether at least `n` elements along one or more [`ndarray`][@stdlib/ndarray/ctor] dimensions pass a test implemented by a predicate function.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var someBy = require( '@stdlib/ndarray/some-by' );
37+
```
38+
39+
#### someBy( x, n\[, options], predicate\[, thisArg] )
40+
41+
Tests whether at least `n` elements along one or more [`ndarray`][@stdlib/ndarray/ctor] dimensions pass a test implemented by a predicate function.
42+
43+
44+
```javascript
45+
var array = require( '@stdlib/ndarray/array' );
46+
47+
function predicate( value ) {
48+
return value > 0.0;
49+
}
50+
51+
// Create an input ndarray:
52+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
53+
// returns <ndarray>
54+
55+
// Perform reduction:
56+
var out = someBy( x, 2, predicate );
57+
// returns <ndarray>
58+
59+
console.log( out.get() );
60+
// => true
61+
```
62+
63+
The function accepts the following arguments:
64+
65+
- **x**: input [`ndarray`][@stdlib/ndarray/ctor].
66+
- **n**: number of elements which must pass the test implemented by a predicate function. May be either a scalar or an [`ndarray`][@stdlib/ndarray/ctor]. Must be [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the non-reduced dimensions of input [`ndarray`][@stdlib/ndarray/ctor]. Must have an integer [data type][@stdlib/ndarray/dtypes].
67+
- **options**: function options (_optional_).
68+
- **predicate**: predicate function.
69+
- **thisArg**: predicate execution context (_optional_).
70+
71+
The function accepts the following `options`:
72+
73+
- **dims**: list of dimensions over which to perform a reduction.
74+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [`ndarray`][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
75+
76+
By default, the function performs a reduction over all elements in a provided [`ndarray`][@stdlib/ndarray/ctor]. To reduce specific dimensions, set the `dims` option.
77+
78+
```javascript
79+
var array = require( '@stdlib/ndarray/array' );
80+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
81+
82+
function predicate( value ) {
83+
return value > 0.0;
84+
}
85+
86+
// Create an input ndarray:
87+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
88+
// returns <ndarray>
89+
90+
var opts = {
91+
'dims': [ 0, 1 ]
92+
};
93+
94+
// Perform reduction:
95+
var out = someBy( x, 2, opts, predicate );
96+
// returns <ndarray>
97+
98+
var v = ndarray2array( out );
99+
// returns [ true, true ]
100+
```
101+
102+
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`.
103+
104+
```javascript
105+
var array = require( '@stdlib/ndarray/array' );
106+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
107+
108+
function predicate( value ) {
109+
return value > 0.0;
110+
}
111+
112+
// Create an input ndarray:
113+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
114+
// returns <ndarray>
115+
116+
var opts = {
117+
'dims': [ 0, 1 ],
118+
'keepdims': true
119+
};
120+
121+
// Perform reduction:
122+
var out = someBy( x, 2, opts, predicate );
123+
// returns <ndarray>
124+
125+
var v = ndarray2array( out );
126+
// returns [ [ [ true, true ] ] ]
127+
```
128+
129+
To set the predicate function execution context, provide a `thisArg`.
130+
131+
<!-- eslint-disable no-invalid-this -->
132+
133+
```javascript
134+
var array = require( '@stdlib/ndarray/array' );
135+
136+
function predicate( value ) {
137+
this.count += 1;
138+
return value > 0.0;
139+
}
140+
141+
// Create an input ndarray:
142+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
143+
// returns <ndarray>
144+
145+
// Create a context object:
146+
var ctx = {
147+
'count': 0
148+
};
149+
150+
// Perform operation:
151+
var out = someBy( x, 2, predicate, ctx );
152+
// returns <ndarray>
153+
154+
var v = out.get();
155+
// returns true
156+
157+
var count = ctx.count;
158+
// returns 2
159+
```
160+
161+
#### someBy.assign( x, n, out\[, options], predicate\[, thisArg] )
162+
163+
Tests whether at least `n` elements along one or more [`ndarray`][@stdlib/ndarray/ctor] dimensions pass a test implemented by a predicate function and assigns results to a provided output [`ndarray`][@stdlib/ndarray/ctor].
164+
165+
166+
```javascript
167+
var array = require( '@stdlib/ndarray/array' );
168+
var empty = require( '@stdlib/ndarray/empty' );
169+
170+
function predicate( value ) {
171+
return value > 0.0;
172+
}
173+
174+
// Create an input ndarray:
175+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
176+
// returns <ndarray>
177+
178+
// Create an output ndarray:
179+
var y = empty( [], {
180+
'dtype': 'bool'
181+
});
182+
183+
// Perform reduction:
184+
var out = someBy.assign( x, 2, y, predicate );
185+
// returns <ndarray>
186+
187+
var bool = ( out === y );
188+
// returns true
189+
190+
var v = y.get();
191+
// returns true
192+
```
193+
194+
The function accepts the following arguments:
195+
196+
- **x**: input [`ndarray`][@stdlib/ndarray/ctor].
197+
- **n**: number of elements which must pass the test implemented by a predicate function. May be either a scalar or an [`ndarray`][@stdlib/ndarray/ctor]. Must be [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the non-reduced dimensions of input [`ndarray`][@stdlib/ndarray/ctor]. Must have an integer [data type][@stdlib/ndarray/dtypes].
198+
- **out**: output [`ndarray`][@stdlib/ndarray/ctor]. The output [`ndarray`][@stdlib/ndarray/ctor] must have a shape matching the non-reduced dimensions of the input [`ndarray`][@stdlib/ndarray/ctor].
199+
- **options**: function options (_optional_).
200+
- **predicate**: predicate function.
201+
- **thisArg**: predicate execution context (_optional_).
202+
203+
The function accepts the following `options`:
204+
205+
- **dims**: list of dimensions over which to perform a reduction.
206+
207+
By default, the function performs a reduction over all elements in a provided [`ndarray`][@stdlib/ndarray/ctor]. To reduce specific dimensions, set the `dims` option.
208+
209+
```javascript
210+
var array = require( '@stdlib/ndarray/array' );
211+
var empty = require( '@stdlib/ndarray/empty' );
212+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
213+
214+
function predicate( value ) {
215+
return value > 0.0;
216+
}
217+
218+
// Create an input ndarray:
219+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 0.0, 6.0 ] ] ] );
220+
// returns <ndarray>
221+
222+
// Create an output ndarray:
223+
var y = empty( [ 2 ], {
224+
'dtype': 'bool'
225+
});
226+
227+
var opts = {
228+
'dims': [ 0, 1 ]
229+
};
230+
231+
// Perform reduction:
232+
var out = someBy.assign( x, 2, y, opts, predicate );
233+
234+
var bool = ( out === y );
235+
// returns true
236+
237+
var v = ndarray2array( y );
238+
// returns [ true, true ]
239+
```
240+
241+
</section>
242+
243+
<!-- /.usage -->
244+
245+
<section class="notes">
246+
247+
## Notes
248+
249+
- The predicate function is provided the following arguments:
250+
251+
- **value**: current array element.
252+
- **indices**: current array element indices.
253+
- **arr**: the input ndarray.
254+
255+
</section>
256+
257+
<!-- /.notes -->
258+
259+
<section class="examples">
260+
261+
## Examples
262+
263+
<!-- eslint no-undef: "error" -->
264+
265+
```javascript
266+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
267+
var isEven = require( '@stdlib/assert/is-even' ).isPrimitive;
268+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
269+
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
270+
var fillBy = require( '@stdlib/ndarray/fill-by' );
271+
var zeros = require( '@stdlib/ndarray/zeros' );
272+
var someBy = require( '@stdlib/ndarray/some-by' );
273+
274+
var x = zeros( [ 2, 4, 5 ], {
275+
'dtype': 'float64'
276+
});
277+
x = fillBy( x, discreteUniform( 0, 10 ) );
278+
console.log( ndarray2array( x ) );
279+
280+
var n = scalar2ndarray( 4, {
281+
'dtype': 'int8'
282+
});
283+
var y = someBy( x, n, isEven );
284+
console.log( y.get() );
285+
```
286+
287+
</section>
288+
289+
<!-- /.examples -->
290+
291+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
292+
293+
<section class="related">
294+
295+
</section>
296+
297+
<!-- /.related -->
298+
299+
<section class="links">
300+
301+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray/tree/main/ctor
302+
303+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/ndarray/tree/main/base/broadcast-shapes
304+
305+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray/tree/main/dtypes
306+
307+
<!-- <related-links> -->
308+
309+
<!-- </related-links> -->
310+
311+
</section>
312+
313+
<!-- /.links -->

0 commit comments

Comments
 (0)