Merge branch 'develop' into features/JAL-2393customMatrices

[jalview.git] / src / jalview / analysis / scoremodels / ScoreMatrix.java

diff --git a/src/jalview/analysis/scoremodels/ScoreMatrix.java b/src/jalview/analysis/scoremodels/ScoreMatrix.java
index baa18e9..22c81f1 100644 (file)
--- a/src/jalview/analysis/scoremodels/ScoreMatrix.java
+++ b/src/jalview/analysis/scoremodels/ScoreMatrix.java
@@ -20,9 +20,12 @@
  */
 package jalview.analysis.scoremodels;
 
+import jalview.math.Matrix;
+import jalview.math.MatrixI;
+
 import java.util.Arrays;
 
-public class ScoreMatrix extends PairwiseSeqScoreModel
+public class ScoreMatrix implements PairwiseScoreModelI
 {
   public static final short UNMAPPED = (short) -1;
 
@@ -58,7 +61,9 @@ public class ScoreMatrix extends PairwiseSeqScoreModel
   private boolean peptide;
 
   /**
-   * Constructor
+   * Constructor given a name, symbol alphabet, and matrix of scores for pairs
+   * of symbols. The matrix should be square and of the same size as the
+   * alphabet, for example 20x20 for a 20 symbol alphabet.
    * 
    * @param name
    *          Unique, human readable name for the matrix
@@ -69,6 +74,20 @@ public class ScoreMatrix extends PairwiseSeqScoreModel
    */
   public ScoreMatrix(String name, char[] alphabet, float[][] matrix)
   {
+    if (alphabet.length != matrix.length)
+    {
+      throw new IllegalArgumentException(
+              "score matrix size must match alphabet size");
+    }
+    for (float[] row : matrix)
+    {
+      if (row.length != alphabet.length)
+      {
+        throw new IllegalArgumentException(
+                "score matrix size must be square");
+      }
+    }
+
     this.matrix = matrix;
     this.name = name;
     this.symbols = alphabet;
@@ -141,25 +160,53 @@ public class ScoreMatrix extends PairwiseSeqScoreModel
     return peptide;
   }
 
-  @Override
+  /**
+   * Returns the score matrix as used in getPairwiseScore. If using this matrix
+   * directly, callers <em>must</em> also call <code>getMatrixIndex</code> in
+   * order to get the matrix index for each character (symbol).
+   * 
+   * @return
+   * @see #getMatrixIndex(char)
+   */
   public float[][] getMatrix()
   {
     return matrix;
   }
 
   /**
+   * Answers the matrix index for a given character, or -1 if unmapped in the
+   * matrix. Use this method only if using <code>getMatrix</code> in order to
+   * compute scores directly (without symbol lookup) for efficiency.
+   * 
+   * @param c
+   * @return
+   * @see #getMatrix()
+   */
+  public int getMatrixIndex(char c)
+  {
+    if (c < symbolIndex.length)
+    {
+      return symbolIndex[c];
+    }
+    else
+    {
+      return UNMAPPED;
+    }
+  }
+
+  /**
    * Returns the pairwise score for substituting c with d, or zero if c or d is
    * an unscored or unexpected character
    */
   @Override
   public float getPairwiseScore(char c, char d)
   {
-    if (c > MAX_ASCII)
+    if (c >= symbolIndex.length)
     {
       System.err.println(String.format(BAD_ASCII_ERROR, c));
       return 0;
     }
-    if (d > MAX_ASCII)
+    if (d >= symbolIndex.length)
     {
       System.err.println(String.format(BAD_ASCII_ERROR, d));
       return 0;
@@ -237,4 +284,58 @@ public class ScoreMatrix extends PairwiseSeqScoreModel
     }
     return sb.toString();
   }
+
+  /**
+   * Answers the number of symbols coded for (also equal to the number of rows
+   * and columns of the score matrix)
+   * 
+   * @return
+   */
+  public int getSize()
+  {
+    return symbols.length;
+  }
+
+  /**
+   * Computes an NxN matrix where N is the number of sequences, and entry [i, j]
+   * is sequence[i] pairwise multiplied with sequence[j], as a sum of scores
+   * computed using the current score matrix. For example
+   * <ul>
+   * <li>Sequences:</li>
+   * <li>FKL</li>
+   * <li>R-D</li>
+   * <li>QIA</li>
+   * <li>GWC</li>
+   * <li>Score matrix is BLOSUM62</li>
+   * <li>Gaps treated same as X (unknown)</li>
+   * <li>product [0, 0] = F.F + K.K + L.L = 6 + 5 + 4 = 15</li>
+   * <li>product [1, 1] = R.R + -.- + D.D = 5 + -1 + 6 = 10</li>
+   * <li>product [2, 2] = Q.Q + I.I + A.A = 5 + 4 + 4 = 13</li>
+   * <li>product [3, 3] = G.G + W.W + C.C = 6 + 11 + 9 = 26</li>
+   * <li>product[0, 1] = F.R + K.- + L.D = -3 + -1 + -3 = -8
+   * <li>and so on</li>
+   * </ul>
+   */
+  public MatrixI computePairwiseScores(String[] seqs)
+  {
+    double[][] values = new double[seqs.length][];
+    for (int row = 0; row < seqs.length; row++)
+    {
+      values[row] = new double[seqs.length];
+      for (int col = 0; col < seqs.length; col++)
+      {
+        int total = 0;
+        int width = Math.min(seqs[row].length(), seqs[col].length());
+        for (int i = 0; i < width; i++)
+        {
+          char c1 = seqs[row].charAt(i);
+          char c2 = seqs[col].charAt(i);
+          float score = getPairwiseScore(c1, c2);
+          total += score;
+        }
+        values[row][col] = total;
+      }
+    }
+    return new Matrix(values);
+  }
 }