Skip to content

README.md

Latest commit

 

History

History
200 lines (132 loc) · 6.01 KB

README.md

File metadata and controls

200 lines (132 loc) · 6.01 KB

gwhere

Take elements from one of two strided arrays depending on a condition.

Usage

var gwhere = require( '@stdlib/blas/ext/base/gwhere' );

gwhere( N, condition, strideC, x, strideX, y, strideY )

Takes elements from one of two strided arrays depending on a condition.

var condition = [ 1, 0, 1 ];
var x = [ 1.0, 2.0, 3.0 ];
var y = [ 4.0, 5.0, 6.0 ];

var out = gwhere( 3, condition, 1, x, 1, y, 1 );
// returns [ 1.0, 5.0, 3.0 ]

The function has the following parameters:

  • N: number of indexed elements.
  • condition: condition array.
  • strideC: stride length for condition.
  • x: first input Array or typed array.
  • strideX: stride length for x.
  • y: second input Array or typed array.
  • strideY: stride length for y.

The N and stride parameters determine which elements in the strided arrays are accessed at runtime. For example, to select from every other element:

var condition = [ 1, 0, 0, 1, 1, 0 ];
var x = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var y = [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ];

var out = gwhere( 3, condition, 2, x, 2, y, 2 );
// returns [ 1.0, 9.0, 5.0 ]

Note that indexing is relative to the first index. To introduce an offset, use typed array views.

var Float64Array = require( '@stdlib/array/float64' );

// Initial arrays...
var condition0 = new Float64Array( [ 0.0, 1.0, 0.0, 1.0, 0.0, 1.0 ] );
var x0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
var y0 = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );

// Create offset views...
var condition1 = new Float64Array( condition0.buffer, condition0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*1 ); // start at 2nd element

var out = gwhere( 3, condition1, 2, x1, 2, y1, 2 );
// returns [ 2.0, 4.0, 6.0 ]

gwhere.ndarray( N, condition, strideC, offsetC, x, strideX, offsetX, y, strideY, offsetY )

Takes elements from one of two strided arrays depending on a condition using alternative indexing semantics.

var condition = [ 1, 0, 1 ];
var x = [ 1.0, 2.0, 3.0 ];
var y = [ 4.0, 5.0, 6.0 ];

var out = gwhere.ndarray( 3, condition, 1, 0, x, 1, 0, y, 1, 0 );
// returns [ 1.0, 5.0, 3.0 ]

The function has the following additional parameters:

  • offsetC: starting index for condition.
  • offsetX: starting index for x.
  • offsetY: starting index for y.

While typed array views mandate a view offset based on the underlying buffer, offset parameters support indexing semantics based on starting indices. For example, to select from every other element starting from the second element:

var condition = [ 0, 1, 0, 0, 0, 1 ];
var x = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var y = [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ];

var out = gwhere.ndarray( 3, condition, 2, 1, x, 2, 1, y, 2, 1 );
// returns [ 2.0, 10.0, 6.0 ]

Notes

  • If N <= 0, both functions return an empty array.
  • Both functions support array-like objects having getter and setter accessors for array element access (e.g., @stdlib/array/base/accessor).
  • Depending on the environment, the typed versions (dwhere, swhere, etc.) are likely to be significantly more performant.

Examples

var bernoulli = require( '@stdlib/random/array/bernoulli' );
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var gwhere = require( '@stdlib/blas/ext/base/gwhere' );

var condition = bernoulli( 20, 0.5, {
    'dtype': 'generic'
});
console.log( condition );
var x = discreteUniform( 20, 0, 100, {
    'dtype': 'generic'
});
console.log( x );
var y = discreteUniform( 20, -100, 0, {
    'dtype': 'generic'
});
console.log( y );

var out = gwhere( condition.length, condition, 1, x, 1, y, 1 );
console.log( out );