Skip to content

docs: improve examples of ndarray/iter namespace #1686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
+89 −7
Open

docs: improve examples of ndarray/iter namespace #1686

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b36dc4a
docs: improve README examples of ndarray/iter namespace
performant23 Mar 4, 2024
aa1b0e4
Update README.md
performant23 Mar 4, 2024
440c045
docs: apply suggestions from code review
performant23 Mar 4, 2024
9e73fd3
Merge remote-tracking branch 'origin/docs/improve_README_examples_of_…
performant23 Mar 4, 2024
e5311a0
Merge branch 'stdlib-js:develop' into docs/improve_README_examples_of…
performant23 Mar 6, 2024
0fa2bb6
Merge remote-tracking branch 'upstream/develop' into docs/improve_REA…
stdlib-bot Nov 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 140 additions & 1 deletion lib/node_modules/@stdlib/ndarray/iter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

@license Apache-2.0

Copyright (c) 2018 The Stdlib Authors.
Copyright (c) 2024 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.
Expand Down Expand Up @@ -71,12 +71,151 @@ var o = ns;
<!-- eslint no-undef: "error" -->

```javascript
// Example: Get an array consisting of keys/properties inside ns.
var objectKeys = require( '@stdlib/utils/keys' );
var ns = require( '@stdlib/ndarray/iter' );

console.log( objectKeys( ns ) );
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefer modifying the existing example code. Project conventions are to not create multiple separate Markdown code blocks. Prefer instead a single Markdown code block with various example usage.

```

```javascript
// Example: Iterate over [index, column] pairs for each column in a matrix
var ndarray = require( '@stdlib/ndarray/ctor' );
var ns = require( '@stdlib/ndarray/iter' );

var array2D = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ];
var data = [].concat.apply( [], array2D );
var x = ndarray( 'generic', data, [ 3, 3 ], [ 3, 1 ], 0, 'row-major' );
var iterEntries = ns.nditerEntries( x );
var entry;

for ( entry of iterEntries ) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ES5.

console.log( 'Index:', entry[ 0 ], 'Value:', entry[ 1 ] );
}
```

```javascript
// Example: Iterate over each row of the ndarray
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These examples seem to just be pulling from the READMEs of the child packages. I think we would prefer something fresh, which ideally combines the functionality of multiple packages to demonstrate how they can all work together.


var ndarray = require( '@stdlib/ndarray/ctor' );
var ns = require( '@stdlib/ndarray/iter' );

var array2D = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ];
var data = [].concat.apply( [], array2D );
var x = ndarray( 'generic', data, [ 3, 3 ], [ 3, 1 ], 0, 'row-major' );
var iterRows = ns.nditerRows( x );
var rowData;
var row;
var i;

while ( true ) {
row = iterRows.next();
if ( row.done ) {
break;
}
rowData = [];
for ( i = 0; i < row.value.shape[ 0 ]; i++ ) {
rowData.push( row.value.get( i ) );
}
console.log( rowData );
}
```

```javascript
// Example: Iterate over each column of the ndarray
var ns = require( '@stdlib/ndarray/iter' );
var ndarray = require( '@stdlib/ndarray/ctor' );

var array2D = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ];
var data = [].concat.apply( [], array2D );
var x = ndarray( 'generic', data, [ 3, 3 ], [ 3, 1 ], 0, 'row-major' );
var iterColumns = ns.nditerColumns( x );
var column;
var k;
var columnData;

while ( true ) {
column = iterColumns.next();
if ( column.done ) {
break;
}
columnData = [];
for ( k = 0; k < column.value.shape[ 0 ]; k++ ) {
columnData.push( column.value.get( k ) );
}
console.log( columnData );
}
```

```javascript
// Example: Iterate over each matrix in the stack
var ns = require( '@stdlib/ndarray/iter' );
var ndarray = require( '@stdlib/ndarray/ctor' );

var matricesData = [
1,
2,
3,
4,
5,
6,
7,
8
];
var dataMatrix = ndarray( 'generic', matricesData, [ 2, 2, 2 ], [ 4, 2, 1 ], 0, 'row-major' );
var iterMatrices = ns.nditerMatrices( dataMatrix );
var matrix;
var rowIndex;
var j;
var matrixData;
var currentRow;

while ( true ) {
matrix = iterMatrices.next();
if ( matrix.done ) {
break;
}
matrixData = [];
for ( rowIndex = 0; rowIndex < matrix.value.shape[ 0 ]; rowIndex++ ) {
currentRow = [];
for ( j = 0; j < matrix.value.shape[ 1 ]; j++ ) {
currentRow.push( matrix.value.get( rowIndex, j ) );
}
matrixData.push( currentRow );
}
console.log( matrixData );
}
```

```javascript
// Example: Converting each iterated ndarray to a generic array
var array = require( '@stdlib/ndarray/array' );
var iter = require( '@stdlib/ndarray/iter' );

var array2D = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ];
var data = [].concat.apply( [], array2D );

var ndMatrix;
ndMatrix = array( data, {
'shape': [ 3, 3 ],
'dtype': 'generic'
} );
var rowIterator;
rowIterator = iter.nditerRows( ndMatrix );
var it = iter.nditer2arrayEach( rowIterator );
var v;

console.log( 'Original ndarray:', ndMatrix.toString() );

while ( true ) {
v = it.next();
if ( v.done ) {
break;
}
console.log( v.value );
}
```

</section>

<!-- /.examples -->
Expand Down
109 changes: 108 additions & 1 deletion lib/node_modules/@stdlib/ndarray/iter/examples/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2023 The Stdlib Authors.
* Copyright (c) 2024 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.
Expand All @@ -19,6 +19,113 @@
'use strict';

var objectKeys = require( '@stdlib/utils/keys' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var array = require( '@stdlib/ndarray/array' );
var iter = require( '@stdlib/ndarray/iter' );
var ns = require( './../lib' );

// Example: Get an array consisting of keys/properties inside ns.
console.log( objectKeys( ns ) );

// Example: Iterate over [index, column] pairs for each column in a matrix
var array2D = [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ];
var data = [].concat.apply( [], array2D );
var x = ndarray( 'generic', data, [ 3, 3 ], [ 3, 1 ], 0, 'row-major' );
var iterEntries = ns.nditerEntries( x );
var entry;

for ( entry of iterEntries ) {
console.log( 'Index:', entry[ 0 ], 'Value:', entry[ 1 ] );
}

// Example: Iterate over each row of the ndarray
var iterRows = ns.nditerRows( x );
var row;
var i;
var rowData;

while ( true ) {
row = iterRows.next();
if ( row.done ) {
break;
}
rowData = [];
for ( i = 0; i < row.value.shape[ 0 ]; i++ ) {
rowData.push( row.value.get( i ) );
}
console.log( rowData );
}

// Example: Iterate over each column of the ndarray
var iterColumns = ns.nditerColumns( x );
var column;
var k;
var columnData;

while ( true ) {
column = iterColumns.next();
if ( column.done ) {
break;
}
columnData = [];
for ( k = 0; k < column.value.shape[ 0 ]; k++ ) {
columnData.push( column.value.get( k ) );
}
console.log( columnData );
}

// Example: Iterate over each matrix in the stack
var matricesData = [
1,
2,
3,
4,
5,
6,
7,
8
];
var dataMatrix = ndarray( 'generic', matricesData, [ 2, 2, 2 ], [ 4, 2, 1 ], 0, 'row-major' );
var iterMatrices = ns.nditerMatrices( dataMatrix );
var matrix;
var rowIndex;
var j;
var matrixData;
var currentRow;

while ( true ) {
matrix = iterMatrices.next();
if ( matrix.done ) {
break;
}
matrixData = [];
for ( rowIndex = 0; rowIndex < matrix.value.shape[ 0 ]; rowIndex++ ) {
currentRow = [];
for ( j = 0; j < matrix.value.shape[ 1 ]; j++ ) {
currentRow.push( matrix.value.get( rowIndex, j ) );
}
matrixData.push( currentRow );
}
console.log( matrixData );
}

// Example: Converting each iterated ndarray to a generic array
var ndMatrix;
ndMatrix = array( data, {
'shape': [ 3, 3 ],
'dtype': 'generic'
} );
var rowIterator;
rowIterator = iter.nditerRows( ndMatrix );
var it = iter.nditer2arrayEach( rowIterator );
var v;

console.log( 'Original ndarray:', ndMatrix.toString() );

while ( true ) {
v = it.next();
if ( v.done ) {
break;
}
console.log( v.value );
}