-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
2fc0a41
commit e8649ec
Showing
14 changed files
with
1,505 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,128 @@ | ||
<!-- | ||
@license Apache-2.0 | ||
Copyright (c) 2023 The Stdlib Authors. | ||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
http://www.apache.org/licenses/LICENSE-2.0 | ||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. | ||
--> | ||
|
||
# take3d | ||
|
||
> Take elements from a three-dimensional nested array. | ||
<section class="usage"> | ||
|
||
## Usage | ||
|
||
```javascript | ||
var take3d = require( '@stdlib/array/base/take3d' ); | ||
``` | ||
|
||
#### take3d( x, indices, dimension, mode ) | ||
|
||
Takes elements along a specified `dimension` from a three-dimensional nested array according to a specified [index `mode`][@stdlib/ndarray/index-modes]. | ||
|
||
```javascript | ||
var x = [ [ [ 1, 2 ], [ 3, 4 ] ] ]; | ||
var indices = [ 1, 1, 0, 0, -1, -1 ]; | ||
|
||
var y = take3d( x, indices, 2, 'normalize' ); | ||
// returns [ [ [ 2, 2, 1, 1, 2, 2 ], [ 4, 4, 3, 3, 4, 4 ] ] ] | ||
``` | ||
|
||
The function accepts the following arguments: | ||
|
||
- **x**: input nested array. | ||
- **indices**: list of indices. | ||
- **dimension**: dimension along which to take elements. If provided a negative integer, the dimension is resolved relative to the last dimension, with the last dimension being `-1`. | ||
- **mode**: [index mode][@stdlib/ndarray/index-modes] specifying how to handle an index which is out-of-bounds. | ||
|
||
If `indices` is an empty array, the function returns empty arrays along the specified `dimension`. | ||
|
||
```javascript | ||
var x = [ [ [ 1, 2 ], [ 3, 4 ] ] ]; | ||
|
||
var y = take3d( x, [], 0, 'throw' ); | ||
// returns [] | ||
|
||
var z = take3d( x, [], 1, 'throw' ); | ||
// returns [ [] ] | ||
|
||
var w = take3d( x, [], 2, 'throw' ); | ||
// returns [ [ [], [] ] ] | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.usage --> | ||
|
||
<section class="notes"> | ||
|
||
## Notes | ||
|
||
- The function does **not** deep copy nested array elements. | ||
|
||
</section> | ||
|
||
<!-- /.notes --> | ||
|
||
<section class="examples"> | ||
|
||
## Examples | ||
|
||
<!-- eslint no-undef: "error" --> | ||
|
||
```javascript | ||
var filled3dBy = require( '@stdlib/array/base/filled3d-by' ); | ||
var filledBy = require( '@stdlib/array/base/filled-by' ); | ||
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); | ||
var take3d = require( '@stdlib/array/base/take3d' ); | ||
|
||
// Generate a random array: | ||
var shape = [ 3, 3, 3 ]; | ||
var x = filled3dBy( shape, discreteUniform.factory( 0, 100 ) ); | ||
console.log( x ); | ||
|
||
// Generate an array of random indices: | ||
var N = discreteUniform( 1, 5 ); | ||
var indices = filledBy( N, discreteUniform.factory( 0, shape[2]-1 ) ); | ||
console.log( indices ); | ||
|
||
// Take a random sample of elements from `x`: | ||
var y = take3d( x, indices, 2, 'throw' ); | ||
console.log( y ); | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.examples --> | ||
|
||
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> | ||
|
||
<section class="related"> | ||
|
||
</section> | ||
|
||
<!-- /.related --> | ||
|
||
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> | ||
|
||
<section class="links"> | ||
|
||
[@stdlib/ndarray/index-modes]: https://github.com/stdlib-js/stdlib | ||
|
||
</section> | ||
|
||
<!-- /.links --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,111 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2023 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
// MODULES // | ||
|
||
var bench = require( '@stdlib/bench' ); | ||
var floor = require( '@stdlib/math/base/special/floor' ); | ||
var pow = require( '@stdlib/math/base/special/pow' ); | ||
var filled3dBy = require( './../../../base/filled3d-by' ); | ||
var filledBy = require( './../../../base/filled-by' ); | ||
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; | ||
var isArrayArray = require( '@stdlib/assert/is-array-array' ); | ||
var numel = require( '@stdlib/ndarray/base/numel' ); | ||
var pkg = require( './../package.json' ).name; | ||
var take3d = require( './../lib' ); | ||
|
||
|
||
// FUNCTIONS // | ||
|
||
/** | ||
* Creates a benchmark function. | ||
* | ||
* @private | ||
* @param {PositiveIntegerArray} shape - array shape | ||
* @returns {Function} benchmark function | ||
*/ | ||
function createBenchmark( shape ) { | ||
var dim; | ||
var idx; | ||
var S; | ||
var x; | ||
|
||
dim = shape.length - 1; | ||
S = shape[ dim ]; | ||
|
||
x = filled3dBy( shape, discreteUniform( -50, 50 ) ); | ||
idx = filledBy( S, discreteUniform( -S, S-1 ) ); | ||
|
||
return benchmark; | ||
|
||
/** | ||
* Benchmark function. | ||
* | ||
* @private | ||
* @param {Benchmark} b - benchmark instance | ||
*/ | ||
function benchmark( b ) { | ||
var v; | ||
var i; | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
v = take3d( x, idx, dim, 'normalize' ); | ||
if ( typeof v !== 'object' ) { | ||
b.fail( 'should return an array' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( !isArrayArray( v ) ) { | ||
b.fail( 'should return an array of arrays' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
} | ||
} | ||
|
||
|
||
// MAIN // | ||
|
||
/** | ||
* Main execution sequence. | ||
* | ||
* @private | ||
*/ | ||
function main() { | ||
var shape; | ||
var min; | ||
var max; | ||
var N; | ||
var f; | ||
var i; | ||
|
||
min = 1; // 10^min | ||
max = 6; // 10^max | ||
|
||
for ( i = min; i <= max; i++ ) { | ||
N = floor( pow( pow( 10, i ), 1.0/3.0 ) ); | ||
shape = [ N, N, N ]; | ||
f = createBenchmark( shape ); | ||
bench( pkg+'::equidimensional,unsorted_indices:size='+numel(shape)+',num_indices='+N, f ); | ||
} | ||
} | ||
|
||
main(); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
|
||
{{alias}}( x, indices, dimension, mode ) | ||
Takes elements from a three-dimensional nested array. | ||
|
||
If `indices` is an empty array, the function returns empty arrays along the | ||
specified dimension. | ||
|
||
The function does *not* deep copy nested array elements. | ||
|
||
Parameters | ||
---------- | ||
x: ArrayLikeObject | ||
Input nested array. | ||
|
||
indices: ArrayLikeObject<integer> | ||
List of indices. | ||
|
||
dimension: integer | ||
Dimension along which to take elements. If provided a negative integer, | ||
the dimension is resolved relative to the last dimension, with the last | ||
dimension being -1. | ||
|
||
mode: string | ||
Specifies how to handle an index which exceeds array dimensions. If | ||
equal to 'throw', the function throws an error when an index exceeds | ||
array dimensions. If equal to 'normalize', the function normalizes | ||
negative indices and throws an error when an index exceeds array | ||
dimensions. If equal to 'wrap', the function wraps around an index | ||
exceeding array dimensions using modulo arithmetic. If equal to | ||
'clamp', the function sets an index exceeding array dimensions to | ||
either 0 (minimum index) or the maximum index. | ||
|
||
Returns | ||
------- | ||
out: Array | ||
Output array. | ||
|
||
Examples | ||
-------- | ||
> var x = [ [ [ 1, 2 ], [ 3, 4 ] ] ]; | ||
> var idx = [ 1, 1, 0, 0, -1, -1 ]; | ||
> var y = {{alias}}( x, idx, 2, 'normalize' ) | ||
[ [ [ 2, 2, 1, 1, 2, 2 ], [ 4, 4, 3, 3, 4, 4 ] ] ] | ||
|
||
See Also | ||
-------- | ||
|
Oops, something went wrong.