more array creation, argmin and argmax, and applyOverAxis functions

README.md

@@ -62,12 +62,13 @@ array([ 1, 2, 3], dtype=uint8)
 
 __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:
+To create arrays with a given shape, you can use `zeros`, `ones`, `random`, and `full` functions:
 
 ```js
 > nj.zeros([2,3]);
 array([[ 0, 0, 0],
        [ 0, 0, 0]])
+
 > nj.ones([2,3,4], 'int32')     // dtype can also be specified
 array([[[ 1, 1, 1, 1],
         [ 1, 1, 1, 1],
@@ -81,6 +82,38 @@ array([[ 0.9182 , 0.85176, 0.22587],
        [ 0.50088, 0.74376, 0.84024],
        [ 0.74045, 0.23345, 0.20289],
        [ 0.00612, 0.37732, 0.06932]])
+
+> nj.full([3,3], -3.14159)
+array([[ -3.14159, -3.14159, -3.14159],
+       [ -3.14159, -3.14159, -3.14159],
+       [ -3.14159, -3.14159, -3.14159]])
+
+> nj.full([3, 2], [1, 2])
+array([[ 1, 2],
+       [ 1, 2],
+       [ 1, 2]])
+```
+
+You can also infer the shape from another array with methods like `zerosLike`, `onesLike`, `randomLike`, and `fullLike`:
+
+Given `const arr = nj.array([[1,2], [3,4]]);` which has shape of (2,2)
+
+```js
+> nj.zerosLike(arr);
+array([[ 0, 0],
+       [ 0, 0]])
+
+> nj.onesLike(arr, 'int32')     // dtype can also be specified
+array([[ 1, 1],
+       [ 1, 1]], dtype=int32)
+
+> nj.randomLike(arr)
+array([[ 0.82251, 0.76331],
+       [ 0.22786, 0.73417]])
+
+> nj.fullLike(arr, -3.14159)
+array([[ -3.14159, -3.14159],
+       [ -3.14159, -3.14159]])
 ```
 
 To create sequences of numbers, __NumJs__ provides a function called `arange`:
@@ -96,6 +129,25 @@ array([ 10, 15, 20, 25])
 array([ 1, 2, 3, 4], dtype=uint8)
 ```
 
+To generate matrices with nice properties like the identity `eye` or a triangular `tri`:
+
+```js
+> nj.eye(3, 3)
+array([[ 1, 0, 0],
+       [ 0, 1, 0], 
+       [ 0, 0, 1]])
+
+> nj.tri(3, 3) // fills diagonal under k=0 
+array([[ 0, 0, 0], 
+       [ 1, 0, 0], 
+       [ 1, 1, 0]])
+
+> nj.tri(3, 3, 1) // fills diagonal under k=1 
+array([[ 1, 0, 0], 
+       [ 1, 1, 0], 
+       [ 1, 1, 1]])
+```
+
 ### More info about the array
 
 __NumJs__’s array class is called `NdArray`. It is also known by the alias `array`. The more important properties of an `NdArray` object are:
@@ -369,16 +421,67 @@ array([[0.62755, 0.8278,0.21384],
 > a.min()
 0.2138431086204946
 >
+> a.argmin() // index of a.min()
+[[0, 2]]
+>
 > a.max()
 0.8278025290928781
 >
+> a.argmax() // index of a.max()
+[[0, 1]]
+>
 > a.mean()
 0.5187748112172509
 >
 > a.std()
 0.22216977543691244
 ```
 
+### Applying Functions over an Axis
+
+Commonly, you might want to apply a vector function across an axis of a matrix. You can do this with the `applyOverAxis` function. For example suppose I have a matrix a
+
+```js
+> a = nj.array([[0, 1, 2], 
+                [3, 4, 5]])
+```
+
+You can sum across the ith axis. For example the last axis is the rows, so I can specify the last axis -1
+
+```js
+> nj.applyOverAxis(a, nj.sum, { axis: -1 })
+array([  3, 12])
+```
+
+Or find the max down the columns (first axis is 0)
+```js
+> nj.applyOverAxis(a, nj.max, { axis: 0 })
+array([ 3, 4, 5])
+```
+
+If you don't want to reduce the shape/dimensions of the output, you can put `keepdims: true`. For example when we summed across the rows I can maintain those row dimensions like 
+
+```js
+> nj.applyOverAxis(a, nj.sum, { axis: -1, keepdims: true })
+array([[  3],
+       [ 12]])
+```
+
+This also works for tensors for example an array with (2,2,2) shape I can find the mean across the last axis:
+
+```js
+> b = array([[[ 0, 1],
+              [ 2, 3]],
+              [[ 4, 5],
+              [ 6, 7]]])
+>
+> nj.applyOverAxis(b, nj.mean, { axis: -1, keepdims: true })
+array([[[ 0.5],
+        [ 2.5]],
+       [[ 4.5],
+        [ 6.5]]])
+```
+
 ### Universal Functions
 __NumJs__ provides familiar mathematical functions such as `sin`, `cos`, and `exp`. These functions operate element-wise on an array, producing an `NdArray` as output: