Multidimensional arrays.
$ npm install compute-ndarrayFor use in the browser, use browserify.
varndarray=require('compute-ndarray');Creates a new multidimensional array.
vardata=newFloat32Array(10);varview=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.
vardata=newFloat32Array(10);// Cast the data array to a Float64Array:varview=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:varview=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.
vardata=newFloat32Array(20);for(vari=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,...]`: varview=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:varview=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.
vardtype=view.dtype;// returns <string>A read-only property returning the number of view dimensions.
varndims=view.ndims;// returns <number>A read-only property returning the view shape.
varshape=view.shape;// returns [...]A read-only property returning the view offset.
varoffset=view.offset;// returns <number>A read-only property returning the view strides.
varstrides=view.strides;// returns [...]A ready-only property returning the view length; i.e., how many elements are in the view, similar to Array#length.
varlen=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.
vardata=newFloat32Array(10);varview=ndarray(data,{'shape': [10]// 1x10});varvalue=view.get(3);// returns 0value=view[3];// returns undefinedA read-only property returning the number of bytes consumed by the view elements.
varnbytes=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.
varview=ndarray(newArray(10),{'dtype': 'generic'});varnbytes=view.nbytes;// returns nullA read-only property pointing to the underlying storage array.
vardata=view.data;// returns [...]Returns a view element specified according to the provided subscripts.
vardata=newFloat32Array(10);for(vari=0;i<data.length;i++){data[i]=i;}// => [0,1,2,3,...,9]varview=ndarray(data,{'shape': [5,2]});/* View: [ 0 1 2 3 4 5 6 7 8 9 ]*/varvalue=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.
vardata=newFloat32Array(10);varview1=ndarray(data,{'shape': [5,2]});/* View: [ 0 0 0 0 0 0 0 0 0 0 ]*/varview2=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.
vardata=newFloat32Array(10);varview=ndarray.raw(data);If the input data type is known, view creation is significantly faster.
varview=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.
varfactory=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.
varfactory=ndarray.factory({'dtype': 'float32','shape': [5,2],'strict': true});varview=factory(newInt8Array(10));// => throws TypeErrorCreates a reusable ndarray factory based on the low-level ndarray interface.
varfactory=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.
vardata=newFloat32Array(10);varview=factory(data);/* View: [ 0 0 0 0 0 0 0 0 0 0 ]*/varndarray=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.