# compute-matrix-function

> Applies a function to each matrix element.

Latest version **1.0.2** (published 2015-08-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install compute-matrix-function
pnpm add compute-matrix-function
yarn add compute-matrix-function
bun add compute-matrix-function
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2015-08-16 |
| First published | 2015-08-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Athan Reines |
| Maintainers | kgryte |
| Keywords | compute.io, compute, computation, utility, util, matrices, matrix, dstructs, element-wise, apply, function |

## Links

- npm: https://www.npmjs.com/package/compute-matrix-function
- Repository: https://github.com/compute-io/matrix-function
- Homepage: https://github.com/compute-io/matrix-function#readme
- Issues: https://github.com/compute-io/matrix-function/issues
- npm.io page: https://npm.io/package/compute-matrix-function

## Dependencies (7)

- [dstructs-matrix](https://npm.io/package/dstructs-matrix.md) ^2.0.0
- [validate.io-object](https://npm.io/package/validate.io-object.md) ^1.0.4
- [validate.io-function](https://npm.io/package/validate.io-function.md) ^1.0.2
- [validate.io-matrix-like](https://npm.io/package/validate.io-matrix-like.md) ^1.0.2
- [validate.io-positive-integer](https://npm.io/package/validate.io-positive-integer.md) ^1.0.0
- [validate.io-string-primitive](https://npm.io/package/validate.io-string-primitive.md) ^1.0.0
- [validate.io-boolean-primitive](https://npm.io/package/validate.io-boolean-primitive.md) ^1.0.0

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2015-08-16
- 1.0.1 — 2015-08-11
- 1.0.0 — 2015-08-11
- 0.0.0 — 2015-08-11

## README

Matrix Function
===
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependencies][dependencies-image]][dependencies-url]

> Applies a function to each [matrix](https://github.com/dstructs/matrix) element.


## Installation

``` bash
$ npm install compute-matrix-function
```

For use in the browser, use [browserify](https://github.com/substack/node-browserify).


## Usage

``` javascript
var matrixfun = require( 'compute-matrix-function' );
```

<a name="matrixfun"></a>
#### matrixfun( fcn, ...matrix[, options] )

Applies a `function` to each [`matrix`](https://github.com/dstructs/matrix) element.

``` javascript
var matrix = require( 'dstructs-matrix' );

var mat = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

function add5( val ) {
	return val + 5;
}

var out = matrixfun( add5, mat );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/
```

The function accepts the following `options`:

*	__dtype__: output data type. Default: `float64`.
*	__out__: `boolean` indicating whether an output [`matrix`](https://github.com/dstructs/matrix) has been provided. Default: `false`.

By default, the output [`matrix`](https://github.com/dstructs/matrix) data type is `float64` in order to preserve precision. To specify a different data type, set the `dtype` option (see [`matrix`](https://github.com/dstructs/matrix) for a list of acceptable data types).

``` javascript
var out = matrixfun( add5, mat, {
	'dtype': 'int8';
});
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/
var dtype = out.dtype;
// returns 'int8'
```

By default, the `function` returns a new [`matrix`](https://github.com/dstructs/matrix). To mutate a [`matrix`](https://github.com/dstructs/matrix) (e.g., when input values can be discarded or when optimizing memory usage), set the `out` option to `true` to indicate that an output [`matrix`](https://github.com/dstructs/matrix) has been provided as the __first__ [`matrix`](https://github.com/dstructs/matrix) argument.

``` javascript
var out = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

matrixfun( add5, out, mat, {
	'out': 'true';
});
/*
      [ 5 5 5 5 5
        5 5 5 5 5
out =   5 5 5 5 5
        5 5 5 5 5
        5 5 5 5 5 ]
*/
```

===
### Factory

The main exported `function` does __not__ make any assumptions regarding the number of input [`matrices`](https://github.com/dstructs/matrix). To create a reusable [`matrix`](https://github.com/dstructs/matrix) function where the number of input [`matrices`](https://github.com/dstructs/matrix) is known, a factory method is provided.


<a name="matrixfun-factory"></a>
#### matrixfun.factory( [fcn,] num[, options] )

Creates an apply `function` to apply a `function` to each [`matrix`](https://github.com/dstructs/matrix) element.

``` javascript
var mfun = matrixfun.factory( 2 );

function add( x, y ) {
	return x + y;
}

var mat1 = matrix( [5,5], 'int8' ),
	mat2 = matrix( [5,5], 'int8' );

for ( var i = 0; i < 5; i++ ) {
	for ( var j = 0; j < 5; j++ ) {
		mat1.set( i, j, 5 );
		mat2.set( i, j, i*5 + j );
	}
}
/*
       [ 5 5 5 5 5
         5 5 5 5 5
mat1 =   5 5 5 5 5
         5 5 5 5 5
         5 5 5 5 5 ]

       [  0  1  2  3  4
          5  6  7  8  9
mat2 =   10 11 12 13 14
         15 16 17 18 19
         20 21 22 23 24 ]
*/

var out = mfun( add, mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/
```

An apply `function` may be provided during `function` creation.

``` javascript
var madd = matrixfun.factory( add, 2 );

var out = madd( mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/
```

The function accepts the following `options`:

*	__dtype__: output data type. Default: `float64`.

By default, the output [`matrix`](https://github.com/dstructs/matrix) data type is `float64`. To specify a different data type, set the `dtype` option.

``` javascript
var madd = matrixfun.factory( add, 2, {
	'dtype': 'int32';
});

var out = madd( mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/

var dtype = out.dtype;
// returns 'int32'

// ...and for all subsequent calls...
out = madd( mat1, mat2 );
dtype = out.dtype;
// returns 'int32'
```

__Note__: a factory `function` __always__ returns a new [`matrix`](https://github.com/dstructs/matrix).


===
### Create

To facilitate using [`matrix`](https://github.com/dstructs/matrix) functions within an application where input arguments are of known types and where memory management occurs externally, a method to create minimal [`matrix`](https://github.com/dstructs/matrix) functions is provided.

#### matrixfun.create( [fcn,] num )

Creates an apply `function` to apply a `function` to each [`matrix`](https://github.com/dstructs/matrix) element, where `num` is the number of input [`matrices`](https://github.com/dstructs/matrix) __excluding__ the output [`matrix`](https://github.com/dstructs/matrix).

``` javascript
var mfcn = matrixfun.create( 2 );

var out = mfcn( add, out, mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/

function subtract( x, y ) {
	return x - y;
}

out = mfcn( subtract, out, mat2, mat1 );
/*
    [ -5 -4 -3 -2 -1
       0  1  2  3  4
       5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19 ]
*/
```

An apply `function` may be provided during `function` creation.

``` javascript
var madd = matrixfun.create( add, 2 );

var out = madd( out, mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/
```



===
### Raw

Lower-level APIs are provided which forgo some of the guarantees of the above APIs, such as input argument validation. While use of the above APIs is encouraged in REPL environments, use of the lower-level interfaces may be warranted when arguments are of a known type or when performance is paramount.

#### matrixfun.raw( fcn, ...matrix[, options] )

Applies a `function` to each [`matrix`](https://github.com/dstructs/matrix) element.

``` javascript
var mat = matrix( [5,5], 'int8' );
/*
    [ 0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0
      0 0 0 0 0 ]
*/

var out = matrixfun.raw( add5, mat );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/
```

The function accepts the same `options` as the main exported [function](#matrixfun).


#### matrixfun.rawFactory( [fcn,] num[, options] )

Creates an apply `function` to apply a `function` to each [`matrix`](https://github.com/dstructs/matrix) element.

``` javascript
var mfun = matrixfun.rawFactory( 2 );

var out = mfun( add, mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/
```

The function accepts the same `options` as [`matrixfun.factory()`](#matrixfun-factory).



## Notes

*	Both factory methods, as well as the `.create()` method, use dynamic code evaluation. Beware when using these methods in the browser as they may violate your [content security policy](https://developer.mozilla.org/en-US/docs/Web/Security/CSP) (CSP). 



## Examples

``` javascript
var matrix = require( 'dstructs-matrix' ),
	matrixfun = require( 'compute-matrix-function' );

var mat1,
	mat2,
	out,
	d, i;

d = new Int32Array( 25 );
for ( i = 0; i < d.length; i++ ) {
	d[ i ] = i;
}
mat1 = matrix( d, [5,5], 'int32' );
/*
    [  0  1  2  3  4
       5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24 ]
*/

d = new Int8Array( 25 );
for ( i = 0; i < d.length; i++ ) {
	d[ i ] = 5;
}
mat2 = matrix( d, [5,5], 'int8' );
/*
    [ 5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5
      5 5 5 5 5 ]
*/

function add( x, y ) {
	return x + y;
}

out = matrixfun( add, mat1, mat2 );
/*
    [  5  6  7  8  9
      10 11 12 13 14
      15 16 17 18 19
      20 21 22 23 24
      25 26 27 28 29 ]
*/
console.log( out.toString() );
```

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

``` bash
$ node ./examples/index.js
```


## Tests

### Unit

Unit tests use the [Mocha](http://mochajs.org/) test framework with [Chai](http://chaijs.com) assertions. To run the tests, execute the following command in the top-level application directory:

``` bash
$ make test
```

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


### Test Coverage

This repository uses [Istanbul](https://github.com/gotwarlost/istanbul) as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

``` bash
$ make test-cov
```

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

``` bash
$ make view-cov
```


---
## License

[MIT license](http://opensource.org/licenses/MIT).


## Copyright

Copyright &copy; 2015. The [Compute.io](https://github.com/compute-io) Authors.


[npm-image]: http://img.shields.io/npm/v/compute-matrix-function.svg
[npm-url]: https://npmjs.org/package/compute-matrix-function

[travis-image]: http://img.shields.io/travis/compute-io/matrix-function/master.svg
[travis-url]: https://travis-ci.org/compute-io/matrix-function

[codecov-image]: https://img.shields.io/codecov/c/github/compute-io/matrix-function/master.svg
[codecov-url]: https://codecov.io/github/compute-io/matrix-function?branch=master

[dependencies-image]: http://img.shields.io/david/compute-io/matrix-function.svg
[dependencies-url]: https://david-dm.org/compute-io/matrix-function

[dev-dependencies-image]: http://img.shields.io/david/dev/compute-io/matrix-function.svg
[dev-dependencies-url]: https://david-dm.org/dev/compute-io/matrix-function

[github-issues-image]: http://img.shields.io/github/issues/compute-io/matrix-function.svg
[github-issues-url]: https://github.com/compute-io/matrix-function/issues

---
_Source: https://npm.io/package/compute-matrix-function · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._