JAL-4159 peek in a Jalview project's PCA viewer's title to decide if it is a "pasimap...

[jalview.git] / src / jalview / math / MatrixI.java

diff --git a/src/jalview/math/MatrixI.java b/src/jalview/math/MatrixI.java
index 5b93c76..7faac73 100644 (file)
--- a/src/jalview/math/MatrixI.java
+++ b/src/jalview/math/MatrixI.java
@@ -22,6 +22,10 @@ package jalview.math;
 
 import java.io.PrintStream;
 
+/**
+ * An interface that describes a rectangular matrix of double values and
+ * operations on it
+ */
 public interface MatrixI
 {
   /**
@@ -57,24 +61,79 @@ public interface MatrixI
   void setValue(int i, int j, double d);
 
   /**
+  * Returns the matrix as a double[][] array
+  *
+  * @return
+  */
+  double[][] asArray();
+
+  /**
    * Answers a copy of the values in the i'th row
    * 
    * @return
    */
   double[] getRow(int i);
 
+  /**
+   * Answers a copy of the values in the i'th column
+   * 
+   * @return
+   */
+  double[] getColumn(int i);
+
+  /**
+   * Answers a new matrix with a copy of the values in this one
+   * 
+   * @return
+   */
   MatrixI copy();
 
+  /**
+   * Returns a new matrix which is the transpose of this one
+   * 
+   * @return
+   */
   MatrixI transpose();
 
+  /**
+   * Returns a new matrix which is the result of premultiplying this matrix by
+   * the supplied argument. If this of size AxB (A rows and B columns), and the
+   * argument is CxA (C rows and A columns), the result is of size CxB.
+   * 
+   * @param in
+   * 
+   * @return
+   * @throws IllegalArgumentException
+   *           if the number of columns in the pre-multiplier is not equal to
+   *           the number of rows in the multiplicand (this)
+   */
   MatrixI preMultiply(MatrixI m);
 
+  /**
+   * Returns a new matrix which is the result of postmultiplying this matrix by
+   * the supplied argument. If this of size AxB (A rows and B columns), and the
+   * argument is BxC (B rows and C columns), the result is of size AxC.
+   * <p>
+   * This method simply returns the result of in.preMultiply(this)
+   * 
+   * @param in
+   * 
+   * @return
+   * @throws IllegalArgumentException
+   *           if the number of rows in the post-multiplier is not equal to the
+   *           number of columns in the multiplicand (this)
+   * @see #preMultiply(Matrix)
+   */
   MatrixI postMultiply(MatrixI m);
 
   double[] getD();
 
   double[] getE();
 
+  void setD(double[] v);
+
+  void setE(double[] v);
+
   void print(PrintStream ps, String format);
 
   void printD(PrintStream ps, String format);
@@ -114,4 +173,145 @@ public interface MatrixI
    * @param d
    */
   void multiply(double d);
+
+  /**
+  * Add d to all entries of this matrix
+  *
+  * @param d ~ value to add
+  */
+  void add(double d);
+
+  /**
+   * Answers true if the two matrices have the same dimensions, and
+   * corresponding values all differ by no more than delta (which should be a
+   * positive value), else false
+   * 
+   * @param m2
+   * @param delta
+   * @return
+   */
+  boolean equals(MatrixI m2, double delta);
+
+  /**
+   * Returns a copy in which  every value in the matrix is its absolute
+   */
+  MatrixI absolute();
+
+  /**
+   * Returns the mean of each row
+   */
+  double[] meanRow();
+
+  /**
+   * Returns the mean of each column
+   */
+  double[] meanCol();
+
+  /**
+  * Returns a flattened matrix containing the sum of each column
+  *
+  * @return
+  */
+  double[] sumCol();
+
+  /**
+  * returns the mean value of the complete matrix
+  */
+  double mean();
+
+  /**
+  * fills up a diagonal matrix with its transposed copy
+  * !other side should be filled with either 0 or Double.NaN
+  */
+  void fillDiagonal();
+
+  /**
+  * counts the number of Double.NaN in the matrix
+  *
+  * @return
+  */
+  int countNaN();
+
+  /**
+  * performs an element-wise addition of this matrix by another matrix
+  * !matrices have to be the same size
+  * @param m ~ other matrix
+  * 
+  * @return
+  * @throws IllegalArgumentException
+  *           if this and m do not have the same dimensions
+  */
+  MatrixI add(MatrixI m);
+
+  /**
+  * performs an element-wise subtraction of this matrix by another matrix
+  * !matrices have to be the same size
+  * @param m ~ other matrix
+  * 
+  * @return
+  * @throws IllegalArgumentException
+  *           if this and m do not have the same dimensions
+  */
+  MatrixI subtract(MatrixI m);
+ 
+  /**
+  * performs an element-wise multiplication of this matrix by another matrix ~ this * m
+  * !matrices have to be the same size
+  * @param m ~ other matrix
+  *
+  * @return
+  * @throws IllegalArgumentException
+  *    if this and m do not have the same dimensions
+  */
+  MatrixI elementwiseMultiply(MatrixI m);
+
+  /**
+  * performs an element-wise division of this matrix by another matrix ~ this / m
+  * !matrices have to be the same size
+  * @param m ~ other matrix
+  *
+  * @return
+  * @throws IllegalArgumentException
+  *    if this and m do not have the same dimensions
+  */
+  MatrixI elementwiseDivide(MatrixI m);
+
+  /**
+  * calculates the root-mean-square for two matrices
+  * @param m ~ other matrix
+  *  
+  * @return
+  */
+  double rmsd(MatrixI m);
+
+  /**
+  * calculates the Frobenius norm of this matrix
+  *
+  * @return
+  */
+  double norm();
+  
+  /**
+  * returns the sum of all values in this matrix
+  *
+  * @return
+  */
+  double sum();
+
+  /**
+  * returns the sum-product of this matrix with vector v
+  * @param v ~ vector
+  *
+  * @return
+  * @throws IllegalArgumentException
+  *    if this.cols and v do not have the same length
+  */
+  double[] sumProduct(double[] v);
+
+  /**
+  * mirrors the columns of this matrix
+  *
+  * @return
+  */
+  MatrixI mirrorCol();
 }