Skip to content

Commit f522872

Browse files
LoayAhmed304LoayAhmed304
committed
docs: add examples, docs and README.md
1 parent 372165a commit f522872

8 files changed

Lines changed: 493 additions & 35 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/base/where/README.md‎

Lines changed: 162 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ limitations under the License.
2020

2121
# Where
2222

23-
> Apply a condition to elements in two input ndarrays and assign results to elements in an output ndarray.
23+
> Applies a condition to elements in two input ndarrays and assigns results to elements in an output ndarray.
2424
2525
<section class="intro">
2626

@@ -30,32 +30,187 @@ limitations under the License.
3030

3131
<section class="usage">
3232

33+
## Usage
34+
35+
```javascript
36+
var where = require( '@stdlib/ndarray/base/where' );
37+
```
38+
39+
#### where( arrays )
40+
41+
Applies a condition to elements in two input ndarrays and assigns results to elements in an output ndarray.
42+
43+
<!-- eslint-disable max-len -->
44+
45+
```javascript
46+
var Float64Array = require( '@stdlib/array/float64' );
47+
var Uint8Array = require( '@stdlib/array/uint8' );
48+
49+
// Create data buffers:
50+
var cbuf = new Uint8Array( [ 1, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1 ] );
51+
var xbuf = 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 ] );
52+
var ybuf = 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 ] );
53+
var obuf = new Float64Array( 6 );
54+
55+
// Define the shape of the input and output arrays:
56+
var shape = [ 3, 1, 2 ];
57+
58+
// Define the array strides:
59+
var sc = [ 4, 4, 1 ];
60+
var sx = [ 4, 4, 1 ];
61+
var sy = [ 4, 4, 1 ];
62+
var so = [ 2, 2, 1 ];
63+
64+
// Define the index offsets:
65+
var oc = 1;
66+
var ox = 1;
67+
var oy = 1;
68+
var oo = 0;
69+
70+
// Create the input and output ndarrays:
71+
var condition = {
72+
'dtype': 'uint8',
73+
'data': cbuf,
74+
'shape': shape,
75+
'strides': sc,
76+
'offset': oc,
77+
'order': 'row-major'
78+
};
79+
var x = {
80+
'dtype': 'float64',
81+
'data': xbuf,
82+
'shape': shape,
83+
'strides': sx,
84+
'offset': ox,
85+
'order': 'row-major'
86+
};
87+
var y = {
88+
'dtype': 'float64',
89+
'data': ybuf,
90+
'shape': shape,
91+
'strides': sy,
92+
'offset': oy,
93+
'order': 'row-major'
94+
};
95+
var out = {
96+
'dtype': 'float64',
97+
'data': obuf,
98+
'shape': shape,
99+
'strides': so,
100+
'offset': oo,
101+
'order': 'row-major'
102+
};
103+
104+
// Apply the condition:
105+
where( [ condition, x, y, out ] );
106+
107+
console.log( out.data );
108+
// => <Float64Array>[ -2.0, -3.0, 6.0, 7.0, -10.0, -11.0 ]
109+
```
110+
111+
The function accepts the following arguments:
112+
113+
- **arrays**: array-like object containing three input ndarrays and one output ndarray.
114+
115+
Each provided ndarray should be an object with the following properties:
116+
117+
- **dtype**: data type.
118+
- **data**: data buffer.
119+
- **shape**: dimensions.
120+
- **strides**: stride lengths.
121+
- **offset**: index offset.
122+
- **order**: specifies whether an ndarray is row-major (C-style) or column major (Fortran-style).
33123

34124
</section>
35125

36126
<!-- /.usage -->
37127

128+
<section class="notes">
129+
130+
## Notes
131+
132+
- For very high-dimensional ndarrays which are non-contiguous, one should consider copying the underlying data to contiguous memory before conditionally assigning elements in order to achieve better performance.
133+
134+
</section>
135+
136+
<!-- /.notes -->
137+
38138
<section class="examples">
39139

140+
## Examples
141+
142+
<!-- eslint no-undef: "error" -->
143+
144+
```javascript
145+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
146+
var bernoulli = require( '@stdlib/random/base/bernoulli' ).factory;
147+
var filledarray = require( '@stdlib/array/filled' );
148+
var filledarrayBy = require( '@stdlib/array/filled-by' );
149+
var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
150+
var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
151+
var where = require( '@stdlib/ndarray/base/where' );
152+
153+
var N = 10;
154+
var shape = [ 5, 2 ];
155+
var condition = {
156+
'dtype': 'uint8',
157+
'data': filledarrayBy( N, 'uint8', bernoulli( 0.5 ) ),
158+
'shape': shape,
159+
'strides': [ 2, 1 ],
160+
'offset': 0,
161+
'order': 'row-major'
162+
};
163+
var x = {
164+
'dtype': 'generic',
165+
'data': filledarrayBy( N, 'generic', discreteUniform( 0, 100 ) ),
166+
'shape': shape,
167+
'strides': [ 2, 1 ],
168+
'offset': 0,
169+
'order': 'row-major'
170+
};
171+
var y = {
172+
'dtype': 'generic',
173+
'data': filledarrayBy( N, 'generic', discreteUniform( -100, 0 ) ),
174+
'shape': shape,
175+
'strides': [ 2, 1 ],
176+
'offset': 0,
177+
'order': 'row-major'
178+
};
179+
var out = {
180+
'dtype': 'generic',
181+
'data': filledarray( 0, N, 'generic' ),
182+
'shape': shape.slice(),
183+
'strides': shape2strides( shape, 'column-major' ),
184+
'offset': 0,
185+
'order': 'column-major'
186+
};
187+
188+
where( [ condition, x, y, out ] );
189+
190+
console.log( ndarray2array( condition.data, condition.shape, condition.strides, condition.offset, condition.order ) ); // eslint-disable-line max-len
191+
console.log( ndarray2array( x.data, x.shape, x.strides, x.offset, x.order ) );
192+
console.log( ndarray2array( y.data, y.shape, y.strides, y.offset, y.order ) );
193+
console.log( ndarray2array( out.data, out.shape, out.strides, out.offset, out.order ) ); // eslint-disable-line max-len
194+
```
195+
40196
</section>
41197

42198
<!-- /.examples -->
43199

44-
<!-- Section for related `stdlib` packages. -->
45-
46-
* * *
200+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
47201

48202
<section class="related">
49203

50-
51204
</section>
52205

53206
<!-- /.related -->
54207

55-
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
56-
57208
<section class="links">
58209

210+
<!-- <related-links> -->
211+
212+
<!-- </related-links> -->
213+
59214
</section>
60215

61216
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/where/benchmark/benchmark.2d_columnmajor.js‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ var sqrt = require( '@stdlib/math/base/special/sqrt' );
3030
var filledarray = require( '@stdlib/array/filled' );
3131
var filledarrayBy = require( '@stdlib/array/filled-by' );
3232
var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
33+
var format = require( '@stdlib/string/format' );
3334
var pkg = require( './../package.json' ).name;
3435
var where2d = require( './../lib/2d.js' );
3536

@@ -48,22 +49,24 @@ var order = 'column-major';
4849
* @private
4950
* @param {PositiveInteger} len - ndarray length
5051
* @param {NonNegativeIntegerArray} shape - ndarray shape
51-
* @param {string} xtype - first input ndarray data type
52-
* @param {string} ytype - second input ndarray data type
52+
* @param {string} ctype - first input ndarray data type
53+
* @param {string} xtype - second input ndarray data type
54+
* @param {string} ytype - third input ndarray data type
55+
* @param {string} otype - fourth input ndarray data type
5356
* @returns {Function} benchmark function
5457
*/
55-
function createBenchmark( len, shape, xtype, ytype ) {
58+
function createBenchmark( len, shape, ctype, xtype, ytype, otype ) {
5659
var condition;
5760
var out;
5861
var x;
5962
var y;
60-
condition = filledarrayBy( len, 'uint8', bernoulli( 0.5 ) );
63+
condition = filledarrayBy( len, ctype, bernoulli( 0.5 ) );
6164
x = filledarrayBy( len, xtype, discreteUniform( -100, 100 ) );
6265
y = filledarrayBy( len, ytype, discreteUniform( -100, 100 ) );
63-
out = filledarray( 0.0, len, xtype );
66+
out = filledarray( 0.0, len, otype );
6467

6568
condition = {
66-
'dtype': 'uint8',
69+
'dtype': ctype,
6770
'data': condition,
6871
'shape': shape,
6972
'strides': shape2strides( shape, order ),
@@ -87,7 +90,7 @@ function createBenchmark( len, shape, xtype, ytype ) {
8790
'order': order
8891
};
8992
out = {
90-
'dtype': xtype,
93+
'dtype': otype,
9194
'data': out,
9295
'shape': shape,
9396
'strides': shape2strides( shape, order ),
@@ -136,6 +139,7 @@ function main() {
136139
var sh;
137140
var t1;
138141
var t2;
142+
var t3;
139143
var f;
140144
var i;
141145
var j;
@@ -146,22 +150,23 @@ function main() {
146150
for ( j = 0; j < types.length; j++ ) {
147151
t1 = types[ j ];
148152
t2 = types[ j ];
153+
t3 = types[ j ];
149154
for ( i = min; i <= max; i++ ) {
150155
len = pow( 10, i );
151156

152157
sh = [ len/2, 2 ];
153-
f = createBenchmark( len, sh, t1, t2 );
154-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
158+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
159+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
155160

156161
sh = [ 2, len/2 ];
157-
f = createBenchmark( len, sh, t1, t2 );
158-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
162+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
163+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
159164

160165
len = floor( sqrt( len ) );
161166
sh = [ len, len ];
162167
len *= len;
163-
f = createBenchmark( len, sh, t1, t2 );
164-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
168+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
169+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
165170
}
166171
}
167172
}

‎lib/node_modules/@stdlib/ndarray/base/where/benchmark/benchmark.2d_rowmajor.js‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,15 @@ var sqrt = require( '@stdlib/math/base/special/sqrt' );
3030
var filledarray = require( '@stdlib/array/filled' );
3131
var filledarrayBy = require( '@stdlib/array/filled-by' );
3232
var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
33+
var format = require( '@stdlib/string/format' );
3334
var pkg = require( './../package.json' ).name;
3435
var where2d = require( './../lib/2d.js' );
3536

3637

3738
// VARIABLES //
3839

3940
var types = [ 'float64' ];
40-
var order = 'row-major';
41+
var order = 'column-major';
4142

4243

4344
// FUNCTIONS //
@@ -48,23 +49,24 @@ var order = 'row-major';
4849
* @private
4950
* @param {PositiveInteger} len - ndarray length
5051
* @param {NonNegativeIntegerArray} shape - ndarray shape
51-
* @param {string} xtype - first input ndarray data type
52-
* @param {string} ytype - second input ndarray data type
52+
* @param {string} ctype - first input ndarray data type
53+
* @param {string} xtype - second input ndarray data type
54+
* @param {string} ytype - third input ndarray data type
55+
* @param {string} otype - fourth input ndarray data type
5356
* @returns {Function} benchmark function
5457
*/
55-
function createBenchmark( len, shape, xtype, ytype ) {
58+
function createBenchmark( len, shape, ctype, xtype, ytype, otype ) {
5659
var condition;
5760
var out;
5861
var x;
5962
var y;
60-
61-
condition = filledarrayBy( len, 'uint8', bernoulli( 0.5 ) );
63+
condition = filledarrayBy( len, ctype, bernoulli( 0.5 ) );
6264
x = filledarrayBy( len, xtype, discreteUniform( -100, 100 ) );
6365
y = filledarrayBy( len, ytype, discreteUniform( -100, 100 ) );
64-
out = filledarray( 0.0, len, xtype );
66+
out = filledarray( 0.0, len, otype );
6567

6668
condition = {
67-
'dtype': 'uint8',
69+
'dtype': ctype,
6870
'data': condition,
6971
'shape': shape,
7072
'strides': shape2strides( shape, order ),
@@ -88,7 +90,7 @@ function createBenchmark( len, shape, xtype, ytype ) {
8890
'order': order
8991
};
9092
out = {
91-
'dtype': xtype,
93+
'dtype': otype,
9294
'data': out,
9395
'shape': shape,
9496
'strides': shape2strides( shape, order ),
@@ -137,6 +139,7 @@ function main() {
137139
var sh;
138140
var t1;
139141
var t2;
142+
var t3;
140143
var f;
141144
var i;
142145
var j;
@@ -147,22 +150,23 @@ function main() {
147150
for ( j = 0; j < types.length; j++ ) {
148151
t1 = types[ j ];
149152
t2 = types[ j ];
153+
t3 = types[ j ];
150154
for ( i = min; i <= max; i++ ) {
151155
len = pow( 10, i );
152156

153157
sh = [ len/2, 2 ];
154-
f = createBenchmark( len, sh, t1, t2 );
155-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
158+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
159+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
156160

157161
sh = [ 2, len/2 ];
158-
f = createBenchmark( len, sh, t1, t2 );
159-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
162+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
163+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
160164

161165
len = floor( sqrt( len ) );
162166
sh = [ len, len ];
163167
len *= len;
164-
f = createBenchmark( len, sh, t1, t2 );
165-
bench( pkg+':ndims='+sh.length+',len='+len+',shape=['+sh.join(',')+'],order='+order+',xtype='+t1+',ytype='+t2, f );
168+
f = createBenchmark( len, sh, 'uint8', t1, t2, t3 );
169+
bench( format( '%s:ndims=%d,len=%d,shape=[%s],order=%s,ctype=%s,xtype=%s,ytype=%s,otype=%s', pkg, sh.length, len, sh.join( ',' ), order, 'uint8', t1, t2, t3 ), f );
166170
}
167171
}
168172
}

0 commit comments

Comments
 (0)