Skip to content

Commit ec9c99b

Browse files
iampratik13iampratik13
committed
stats/mskmax
1 parent 3138d95 commit ec9c99b

File tree

14 files changed

+3183
-0
lines changed

14 files changed

+3183
-0
lines changed

‎lib/node_modules/@stdlib/stats/mskmax/README.md‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
<!--
2+
@license Apache-2.0
3+
Copyright (c) 2025 The Stdlib Authors.
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
Unless required by applicable law or agreed to in writing, software
9+
distributed under the License is distributed on an "AS IS" BASIS,
10+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
See the License for the specific language governing permissions and
12+
limitations under the License.
13+
-->
14+
15+
# mskmax
16+
17+
> Compute the maximum value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a mask.
18+
<section class="usage">
19+
20+
## Usage
21+
22+
```javascript
23+
var mskmax = require( '@stdlib/stats/mskmax' );
24+
```
25+
26+
#### mskmax( x, mask\[, options] )
27+
28+
Compute the maximum value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a mask.
29+
30+
```javascript
31+
var Uint8Array = require( '@stdlib/array/uint8' );
32+
var array = require( '@stdlib/ndarray/array' );
33+
34+
var x = array( [ -1.0, 2.0, -3.0 ] );
35+
var mask = array( new Uint8Array( [ 0, 0, 1 ] ) );
36+
37+
var y = mskmax( x, mask );
38+
// returns <ndarray>
39+
40+
var v = y.get();
41+
// returns 2.0
42+
```
43+
44+
The function has the following parameters:
45+
46+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
47+
- **mask**: mask [ndarray][@stdlib/ndarray/ctor]. Must be [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with `x`. If a mask element is `0`, the corresponding element in `x` is considered valid. If a mask element is non-zero, the corresponding element in `x` is ignored.
48+
- **options**: function options (_optional_).
49+
50+
The function accepts the following options:
51+
52+
- **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].
53+
- **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. Must be a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
54+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [ndarray][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
55+
56+
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.
57+
58+
```javascript
59+
var Uint8Array = require( '@stdlib/array/uint8' );
60+
var mskmax = require( '@stdlib/stats/mskmax' );
61+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
62+
var array = require( '@stdlib/ndarray/array' );
63+
64+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
65+
'shape': [ 2, 2 ],
66+
'order': 'row-major'
67+
});
68+
var mask = array( new Uint8Array( [ 0, 0, 1, 0 ] ), {
69+
'shape': [ 2, 2 ],
70+
'order': 'row-major'
71+
});
72+
var v = ndarray2array( x );
73+
// returns [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
74+
75+
var y = mskmax( x, mask, {
76+
'dims': [ 0 ]
77+
});
78+
// returns <ndarray>
79+
80+
v = ndarray2array( y );
81+
// returns [ -1.0, 4.0 ]
82+
83+
y = mskmax( x, mask, {
84+
'dims': [ 1 ]
85+
});
86+
// returns <ndarray>
87+
88+
v = ndarray2array( y );
89+
// returns [ 2.0, 4.0 ]
90+
91+
y = mskmax( x, mask, {
92+
'dims': [ 0, 1 ]
93+
});
94+
// returns <ndarray>
95+
96+
v = y.get();
97+
// returns 4.0
98+
```
99+
100+
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`.
101+
102+
```javascript
103+
var Uint8Array = require( '@stdlib/array/uint8' );
104+
var mskmax = require( '@stdlib/stats/mskmax' );
105+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
106+
var array = require( '@stdlib/ndarray/array' );
107+
108+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
109+
'shape': [ 2, 2 ],
110+
'order': 'row-major'
111+
});
112+
var mask = array( new Uint8Array( [ 0, 0, 1, 0 ] ), {
113+
'shape': [ 2, 2 ],
114+
'order': 'row-major'
115+
});
116+
117+
var v = ndarray2array( x );
118+
// returns [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
119+
120+
var y = mskmax( x, mask, {
121+
'dims': [ 0 ],
122+
'keepdims': true
123+
});
124+
// returns <ndarray>
125+
126+
v = ndarray2array( y );
127+
// returns [ [ -1.0, 4.0 ] ]
128+
129+
y = mskmax( x, mask, {
130+
'dims': [ 1 ],
131+
'keepdims': true
132+
});
133+
// returns <ndarray>
134+
135+
v = ndarray2array( y );
136+
// returns [ [ 2.0 ], [ 4.0 ] ]
137+
138+
y = mskmax( x, mask, {
139+
'dims': [ 0, 1 ],
140+
'keepdims': true
141+
});
142+
// returns <ndarray>
143+
144+
v = ndarray2array( y );
145+
// returns [ [ 4.0 ] ]
146+
```
147+
148+
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.
149+
150+
```javascript
151+
var Uint8Array = require( '@stdlib/array/uint8' );
152+
var mskmax = require( '@stdlib/stats/mskmax' );
153+
var getDType = require( '@stdlib/ndarray/dtype' );
154+
var array = require( '@stdlib/ndarray/array' );
155+
156+
var x = array( [ -1.0, 2.0, -3.0 ], {
157+
'dtype': 'generic'
158+
});
159+
var mask = array( new Uint8Array( [ 0, 0, 1 ] ) );
160+
161+
var y = mskmax( x, mask, {
162+
'dtype': 'float64'
163+
});
164+
// returns <ndarray>
165+
166+
var dt = String( getDType( y ) );
167+
// returns 'float64'
168+
```
169+
170+
#### mskmax.assign( x, mask, out\[, options] )
171+
172+
Computes the maximum value of [ndarray][@stdlib/ndarray/ctor] along one or more dimensions and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor] according to mask.
173+
174+
```javascript
175+
var Uint8Array = require( '@stdlib/array/uint8' );
176+
var mskmax = require( '@stdlib/stats/mskmax' );
177+
var array = require( '@stdlib/ndarray/array' );
178+
var zeros = require( '@stdlib/ndarray/zeros' );
179+
180+
var x = array( [ -1.0, 2.0, -3.0 ] );
181+
var mask = array( new Uint8Array( [ 0, 0, 1 ] ) );
182+
var y = zeros( [] );
183+
184+
var out = mskmax.assign( x, mask, y );
185+
// returns <ndarray>
186+
187+
var v = out.get();
188+
// returns 2.0
189+
190+
var bool = ( out === y );
191+
// returns true
192+
```
193+
194+
The method has the following parameters:
195+
196+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or generic [data type][@stdlib/ndarray/dtypes].
197+
- **mask**: mask [ndarray][@stdlib/ndarray/ctor]. Must be [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with `x`. If a mask element is `0`, the corresponding element in `x` is considered valid. If a mask element is non-zero, the corresponding element in `x` is ignored.
198+
- **out**: output [ndarray][@stdlib/ndarray/ctor].
199+
- **options**: function options (_optional_).
200+
201+
The method accepts the following options:
202+
203+
- **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].
204+
205+
</section>
206+
207+
<!-- /.usage -->
208+
209+
<section class="notes">
210+
211+
## Notes
212+
213+
- 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].
214+
- 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 the same [data type][@stdlib/ndarray/dtypes] as the input [ndarray][@stdlib/ndarray/ctor]. For the `assign` method, the output [ndarray][@stdlib/ndarray/ctor] is allowed to have any supported output [data type][@stdlib/ndarray/dtypes].
215+
216+
</section>
217+
218+
<!-- /.notes -->
219+
220+
<section class="examples">
221+
222+
## Examples
223+
224+
<!-- eslint no-undef: "error" -->
225+
226+
```javascript
227+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
228+
var getDType = require( '@stdlib/ndarray/dtype' );
229+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
230+
var ndarray = require( '@stdlib/ndarray/ctor' );
231+
var mskmax = require( '@stdlib/stats/mskmax' );
232+
233+
// Generate an array of random numbers:
234+
var xbuf = discreteUniform( 25, 0, 20, {
235+
'dtype': 'generic'
236+
});
237+
238+
// Generate a mask array:
239+
var mbuf = discreteUniform( 25, 0, 1, {
240+
'dtype': 'uint8'
241+
});
242+
243+
// Wrap in ndarrays:
244+
var x = new ndarray( 'generic', xbuf, [ 5, 5 ], [ 5, 1 ], 0, 'row-major' );
245+
var mask = new ndarray( 'uint8', mbuf, [ 5, 5 ], [ 5, 1 ], 0, 'row-major' );
246+
console.log( ndarray2array( x ) );
247+
console.log( ndarray2array( mask ) );
248+
249+
// Perform a reduction:
250+
var y = mskmax( x, mask, {
251+
'dims': [ 0 ]
252+
});
253+
254+
// Resolve the output array data type:
255+
var dt = getDType( y );
256+
console.log( dt );
257+
258+
// Print the results:
259+
console.log( ndarray2array( y ) );
260+
```
261+
262+
</section>
263+
264+
<!-- /.examples -->
265+
266+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
267+
268+
<section class="related">
269+
270+
</section>
271+
272+
<!-- /.related -->
273+
274+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
275+
276+
<section class="links">
277+
278+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
279+
280+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
281+
282+
[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/output-dtype-policies
283+
284+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/broadcast-shapes
285+
286+
</section>
287+
288+
<!-- /.links -->

0 commit comments

Comments
 (0)