ml-matrix 6.8.1 → 6.10.0

package/README.md

@@ -12,9 +12,9 @@ Matrix manipulation and computation library.
     Maintained by <a href="https://www.zakodium.com">Zakodium</a>
   </p>
 
-  [![NPM version][npm-image]][npm-url]
-  [![build status][ci-image]][ci-url]
-  [![npm download][download-image]][download-url]
+[![NPM version][npm-image]][npm-url]
+[![build status][ci-image]][ci-url]
+[![npm download][download-image]][download-url]
 
 </h3>
 
@@ -40,7 +40,7 @@ const { Matrix } = require('ml-matrix');
 const matrix = Matrix.ones(5, 5);
 ```
 
-## [API Documentation](https://mljs.github.io/matrix/globals.html)
+## [API Documentation](https://mljs.github.io/matrix/)
 
 ## Examples
 
@@ -49,9 +49,18 @@ const matrix = Matrix.ones(5, 5);
 ```js
 const { Matrix } = require('ml-matrix');
 
-var A = new Matrix([[1, 1], [2, 2]]);
-var B = new Matrix([[3, 3], [1, 1]]);
-var C = new Matrix([[3, 3], [1, 1]]);
+var A = new Matrix([
+  [1, 1],
+  [2, 2],
+]);
+var B = new Matrix([
+  [3, 3],
+  [1, 1],
+]);
+var C = new Matrix([
+  [3, 3],
+  [1, 1],
+]);
 
 // ============================
 // Operations with the matrix :
@@ -75,8 +84,11 @@ C.div(10); // => C = Cinit
 C.mod(2); // => C = Cinit % 2
 
 // Standard Math operations : (abs, cos, round, etc.)
-var A = new Matrix([[1, 1], [-1, -1]]);
-var expon = Matrix.exp(A); // expon = Matrix [[Math.exp(1), Math.exp(1)], [Math.exp(-1), Math.exp(-1)], rows: 2, columns: 2].
+var A = new Matrix([
+  [1, 1],
+  [-1, -1],
+]);
+var exponential = Matrix.exp(A); // exponential = Matrix [[Math.exp(1), Math.exp(1)], [Math.exp(-1), Math.exp(-1)], rows: 2, columns: 2].
 var cosinus = Matrix.cos(A); // cosinus = Matrix [[Math.cos(1), Math.cos(1)], [Math.cos(-1), Math.cos(-1)], rows: 2, columns: 2].
 var absolute = Matrix.abs(A); // expon = absolute [[1, 1], [1, 1], rows: 2, columns: 2].
 // you can use 'abs', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atanh', 'cbrt', 'ceil', 'clz32', 'cos', 'cosh', 'exp', 'expm1', 'floor', 'fround', 'log', 'log1p', 'log10', 'log2', 'round', 'sign', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'trunc'
@@ -122,24 +134,36 @@ const {
   QrDecomposition,
   LuDecomposition,
   CholeskyDecomposition,
-  EigenvalueDecomposition
+  EigenvalueDecomposition,
 } = require('ml-matrix');
 
 //===========================
 // inverse and pseudo-inverse
 //===========================
 
-var A = new Matrix([[2, 3, 5], [4, 1, 6], [1, 3, 0]]);
+var A = new Matrix([
+  [2, 3, 5],
+  [4, 1, 6],
+  [1, 3, 0],
+]);
 var inverseA = inverse(A);
 var B = A.mmul(inverseA); // B = A * inverse(A), so B ~= Identity
 
 // if A is singular, you can use SVD :
-var A = new Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]]); // A is singular, so the standard computation of inverse won't work (you can test if you don't trust me^^)
+var A = new Matrix([
+  [1, 2, 3],
+  [4, 5, 6],
+  [7, 8, 9],
+]); // A is singular, so the standard computation of inverse won't work (you can test if you don't trust me^^)
 var inverseA = inverse(A, (useSVD = true)); // inverseA is only an approximation of the inverse, by using the Singular Values Decomposition
 var B = A.mmul(inverseA); // B = A * inverse(A), but inverse(A) is only an approximation, so B doesn't really be identity.
 
 // if you want the pseudo-inverse of a matrix :
-var A = new Matrix([[1, 2], [3, 4], [5, 6]]);
+var A = new Matrix([
+  [1, 2],
+  [3, 4],
+  [5, 6],
+]);
 var pseudoInverseA = A.pseudoInverse();
 var B = A.mmul(pseudoInverseA).mmul(A); // with pseudo inverse, A*pseudo-inverse(A)*A ~= A. It's the case here
 
@@ -151,13 +175,22 @@ var B = A.mmul(pseudoInverseA).mmul(A); // with pseudo inverse, A*pseudo-inverse
 // Below, how to solve least square with our function
 
 // If A is non singular :
-var A = new Matrix([[3, 1], [4.25, 1], [5.5, 1], [8, 1]]);
+var A = new Matrix([
+  [3, 1],
+  [4.25, 1],
+  [5.5, 1],
+  [8, 1],
+]);
 var b = Matrix.columnVector([4.5, 4.25, 5.5, 5.5]);
 var x = solve(A, b);
 var error = Matrix.sub(b, A.mmul(x)); // The error enables to evaluate the solution x found.
 
 // If A is non singular :
-var A = new Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
+var A = new Matrix([
+  [1, 2, 3],
+  [4, 5, 6],
+  [7, 8, 9],
+]);
 var b = Matrix.columnVector([8, 20, 32]);
 var x = solve(A, b, (useSVD = true)); // there are many solutions. x can be [1, 2, 1].transpose(), or [1.33, 1.33, 1.33].transpose(), etc.
 var error = Matrix.sub(b, A.mmul(x)); // The error enables to evaluate the solution x found.
@@ -168,7 +201,11 @@ var error = Matrix.sub(b, A.mmul(x)); // The error enables to evaluate the solut
 
 // QR Decomposition
 
-var A = new Matrix([[2, 3, 5], [4, 1, 6], [1, 3, 0]]);
+var A = new Matrix([
+  [2, 3, 5],
+  [4, 1, 6],
+  [1, 3, 0],
+]);
 var QR = new QrDecomposition(A);
 var Q = QR.orthogonalMatrix;
 var R = QR.upperTriangularMatrix;
@@ -176,7 +213,11 @@ var R = QR.upperTriangularMatrix;
 
 // LU Decomposition
 
-var A = new Matrix([[2, 3, 5], [4, 1, 6], [1, 3, 0]]);
+var A = new Matrix([
+  [2, 3, 5],
+  [4, 1, 6],
+  [1, 3, 0],
+]);
 var LU = new LuDecomposition(A);
 var L = LU.lowerTriangularMatrix;
 var U = LU.upperTriangularMatrix;
@@ -185,13 +226,21 @@ var P = LU.pivotPermutationVector;
 
 // Cholesky Decomposition
 
-var A = new Matrix([[2, 3, 5], [4, 1, 6], [1, 3, 0]]);
+var A = new Matrix([
+  [2, 3, 5],
+  [4, 1, 6],
+  [1, 3, 0],
+]);
 var cholesky = new CholeskyDecomposition(A);
 var L = cholesky.lowerTriangularMatrix;
 
 // Eigenvalues & eigenvectors
 
-var A = new Matrix([[2, 3, 5], [4, 1, 6], [1, 3, 0]]);
+var A = new Matrix([
+  [2, 3, 5],
+  [4, 1, 6],
+  [1, 3, 0],
+]);
 var e = new EigenvalueDecomposition(A);
 var real = e.realEigenvalues;
 var imaginary = e.imaginaryEigenvalues;
@@ -218,7 +267,7 @@ var dependencies = linearDependencies(A); // dependencies is a matrix with the d
 
 [npm-image]: https://img.shields.io/npm/v/ml-matrix.svg
 [npm-url]: https://npmjs.org/package/ml-matrix
-[ci-image]: https://github.com/mljs/matrix/workflows/Node.js%20CI/badge.svg?branch=master
+[ci-image]: https://github.com/mljs/matrix/workflows/Node.js%20CI/badge.svg?branch=main
 [ci-url]: https://github.com/mljs/matrix/actions?query=workflow%3A%22Node.js+CI%22
 [download-image]: https://img.shields.io/npm/dm/ml-matrix.svg
 [download-url]: https://npmjs.org/package/ml-matrix

package/matrix.d.ts

@@ -1,4 +1,4 @@
-type MaybeMatrix = AbstractMatrix | number[][];
+type MaybeMatrix = AbstractMatrix | ArrayLike<ArrayLike<number>>;
 type ScalarOrMatrix = number | MaybeMatrix;
 type MatrixDimension = 'row' | 'column';
 
@@ -59,21 +59,21 @@ export interface IVarianceOptions {
 }
 export interface IVarianceByOptions {
   unbiased?: boolean;
-  mean?: number[];
+  mean?: ArrayLike<number>;
 }
 
 export interface ICenterOptions {
   center?: number;
 }
 export interface ICenterByOptions {
-  center?: number[];
+  center?: ArrayLike<number>;
 }
 
 export interface IScaleOptions {
   scale?: number;
 }
 export interface IScaleByOptions {
-  scale?: number[];
+  scale?: ArrayLike<number>;
 }
 
 export interface ICovarianceOptions {
@@ -138,7 +138,7 @@ export abstract class AbstractMatrix {
   static from1DArray(
     newRows: number,
     newColumns: number,
-    newData: number[],
+    newData: ArrayLike<number>,
   ): Matrix;
 
   /**
@@ -146,14 +146,14 @@ export abstract class AbstractMatrix {
    * @param newData - A 1D array containing data for the vector.
    * @returns The new matrix.
    */
-  static rowVector(newData: number[]): Matrix;
+  static rowVector(newData: ArrayLike<number>): Matrix;
 
   /**
    * Creates a column vector, a matrix with only one column.
    * @param newData - A 1D array containing data for the vector.
    * @returns The new matrix.
    */
-  static columnVector(newData: number[]): Matrix;
+  static columnVector(newData: ArrayLike<number>): Matrix;
 
   /**
    * Creates a matrix with the given dimensions. Values will be set to zero.
@@ -219,12 +219,16 @@ export abstract class AbstractMatrix {
    * @param columns - Number of columns. Default: `rows`.
    * @returns - The new diagonal matrix.
    */
-  static diag(data: number[], rows?: number, columns?: number): Matrix;
+  static diag(data: ArrayLike<number>, rows?: number, columns?: number): Matrix;
 
   /**
    * Alias for {@link AbstractMatrix.diag}.
    */
-  static diagonal(data: number[], rows?: number, columns?: number): Matrix;
+  static diagonal(
+    data: ArrayLike<number>,
+    rows?: number,
+    columns?: number,
+  ): Matrix;
 
   /**
    * Returns a matrix whose elements are the minimum between `matrix1` and `matrix2`.
@@ -379,7 +383,7 @@ export abstract class AbstractMatrix {
    * @param index - Row index.
    * @param array - Array or vector to set.
    */
-  setRow(index: number, array: number[] | AbstractMatrix): this;
+  setRow(index: number, array: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Swap two rows.
@@ -405,7 +409,7 @@ export abstract class AbstractMatrix {
    * @param index - Column index.
    * @param array - Array or vector to set.
    */
-  setColumn(index: number, array: number[] | AbstractMatrix): this;
+  setColumn(index: number, array: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Swap two columns.
@@ -418,49 +422,49 @@ export abstract class AbstractMatrix {
    * Adds the values of a vector to each row.
    * @param vector - Array or vector.
    */
-  addRowVector(vector: number[] | AbstractMatrix): this;
+  addRowVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Subtracts the values of a vector from each row.
    * @param vector - Array or vector.
    */
-  subRowVector(vector: number[] | AbstractMatrix): this;
+  subRowVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Multiplies the values of a vector with each row.
    * @param vector - Array or vector.
    */
-  mulRowVector(vector: number[] | AbstractMatrix): this;
+  mulRowVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Divides the values of each row by those of a vector.
    * @param vector - Array or vector.
    */
-  divRowVector(vector: number[] | AbstractMatrix): this;
+  divRowVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Adds the values of a vector to each column.
    * @param vector - Array or vector.
    */
-  addColumnVector(vector: number[] | AbstractMatrix): this;
+  addColumnVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Subtracts the values of a vector from each column.
    * @param vector - Array or vector.
    */
-  subColumnVector(vector: number[] | AbstractMatrix): this;
+  subColumnVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Multiplies the values of a vector with each column.
    * @param vector - Array or vector.
    */
-  mulColumnVector(vector: number[] | AbstractMatrix): this;
+  mulColumnVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Divides the values of each column by those of a vector.
    * @param vector - Array or vector.
    */
-  divColumnVector(vector: number[] | AbstractMatrix): this;
+  divColumnVector(vector: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Multiplies the values of a row with a scalar.
@@ -481,6 +485,12 @@ export abstract class AbstractMatrix {
    */
   max(): number;
 
+  /**
+   * Returns the maximum value by the given dimension.
+   * @param by - max by 'row' or 'column'.
+   */
+  max(by: MatrixDimension): number[];
+
   /**
    * Returns the index of the maximum value.
    */
@@ -491,6 +501,12 @@ export abstract class AbstractMatrix {
    */
   min(): number;
 
+  /**
+   * Returns the minimum value by the given dimension.
+   * @param by - min by 'row' or 'column'.
+   */
+  min(by: MatrixDimension): number[];
+
   /**
    * Returns the index of the minimum value.
    */
@@ -608,7 +624,7 @@ export abstract class AbstractMatrix {
    * @param other - Other matrix.
    */
   kroneckerProduct(other: MaybeMatrix): Matrix;
-  
+
   /**
    * Returns the Kronecker sum between `this` and `other`.
    * @link https://en.wikipedia.org/wiki/Kronecker_product#Kronecker_sum
@@ -659,7 +675,7 @@ export abstract class AbstractMatrix {
    * @param endColumn - Last column index. Default: `this.columns - 1`.
    */
   subMatrixRow(
-    indices: number[],
+    indices: ArrayLike<number>,
     startColumn?: number,
     endColumn?: number,
   ): Matrix;
@@ -671,7 +687,7 @@ export abstract class AbstractMatrix {
    * @param endRow - Last row index. Default: `this.rows - 1`.
    */
   subMatrixColumn(
-    indices: number[],
+    indices: ArrayLike<number>,
     startRow?: number,
     endRow?: number,
   ): Matrix;
@@ -683,7 +699,7 @@ export abstract class AbstractMatrix {
    * @param startColumn - The index of the first column to set.
    */
   setSubMatrix(
-    matrix: MaybeMatrix | number[],
+    matrix: MaybeMatrix,
     startRow: number,
     startColumn: number,
   ): this;
@@ -694,7 +710,10 @@ export abstract class AbstractMatrix {
    * @param rowIndices - The row indices to select.
    * @param columnIndices - The column indices to select.
    */
-  selection(rowIndices: number[], columnIndices: number[]): Matrix;
+  selection(
+    rowIndices: ArrayLike<number>,
+    columnIndices: ArrayLike<number>,
+  ): Matrix;
 
   /**
    * Returns the trace of the matrix (sum of the diagonal elements).
@@ -912,7 +931,7 @@ export abstract class AbstractMatrix {
 
 export class Matrix extends AbstractMatrix {
   constructor(nRows: number, nColumns: number);
-  constructor(data: number[][]);
+  constructor(data: ArrayLike<ArrayLike<number>>);
   constructor(otherMatrix: AbstractMatrix);
 
   /**
@@ -932,14 +951,14 @@ export class Matrix extends AbstractMatrix {
    * @param index - Column index. Default: `this.columns`.
    * @param array - Column to add.
    */
-  addColumn(index: number, array: number[] | AbstractMatrix): this;
+  addColumn(index: number, array: ArrayLike<number> | AbstractMatrix): this;
 
   /**
    * Adds a new row to the matrix (in place).
    * @param index - Row index. Default: `this.rows`.
    * @param array - Row to add.
    */
-  addRow(index: number, array: number[] | AbstractMatrix): this;
+  addRow(index: number, array: ArrayLike<number> | AbstractMatrix): this;
 }
 
 export default Matrix;
@@ -949,7 +968,7 @@ export class MatrixColumnView extends AbstractMatrix {
 }
 
 export class MatrixColumnSelectionView extends AbstractMatrix {
-  constructor(matrix: AbstractMatrix, columnIndices: number[]);
+  constructor(matrix: AbstractMatrix, columnIndices: ArrayLike<number>);
 }
 
 export class MatrixFlipColumnView extends AbstractMatrix {
@@ -965,14 +984,14 @@ export class MatrixRowView extends AbstractMatrix {
 }
 
 export class MatrixRowSelectionView extends AbstractMatrix {
-  constructor(matrix: AbstractMatrix, rowIndices: number[]);
+  constructor(matrix: AbstractMatrix, rowIndices: ArrayLike<number>);
 }
 
 export class MatrixSelectionView extends AbstractMatrix {
   constructor(
     matrix: AbstractMatrix,
-    rowIndices: number[],
-    columnIndices: number[],
+    rowIndices: ArrayLike<number>,
+    columnIndices: ArrayLike<number>,
   );
 }
 
@@ -998,18 +1017,18 @@ export interface IWrap1DOptions {
 }
 
 export function wrap(
-  array: number[],
+  array: ArrayLike<number>,
   options?: IWrap1DOptions,
 ): WrapperMatrix1D;
 
-export function wrap(twoDAray: number[][]): WrapperMatrix2D;
+export function wrap(twoDAray: ArrayLike<ArrayLike<number>>): WrapperMatrix2D;
 
 export class WrapperMatrix1D extends AbstractMatrix {
-  constructor(data: number[], options?: IWrap1DOptions);
+  constructor(data: ArrayLike<number>, options?: IWrap1DOptions);
 }
 
 export class WrapperMatrix2D extends AbstractMatrix {
-  constructor(data: number[][]);
+  constructor(data: ArrayLike<ArrayLike<number>>);
 }
 
 /**
@@ -1133,7 +1152,7 @@ export class SingularValueDecomposition {
    * @returns - The vector x.
    */
   solve(value: Matrix): Matrix;
-  solveForDiagonal(value: number[]): Matrix;
+  solveForDiagonal(value: ArrayLike<number>): Matrix;
   readonly norm2: number;
   readonly threshold: number;
   readonly leftSingularVectors: Matrix;
@@ -1223,7 +1242,7 @@ export interface INipalsOptions {
   /**
    * A column vector of length `X.rows` that contains known labels for supervised PLS.
    */
-  Y?: MaybeMatrix | number[];
+  Y?: MaybeMatrix | ArrayLike<number>;
   /**
    * The maximum number of allowed iterations before beraking the loop if convergence is not achieved.
    * @default 1000