ndarray

Multidimensional arrays.

Table of Contents

Usage
- ndarray
  - options
    - dtype
    - shape
    - offset
    - strides
  - Views
    - dtype
    - ndims
    - shape
    - offset
    - strides
    - length
    - nbytes
    - data
    - get
    - set
  - Constructors
- ndarray.raw
  - Views
  - Constructors
- Factories
  - ndarray.factory
  - ndarray.rawFactory
Examples

Installation

$ npm install compute-ndarray

For use in the browser, use browserify.

Usage

var ndarray = require( 'compute-ndarray' );

ndarray( data[, options] )

Creates a new multidimensional array.

var data = new Float32Array( 10 );

var view = ndarray( data );

The ndarray constructor accepts the following options:

dtype: specifies the underlying storage data type. If the input data is not of the same type, the data is cast to the specified dtype.
shape: specifies the array shape. Default: [ data.length ].
strides: specifies the array strides, which describe how to index into the input data array to create a multidimensional view.
offset: specifies the view offset, which points to where the view should begin in the input data array. Default: 0.

To cast the input data to a different underlying array data type, set the dtype option.

var data = new Float32Array( 10 );

// Cast the data array to a Float64Array:
var view = ndarray( data, {
	'dtype': 'float64'
});

A dtype may be any one of the following:

int8
uint8
uint8_clamped
int16
uint16
int32
uint32
float32
float64
binary
string (not currently supported)
boolean (not currently supported)
logical (not currently supported)
generic

To create multidimensional views, specify the view shape.

// Create a 5x2 matrix:
var view = ndarray( data, {
	'shape': [5,2]
});
/* View:
	[ 0 0
	  0 0
	  0 0
	  0 0
	  0 0 ]
*/

To control how an input data array is indexed when creating a multidimensional view, specify the view strides.

var data = new Float32Array( 20 );

for ( var i = 0; i < data.length; i++ ) {
	data[ i ] = i;
}
// => [0,1,2,3,...,19]

// Create a custom 5x2 view using only the even indices `[0,2,4,...]`: 
var view = ndarray( data, {
	'shape': [5,2],
	'strides': [10,2]
});
/* View:
	[  0  2
	   4  6
	   8 10
	  12 14
	  16 18	]
*/

To specify a custom view offset, set the offset option.

// Create a 5x2 view starting at the 10th element in the input array:
var view = ndarray( data, {
	'shape': [5,2],
	'offset': 10
});
/* View:
	[ 10 11
	  12 13
	  14 15
	  16 17
	  18 19 ]
*/

Views

Multidimensional views have the following properties and methods...

view.dtype

A read-only property returning the underlying storage data type.

var dtype = view.dtype;
// returns <string>

view.ndims

A read-only property returning the number of view dimensions.

var ndims = view.ndims;
// returns <number>

view.shape

A read-only property returning the view shape.

var shape = view.shape;
// returns [...]

view.offset

A read-only property returning the view offset.

var offset = view.offset;
// returns <number>

view.strides

A read-only property returning the view strides.

var strides = view.strides;
// returns [...]

view.length

A ready-only property returning the view length; i.e., how many elements are in the view, similar to Array#length.

var len = view.length;
// returns <number>

Note: while views have a length property, a view should not be considered array-like, as array indexing will not work as expected.

var data = new Float32Array( 10 );

var view = ndarray( data, {
	'shape': [10] // 1x10
});

var value = view.get( 3 );
// returns 0

value = view[ 3 ];
// returns undefined

view.nbytes

A read-only property returning the number of bytes consumed by the view elements.

var nbytes = view.nbytes;
// returns <number>

Note: this property can only be calculated for typed arrays and Buffers. For any other underlying storage type, the number of bytes cannot be reliably calculated and this property is null.

var view = ndarray( new Array( 10 ), {
	'dtype': 'generic'
});

var nbytes = view.nbytes;
// returns null

view.data

A read-only property pointing to the underlying storage array.

var data = view.data;
// returns [...]

view.get( i, j, k,...)

Returns a view element specified according to the provided subscripts.

var data = new Float32Array( 10 );

for ( var i = 0; i < data.length; i++ ) {
	data[ i ] = i;
}
// => [0,1,2,3,...,9]

var view = ndarray( data, {
	'shape': [5,2]
});
/* View:
	[ 0 1
	  2 3
	  4 5
	  6 7
	  8 9 ]
*/

var value = view.get( 3, 1 );
// returns 7

Note: subscripts are not validated. Out-of-bounds subscripts are permitted and will return either a value of undefined or a value located outside the view domain.

view.set( i, j, k,..., value )

Sets a view element specified according to the provided subscripts.

view.set( 3, 1, 20 );
/* View:
	[ 0 1
	  2 3
	  4 5
	  6 20
	  8 9 ]
*/

Note: subscripts are not validated. Out-of-bounds subscripts are permitted and may result in corrupted underlying data stores. Consumers are advised to validate indices before invoking the method.

Constructors

Each ndarray view has a specialized constructor determined by the view dtype and ndims. Every constructor has the same API which is as follows...

view.constructor( data, shape, offset, strides )

Creates a new multidimensional array having a specified shape, offsets, and strides.

var data = new Float32Array( 10 );

var view1 = ndarray( data, {
	'shape': [5,2]
});
/* View:
	[ 0 0
	  0 0
	  0 0
	  0 0
	  0 0 ]
*/

var view2 = view1.constructor( data, [2,5] );
/* View:
	[ 0 0 0 0 0
	  0 0 0 0 0 ]
*/

Constructing views in this manner provides a shortcut for creating views with known parameters and having the same underlying data type and dimensions.

===

Raw

For performance, a low-level API is provided which forgoes some of the guarantees of the above API, such as input argument validation and measures to prevent views from becoming corrupted. While use of the above API is encouraged in REPL environments, use of the lower-level interface may be warranted when arguments are of a known type or when many ndarrays must be created.

ndarray.raw( data[, dtype[, shape[, offset[, strides ] ] ] ] )

Creates a new multidimensional array.

var data = new Float32Array( 10 );

var view = ndarray.raw( data );

If the input data type is known, view creation is significantly faster.

var view = ndarray.raw( data, 'float32' );

Note: specifying a dtype does not cast the data to a different storage type. Instead, providing the argument circumvents the needed to determine the input data type, resulting in increased performance.

The shape, offset, and strides parameters are the same as above.

Views

Views properties and methods are the same as for the higher-level API, with the exception that the following properties are no longer read-only:

offset
strides
shape
length
nbytes
data

Setting these properties is not recommended as the view can become corrupted; e.g., incompatible dimensions, out-of-bounds indexing, etc. In contrast to the strict API above, setting these properties will not result in an error being thrown. Accordingly, modifying the properties may introduce silent bugs.

Constructors

Constructors produced using the low-level API have the same interface as those created via the higher-level API.

===

Factories

To facilitate creating ndarrays, the module provides factory functions. Using a factory when creating ndarrays can dramatically boost creation performance.

ndarray.factory( options )

Creates a reusable ndarray factory.

var factory = ndarray.factory({
	'shape': [5,2]
});

The factory method requires that a shape is provided and accepts the same ndarray options as above.

strides: view strides.
offset: view offset.
dtype: underlying data storage type. Default: generic.

One additional option is accepted:

strict: boolean indicating if a factory should accept input data having a different data type. Default: false, in which case, input data of a different data type is cast to dtype.

To prevent input data having a different data type, set the strict option to true.

var factory = ndarray.factory({
	'dtype': 'float32',
	'shape': [5,2],
	'strict': true
});

var view = factory( new Int8Array( 10 ) );
// => throws TypeError

ndarray.rawFactory( options )

Creates a reusable ndarray factory based on the low-level ndarray interface.

var factory = ndarray.rawFactory({
	'dtype': 'float32',
	'shape': [5,2]
});

Similar to the low-level interface, input arguments are not validated and casting is not supported. As casting is not supported, a strict option is not supported by this method.

factory( data )

Creates a new multidimensional array configured according to the options specified when creating a view factory.

var data = new Float32Array( 10 );

var view = factory( data );
/* View:
	[ 0 0 
	  0 0
	  0 0
	  0 0
	  0 0 ]
*/

Examples

var ndarray = require( 'compute-ndarray' );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Credits

This module was inspired by ndarray.

License

MIT license.

Copyright

Copyright © 2015. The Compute.io Authors.

License

dstructs/ndarray

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages