Skip to content

Commit 68ca019

Browse files
iampratik13iampratik13
committed
stats/mskmax
1 parent 97deb1c commit 68ca019

File tree

13 files changed

+3026
-0
lines changed

13 files changed

+3026
-0
lines changed

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

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
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+
# mskmax
22+
23+
> Compute the maximum value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a mask.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var mskmax = require( '@stdlib/stats/mskmax' );
31+
```
32+
33+
#### mskmax( x, mask\[, options] )
34+
35+
Compute the maximum value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions according to a mask.
36+
37+
```javascript
38+
var array = require( '@stdlib/ndarray/array' );
39+
40+
var x = array( [ -1.0, 2.0, -3.0 ] );
41+
var mask = array( [ 0, 0, 1 ] );
42+
43+
var y = mskmax( x, mask );
44+
// returns <ndarray>
45+
46+
var v = y.get();
47+
// returns 2.0
48+
```
49+
50+
The function has the following parameters:
51+
52+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
53+
- **mask**: mask [ndarray][@stdlib/ndarray/ctor]. Must have the same shape as `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.
54+
- **options**: function options (_optional_).
55+
56+
The function accepts the following options:
57+
58+
- **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].
59+
- **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. Must be a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
60+
- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned [ndarray][@stdlib/ndarray/ctor] as singleton dimensions. Default: `false`.
61+
62+
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.
63+
64+
```javascript
65+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
66+
var array = require( '@stdlib/ndarray/array' );
67+
68+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
69+
'shape': [ 2, 2 ],
70+
'order': 'row-major'
71+
});
72+
var mask = array( [ 0, 0, 1, 0 ], {
73+
'shape': [ 2, 2 ],
74+
'order': 'row-major'
75+
});
76+
var v = ndarray2array( x );
77+
// returns [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
78+
79+
var y = mskmax( x, mask, {
80+
'dims': [ 0 ]
81+
});
82+
// returns <ndarray>
83+
84+
v = ndarray2array( y );
85+
// returns [ -1.0, 4.0 ]
86+
87+
y = mskmax( x, mask, {
88+
'dims': [ 1 ]
89+
});
90+
// returns <ndarray>
91+
92+
v = ndarray2array( y );
93+
// returns [ 2.0, 4.0 ]
94+
95+
y = mskmax( x, mask, {
96+
'dims': [ 0, 1 ]
97+
});
98+
// returns <ndarray>
99+
100+
v = y.get();
101+
// returns 4.0
102+
```
103+
104+
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`.
105+
106+
```javascript
107+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
108+
var array = require( '@stdlib/ndarray/array' );
109+
110+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
111+
'shape': [ 2, 2 ],
112+
'order': 'row-major'
113+
});
114+
var mask = array( [ 0, 0, 1, 0 ], {
115+
'shape': [ 2, 2 ],
116+
'order': 'row-major'
117+
});
118+
119+
var v = ndarray2array( x );
120+
// returns [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]
121+
122+
var y = mskmax( x, mask, {
123+
'dims': [ 0 ],
124+
'keepdims': true
125+
});
126+
// returns <ndarray>
127+
128+
v = ndarray2array( y );
129+
// returns [ [ -1.0, 4.0 ] ]
130+
131+
y = mskmax( x, mask, {
132+
'dims': [ 1 ],
133+
'keepdims': true
134+
});
135+
// returns <ndarray>
136+
137+
v = ndarray2array( y );
138+
// returns [ [ 2.0 ], [ 4.0 ] ]
139+
140+
y = mskmax( x, mask, {
141+
'dims': [ 0, 1 ],
142+
'keepdims': true
143+
});
144+
// returns <ndarray>
145+
146+
v = ndarray2array( y );
147+
// returns [ [ 4.0 ] ]
148+
```
149+
150+
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.
151+
152+
```javascript
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( [ 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 array = require( '@stdlib/ndarray/array' );
176+
var zeros = require( '@stdlib/ndarray/zeros' );
177+
178+
var x = array( [ -1.0, 2.0, -3.0 ] );
179+
var mask = array( [ 0, 0, 1 ] );
180+
var y = zeros( [] );
181+
182+
var out = mskmax.assign( x, mask, y );
183+
// returns <ndarray>
184+
185+
var v = out.get();
186+
// returns 2.0
187+
188+
var bool = ( out === y );
189+
// returns true
190+
```
191+
192+
The method has the following parameters:
193+
194+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or generic [data type][@stdlib/ndarray/dtypes].
195+
- **mask**: mask [ndarray][@stdlib/ndarray/ctor]. Must have the same shape as `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.
196+
- **out**: output [ndarray][@stdlib/ndarray/ctor].
197+
- **options**: function options (_optional_).
198+
199+
The method accepts the following options:
200+
201+
- **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].
202+
203+
</section>
204+
205+
<!-- /.usage -->
206+
207+
<section class="notes">
208+
209+
## Notes
210+
211+
- 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].
212+
- 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].
213+
214+
</section>
215+
216+
<!-- /.notes -->
217+
218+
<section class="examples">
219+
220+
## Examples
221+
222+
<!-- eslint no-undef: "error" -->
223+
224+
```javascript
225+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
226+
var getDType = require( '@stdlib/ndarray/dtype' );
227+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
228+
var ndarray = require( '@stdlib/ndarray/ctor' );
229+
var mskmax = require( '@stdlib/stats/mskmax' );
230+
231+
// Generate an array of random numbers:
232+
var xbuf = discreteUniform( 25, 0, 20, {
233+
'dtype': 'generic'
234+
});
235+
236+
// Generate a mask array:
237+
var mbuf = discreteUniform( 25, 0, 1, {
238+
'dtype': 'generic'
239+
});
240+
241+
// Wrap in ndarrays:
242+
var x = new ndarray( 'generic', xbuf, [ 5, 5 ], [ 5, 1 ], 0, 'row-major' );
243+
var mask = new ndarray( 'generic', mbuf, [ 5, 5 ], [ 5, 1 ], 0, 'row-major' );
244+
console.log( ndarray2array( x ) );
245+
console.log( ndarray2array( mask ) );
246+
247+
// Perform a reduction:
248+
var y = mskmax( x, mask, {
249+
'dims': [ 0 ]
250+
});
251+
252+
// Resolve the output array data type:
253+
var dt = getDType( y );
254+
console.log( dt );
255+
256+
// Print the results:
257+
console.log( ndarray2array( y ) );
258+
```
259+
260+
</section>
261+
262+
<!-- /.examples -->
263+
264+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
265+
266+
<section class="related">
267+
268+
</section>
269+
270+
<!-- /.related -->
271+
272+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
273+
274+
<section class="links">
275+
276+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
277+
278+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
279+
280+
[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/output-dtype-policies
281+
282+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/broadcast-shapes
283+
284+
</section>
285+
286+
<!-- /.links -->

0 commit comments

Comments
 (0)