Multidimensional arrays.
$ npm install compute-ndarrayFor use in the browser, use browserify.
var ndarray = require( 'compute-ndarray' );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
datais not of the same type, thedatais cast to the specifieddtype. - shape: specifies the array
shape. Default:[ data.length ]. - strides: specifies the array
strides, which describe how to index into the inputdataarray to create a multidimensional view. - offset: specifies the view
offset, which points to where the view should begin in the inputdataarray. 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:
int8uint8uint8_clampedint16uint16int32uint32float32float64binarystring(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 ]
*/Multidimensional views have the following properties and methods...
A read-only property returning the underlying storage data type.
var dtype = view.dtype;
// returns <string>A read-only property returning the number of view dimensions.
var ndims = view.ndims;
// returns <number>A read-only property returning the view shape.
var shape = view.shape;
// returns [...]A read-only property returning the view offset.
var offset = view.offset;
// returns <number>A read-only property returning the view strides.
var strides = view.strides;
// returns [...]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 undefinedA 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 nullA read-only property pointing to the underlying storage array.
var data = view.data;
// returns [...]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 7Note: 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.
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.
Each ndarray view has a specialized constructor determined by the view dtype and ndims. Every constructor has the same API which is as follows...
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.
===
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.
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 properties and methods are the same as for the higher-level API, with the exception that the following properties are no longer read-only:
offsetstridesshapelengthnbytesdata
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 produced using the low-level API have the same interface as those created via the higher-level API.
===
To facilitate creating ndarrays, the module provides factory functions. Using a factory when creating ndarrays can dramatically boost creation performance.
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:
booleanindicating if a factory should accept inputdatahaving a different data type. Default:false, in which case, inputdataof a different data type is cast todtype.
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 TypeErrorCreates 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.
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 ]
*/var ndarray = require( 'compute-ndarray' );To run the example code from the top-level application directory,
$ node ./examples/index.jsUnit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make testAll new feature development should have corresponding unit tests to validate correct functionality.
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-covIstanbul creates a ./reports/coverage directory. To access an HTML version of the report,
$ make view-covThis module was inspired by ndarray.
Copyright © 2015. The Compute.io Authors.