lomath
Version:
Lomath is a tensorial math library extended from lodash.
2,283 lines (1,578 loc) • 80 kB
Markdown
# index.js API documentation
<!-- div class="toc-container" -->
<!-- div -->
## `basics`
* <a href="#add">`add`</a>
* <a href="#c">`c`</a>
* <a href="#divide">`divide`</a>
* <a href="#fsum">`fsum`</a>
* <a href="#log">`log`</a>
* <a href="#logistic">`logistic`</a>
* <a href="#multiply">`multiply`</a>
* <a href="#prod">`prod`</a>
* <a href="#root">`root`</a>
* <a href="#square">`square`</a>
* <a href="#subtract">`subtract`</a>
* <a href="#sum">`sum`</a>
<!-- /div -->
<!-- div -->
## `combinatorics`
* <a href="#combList">`combList`</a>
* <a href="#combination">`combination`</a>
* <a href="#factorial">`factorial`</a>
* <a href="#genAry">`genAry`</a>
* <a href="#pSubset">`pSubset`</a>
* <a href="#permList">`permList`</a>
* <a href="#permutation">`permutation`</a>
* <a href="#permute">`permute`</a>
* <a href="#subset">`subset`</a>
* <a href="#toNumArr">`toNumArr`</a>
<!-- /div -->
<!-- div -->
## `composition`
* <a href="#asso">`asso`</a>
* <a href="#assodist">`assodist`</a>
* <a href="#distribute">`distribute`</a>
* <a href="#distributeBoth">`distributeBoth`</a>
* <a href="#distributeLeft">`distributeLeft`</a>
* <a href="#distributeRight">`distributeRight`</a>
* <a href="#distributeSingle">`distributeSingle`</a>
* <a href="#op">`op`</a>
<!-- /div -->
<!-- div -->
## `initialization`
* <a href="#numeric">`numeric`</a>
* <a href="#seq">`seq`</a>
<!-- /div -->
<!-- div -->
## `matrices`
* <a href="#adj">`adj`</a>
* <a href="#coMatrix">`coMatrix`</a>
* <a href="#coSubMatrix">`coSubMatrix`</a>
* <a href="#det">`det`</a>
* <a href="#detSum">`detSum`</a>
* <a href="#inv">`inv`</a>
* <a href="#matMultiply">`matMultiply`</a>
* <a href="#trace">`trace`</a>
* <a href="#transpose">`transpose`</a>
<!-- /div -->
<!-- div -->
## `native-Math`
* <a href="#abs">`abs`</a>
* <a href="#acos">`acos`</a>
* <a href="#acosh">`acosh`</a>
* <a href="#asin">`asin`</a>
* <a href="#asinh">`asinh`</a>
* <a href="#atan">`atan`</a>
* <a href="#atanh">`atanh`</a>
* <a href="#ceil">`ceil`</a>
* <a href="#cos">`cos`</a>
* <a href="#cosh">`cosh`</a>
* <a href="#exp">`exp`</a>
* <a href="#floor">`floor`</a>
* <a href="#log10">`log10`</a>
* <a href="#log1p">`log1p`</a>
* <a href="#log2">`log2`</a>
* <a href="#pow">`pow`</a>
* <a href="#round">`round`</a>
* <a href="#sign">`sign`</a>
* <a href="#sin">`sin`</a>
* <a href="#sinh">`sinh`</a>
* <a href="#sqrt">`sqrt`</a>
* <a href="#tan">`tan`</a>
* <a href="#tanh">`tanh`</a>
* <a href="#trunc">`trunc`</a>
<!-- /div -->
<!-- div -->
## `plotting`
* <a href="#advPlot">`advPlot`</a>
* <a href="#hc">`hc`</a>
* <a href="#plot">`plot`</a>
* <a href="#render">`render`</a>
<!-- /div -->
<!-- div -->
## `properties`
* <a href="#depth">`depth`</a>
* <a href="#dim">`dim`</a>
* <a href="#isFlat">`isFlat`</a>
* <a href="#maxDeepestLength">`maxDeepestLength`</a>
* <a href="#volume">`volume`</a>
<!-- /div -->
<!-- div -->
## `regexp`
* <a href="#reAnd">`reAnd`</a>
* <a href="#reAndMatch">`reAndMatch`</a>
* <a href="#reGet">`reGet`</a>
* <a href="#reMatch">`reMatch`</a>
* <a href="#reNotMatch">`reNotMatch`</a>
* <a href="#reOr">`reOr`</a>
* <a href="#reOrMatch">`reOrMatch`</a>
* <a href="#reString">`reString`</a>
* <a href="#reWrap">`reWrap`</a>
<!-- /div -->
<!-- div -->
## `signature`
* <a href="#deepEqual">`deepEqual`</a>
* <a href="#inRange">`inRange`</a>
* <a href="#isDouble">`isDouble`</a>
* <a href="#isInteger">`isInteger`</a>
* <a href="#isNegative">`isNegative`</a>
* <a href="#isPositive">`isPositive`</a>
* <a href="#isZero">`isZero`</a>
* <a href="#nonNegative">`nonNegative`</a>
* <a href="#nonPositive">`nonPositive`</a>
* <a href="#nonZero">`nonZero`</a>
* <a href="#parity">`parity`</a>
* <a href="#sameSig">`sameSig`</a>
<!-- /div -->
<!-- div -->
## `statistics`
* <a href="#expGRate">`expGRate`</a>
* <a href="#expVal">`expVal`</a>
* <a href="#mean">`mean`</a>
* <a href="#stdev">`stdev`</a>
* <a href="#trailExpGRate">`trailExpGRate`</a>
* <a href="#variance">`variance`</a>
<!-- /div -->
<!-- div -->
## `timing`
* <a href="#p">`p`</a>
* <a href="#tick">`tick`</a>
* <a href="#tock">`tock`</a>
<!-- /div -->
<!-- div -->
## `transformation`
* <a href="#batchIndexOf">`batchIndexOf`</a>
* <a href="#cbind">`cbind`</a>
* <a href="#cbindByField">`cbindByField`</a>
* <a href="#extend">`extend`</a>
* <a href="#flattenJSON">`flattenJSON`</a>
* <a href="#rbind">`rbind`</a>
* <a href="#rectangularize">`rectangularize`</a>
* <a href="#reshape">`reshape`</a>
* <a href="#reverse">`reverse`</a>
* <a href="#swap">`swap`</a>
* <a href="#unflattenJSON">`unflattenJSON`</a>
* <a href="#validInds">`validInds`</a>
<!-- /div -->
<!-- div -->
## `trend`
* <a href="#decreasing">`decreasing`</a>
* <a href="#increasing">`increasing`</a>
* <a href="#nonDecreasing">`nonDecreasing`</a>
* <a href="#nonIncreasing">`nonIncreasing`</a>
* <a href="#stairs">`stairs`</a>
* <a href="#stairsTrend">`stairsTrend`</a>
<!-- /div -->
<!-- div -->
## `vector`
* <a href="#dot">`dot`</a>
* <a href="#norm">`norm`</a>
* <a href="#normalize">`normalize`</a>
* <a href="#powSum">`powSum`</a>
* <a href="#rescale">`rescale`</a>
<!-- /div -->
<!-- div -->
## `Methods`
* <a href="#histogram">`histogram`</a>
<!-- /div -->
<!-- div -->
## `Properties`
<!-- /div -->
<!-- /div -->
<!-- div class="doc-container" -->
<!-- div -->
## `“basics” Methods`
<!-- div -->
### <a id="add"></a>`add([...X])`
<a href="#add">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L355 "View in source") [Ⓣ][1]
Adds tensors using `_.assodist`.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.add(1, 2, 3)
// → 6
_.add(1, [1, 2, 3])
// → [2, 3, 4]
_.add(1, [[1, 2], [3, 4]])
// → [[2, 3], [4, 5]]
_.add([10, 20], [[1, 2], [3, 4]])
// → [[11, 12], [23, 24]]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="c"></a>`c([...X])`
<a href="#c">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L245 "View in source") [Ⓣ][1]
Concatenates all arguments into single vector by `_.flattenDeep`.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(vector)*: A vector with the scalars from all tensors.
#### Example
```js
_.c('a', 'b', 'c')
// → ['a', 'b', 'c']
_.c(1, ['a', 'b', 'c'], 2)
// → [1, 'a', 'b', 'c', 2]
_.c([[1, 2], [3, 4])
// → [1, 2, 3, 4]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="divide"></a>`divide([...X])`
<a href="#divide">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L436 "View in source") [Ⓣ][1]
Divides tensors using `_.assodist`.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.divide(3, 2, 1)
// → 1.5
_.divide([1, 2, 3], 2)
// → [0.5, 1, 1.5]
_.divide([[1, 2], [3, 4]], 2)
// → [[0.5, 1], [1.5, 2]]
_.divide([[1, 2], [3, 4]], [1, 2])
// → [[1, 2], [1.5, 2]]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="fsum"></a>`fsum(T, fn)`
<a href="#fsum">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L293 "View in source") [Ⓣ][1]
Functional sum, Basically Sigma_i fn(T[i]) with fn(T, i), where T is a tensor, i is first level index.
#### Arguments
1. `T` *(tensor)*: A tensor.
2. `fn` *(function)*: A function fn(T, i) applied to the i-th term of T for the sum. Note the function can access the whole T for any term i for greater generality.
#### Returns
*(scalar)*: A scalar summed from all the terms from the mapped T fn(T, i).
#### Example
```js
// sum of the elements multiplied by indices in a sequence, i.e. Sigma_i i*(x_i)
_.fsum([1,1,1], function(T, i){
return T[i] * i;
})
// → 0+1+2
```
* * *
<!-- /div -->
<!-- div -->
### <a id="log"></a>`log(T, [n=e])`
<a href="#log">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L455 "View in source") [Ⓣ][1]
Takes the log of tensor T to base n (defaulted to e) element-wise using `_.distribute`.
#### Arguments
1. `T` *(tensor)*: A tensor.
2. `[n=e]` *(number)*: The optional base; defaulted to e.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.log([1, Math.E])
// → [0, 1]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="logistic"></a>`logistic(T)`
<a href="#logistic">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L516 "View in source") [Ⓣ][1]
Applies the logistic (sigmoid) function to tensor T element-wise.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.logistic([-10, 0, 10])
// → [ 0.00004539786870243441, 0.5, 0.9999546021312976 ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="multiply"></a>`multiply([...X])`
<a href="#multiply">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L409 "View in source") [Ⓣ][1]
Multiplies tensors using `_.assodist`.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.multiply(1, 2, 3)
// → 6
_.multiply(1, [1, 2, 3])
// → [1, 2, 3]
_.multiply(1, [[1, 2], [3, 4]])
// → [[1, 2], [3, 4]]
_.multiply([10, 20], [[1, 2], [3, 4]])
// → [[10, 20], [60, 80]]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="prod"></a>`prod([...X])`
<a href="#prod">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L324 "View in source") [Ⓣ][1]
Multiplies together all scalars in all argument tensors.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(scalar)*: A product scalar from all scalars in the tensors.
#### Example
```js
_.prod(1, 2, 3)
// → 6
_.prod([1, 2, 3])
// → 6
_.prod(1, [1, 2, 3], [[1, 2], [3, 4]])
// → 144
```
* * *
<!-- /div -->
<!-- div -->
### <a id="root"></a>`root(T, [n=2])`
<a href="#root">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L498 "View in source") [Ⓣ][1]
Takes the n-th root (defaulted to 2) of tensor T element-wise using `_.distribute`.
#### Arguments
1. `T` *(tensor)*: A tensor.
2. `[n=2]` *(number)*: The optional base; defaulted to `2` for squareroot.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.root([1, 4])
// → [1, 2]
_.root([-1, -8], 3)
// → [-1, -2]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="square"></a>`square(T)`
<a href="#square">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L473 "View in source") [Ⓣ][1]
Squares a tensor element-wise using `_.distributeSingle`.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.square([1, 2])
// → [1, 4]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="subtract"></a>`subtract([...X])`
<a href="#subtract">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L382 "View in source") [Ⓣ][1]
Subtracts tensors using `_.assodist`.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(tensor)*: A tensor.
#### Example
```js
_.subtract(1, 2, 3)
// → -5
_.subtract(1, [1, 2, 3])
// → [0, -1, -2]
_.subtract(1, [[1, 2], [3, 4]])
// → [[0, -1], [-2, -3]]
_.subtract([10, 20], [[1, 2], [3, 4]])
// → [[9, 8], [17, 16]]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="sum"></a>`sum([...X])`
<a href="#sum">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L270 "View in source") [Ⓣ][1]
Sums all scalars in all argument tensors.
#### Arguments
1. `[...X]` *(...tensors)*: tensors.
#### Returns
*(scalar)*: A scalar summed from all scalars in the tensors.
#### Example
```js
_.sum('a', 'b', 'c')
// → 'abc'
_.sum(0, [1, 2, 3], [[1, 2], [3, 4])
// → 16
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“combinatorics” Methods`
<!-- div -->
### <a id="combList"></a>`combList(n, r)`
<a href="#combList">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2042 "View in source") [Ⓣ][1]
Generates the indices of n-choose-r. Calls `_.subset` internally, chooses the array with string length r, and converts to numbers.
#### Arguments
1. `n` *(number)*: The number of items to choose.
2. `r` *(number)*: The number of items chosen.
#### Returns
*(Array)*: T The array of index arrays specifying the subset indices.
#### Example
```js
_.combList(3, 2)
// → [ [ 0, 1 ], [ 0, 2 ], [ 1, 2 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="combination"></a>`combination(n, r)`
<a href="#combination">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2146 "View in source") [Ⓣ][1]
Returns n-choose-r.
#### Arguments
1. `n` *(number)*: The integer.
2. `r` *(number)*: The integer.
#### Returns
*(number)*: nCr
#### Example
```js
_.combination(1000, 1)
// → 1000
_.combination(1000, 1000) // No integer overflow; uses symmetry.
// → 1
_.combination(1000, 500) // Inevitable overflow.
// → NaN
```
* * *
<!-- /div -->
<!-- div -->
### <a id="factorial"></a>`factorial(n)`
<a href="#factorial">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2092 "View in source") [Ⓣ][1]
Returns n!.
#### Arguments
1. `n` *(number)*: The integer.
#### Returns
*(number)*: n!
#### Example
```js
_.factorial(5)
// → 120
```
* * *
<!-- /div -->
<!-- div -->
### <a id="genAry"></a>`genAry(length, N)`
<a href="#genAry">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1915 "View in source") [Ⓣ][1]
Generates all the strings of N-nary numbers up to length.
#### Arguments
1. `length` *(number)*: The length of the N-nary numbers.
2. `N` *(number)*: The number base.
#### Returns
*(Array)*: T The array of strings of the N-nary numbers.
#### Example
```js
_.genAry(3, 2) // binary, length 3
// → ['000', '001', '010', '011', '100', '101', '110', '111']
_.genAry(2, 3) // ternary, length 2
// → ['00', '01', '02', '10', '11', '12', '20', '21', '22']
```
* * *
<!-- /div -->
<!-- div -->
### <a id="pSubset"></a>`pSubset(n)`
<a href="#pSubset">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1962 "View in source") [Ⓣ][1]
Generates all the permutation subset indices of n items.
#### Arguments
1. `n` *(number)*: The number of items to permute.
#### Returns
*(Array)*: T The array of strings of length n, specifying the permutation indices.
#### Example
```js
_.pSubset(3)
// → [
// ['0', '1', '2'],
// ['01', '02', '10', '12', '20', '21'],
// ['012', '021', '102', '120', '201', '210']
// ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="permList"></a>`permList(n, r)`
<a href="#permList">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2026 "View in source") [Ⓣ][1]
Generates the indices of n-permute-r. Calls `_.pSubset` internally, chooses the array with string length r, and converts to numbers.
#### Arguments
1. `n` *(number)*: The number of items to permute.
2. `r` *(number)*: The number of items chosen.
#### Returns
*(Array)*: T The array of index arrays specifying the permutation indices.
#### Example
```js
_.permList(3, 2)
// → [ [ 0, 1 ], [ 0, 2 ], [ 1, 0 ], [ 1, 2 ], [ 2, 0 ], [ 2, 1 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="permutation"></a>`permutation(n, r)`
<a href="#permutation">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2117 "View in source") [Ⓣ][1]
Returns n-permute-r.
#### Arguments
1. `n` *(number)*: The integer.
2. `r` *(number)*: The integer.
#### Returns
*(number)*: nPr
#### Example
```js
_.permutation(5, 5)
// → 120
_.permutation(1000, 1)
// → 1000
```
* * *
<!-- /div -->
<!-- div -->
### <a id="permute"></a>`permute(n)`
<a href="#permute">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2064 "View in source") [Ⓣ][1]
Generates the permutation indices of n items in lexicographical order.
#### Arguments
1. `n` *(number)*: The number of items to permute.
#### Returns
*(Array)*: T The array of index arrays specifying the permutation indices.
#### Example
```js
_.permute(3)
// → [
// [ 0, 1, 2 ],
// [ 0, 2, 1 ],
// [ 1, 0, 2 ],
// [ 1, 2, 0 ],
// [ 2, 0, 1 ],
// [ 2, 1, 0 ]
// ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="subset"></a>`subset(n)`
<a href="#subset">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1996 "View in source") [Ⓣ][1]
Generates all the (combination) subset indices of n items.
#### Arguments
1. `n` *(number)*: The number of items to choose.
#### Returns
*(Array)*: T The array of strings of length n, specifying the subset indices.
#### Example
```js
_.subset(3)
// → [
// ['0', '1', '2'],
// ['01', '02', '12'],
// ['012']
// ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="toNumArr"></a>`toNumArr(strings)`
<a href="#toNumArr">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1939 "View in source") [Ⓣ][1]
Converts an array of strings to array of array of numbers.
Used with `_.genAry` and related number/subset-generating functions.
#### Arguments
1. `strings` *(Array)*: The strings of numbers to convert into arrays.
#### Returns
*(Array)*: T The array of array of numbers from the strings.
#### Example
```js
_.toNumArr(['00', '01', '10', '11']) // binary, length 2
// → [[0, 0], [0, 1], [1, 0], [1, 1]]
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“composition” Methods`
<!-- div -->
### <a id="asso"></a>`asso(fn, [...x])`
<a href="#asso">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L185 "View in source") [Ⓣ][1]
Generic association: take the arguments object or array and apply atomic function (with scalar arguments) from left to right.
#### Arguments
1. `fn` *(Function)*: An atomic binary function *(both arguments must be scalars)*.
2. `[...x]` *(...number)*: Scalars; can be grouped in a single array.
#### Returns
*(number)*: A scalar from the function applied to all arguments in order.
#### Example
```js
_.asso(_.op, 'a', 'b', 'c')
// where _.op is used to show the order of composition
// → 'a*b*c'
_.asso(_.op, ['a', 'b', 'c'])
// → 'a*b*c'
```
* * *
<!-- /div -->
<!-- div -->
### <a id="assodist"></a>`assodist(fn, [...X])`
<a href="#assodist">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L218 "View in source") [Ⓣ][1]
Generic association with distributivity: Similar to `_.asso` but is for tensor functions; apply atomic fn distributively in order using `_.distribute`.
Usage: for applying fn on tensors element-wise if they have compatible dimensions.
#### Arguments
1. `fn` *(Function)*: An atomic binary function *(both arguments must be scalars)*.
2. `[...X]` *(...tensors)*: tensors.
#### Returns
*(tensor)*: A tensor from the function applied to all arguments in order.
#### Example
```js
_.assodist(_.op, 'a', 'b', 'c')
// where _.op is used to show the order of composition
// → 'a*b*c'
_.assodist(_.op, 'a', [1, 2, 3], 'b')
// → ['a*1*b', 'a*2*b', 'a*3*b']
_.assodist(_.op, 'a', [[1, 2], [3, 4]])
// → [['a*1', 'a*2'], ['a*3', 'a*4']]
_.assodist(_.op, ['a', 'b'], [[1, 2], [3, 4]])
// → [['a*1', 'a*2'], ['b*3', 'b*4']]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="distribute"></a>`distribute(fn, X, Y)`
<a href="#distribute">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L160 "View in source") [Ⓣ][1]
Generic Distribution: Distribute fn between left tensor X and right tensor Y, while preserving the argument-ordering (vital for non-commutative functions).
Pairs up the tensors term-wise while descending down the depths recursively using `_.distributeBoth`, until finding a scalar to `_.distributeLeft/Right`.
#### Arguments
1. `fn` *(Function)*: A binary function.
2. `X` *(tensor)*: A tensor.
3. `Y` *(tensor)*: A tensor.
#### Returns
*(tensor)*: A tensor from the function applied element-wise between X and Y.
#### Example
```js
_.distribute(_.op, 'a', [1, 2, 3])
// where _.op is used to show the order of composition
// → ['a*1', 'a*2', 'a*3']
_.distribute(_.op, 'a', [[1, 2], [3, 4])
// → [ [ 'a*1', 'a*2' ], [ 'a*3', 'a*4' ] ]
_.distribute(_.op, ['a', 'b', 'c'], [1, 2, 3])
// → [ 'a*1', 'b*2', 'c*3' ]
_.distribute(_.op, ['a', 'b', 'c'], [1, 2, 3, 4, 5, 6])
// → [ 'a*1', 'b*2', 'c*3' , 'a*4', 'b*5', 'c*6']
_.distribute(_.op, ['a', 'b', 'c'], [[1, 2], [3, 4], [5, 6]])
// → [ [ 'a*1', 'a*2' ], [ 'b*3', 'b*4' ], [ 'c*5', 'c*6' ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="distributeBoth"></a>`distributeBoth(fn, X, Y)`
<a href="#distributeBoth">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L117 "View in source") [Ⓣ][1]
Distributes a binary function between non-scalar tensors X, Y: pair them up term-wise and calling `_.distribute` recursively. Perserves the order of arguments.
If at any depth X and Y have different lengths, recycle if the mod of lengths is 0.
#### Arguments
1. `fn` *(Function)*: A binary function.
2. `X` *(tensor)*: A non-scalar tensor.
3. `Y` *(tensor)*: A non-scalar tensor.
#### Returns
*(tensor)*: A tensor from the function applied element-wise between X and Y.
#### Example
```js
_.distributeBoth(_.op, ['a', 'b', 'c'], [1, 2, 3])
// where _.op is used to show the order of composition
// → [ 'a*1', 'b*2', 'c*3' ]
_.distributeBoth(_.op, ['a', 'b', 'c'], [1, 2, 3, 4, 5, 6])
// → [ 'a*1', 'b*2', 'c*3' , 'a*4', 'b*5', 'c*6']
_.distributeBoth(_.op, ['a', 'b', 'c'], [[1, 2], [3, 4], [5, 6]])
// → [ [ 'a*1', 'a*2' ], [ 'b*3', 'b*4' ], [ 'c*5', 'c*6' ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="distributeLeft"></a>`distributeLeft(fn, X, y)`
<a href="#distributeLeft">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L63 "View in source") [Ⓣ][1]
Distributes a binary function with left tensor X over right scalar y. Preserves the order of arguments.
#### Arguments
1. `fn` *(Function)*: A binary function.
2. `X` *(tensor)*: A non-scalar tensor.
3. `y` *(number)*: A scalar.
#### Returns
*(tensor)*: A tensor from the function applied element-wise between X and y.
#### Example
```js
_.distributeLeft(_.op([1, 2, 3, 4], 5))
// where _.op is used to show the order of composition
// → [ '1*5', '2*5', '3*5', '4*5' ]
_.distributeLeft(_.op, [[1, 2], [3, 4]], 5)
// → [ [ '1*5', '2*5' ], [ '3*5', '4*5' ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="distributeRight"></a>`distributeRight(fn, x, Y)`
<a href="#distributeRight">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L88 "View in source") [Ⓣ][1]
Distributes a binary function with left scalar x over right tensor Y. Preserves the order of arguments.
#### Arguments
1. `fn` *(Function)*: A binary function.
2. `x` *(number)*: A scalar.
3. `Y` *(tensor)*: A non-scalar tensor.
#### Returns
*(tensor)*: A tensor from the function applied element-wise between x and Y.
#### Example
```js
_.distributeRight(_.op, 5, [1, 2, 3, 4])
// where _.op is used to show the order of composition
// → [ '5*1', '5*2', '5*3', '5*4' ]
_.distributeRight(_.op, 5, [[1, 2], [3, 4]])
// → [ [ '5*1', '5*2' ], [ '5*3', '5*4' ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="distributeSingle"></a>`distributeSingle(fn, Y)`
<a href="#distributeSingle">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L37 "View in source") [Ⓣ][1]
Distributes a unary function over every scalar in tensor Y.
#### Arguments
1. `fn` *(Function)*: A unary function.
2. `Y` *(tensor)*: A non-scalar tensor.
#### Returns
*(tensor)*: A tensor from the function applied element-wise to Y.
#### Example
```js
_.distributeSingle(_.square, [1, 2, 3, 4])
// → [ 1, 4, 9, 16 ]
_.distributeSingle(_.square, [[1, 2], [3, 4]])
// → [ [ 1, 4 ], [ 9, 16 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="op"></a>`op(x, y)`
<a href="#op">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L18 "View in source") [Ⓣ][1]
Sample operation to demonstrate function composition.
#### Arguments
1. `x` *(*)*: An argument.
2. `y` *(*)*: An argument.
#### Example
```js
_.op('a', 'b')
// → 'a*b'
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“initialization” Methods`
<!-- div -->
### <a id="numeric"></a>`numeric(N, [val=0])`
<a href="#numeric">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1136 "View in source") [Ⓣ][1]
Returns an initialized array of length N filled with the value (defaulted to 0). Reminiscent of `numeric()` of `R`.
#### Arguments
1. `N` *(number)*: The length of array.
2. `[val=0]` *(*)*: The value to fill array with.
#### Returns
*(Array)*: filled An array initialized to the value.
#### Example
```js
_.numeric(3)
// → [0, 0, 0]
_.numeric(3, 'a')
// → ['a', 'a', 'a']
```
* * *
<!-- /div -->
<!-- div -->
### <a id="seq"></a>`seq([start=0], end, [step=1])`
<a href="#seq">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1105 "View in source") [Ⓣ][1]
Returns a sequence of numbers from start to end, with interval. Similar to lodash's `_.range` but the default starts from 1; this is for `R` users who are familiar with `seq()`.
#### Arguments
1. `[start=0]` *(number)*: The start value.
2. `end` *(number)*: The end value.
3. `[step=1]` *(number)*: The interval step.
#### Returns
*(Array)*: seq An array initialized to the sequence.
#### Example
```js
_.seq(3)
// → [1, 2, 3]
_.seq(2, 4)
// → [2, 3, 4]
_.seq(1, 9, 2)
[ 1, 3, 5, 7, 9 ]
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“matrices” Methods`
<!-- div -->
### <a id="adj"></a>`adj(M)`
<a href="#adj">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1817 "View in source") [Ⓣ][1]
Returns the adjugate matrix, i.e. the transpose of the comatrix.
#### Arguments
1. `M` *(tensor)*: The original matrix.
#### Returns
*(tensor)*: A The adj matrix.
#### Example
```js
_.adj([[1,2,3],[4,5,6],[11,13,17]])
// → [ [ 7, 5, -3 ], [ -2, -16, 6 ], [ -3, 9, -3 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="coMatrix"></a>`coMatrix(M)`
<a href="#coMatrix">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1793 "View in source") [Ⓣ][1]
Returns the comatrix, i.e. the minor matrix or matrix of cofactors, of M.
#### Arguments
1. `M` *(tensor)*: The original matrix.
#### Returns
*(tensor)*: C The comatrix.
#### Example
```js
_.coMatrix([[1,2,3],[4,5,6],[11,13,17]])
// → [ [ 7, -2, -3 ], [ 5, -16, 9 ], [ -3, 6, -3 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="coSubMatrix"></a>`coSubMatrix(M, [r=0], [c=0])`
<a href="#coSubMatrix">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1765 "View in source") [Ⓣ][1]
Returns the submatrix for calculating cofactor, i.e. by taking out row r, col c from M.
#### Arguments
1. `M` *(tensor)*: The original matrix.
2. `[r=0]` *(number)*: The cofactor row.
3. `[c=0]` *(number)*: The cofactor col.
#### Returns
*(tensor)*: F The submatrix.
#### Example
```js
_.coSubMatrix([[1,2,3],[4,5,6],[7,8,9]])
// → [ [ 5, 6 ], [ 8, 9 ] ]
_.coSubMatrix([[1,2,3],[4,5,6],[7,8,9]], 0, 1)
// → [ [ 4, 6 ], [ 7, 9 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="det"></a>`det(M)`
<a href="#det">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1860 "View in source") [Ⓣ][1]
Returns the determinant of a matrix.
#### Arguments
1. `M` *(tensor)*: The matrix.
#### Returns
*(number)*: det The determinant.
#### Example
```js
_.det([[1,2,3],[4,5,6],[11,13,17]])
// → -6
```
* * *
<!-- /div -->
<!-- div -->
### <a id="detSum"></a>`detSum(M, i)`
<a href="#detSum">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1842 "View in source") [Ⓣ][1]
Helper function for determinant, used with _.fsum. Sums all the cofactors multiplied with the comatrices.
#### Arguments
1. `M` *(tensor)*: The original matrix.
2. `i` *(number)*: The index of cofactor, needed for parity.
#### Returns
*(number)*: recursive-sub-determinant Parity * cofactor * det(coSubMatrix)
#### Example
```js
_.detSum([[1,2,3],[4,5,6],[11,13,17]], 0)
// → 7
```
* * *
<!-- /div -->
<!-- div -->
### <a id="inv"></a>`inv(M)`
<a href="#inv">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1892 "View in source") [Ⓣ][1]
Returns the inverse of a matrix, or null if non-invertible.
#### Arguments
1. `M` *(tensor)*: The matrix.
#### Returns
*(tensor)*: Inv The inverse matrix, or null.
#### Example
```js
_.inv([[1,4,7],[3,0,5],[-1,9,11]])
// → [ [ 5.625, -2.375, -2.5 ],
// [ 4.75, -2.25, -2 ],
// [ -3.375, 1.625, 1.5 ] ]
_.inv([[1,1],[1,1]])
// → null
```
* * *
<!-- /div -->
<!-- div -->
### <a id="matMultiply"></a>`matMultiply(A, B)`
<a href="#matMultiply">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1742 "View in source") [Ⓣ][1]
Multiply two matrices.
#### Arguments
1. `A` *(tensor)*: The first matrix.
2. `B` *(tensor)*: The second matrix.
#### Returns
*(tensor)*: AB The two matrices multiplied together.
#### Example
```js
_.matMultiply([[1,2],[3,4]], [[1,2],[3,4]])
// → [ [ 7, 10 ], [ 15, 22 ] ]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="trace"></a>`trace(M)`
<a href="#trace">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1722 "View in source") [Ⓣ][1]
Returns the trace of a square matrix.
#### Arguments
1. `M` *(tensor)*: The matrix.
#### Returns
*(number)*: trM The trace of the matrix.
#### Example
```js
_.trace([[1, 2], [3, 4]])
// → 5
```
* * *
<!-- /div -->
<!-- div -->
### <a id="transpose"></a>`transpose(M)`
<a href="#transpose">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1707 "View in source") [Ⓣ][1]
Returns a copy of a matrix transposed.
#### Arguments
1. `M` *(tensor)*: The original matrix.
#### Returns
*(tensor)*: M' The copy transposed matrix.
#### Example
```js
_.transpose([[1, 2], [3, 4]])
// → [[ 1, 3 ], [ 2, 4 ]]
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“native-Math” Methods`
<!-- div -->
### <a id="abs"></a>`abs(T)`
<a href="#abs">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L690 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
#### Example
```js
_.abs([-1, -2, -3])
// → [1, 2, 3]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="acos"></a>`acos(T)`
<a href="#acos">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L699 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="acosh"></a>`acosh(T)`
<a href="#acosh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L708 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="asin"></a>`asin(T)`
<a href="#asin">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L717 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="asinh"></a>`asinh(T)`
<a href="#asinh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L726 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="atan"></a>`atan(T)`
<a href="#atan">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L735 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="atanh"></a>`atanh(T)`
<a href="#atanh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L744 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="ceil"></a>`ceil(T)`
<a href="#ceil">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L753 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="cos"></a>`cos(T)`
<a href="#cos">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L762 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="cosh"></a>`cosh(T)`
<a href="#cosh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L771 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="exp"></a>`exp(T)`
<a href="#exp">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L780 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="floor"></a>`floor(T)`
<a href="#floor">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L789 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="log10"></a>`log10(T)`
<a href="#log10">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L798 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="log1p"></a>`log1p(T)`
<a href="#log1p">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L807 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="log2"></a>`log2(T)`
<a href="#log2">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L816 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="pow"></a>`pow(T)`
<a href="#pow">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L834 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="round"></a>`round(T)`
<a href="#round">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L825 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="sign"></a>`sign(T)`
<a href="#sign">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L843 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="sin"></a>`sin(T)`
<a href="#sin">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L852 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="sinh"></a>`sinh(T)`
<a href="#sinh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L861 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="sqrt"></a>`sqrt(T)`
<a href="#sqrt">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L870 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="tan"></a>`tan(T)`
<a href="#tan">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L879 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="tanh"></a>`tanh(T)`
<a href="#tanh">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L888 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- div -->
### <a id="trunc"></a>`trunc(T)`
<a href="#trunc">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L897 "View in source") [Ⓣ][1]
Generalized JS Math applicable to tensor using function composition.
#### Arguments
1. `T` *(tensor)*: A tensor.
#### Returns
*(tensor)*: T A tensor.
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“plotting” Methods`
<!-- div -->
### <a id="advPlot"></a>`advPlot(options)`
<a href="#advPlot">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2705 "View in source") [Ⓣ][1]
Method of the constructed `hc` object.
Advanced plotting for users familiar with HighCharts (see http://www.highcharts.com).
This is a highcharts wrapper; takes in a complete HighCharts plot options object.
#### Arguments
1. `options` *(Object)*: The HighCharts options object.
#### Returns
*(Object)*: options The options passed, for reference.
#### Example
```js
// Plots using the highcharts options
hc.advPlot({
chart: {
type: 'column'
},
title: {
text: 'Monthly Average Rainfall'
},
subtitle: {
text: 'Source: WorldClimate.com'
},
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
crosshair: true
},
yAxis: {
min: 0,
title: {
text: 'Rainfall (mm)'
}
},
plotOptions: {
column: {
pointPadding: 0.2,
borderWidth: 0
}
},
series: [{
name: 'Tokyo',
data: [49.9, 71.5, 106.4, 129.2, 144.0, 176.0]
}, {
name: 'New York',
data: [83.6, 78.8, 98.5, 93.4, 106.0, 84.5]
}, {
name: 'London',
data: [48.9, 38.8, 39.3, 41.4, 47.0, 48.3]
}, {
name: 'Berlin',
data: [42.4, 33.2, 34.5, 39.7, 52.6, 75.5]
}]
})
// renders the plot
hc.render()
```
* * *
<!-- /div -->
<!-- div -->
### <a id="hc"></a>`hc()`
<a href="#hc">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2602 "View in source") [Ⓣ][1]
The plotting module constructor.
Uses `HighCharts` to plot and `browserSync`. Pulls up browser directly showing your charts like magic!
To use this, go into `node_modules/lomath` and do `npm install` there to install the dev dependencies.
#### Returns
*(Object)*: hc The plotting module of lomath.
#### Example
```js
// in the terminal at your project's root, do:
cd node_modules/lomath
npm install
// Go back to your project .js file
var _ = require('lomath');
var v = _.range(10);
var vv = _.square(v);
// Construct the plotting modules
var hc = _.hc();
// first, list all you wish to plot.
hc.plot(
[{
name: "linear",
data: v
}, {
name: "square",
data: vv
}],
"Title 1"
)
hc.plot(
[{
name: "log",
data: _.log(v)
}],
"Title 2"
)
// Finally, the command to render all the plots above.
// Pulls up a browser (default to chrome for better support) with the charts.
// calling hc.render(true) will autosave all plots to your downloads folder.
hc.render();
// Magical, eh?
```
* * *
<!-- /div -->
<!-- div -->
### <a id="plot"></a>`plot(seriesArr, [title=""], [yLabel=""], [xLabel=""])`
<a href="#plot">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2643 "View in source") [Ⓣ][1]
Method of the constructed `hc` object.
A simplified wrapper of the HighCharts plot options object.
Allows one to use simple data plot by specifying data sets in objects consisting of data name and data.
The data specified can be array of y-values, or array of x-y values.
#### Arguments
1. `seriesArr` *(Array)*: The array of data series, i.e. the series objects in the HighCharts options.
2. `[title=""]` *(string)*: The title of this plot.
3. `[yLabel=""]` *(string)*: The y-axis label.
4. `[xLabel=""]` *(string)*: The x-axis label.
#### Returns
*(Object)*: options The options passed, for reference.
#### Example
```js
// Plots two data sets using y-values (x-values start from 0).
hc.plot(
[{
name: "linear",
data: [1, 2, 3, 4, 5, 6]
}, {
name: "square",
data: [1, 4, 9, 16, 25, 36]
}],
"Title 1"
)
// Plots a data set using x-y values.
hc.plot(
[{
name: "square",
data: [[3, 9], [4, 16], [5, 25], [6, 36]]
}],
"Title 2"
)
// renders the plot
hc.render()
```
* * *
<!-- /div -->
<!-- div -->
### <a id="render"></a>`render([autosave])`
<a href="#render">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L2725 "View in source") [Ⓣ][1]
Method of the constructed `hc` object.
Renders the plots: Launches a browser with all the plots listed before this line. Uses a gulp task and browserSync.
Pass argument `true` will auto save all the plots to downloads.
#### Arguments
1. `[autosave]` *(boolean)*: If true, will autosave all the plots to downloads.
#### Returns
*(*)*: browser Pulls up a browser.
#### Example
```js
hc.plot(...)
// renders the plot in a browser
hc.render()
// hc.render(true) will autosave all plots.
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“properties” Methods`
<!-- div -->
### <a id="depth"></a>`depth(T)`
<a href="#depth">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1160 "View in source") [Ⓣ][1]
Returns the depth of an (nested) array, i.e. the rank of a tensor.
Scalar = rank-0, vector = rank-1, matrix = rank-2, ... so on.
Note that a tensor has homogenous depth, that is, there cannot tensors of different ranks in the same vector, e.g. [1, [2,3], 4] is prohibited.
#### Arguments
1. `T` *(tensor)*: The tensor.
#### Returns
*(number)*: depth The depth of the array.
#### Example
```js
_.depth(0)
// → 0
_.depth([1, 2, 3])
// → 1
_.depth([[1, 2], [3, 4]])
// → 2
```
* * *
<!-- /div -->
<!-- div -->
### <a id="dim"></a>`dim(T)`
<a href="#dim">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1217 "View in source") [Ⓣ][1]
Returns the "dimension" of a tensor.
Note that a tensor has homogenous depth, that is, there cannot tensors of different ranks in the same vector, e.g. [1, [2,3], 4] is prohibited.
#### Arguments
1. `T` *(tensor)*: The tensor.
#### Returns
*(Array)*: dim The dimension the tensor.
#### Example
```js
_.dim(0)
// → []
_.dim([1, 2, 3])
// → [3]
_.dim([[1, 2, 3], [4, 5, 6]])
// → [2, 3]
_.dim([
[[1,1,1,1],[2,2,2,2],[3,3,3,3]],
[[4,4,4,4],[5,5,5,5],[6,6,6,6]]
])
// → [2, 3, 4]
```
* * *
<!-- /div -->
<!-- div -->
### <a id="isFlat"></a>`isFlat(T)`
<a href="#isFlat">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1244 "View in source") [Ⓣ][1]
Checks if a tensor is "flat", i.e. all entries are scalars.
#### Arguments
1. `T` *(tensor)*: The tensor.
#### Returns
*(boolean)*: true If tensor is flat.
#### Example
```js
_.isFlat(0)
// → true
_.isFlat([1, 2, 3])
// → true
_.isFlat([[1, 2], [3, 4]])
// → false
```
* * *
<!-- /div -->
<!-- div -->
### <a id="maxDeepestLength"></a>`maxDeepestLength(T)`
<a href="#maxDeepestLength">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1272 "View in source") [Ⓣ][1]
Returns the maximum length of the deepest array in (non-scalar) tensor T.
Useful for probing the data structure and ensuring tensor is rectangular.
#### Arguments
1. `T` *(tensor)*: The tensor.
#### Returns
*(number)*: length The maximum length of the deepest array in T.
#### Example
```js
_.maxDeepestLength(0)
// → 0
_.maxDeepestLength([1, 2, 3])
// → 3
_.maxDeepestLength([[1, 2], [3, 4]])
// → 2
```
* * *
<!-- /div -->
<!-- div -->
### <a id="volume"></a>`volume(T)`
<a href="#volume">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1188 "View in source") [Ⓣ][1]
Returns the "volume" of a tensor, i.e. the totaly number of scalars in it.
#### Arguments
1. `T` *(tensor)*: The tensor.
#### Returns
*(number)*: volume The number of scalar entries in the tensor.
#### Example
```js
_.volume(0)
// → 0
_.volume([1, 2, 3])
// → 3
_.volume([[1, 2], [3, 4]])
// → 4
```
* * *
<!-- /div -->
<!-- /div -->
<!-- div -->
## `“regexp” Methods`
<!-- div -->
### <a id="reAnd"></a>`reAnd(regexs)`
<a href="#reAnd">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1006 "View in source") [Ⓣ][1]
Returns a single regex as the "AND" conjunction of all input regexs. This picks up as MANY adjacent substrings that satisfy all the regexs in order.
#### Arguments
1. `regexs` *(...RegExp)*: All the regexs to conjunct together.
#### Returns
*(RegExp)*: regex The conjuncted regex of the form `(?:re1)...(?:reN)`
#### Example
```js
var reg1 = _.reAnd('foo', /\d+/)
// → /(?:foo)(?:\d+)/
_.reGet(reg1)('Mayfoo1995')
// → 'foo1995'
var reg2 = _.reAnd(/\d+/, 'foo') // order matters here
// → /(?:\d+)(?:foo)/
_.reGet(reg2)('Mayfoo1995')
// → null
```
* * *
<!-- /div -->
<!-- div -->
### <a id="reAndMatch"></a>`reAndMatch(regexs)`
<a href="#reAndMatch">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1024 "View in source") [Ⓣ][1]
Returns a boolean function that matches all the regexs conjuncted in the specified order.
#### Arguments
1. `regexs` *(...RegExp)*: All the regexs to conjunct together.
#### Returns
*(Function)*: fn A boolean function used for matching the conjuncted regexs.
#### Example
```js
_.reAndMatch('foo', /\d+/)('Mayfoo1995')
// → true
_.reAndMatch(/\d+/, 'foo')('Mayfoo1995') // order matters
// → false
```
* * *
<!-- /div -->
<!-- div -->
### <a id="reGet"></a>`reGet(regex)`
<a href="#reGet">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L965 "View in source") [Ⓣ][1]
Returns a function that returns the first string portion matching the regex.
#### Arguments
1. `regex` *(RegExp)*: A RegExp to match.
#### Returns
*(Function)*: fn A function that returns the string matching the regex.
#### Example
```js
var getBar = _.reGet('bar') // using a string
getBar('foobarbaz')
// → 'bar'
var getNum = _.reGet(/\d+/) // using a regex
getNum('May 1995')
// → '1995'
getNum('May')
// → null
```
* * *
<!-- /div -->
<!-- div -->
### <a id="reMatch"></a>`reMatch(regex)`
<a href="#reMatch">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L917 "View in source") [Ⓣ][1]
Returns a boolean function that matches the regex.
#### Arguments
1. `regex` *(RegExp)*: A RegExp.
#### Returns
*(Function)*: fn A boolean function used for matching the regex.
#### Example
```js
var matcher1 = _.reMatch('foo') // using a string
matcher1('foobarbaz')
// → true
var matcher2 = _.reMatch(/\d+/) // using a regexp
matcher2('May 1995')
// → true
```
* * *
<!-- /div -->
<!-- div -->
### <a id="reNotMatch"></a>`reNotMatch(regex)`
<a href="#reNotMatch">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L940 "View in source") [Ⓣ][1]
Returns a boolean function that dis-matches the regex.
#### Arguments
1. `regex` *(RegExp)*: A RegExp to NOT match.
#### Returns
*(Function)*: fn A boolean function used for dis-matching the regex.
#### Example
```js
var matcher1 = _.reNotMatch('foo') // using a string
matcher1('barbaz')
// → true
var matcher2 = _.reNotMatch(/\d+/) // using a regexp
matcher2('foobar')
// → true
```
* * *
<!-- /div -->
<!-- div -->
### <a id="reOr"></a>`reOr(regexs)`
<a href="#reOr">#</a> [Ⓢ](https://github.com/kengz/lomath/blob/master/index.js#L1045 "View in source") [Ⓣ][1]
Returns a single regex as the "OR" union of all input regexs. This picks up the FIRST substring that satisfies any of the regexs in any order.
#### Arguments
1. `regexs` *(...RegExp)*: All the regexs to union together.
#### Returns
*(RegExp)*: regex The unioned regex of the form `(?:re1)|...|(?:reN)`
#### Example
```js
var reg1 = _.reOr('foo