Num4JS is a npm/bower package for scientific computing with JavaScript. It contains among other things:
- a powerful N-dimensional array object
- linear algebra function
- fast Fourier transform
- tools for basic image processing
Besides its obvious scientific uses, Num4JS can also be used as an efficient multi-dimensional container of generic data.
It works both in node.js and in the browser (with or without browserify)
Num4JS is licensed under the MIT license, enabling reuse with almost no restrictions.
Installation
on node.js
npm install num4js
var nj = ;...
on the browser
bower install num4js
Basics
Array Creation
> var a = nj;> a> var b = nj;> b
Note: Default data container is Javascript Array
object. If needed, you can also use typed array such as Int8Array
:
> var a = nj;> a
Note: possible types are int8, uint8, int16, uint16, int32, uint32, float32, float64 and array (the default)
To create arrays with a given shape, you can use zeros
, ones or random
functions:
> nj;> nj // dtype can also be specified > nj
To create sequences of numbers, Num4JS provides a function called arange
:
> nj; > nj > nj;
More info about the array
Num4JS’s array class is called NdArray
. It is also known by the alias array
. The more important properties of an NdArray
object are:
NdArray#ndim
: the number of axes (dimensions) of the array.NdArray#shape
: the dimensions of the array. This is a list of integers indicating the size of the array in each dimension. For a matrix with n rows and m columns, shape will be [n,m]. The length of the shape is therefore the number of dimensions, ndim.NdArray#size
: the total number of elements of the array. This is equal to the product of the elements of shape.NdArray#dtype
: a string describing the type of the elements in the array.int32
,int16
, andfloat64
are some examples. Default dtype isarray
.
An NdArray
can always be converted to a native JavaScript Array
using NdArray#tolist()
method.
Example:
> a = nj; > ashape 3 5> andim2> adtype'array'> a instanceof njNdArraytrue> a instanceof Arraytrue> a6> a> a
Printing arrays
When you print an array, Num4JS displays it in a similar way to nested lists, but with the following layout:
- the last axis is printed from left to right,
- the second-to-last is printed from top to bottom,
- the rest are also printed from top to bottom, with each slice separated from the next by an empty line.
One-dimensional arrays are then printed as rows, bidimensionals as matrices and tridimensionals as lists of matrices.
> var a = nj; // 1d array> console;>> var b = nj; // 2d array> console;>> var c = nj; // 3d array> console;
If an array is too large to be printed, Num4JS automatically skips the central part of the array and only prints the corners:
> console
To customize this behaviour, you can change the printing options using nj.config.printThreshold
(default is 7
):
> njconfigprintThreshold = 9;> console
Basic operations
Arithmetic operators such as *
(multiply
), +
(add
), -
(subtract
), /
(divide
), **
(pow
) apply elemen-twise. A new array is created and filled with the result:
> zeros = nj;>> ones = nj;>> ones>> ones>> zeros
To modify an existing array rather than create a new one you can set the copy
parameter to false
:
> ones = nj;>> ones>> ones
Note: available for add
, subtract
, multiply
, divide
and pow
methods.
The matrix product can be performed using the dot
function:
> a = nj;>> nj>> nj
Many unary operations, such as computing the sum of all the elements in the array, are implemented as methods of the NdArray
class:
> a = nj> a31126488673035055>> a02138431086204946>> a08278025290928781>> a05187748112172509>> a022216977543691244
Universal Functions
Num4JS provides familiar mathematical functions such as sin
, cos
, and exp
. These functions operate element-wise on an array, producing an NdArray
as output:
> a = nj>> nj>> nj>> nj>> nj>> nj>> nj>> nj>> nj>> nj>> nj>> nj
Shape Manipulation
An array has a shape given by the number of elements along each axis:
> a = nj; > ashape 3 4
The shape of an array can be changed with various commands:
> a;>> aT // equivalent to a.transpose(1,0)>> a
Concatenate different arrays
Several arrays can be stacked together using concatenate
function:
> a = nj>> b = nj>> nj
Notes:
- the arrays must have the same shape, except in the last dimension
- arrays are concatenated along the last axis
It is still possible to concatenate along other dimensions using transpositions:
> a = nj>> b = nj>> njT
Deep Copy
The clone
method makes a complete copy of the array and its data.
> a = nj>> b = a>> a === bfalse>> a> a> b
Fast Fourier Transform (FFT)
fft
and ifft
functions can be used to compute the N-dimensional discrete Fourier Transform and its inverse.
Example:
> RI = nj>> fft = nj>> nj
Note: both fft
and ifft
expect last dimension of the array to contain 2 values: the real and the imaginary value
Convolution
convolve
and fftconvolve
functions can be used to compute the discrete, linear convolution of two multi-dimensional arrays.
Example:
> x = nj>> nj>> var a = nj> a> nj> nj
Note: fftconvolve
uses Fast Fourier Transform (FFT) to speed up computation on large arrays.
Images manipulation
Num4JS’s comes with powerful functions for image processing. Theses function are located in nj.images
module.
The different color bands/channels are stored using the NdArray
object such that a grey-image is [H,W]
, an RGB-image is [H,W,3]
and an RGBA-image is [H,W,4]
.
Use nj.images.read
, nj.images.write
and nj.images.resize
to (respectively) read, write or resize images.
Example:
> njconfigprintThreshold = 28;>> var img = njimagesdatadigit; // WARN: this is a property, not a function. See also `nj.images.data.moon`, `nj.images.data.lenna` and `nj.images.data.node`>> img> var resized = njimages>> resizedshape 14 12 >> resized
See also this jsfiddle for more details on what is possible from the browser.
More ?
See documentation.
Credits
Num4JS is built on top of ndarray and uses many scijs packages