dstructs-matrix
Advanced tools
Matrices.
This module exports a Matrix data structure for efficient storage and computation of numeric values. The data structure provides an interface for accessing and modifying one or more stored values. Matrices find common use in linear algebra, numerical analysis, image manipulation, machine learning, and data processing.
$ npm install dstructs-matrix
For use in the browser, use browserify.
var matrix = require( 'dstructs-matrix' );
Creates a new Matrix having a specified shape (dimensions => [rows,cols]).
var mat = matrix( [3,2] );
/*
[ 0 0
0 0
0 0 ]
*/
By default, the matrix elements are floating-point 64-bit numbers (float64). To specify a different data type, provide a dtype.
var mat = matrix( [2,2], 'int8' );
/*
[ 0 0
0 0 ]
*/
The following dtypes are accepted:
int8uint8uint8_clampedint16uint16int32uint32float32float64If a linear numeric array is not provided, the function initializes a zero-filled matrix. To initialize a matrix, provide a typed input data array, whose length matches the specified shape.
var data = new Int8Array( 6 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
var mat = matrix( data, [2,3] ); // 2*3 = 6
/*
[ 0 1 2
3 4 5 ]
*/
To cast an input data array to a different data type, provide a dtype.
var mat = matrix( data, [2,2], 'uint32' );
/*
[ 0 1
2 3 ]
*/
If provided an Array instead of a typed array and no dtype is specified, the input data array is cast to float64.
var data = [ 10, 20, 30, 40, 50, 60 ];
var mat = matrix( data, [3,2] );
/*
[ 10 20
30 40
50 60 ]
*/
var dtype = mat.dtype;
// returns 'float64'
A Matrix has the following properties...
A read-only property returning the underlying storage data type.
var dtype = mat.dtype;
// returns <string>
A read-only property returning the number of dimensions.
var ndims = mat.ndims;
// returns 2
A read-only property returning the matrix shape.
var shape = mat.shape;
// returns [...]
A property returning the offset used to index into the underlying data store.
var offset = mat.offset;
// returns 0
By default, the offset is 0. While not read-only, most consumers should treat the offset as a read-only property.
A read-only property returning the strides used to index into the underlying data store.
var strides = mat.strides;
// returns [...]
While not frozen, most consumers should treat the strides elements as read-only elements.
A read-only property returning the matrix length; i.e., how many elements are in the Matrix, similar to Array#length.
var len = mat.length;
// returns <number>
Note: while a Matrix has a length property, a Matrix should not be considered array-like, as array indexing with not work as expected.
var data = new Float32Array( 10 );
var mat = matrix( data, [10,1] );
// [ 0 0 0 0 0 0 0 0 0 0 ]
var value = mat.get( 3, 1 );
// returns 0
value = mat[ 3 ];
// returns undefined
A read-only property returning the number of bytes consumed by the Matrix elements.
var nbytes = mat.nbytes;
// returns <number>
A read-only property pointing to the underlying storage array.
var data = mat.data;
// returns <TypedArray>
A Matrix has the following methods...
These methods mutate a Matrix:
Sets a Matrix element located at a row and column index.
mat.set( 3, 1, 20 );
/*
[ 0 1
2 3
4 5
6 20
8 9 ]
*/
Set methods return the Matrix instance and are thus chainable.
mat
.set( 3, 1, 21 )
.set( 3, 1, 22 )
.set( 3, 1, 23 )
.set( 3, 1, 24 )
.get( 3, 1 );
// returns 24
Note: out-of-bounds row and column indices will silently fail.
Sets a Matrix element located at a specified index. If index < 0, the index refers to a position relative to the Matrix length, where index = -1 corresponds to the last element.
mat.iset( 7, 25 );
/*
[ 0 1
2 3
4 5
6 25
8 9 ]
*/
mat.iset( -3, 20 );
/*
[ 0 1
2 3
4 5
6 20
8 9 ]
*/
Note: out-of-bounds indices will silently fail.
Sets multiple Matrix elements. If provided a single array, idx is treated as an array of linear indices. The value argument may be either a number primitive, a Matrix containing values to set, or a callback function.
var data = new Int8Array( 10*10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
// Create a 10x10 matrix:
var mat = matrix( data, [10,10] );
var submat = mat.mget( [0,2,4], [1,4,5] );
/*
[ 1 4 5
21 24 25
41 44 45 ]
*/
mat.mset( [1,4,5,21,24,25,41,44,45], 5 );
submat = mat.mget( [0,2,4], [1,4,5] );
/*
[ 5 5 5
5 5 5
5 5 5 ]
*/
var zeros = matrix( [1,3], 'int8' );
/*
[ 0 0 0 ]
*/
mat.mset( [2], [1,4,5], zeros );
submat = mat.mget( [0,2,4], [1,4,5] );
/*
[ 5 5 5
0 0 0
5 5 5 ]
*/
A callback is provided four arguments:
and is expected to return a number primitive or a value which can be cast to a number primitive.
function set( d, i, j, idx ) {
return '' + j + i;
}
mat.mset( [0], [1,4,5], set );
mat.mget( [0,2,4], [1,4,5] );
/*
[ 10 40 50
0 0 0
5 5 5 ]
*/
By default, the callback this context is set to the Matrix instance. To specify a different this context, provide a thisArg.
function set( d, i, j, idx ) {
console.log( this );
// returns null
return '' + j + i;
}
mat.mset( [0], [1,4,5], set, null );
Notes:
Matrix data type.Matrix must have dimensions which match the submatrix defined by row and column indices.Matrix must have a length equal to the number of provided indices.Sets Matrix elements according to a specified subsequence. The subsequence must specify both row and column subsequences; e.g., '3:7,5:9', where 3:7 corresponds to row indices 3,4,5,6 and 5:9 corresponds to column indices 5,6,7,8. The second argument may be either a number primitive, a Matrix containing values to set, or a callback function.
var data = new Float32Array( 10*10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
// Create a 10x10 matrix:
var mat = matrix( data, [10,10] );
var submat = mat.sget( '3:7,5:9' );
/*
[ 35 36 37 38
45 46 47 48
55 56 57 58
65 66 67 68 ]
*/
var zeros = matrix( [2,2], 'float32' );
/*
[ 0 0
0 0 ]
*/
mat.sset( '4:6,6:8', zeros );
submat = mat.sget( '3:7,5:9' );
/*
[ 35 36 37 38
45 0 0 48
55 0 0 58
65 66 67 68 ]
*/
A callback is provided four arguments:
and is expected to return a number primitive or a value which can be cast to a number primitive.
function set( d, i, j, idx ) {
return '' + j + i;
}
mat.sset( '4:6,6:8', set );
submat = mat.sget( '3:7,5:9' );
/*
[ 35 36 37 38
45 64 74 48
55 65 75 58
65 66 67 68 ]
*/
By default, the callback this context is set to the Matrix instance. To specify a different this context, provide a thisArg.
function set( d, i, j, idx ) {
console.log( this );
// returns null
return '' + j + i;
}
mat.sset( '4:6,6:8', set, null );
Notes:
Matrix data type.Matrix must have dimensions which match the submatrix defined by row and column subsequences.===
These methods provide access to Matrix elements:
Returns a Matrix element located at a row and column index.
var data = new Float32Array( 10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
var mat = matrix( data, [5,2] );
/*
[ 0 1
2 3
4 5
6 7
8 9 ]
*/
var values = mat.get( 3, 1 );
// returns 7
Note: out-of-bounds row and column indices will return a value of undefined.
Returns a Matrix element located at a specified index. If index < 0, the index refers to a position relative to the Matrix length, where index = -1 corresponds to the last element.
var value = mat.iget( 7 );
// returns 7
value = mat.iget( -3 );
// returns 7
Note: out-of-bounds indices will return a value of undefined.
Returns multiple Matrix elements. If provided a single argument, the method treats idx as an array of linear indices (idx[i] >= 0) and returns a new Matrix instance having a single row. Otherwise, idx and cols are integer arrays which specify row and column indices and the method returns a new Matrix instance having dimensions determined by the number of defined rows and columns.
var data = new Int8Array( 10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i*2;
}
var mat = matrix( data, [5,2] );
/*
[ 0 2
4 6
8 10
12 14
16 18 ]
*/
// Scramble the second column:
var vals = mat.mget( [1,5,3,9,7] );
/*
[ 2, 10, 6, 18, 14 ]
*/
// Extract select rows and columns in arbitrary order:
var mat1 = mat.mget( [1,3,2], [1] );
/*
[ 4
14
8 ]
*/
If idx and/or cols is null, all rows (columns) are extracted.
// Replicate a column:
var rep = mat.mget( null, [1,1,1,1,1] );
/*
[ 2 2 2 2 2
6 6 6 6 6
10 10 10 10 10
14 14 14 14 14
18 18 18 18 18 ]
*/
// Tile select rows and columns:
var tile = mat.mget( [1,2,1,2], [0,1,0,1] );
/*
[
4 6 4 6
8 10 8 10
4 6 4 6
8 10 8 10
]
*/
Note: out-of-bounds indices are ignored.
Returns Matrix elements in a new Matrix according to a specified subsequence. The subsequence must specify both row and column subsequences; e.g., '3:7,5:9', where 3:7 corresponds to row indices 3,4,5,6 and 5:9 corresponds to column indices 5,6,7,8. If a subsequence does not correspond to any Matrix elements, the method returns an empty Matrix.
var submatrix;
submatrix = mat.sget( ':,:' ); // Copy a matrix
/*
[ 0 1
2 3
4 5
6 7
8 9 ]
*/
submatrix = mat.sget( '1:4,:' );
/*
[ 2 3
4 5
6 7 ]
*/
submatrix = mat.sget( '::-1,:' ); // flip top-to-bottom
/*
[ 8 9
6 7
4 5
2 3
0 1 ]
*/
submatrix = mat.sget( ':,::-1' ); // flip left-to-right
/*
[ 1 0
3 2
5 4
7 6
9 8 ]
*/
submatrix = mat.sget( '50:100,:' );
/*
[]
*/
Notes:
===
These methods do not mutate a Matrix and return some representation of a Matrix:
Returns a string representation of a Matrix. This method is similar to Array#toString, except that rows are delineated by semicolons and column values are delineated by commas.
var data = new Int8Array( 10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
var mat = matrix( data, [5,2] );
var str = mat.toString();
// 0,1;2,3;4,5;6,7;8,9
To construct an array of arrays from the string representation,
var rows,
cols,
i, j;
rows = str.split( ';' );
for ( i = 0; i < rows.length; i++ ) {
cols = rows[ i ].split( ',' );
rows[ i ] = new Array( cols.length );
for ( j = 0; j < cols.length; j++ ) {
rows[ i ][ j ] = parseFloat( cols[ j ] );
}
}
Returns a JSON representation of a Matrix. JSON#stringify implicitly calls this method when stringifying a Matrix instance.
var data = new Int8Array( 10 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
var mat = matrix( data, [5,2] );
/*
[ 0 1
2 3
4 5
6 7
8 9 ]
*/
var json = mat.toJSON();
/*
{
"type": "Matrix",
"dtype": "int8",
"shape": [5,2],
"offset": 0,
"strides": [2,1],
"raw": false,
"data": [0,1,2,3,4,5,6,7,8,9]
}
*/
To a revive a Matrix from a JSON string,
// Matrix reviver:
var reviver = require( 'dstructs-matrix-reviver' );
// Stringify a matrix (implicitly calls `.toJSON`):
var str = JSON.stringify( mat );
// returns '{"type":"Matrix","dtype":"int8","shape":[5,2],"offset":0,"strides":[2,1],"raw":false,"data":[0,1,2,3,4,5,6,7,8,9]}'
// Revive a Matrix from a JSON string:
var mat = JSON.parse( str, reviver );
/*
[ 0 1
2 3
4 5
6 7
8 9 ]
*/
A Matrix has a constructor having the following interface...
Creates a new Matrix having a specified shape, offset, strides, dtype, and underlying typed data store.
var data = new Float32Array( 10 );
var mat1 = matrix( data, [5,2] );
/*
[ 0 0
0 0
0 0
0 0
0 0 ]
*/
var mat2 = new mat1.constructor( data, mat1.dtype, [2,5], 0, [5,1] );
/*
[ 0 0 0 0 0
0 0 0 0 0 ]
*/
Note: while more performant, constructing a Matrix in this manner should be carefully considered. Arguments are not validated or sanity checked.
For performance, a lower-level interface is provided which forgoes some of the guarantees of the above API, such as input argument validation and measures to prevent Matrices 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 Matrices must be created.
Creates a new Matrix having a specified shape.
var data = new Float32Array( 10 );
var mat = matrix.raw( data, [5,2] );
/*
[ 0 0
0 0
0 0
0 0
0 0 ]
*/
If the input data type is known, Matrix creation is significantly faster.
var mat = matrix.raw( data, [5,2], 'float32' );
/*
[ 0 0
0 0
0 0
0 0
0 0 ]
*/
Notes:
shape and dtype parameters are the same as for the higher-level Matrix interface.dtype does not cast the data to a different storage type. Instead, providing the argument circumvents the need to determine the input data type, resulting in increased performance.data must be a typed array. Unlike the higher-level Matrix interface, plain arrays are not cast to float64. Providing a plain array can lead to subtle bugs and affect performance.Matrix properties and methods are the same as for the higher-level API, with the exception that Matrix properties are no longer read-only and methods do not perform input argument validation.Matrix can become corrupted; e.g., incompatible dimensions, out-of-bounds indexing, etc. In contrast to the strict API above, setting Matrix properties will not result in an error being thrown. Accordingly, property modification may introduce silent bugs.Matrix constructor has the same interface as the higher-level Matrix constructor.A linear index corresponds to an element position in a flattened Matrix arranged in row-major order. For example, consider a zero-filled 5x2 matrix, its subscripts, and its corresponding linear indices.
/*
Matrix Subscripts Indices
[ 0 0 [ a00 a01 [ 0 1
0 0 a10 a11 2 3
A = 0 0 => a20 a21 => 4 5
0 0 a30 a31 6 7
0 0 ] a40 a41 ] 8 9 ]
*/
var matrix = require( 'dstructs-matrix' );
// Create a new 2x2 matrix:
var mat = matrix( [2,2] );
console.log( mat );
// Inspect the initialized matrix elements:
console.log( mat.get( 1, 1 ) );
// Set a matrix element:
console.log( mat.set( 1, 1, 5 ) );
// Confirm that the matrix element was set:
console.log( mat.get( 1, 1 ) );
// Convert the matrix to a string:
console.log( mat.toString() );
// Convert the matrix to JSON:
console.log( mat.toJSON() );
To run the example code from the top-level application directory,
$ node ./examples/index.js
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.
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
Copyright © 2015. The Compute.io Authors.
FAQs
Matrices.
The npm package dstructs-matrix receives a total of 1,776 weekly downloads. As such, dstructs-matrix popularity was classified as popular.
We found that dstructs-matrix demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."