ml-matrix 6.5.3 → 6.8.1

package/README.md

@@ -1,11 +1,23 @@
 # ml-matrix
 
-[![NPM version][npm-image]][npm-url]
-[![build status][ci-image]][ci-url]
-[![npm download][download-image]][download-url]
-
 Matrix manipulation and computation library.
 
+<h3 align="center">
+
+  <a href="https://www.zakodium.com">
+    <img src="https://www.zakodium.com/brand/zakodium-logo-white.svg" width="50" alt="Zakodium logo" />
+  </a>
+
+  <p>
+    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]
+
+</h3>
+
 ## Installation
 
 `$ npm install ml-matrix`
@@ -47,7 +59,7 @@ var C = new Matrix([[3, 3], [1, 1]]);
 
 // operations :
 const addition = Matrix.add(A, B); // addition = Matrix [[4, 4], [3, 3], rows: 2, columns: 2]
-const substraction = Matrix.sub(A, B); // substraction = Matrix [[-2, -2], [1, 1], rows: 2, columns: 2]
+const subtraction = Matrix.sub(A, B); // subtraction = Matrix [[-2, -2], [1, 1], rows: 2, columns: 2]
 const multiplication = A.mmul(B); // multiplication = Matrix [[4, 4], [8, 8], rows: 2, columns: 2]
 const mulByNumber = Matrix.mul(A, 10); // mulByNumber = Matrix [[10, 10], [20, 20], rows: 2, columns: 2]
 const divByNumber = Matrix.div(A, 10); // divByNumber = Matrix [[0.1, 0.1], [0.2, 0.2], rows: 2, columns: 2]
@@ -88,10 +100,10 @@ var diag = A.diag(); // diag = [1, -1], i.e values in the diagonal.
 var m = A.mean(); // m = 2.75
 var product = A.prod(); // product = -10, i.e product of all values of the matrix
 var norm = A.norm(); // norm = 10.14889156509222, i.e Frobenius norm of the matrix
-var transpose = A.transpose(); // tranpose = Matrix [[1, 10], [1, -1], rows: 2, columns: 2]
+var transpose = A.transpose(); // transpose = Matrix [[1, 10], [1, -1], rows: 2, columns: 2]
 
 // ============================
-// Instanciation of matrix :
+// Instantiation of matrix :
 // =============================
 
 var z = Matrix.zeros(3, 2); // z = Matrix [[0, 0], [0, 0], [0, 0], rows: 3, columns: 2]
@@ -110,6 +122,7 @@ const {
   QrDecomposition,
   LuDecomposition,
   CholeskyDecomposition,
+  EigenvalueDecomposition
 } = require('ml-matrix');
 
 //===========================

package/matrix.d.ts

@@ -304,6 +304,11 @@ export abstract class AbstractMatrix {
    */
   isSquare(): boolean;
 
+  /**
+   * Returns whether the number of rows or columns (or both) is zero.
+   */
+  isEmpty(): boolean;
+
   /**
    * Returns whether the matrix is square and has the same values on both sides of the diagonal.
    */
@@ -603,6 +608,13 @@ 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
+   * @param other - Other matrix.
+   */
+  kroneckerSum(other: MaybeMatrix): Matrix;
 
   /**
    * Alias for {@link AbstractMatrix.kroneckerProduct}.
@@ -1216,7 +1228,7 @@ export interface INipalsOptions {
    * The maximum number of allowed iterations before beraking the loop if convergence is not achieved.
    * @default 1000
    */
-  maxIterations?: boolean;
+  maxIterations?: number;
   /**
    * Termination criteria
    * @default 1e-10
@@ -1237,13 +1249,13 @@ export class Nipals {
   constructor(X: MaybeMatrix, options?: INipalsOptions);
   w: Matrix;
   s: Matrix;
-  t: number;
+  t: Matrix;
   xResidual: Matrix;
   p: Matrix;
   q: Matrix;
-  u: number;
+  u: Matrix;
   yResidual: Matrix;
-  betas: number;
+  betas: Matrix;
 }
 
 export { Nipals as NIPALS };

package/matrix.js

@@ -1032,6 +1032,12 @@ function checkNumber(name, value) {
   }
 }
 
+function checkNonEmpty(matrix) {
+  if (matrix.isEmpty()) {
+    throw new Error('Empty matrix has no elements to index');
+  }
+}
+
 function sumByRow(matrix) {
   let sum = newArray(matrix.rows);
   for (let i = 0; i < matrix.rows; ++i) {
@@ -1431,6 +1437,10 @@ class AbstractMatrix {
     return this.rows === this.columns;
   }
 
+  isEmpty() {
+    return this.rows === 0 || this.columns === 0;
+  }
+
   isSymmetric() {
     if (this.isSquare()) {
       for (let i = 0; i < this.rows; i++) {
@@ -1768,6 +1778,9 @@ class AbstractMatrix {
   }
 
   max() {
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(0, 0);
     for (let i = 0; i < this.rows; i++) {
       for (let j = 0; j < this.columns; j++) {
@@ -1780,6 +1793,7 @@ class AbstractMatrix {
   }
 
   maxIndex() {
+    checkNonEmpty(this);
     let v = this.get(0, 0);
     let idx = [0, 0];
     for (let i = 0; i < this.rows; i++) {
@@ -1795,6 +1809,9 @@ class AbstractMatrix {
   }
 
   min() {
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(0, 0);
     for (let i = 0; i < this.rows; i++) {
       for (let j = 0; j < this.columns; j++) {
@@ -1807,6 +1824,7 @@ class AbstractMatrix {
   }
 
   minIndex() {
+    checkNonEmpty(this);
     let v = this.get(0, 0);
     let idx = [0, 0];
     for (let i = 0; i < this.rows; i++) {
@@ -1823,6 +1841,9 @@ class AbstractMatrix {
 
   maxRow(row) {
     checkRowIndex(this, row);
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(row, 0);
     for (let i = 1; i < this.columns; i++) {
       if (this.get(row, i) > v) {
@@ -1834,6 +1855,7 @@ class AbstractMatrix {
 
   maxRowIndex(row) {
     checkRowIndex(this, row);
+    checkNonEmpty(this);
     let v = this.get(row, 0);
     let idx = [row, 0];
     for (let i = 1; i < this.columns; i++) {
@@ -1847,6 +1869,9 @@ class AbstractMatrix {
 
   minRow(row) {
     checkRowIndex(this, row);
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(row, 0);
     for (let i = 1; i < this.columns; i++) {
       if (this.get(row, i) < v) {
@@ -1858,6 +1883,7 @@ class AbstractMatrix {
 
   minRowIndex(row) {
     checkRowIndex(this, row);
+    checkNonEmpty(this);
     let v = this.get(row, 0);
     let idx = [row, 0];
     for (let i = 1; i < this.columns; i++) {
@@ -1871,6 +1897,9 @@ class AbstractMatrix {
 
   maxColumn(column) {
     checkColumnIndex(this, column);
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(0, column);
     for (let i = 1; i < this.rows; i++) {
       if (this.get(i, column) > v) {
@@ -1882,6 +1911,7 @@ class AbstractMatrix {
 
   maxColumnIndex(column) {
     checkColumnIndex(this, column);
+    checkNonEmpty(this);
     let v = this.get(0, column);
     let idx = [0, column];
     for (let i = 1; i < this.rows; i++) {
@@ -1895,6 +1925,9 @@ class AbstractMatrix {
 
   minColumn(column) {
     checkColumnIndex(this, column);
+    if (this.isEmpty()) {
+      return NaN;
+    }
     let v = this.get(0, column);
     for (let i = 1; i < this.rows; i++) {
       if (this.get(i, column) < v) {
@@ -1906,6 +1939,7 @@ class AbstractMatrix {
 
   minColumnIndex(column) {
     checkColumnIndex(this, column);
+    checkNonEmpty(this);
     let v = this.get(0, column);
     let idx = [0, column];
     for (let i = 1; i < this.rows; i++) {
@@ -2224,7 +2258,9 @@ class AbstractMatrix {
     let newMatrix = new Matrix(this.rows, this.columns);
     for (let i = 0; i < this.rows; i++) {
       const row = this.getRow(i);
-      rescale__default['default'](row, { min, max, output: row });
+      if (row.length > 0) {
+        rescale__default["default"](row, { min, max, output: row });
+      }
       newMatrix.setRow(i, row);
     }
     return newMatrix;
@@ -2241,11 +2277,13 @@ class AbstractMatrix {
     let newMatrix = new Matrix(this.rows, this.columns);
     for (let i = 0; i < this.columns; i++) {
       const column = this.getColumn(i);
-      rescale__default['default'](column, {
-        min: min,
-        max: max,
-        output: column,
-      });
+      if (column.length) {
+        rescale__default["default"](column, {
+          min: min,
+          max: max,
+          output: column,
+        });
+      }
       newMatrix.setColumn(i, column);
     }
     return newMatrix;
@@ -2298,6 +2336,18 @@ class AbstractMatrix {
     return result;
   }
 
+  kroneckerSum(other) {
+    other = Matrix.checkMatrix(other);
+    if (!this.isSquare() || !other.isSquare()) {
+      throw new Error('Kronecker Sum needs two Square Matrices');
+    }
+    let m = this.rows;
+    let n = other.rows;
+    let AxI = this.kroneckerProduct(Matrix.eye(n, n));
+    let IxB = Matrix.eye(m, m).kroneckerProduct(other);
+    return AxI.add(IxB);
+  }
+
   transpose() {
     let result = new Matrix(this.columns, this.rows);
     for (let i = 0; i < this.rows; i++) {
@@ -2388,6 +2438,9 @@ class AbstractMatrix {
 
   setSubMatrix(matrix, startRow, startColumn) {
     matrix = Matrix.checkMatrix(matrix);
+    if (matrix.isEmpty()) {
+      return this;
+    }
     let endRow = startRow + matrix.rows - 1;
     let endColumn = startColumn + matrix.columns - 1;
     checkRange(this, startRow, endRow, startColumn, endColumn);
@@ -2616,9 +2669,8 @@ class AbstractMatrix {
 
 AbstractMatrix.prototype.klass = 'Matrix';
 if (typeof Symbol !== 'undefined') {
-  AbstractMatrix.prototype[
-    Symbol.for('nodejs.util.inspect.custom')
-  ] = inspectMatrix;
+  AbstractMatrix.prototype[Symbol.for('nodejs.util.inspect.custom')] =
+    inspectMatrix;
 }
 
 function compareNumbers(a, b) {
@@ -2641,10 +2693,10 @@ class Matrix extends AbstractMatrix {
     if (Matrix.isMatrix(nRows)) {
       // eslint-disable-next-line no-constructor-return
       return nRows.clone();
-    } else if (Number.isInteger(nRows) && nRows > 0) {
+    } else if (Number.isInteger(nRows) && nRows >= 0) {
       // Create an empty matrix
       this.data = [];
-      if (Number.isInteger(nColumns) && nColumns > 0) {
+      if (Number.isInteger(nColumns) && nColumns >= 0) {
         for (let i = 0; i < nRows; i++) {
           this.data.push(new Float64Array(nColumns));
         }
@@ -2655,8 +2707,8 @@ class Matrix extends AbstractMatrix {
       // Copy the values from the 2D array
       const arrayData = nRows;
       nRows = arrayData.length;
-      nColumns = arrayData[0].length;
-      if (typeof nColumns !== 'number' || nColumns === 0) {
+      nColumns = nRows ? arrayData[0].length : 0;
+      if (typeof nColumns !== 'number') {
         throw new TypeError(
           'Data must be a 2D array with at least one element',
         );
@@ -2688,9 +2740,6 @@ class Matrix extends AbstractMatrix {
 
   removeRow(index) {
     checkRowIndex(this, index);
-    if (this.rows === 1) {
-      throw new RangeError('A matrix cannot have less than one row');
-    }
     this.data.splice(index, 1);
     this.rows -= 1;
     return this;
@@ -2710,9 +2759,6 @@ class Matrix extends AbstractMatrix {
 
   removeColumn(index) {
     checkColumnIndex(this, index);
-    if (this.columns === 1) {
-      throw new RangeError('A matrix cannot have less than one column');
-    }
     for (let i = 0; i < this.rows; i++) {
       const newRow = new Float64Array(this.columns - 1);
       for (let j = 0; j < index; j++) {
@@ -3315,6 +3361,10 @@ class SingularValueDecomposition {
   constructor(value, options = {}) {
     value = WrapperMatrix2D.checkMatrix(value);
 
+    if (value.isEmpty()) {
+      throw new Error('Matrix must be non-empty');
+    }
+
     let m = value.rows;
     let n = value.columns;
 
@@ -3851,6 +3901,10 @@ function solve(leftHandSide, rightHandSide, useSVD = false) {
 function determinant(matrix) {
   matrix = Matrix.checkMatrix(matrix);
   if (matrix.isSquare()) {
+    if (matrix.columns === 0) {
+      return 1;
+    }
+
     let a, b, c, d;
     if (matrix.columns === 2) {
       // 2 x 2 matrix
@@ -3937,6 +3991,12 @@ function linearDependencies(matrix, options = {}) {
 
 function pseudoInverse(matrix, threshold = Number.EPSILON) {
   matrix = Matrix.checkMatrix(matrix);
+  if (matrix.isEmpty()) {
+    // with a zero dimension, the pseudo-inverse is the transpose, since all 0xn and nx0 matrices are singular
+    // (0xn)*(nx0)*(0xn) = 0xn
+    // (nx0)*(0xn)*(nx0) = nx0
+    return matrix.transpose();
+  }
   let svdSolution = new SingularValueDecomposition(matrix, { autoTranspose: true });
 
   let U = svdSolution.leftSingularVectors;
@@ -4046,6 +4106,10 @@ class EigenvalueDecomposition {
       throw new Error('Matrix is not a square matrix');
     }
 
+    if (matrix.isEmpty()) {
+      throw new Error('Matrix must be non-empty');
+    }
+
     let n = matrix.columns;
     let V = new Matrix(n, n);
     let d = new Float64Array(n);
@@ -4930,10 +4994,10 @@ class nipals {
       } else {
         Y = WrapperMatrix2D.checkMatrix(Y);
       }
-      if (!Y.isColumnVector() || Y.rows !== X.rows) {
-        throw new Error('Y must be a column vector of length X.rows');
+      if (Y.rows !== X.rows) {
+        throw new Error('Y should have the same number of rows as X');
       }
-      u = Y;
+      u = Y.getColumnVector(0);
     } else {
       u = X.getColumnVector(0);
     }
@@ -5024,7 +5088,7 @@ exports.WrapperMatrix1D = WrapperMatrix1D;
 exports.WrapperMatrix2D = WrapperMatrix2D;
 exports.correlation = correlation;
 exports.covariance = covariance;
-exports.default = Matrix;
+exports["default"] = Matrix;
 exports.determinant = determinant;
 exports.inverse = inverse;
 exports.linearDependencies = linearDependencies;