Skip to content

Commit 5c735c2

Browse files
Sachinn-64Sachinn-64
committed
feat: add stats/nanrange-by
1 parent 4304bee commit 5c735c2

13 files changed

Lines changed: 3959 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/stats/nanrange-by/README.md‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
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+
# nanrangeBy
22+
23+
> Compute the [**range**][range] along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a callback function, ignoring `NaN` values.
24+
25+
<section class="intro">
26+
27+
The [**range**][range] is defined as the difference between the maximum and minimum values.
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<section class="usage">
34+
35+
## Usage
36+
37+
```javascript
38+
var nanrangeBy = require( '@stdlib/stats/nanrange-by' );
39+
```
40+
41+
#### nanrangeBy( x\[, options], clbk\[, thisArg] )
42+
43+
Computes the [**range**][range] along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a callback function, ignoring `NaN` values.
44+
45+
```javascript
46+
var array = require( '@stdlib/ndarray/array' );
47+
48+
var x = array( [ -1.0, 2.0, NaN ] );
49+
50+
function clbk( v ) {
51+
return v * 2.0;
52+
}
53+
54+
var y = nanrangeBy( x, clbk );
55+
// returns <ndarray>[ 6.0 ]
56+
```
57+
58+
The function has the following parameters:
59+
60+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
61+
- **options**: function options (_optional_).
62+
- **clbk**: callback function.
63+
- **thisArg**: callback function execution context (_optional_).
64+
65+
The invoked callback is provided three arguments:
66+
67+
- **value**: current array element.
68+
- **index**: current array element index.
69+
- **array**: input ndarray.
70+
71+
To set the callback execution context, provide a `thisArg`.
72+
73+
<!-- eslint-disable no-invalid-this -->
74+
75+
```javascript
76+
var array = require( '@stdlib/ndarray/array' );
77+
78+
var x = array( [ -1.0, 2.0, NaN ] );
79+
80+
function clbk( v ) {
81+
this.count += 1;
82+
return v * 2.0;
83+
}
84+
85+
var ctx = {
86+
'count': 0
87+
};
88+
var y = nanrangeBy( x, clbk, ctx );
89+
// returns <ndarray>[ 6.0 ]
90+
91+
var count = ctx.count;
92+
// returns 3
93+
```
94+
95+
The function accepts the following options:
96+
97+
- **dims**: list of dimensions over which to perform a reduction. If not provided, the function performs a reduction over all elements in a provided input [ndarray][@stdlib/ndarray/ctor].
98+
- **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. Must be a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
99+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [ndarray][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
100+
101+
By default, the function performs a reduction over all elements in a provided input [ndarray][@stdlib/ndarray/ctor]. To perform a reduction over specific dimensions, provide a `dims` option.
102+
103+
```javascript
104+
var array = require( '@stdlib/ndarray/array' );
105+
106+
function clbk( v ) {
107+
return v * 100.0;
108+
}
109+
110+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
111+
'shape': [ 2, 2 ],
112+
'order': 'row-major'
113+
});
114+
// returns <ndarray>[ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
115+
116+
var y = nanrangeBy( x, {
117+
'dims': [ 0 ]
118+
}, clbk );
119+
// returns <ndarray>[ 200.0, 200.0 ]
120+
121+
y = nanrangeBy( x, {
122+
'dims': [ 1 ]
123+
}, clbk );
124+
// returns <ndarray>[ 300.0, 700.0 ]
125+
126+
y = nanrangeBy( x, {
127+
'dims': [ 0, 1 ]
128+
}, clbk );
129+
// returns <ndarray>[ 700.0 ]
130+
```
131+
132+
By default, the function excludes reduced dimensions from the output [ndarray][@stdlib/ndarray/ctor]. To include the reduced dimensions as singleton dimensions, set the `keepdims` option to `true`.
133+
134+
```javascript
135+
var array = require( '@stdlib/ndarray/array' );
136+
137+
function clbk( v ) {
138+
return v * 100.0;
139+
}
140+
141+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
142+
'shape': [ 2, 2 ],
143+
'order': 'row-major'
144+
});
145+
// returns <ndarray>[ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
146+
147+
var y = nanrangeBy( x, {
148+
'dims': [ 0 ],
149+
'keepdims': true
150+
}, clbk );
151+
// returns <ndarray>[ [ 200.0, 200.0 ] ]
152+
153+
y = nanrangeBy( x, {
154+
'dims': [ 1 ],
155+
'keepdims': true
156+
}, clbk );
157+
// returns <ndarray>[ [ 300.0 ], [ 700.0 ] ]
158+
159+
y = nanrangeBy( x, {
160+
'dims': [ 0, 1 ],
161+
'keepdims': true
162+
}, clbk );
163+
// returns <ndarray>[ [ 700.0 ] ]
164+
```
165+
166+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a [data type][@stdlib/ndarray/dtypes] determined by the function's output data type [policy][@stdlib/ndarray/output-dtype-policies]. To override the default behavior, set the `dtype` option.
167+
168+
```javascript
169+
var getDType = require( '@stdlib/ndarray/dtype' );
170+
var array = require( '@stdlib/ndarray/array' );
171+
172+
function clbk( v ) {
173+
return v * 100.0;
174+
}
175+
176+
var x = array( [ -1.0, 2.0, -3.0 ], {
177+
'dtype': 'generic'
178+
});
179+
180+
var y = nanrangeBy( x, {
181+
'dtype': 'float64'
182+
}, clbk );
183+
// returns <ndarray>[ 500.0 ]
184+
185+
var dt = String( getDType( y ) );
186+
// returns 'float64'
187+
```
188+
189+
#### nanrangeBy.assign( x, out\[, options], clbk\[, thisArg] )
190+
191+
Computes the [**range**][range] along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a callback function and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor].
192+
193+
```javascript
194+
var array = require( '@stdlib/ndarray/array' );
195+
var zeros = require( '@stdlib/ndarray/zeros' );
196+
197+
function clbk( v ) {
198+
return v * 100.0;
199+
}
200+
201+
var x = array( [ -1.0, 2.0, NaN ] );
202+
var y = zeros( [] );
203+
204+
var out = nanrangeBy.assign( x, y, clbk );
205+
// returns <ndarray>[ 300.0 ]
206+
207+
var bool = ( out === y );
208+
// returns true
209+
```
210+
211+
The method has the following parameters:
212+
213+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
214+
- **out**: output [ndarray][@stdlib/ndarray/ctor].
215+
- **options**: function options (_optional_).
216+
- **clbk**: callback function.
217+
- **thisArg**: callback execution context (_optional_).
218+
219+
The method accepts the following options:
220+
221+
- **dims**: list of dimensions over which to perform a reduction. If not provided, the function performs a reduction over all elements in a provided input [ndarray][@stdlib/ndarray/ctor].
222+
223+
</section>
224+
225+
<!-- /.usage -->
226+
227+
<section class="notes">
228+
229+
## Notes
230+
231+
- A provided callback function should return a numeric value.
232+
- If a provided callback function returns `NaN`, the value is ignored.
233+
- If a provided callback function does not return any value (or equivalently, explicitly returns `undefined`), the value is **ignored**.
234+
- Setting the `keepdims` option to `true` can be useful when wanting to ensure that the output [ndarray][@stdlib/ndarray/ctor] is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with ndarrays having the same shape as the input [ndarray][@stdlib/ndarray/ctor].
235+
- The output data type [policy][@stdlib/ndarray/output-dtype-policies] only applies to the main function and specifies that, by default, the function must return an [ndarray][@stdlib/ndarray/ctor] having a real-valued or "generic" [data type][@stdlib/ndarray/dtypes]. For the `assign` method, the output [ndarray][@stdlib/ndarray/ctor] is allowed to have any supported output [data type][@stdlib/ndarray/dtypes].
236+
237+
</section>
238+
239+
<!-- /.notes -->
240+
241+
<section class="examples">
242+
243+
## Examples
244+
245+
<!-- eslint no-undef: "error" -->
246+
247+
```javascript
248+
var filledarrayBy = require( '@stdlib/array/filled-by' );
249+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
250+
var getDType = require( '@stdlib/ndarray/dtype' );
251+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
252+
var ndarray = require( '@stdlib/ndarray/ctor' );
253+
var nanrangeBy = require( '@stdlib/stats/nanrange-by' );
254+
255+
// Define a function for generating an object having a random value:
256+
function random() {
257+
return {
258+
'value': discreteUniform( 0, 20 )
259+
};
260+
}
261+
262+
// Generate an array of random objects:
263+
var xbuf = filledarrayBy( 25, 'generic', random );
264+
265+
// Wrap in an ndarray:
266+
var x = new ndarray( 'generic', xbuf, [ 5, 5 ], [ 5, 1 ], 0, 'row-major' );
267+
console.log( ndarray2array( x ) );
268+
269+
// Define an accessor function:
270+
function accessor( v ) {
271+
return v.value * 100;
272+
}
273+
274+
// Perform a reduction:
275+
var opts = {
276+
'dims': [ 0 ]
277+
};
278+
var y = nanrangeBy( x, opts, accessor );
279+
280+
// Resolve the output array data type:
281+
var dt = getDType( y );
282+
console.log( dt );
283+
284+
// Print the results:
285+
console.log( ndarray2array( y ) );
286+
```
287+
288+
</section>
289+
290+
<!-- /.examples -->
291+
292+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
293+
294+
<section class="related">
295+
296+
</section>
297+
298+
<!-- /.related -->
299+
300+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
301+
302+
<section class="links">
303+
304+
[range]: https://en.wikipedia.org/wiki/Range_%28statistics%29
305+
306+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
307+
308+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
309+
310+
[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/output-dtype-policies
311+
312+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/broadcast-shapes
313+
314+
</section>
315+
316+
<!-- /.links -->

0 commit comments

Comments
 (0)