X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fanalysis%2Fscoremodels%2FScoreMatrix.java;h=b206339805cf4d1f026c15eb34f3987a21a543b9;hb=890092d4ca9b8c17a3f356eeb12f49440d5fc51c;hp=22c81f19f908e634fc06b436edb50c56b16b527c;hpb=f46c404585087d8937c48504bfcff716440d5186;p=jalview.git

diff --git a/src/jalview/analysis/scoremodels/ScoreMatrix.java b/src/jalview/analysis/scoremodels/ScoreMatrix.java
index 22c81f1..b206339 100644
--- a/src/jalview/analysis/scoremodels/ScoreMatrix.java
+++ b/src/jalview/analysis/scoremodels/ScoreMatrix.java
@@ -20,13 +20,42 @@
  */
 package jalview.analysis.scoremodels;
 
+import jalview.api.AlignmentViewPanel;
+import jalview.api.analysis.PairwiseScoreModelI;
+import jalview.api.analysis.ScoreModelI;
+import jalview.api.analysis.SimilarityParamsI;
+import jalview.datamodel.AlignmentView;
 import jalview.math.Matrix;
 import jalview.math.MatrixI;
+import jalview.util.Comparison;
 
 import java.util.Arrays;
 
-public class ScoreMatrix implements PairwiseScoreModelI
+/**
+ * A class that models a substitution score matrix for any given alphabet of
+ * symbols. Instances of this class are immutable and thread-safe, so the same
+ * object is returned from calls to getInstance().
+ */
+public class ScoreMatrix extends SimilarityScoreModel
+        implements PairwiseScoreModelI
 {
+  private static final char GAP_CHARACTER = Comparison.GAP_DASH;
+
+  /*
+   * an arbitrary score to assign for identity of an unknown symbol
+   * (this is the value on the diagonal in the * column of the NCBI matrix)
+   * (though a case could be made for using the minimum diagonal value)
+   */
+  private static final int UNKNOWN_IDENTITY_SCORE = 1;
+
+  /*
+   * Jalview 2.10.1 treated gaps as X (peptide) or N (nucleotide)
+   * for pairwise scoring; 2.10.2 uses gap score (last column) in
+   * score matrix (JAL-2397)
+   * Set this flag to true (via Groovy) for 2.10.1 behaviour
+   */
+  private static boolean scoreGapAsAny = false;
+
   public static final short UNMAPPED = (short) -1;
 
   private static final String BAD_ASCII_ERROR = "Unexpected character %s in getPairwiseScore";
@@ -35,10 +64,16 @@ public class ScoreMatrix implements PairwiseScoreModelI
 
   /*
    * the name of the model as shown in menus
+   * each score model in use should have a unique name
    */
   private String name;
 
   /*
+   * a description for the model as shown in tooltips
+   */
+  private String description;
+
+  /*
    * the characters that the model provides scores for
    */
   private char[] symbols;
@@ -60,26 +95,52 @@ public class ScoreMatrix implements PairwiseScoreModelI
    */
   private boolean peptide;
 
+  private float minValue;
+
+  private float maxValue;
+
+  private boolean symmetric;
+
   /**
    * 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
+   * @param theName
    *          Unique, human readable name for the matrix
    * @param alphabet
    *          the symbols to which scores apply
-   * @param matrix
+   * @param values
    *          Pairwise scores indexed according to the symbol alphabet
    */
-  public ScoreMatrix(String name, char[] alphabet, float[][] matrix)
+  public ScoreMatrix(String theName, char[] alphabet, float[][] values)
   {
-    if (alphabet.length != matrix.length)
+    this(theName, null, alphabet, values);
+  }
+
+  /**
+   * Constructor given a name, description, 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 theName
+   *          Unique, human readable name for the matrix
+   * @param theDescription
+   *          descriptive display name suitable for use in menus
+   * @param alphabet
+   *          the symbols to which scores apply
+   * @param values
+   *          Pairwise scores indexed according to the symbol alphabet
+   */
+  public ScoreMatrix(String theName, String theDescription, char[] alphabet,
+          float[][] values)
+  {
+    if (alphabet.length != values.length)
     {
       throw new IllegalArgumentException(
               "score matrix size must match alphabet size");
     }
-    for (float[] row : matrix)
+    for (float[] row : values)
     {
       if (row.length != alphabet.length)
       {
@@ -88,12 +149,17 @@ public class ScoreMatrix implements PairwiseScoreModelI
       }
     }
 
-    this.matrix = matrix;
-    this.name = name;
+    this.matrix = values;
+    this.name = theName;
+    this.description = theDescription;
     this.symbols = alphabet;
 
     symbolIndex = buildSymbolIndex(alphabet);
 
+    findMinMax();
+
+    symmetric = checkSymmetry();
+
     /*
      * crude heuristic for now...
      */
@@ -101,6 +167,52 @@ public class ScoreMatrix implements PairwiseScoreModelI
   }
 
   /**
+   * Answers true if the matrix is symmetric, else false. Usually, substitution
+   * matrices are symmetric, which allows calculations to be short cut.
+   * 
+   * @return
+   */
+  private boolean checkSymmetry()
+  {
+    for (int i = 0; i < matrix.length; i++)
+    {
+      for (int j = i; j < matrix.length; j++)
+      {
+        if (matrix[i][j] != matrix[j][i])
+        {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Record the minimum and maximum score values
+   */
+  protected void findMinMax()
+  {
+    float min = Float.MAX_VALUE;
+    float max = -Float.MAX_VALUE;
+    if (matrix != null)
+    {
+      for (float[] row : matrix)
+      {
+        if (row != null)
+        {
+          for (float f : row)
+          {
+            min = Math.min(min, f);
+            max = Math.max(max, f);
+          }
+        }
+      }
+    }
+    minValue = min;
+    maxValue = max;
+  }
+
+  /**
    * Returns an array A where A[i] is the position in the alphabet array of the
    * character whose value is i. For example if the alphabet is { 'A', 'D', 'X'
    * } then A['D'] = A[68] = 1.
@@ -110,11 +222,14 @@ public class ScoreMatrix implements PairwiseScoreModelI
    * Mappings are added automatically for lower case symbols (for non case
    * sensitive scoring), unless they are explicitly present in the alphabet (are
    * scored separately in the score matrix).
+   * <p>
+   * the gap character (space, dash or dot) included in the alphabet (if any) is
+   * recorded in a field
    * 
    * @param alphabet
    * @return
    */
-  static short[] buildSymbolIndex(char[] alphabet)
+  short[] buildSymbolIndex(char[] alphabet)
   {
     short[] index = new short[MAX_ASCII + 1];
     Arrays.fill(index, UNMAPPED);
@@ -149,6 +264,12 @@ public class ScoreMatrix implements PairwiseScoreModelI
   }
 
   @Override
+  public String getDescription()
+  {
+    return description;
+  }
+
+  @Override
   public boolean isDNA()
   {
     return !peptide;
@@ -161,16 +282,22 @@ public class ScoreMatrix implements PairwiseScoreModelI
   }
 
   /**
-   * 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).
+   * Returns a copy of 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;
+    float[][] v = new float[matrix.length][matrix.length];
+    for (int i = 0; i < matrix.length; i++)
+    {
+      v[i] = Arrays.copyOf(matrix[i], matrix[i].length);
+    }
+    return v;
   }
 
   /**
@@ -195,8 +322,9 @@ public class ScoreMatrix implements PairwiseScoreModelI
   }
 
   /**
-   * Returns the pairwise score for substituting c with d, or zero if c or d is
-   * an unscored or unexpected character
+   * Returns the pairwise score for substituting c with d. If either c or d is
+   * an unexpected character, returns 1 for identity (c == d), else the minimum
+   * score value in the matrix.
    */
   @Override
   public float getPairwiseScore(char c, char d)
@@ -218,7 +346,14 @@ public class ScoreMatrix implements PairwiseScoreModelI
     {
       return matrix[cIndex][dIndex];
     }
-    return 0;
+
+    /*
+     * one or both symbols not found in the matrix
+     * currently scoring as 1 (for identity) or the minimum
+     * matrix score value (otherwise)
+     * (a case could be made for using minimum row/column value instead)
+     */
+    return c == d ? UNKNOWN_IDENTITY_SCORE : getMinimumScore();
   }
 
   /**
@@ -231,7 +366,12 @@ public class ScoreMatrix implements PairwiseScoreModelI
   }
 
   /**
-   * Print the score matrix, optionally formatted as html, with the alphabet symbols as column headings and at the start of each row
+   * Print the score matrix, optionally formatted as html, with the alphabet
+   * symbols as column headings and at the start of each row.
+   * <p>
+   * The non-html format should give an output which can be parsed as a score
+   * matrix file
+   * 
    * @param html
    * @return
    */
@@ -247,6 +387,10 @@ public class ScoreMatrix implements PairwiseScoreModelI
       sb.append("<table border=\"1\">");
       sb.append(html ? "<tr><th></th>" : "");
     }
+    else
+    {
+      sb.append("ScoreMatrix ").append(getName()).append("\n");
+    }
     for (char sym : symbols)
     {
       if (html)
@@ -315,27 +459,170 @@ public class ScoreMatrix implements PairwiseScoreModelI
    * <li>product[0, 1] = F.R + K.- + L.D = -3 + -1 + -3 = -8
    * <li>and so on</li>
    * </ul>
+   * This method is thread-safe.
    */
-  public MatrixI computePairwiseScores(String[] seqs)
+  @Override
+  public MatrixI findSimilarities(AlignmentView seqstrings,
+          SimilarityParamsI options)
   {
-    double[][] values = new double[seqs.length][];
+    char gapChar = scoreGapAsAny ? (seqstrings.isNa() ? 'N' : 'X')
+            : GAP_CHARACTER;
+    String[] seqs = seqstrings.getSequenceStrings(gapChar);
+    return findSimilarities(seqs, options);
+  }
+
+  /**
+   * Computes pairwise similarities of a set of sequences using the given
+   * parameters
+   * 
+   * @param seqs
+   * @param params
+   * @return
+   */
+  protected MatrixI findSimilarities(String[] seqs,
+          SimilarityParamsI params)
+  {
+    double[][] values = new double[seqs.length][seqs.length];
     for (int row = 0; row < seqs.length; row++)
     {
-      values[row] = new double[seqs.length];
-      for (int col = 0; col < seqs.length; col++)
+      for (int col = symmetric ? row : 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++)
+        double total = computeSimilarity(seqs[row], seqs[col], params);
+        values[row][col] = total;
+        if (symmetric)
         {
-          char c1 = seqs[row].charAt(i);
-          char c2 = seqs[col].charAt(i);
-          float score = getPairwiseScore(c1, c2);
-          total += score;
+          values[col][row] = total;
         }
-        values[row][col] = total;
       }
     }
     return new Matrix(values);
   }
+
+  /**
+   * Calculates the pairwise similarity of two strings using the given
+   * calculation parameters
+   * 
+   * @param seq1
+   * @param seq2
+   * @param params
+   * @return
+   */
+  protected double computeSimilarity(String seq1, String seq2,
+          SimilarityParamsI params)
+  {
+    int len1 = seq1.length();
+    int len2 = seq2.length();
+    double total = 0;
+
+    int width = Math.max(len1, len2);
+    for (int i = 0; i < width; i++)
+    {
+      if (i >= len1 || i >= len2)
+      {
+        /*
+         * off the end of one sequence; stop if we are only matching
+         * on the shorter sequence length, else treat as trailing gap
+         */
+        if (params.denominateByShortestLength())
+        {
+          break;
+        }
+      }
+
+      char c1 = i >= len1 ? GAP_CHARACTER : seq1.charAt(i);
+      char c2 = i >= len2 ? GAP_CHARACTER : seq2.charAt(i);
+      boolean gap1 = Comparison.isGap(c1);
+      boolean gap2 = Comparison.isGap(c2);
+
+      if (gap1 && gap2)
+      {
+        /*
+         * gap-gap: include if options say so, else ignore
+         */
+        if (!params.includeGappedColumns())
+        {
+          continue;
+        }
+      }
+      else if (gap1 || gap2)
+      {
+        /*
+         * gap-residue: score if options say so
+         */
+        if (!params.includeGaps())
+        {
+          continue;
+        }
+      }
+      float score = getPairwiseScore(c1, c2);
+      total += score;
+    }
+    return total;
+  }
+
+  /**
+   * Answers a hashcode computed from the symbol alphabet and the matrix score
+   * values
+   */
+  @Override
+  public int hashCode()
+  {
+    int hs = Arrays.hashCode(symbols);
+    for (float[] row : matrix)
+    {
+      hs = hs * 31 + Arrays.hashCode(row);
+    }
+    return hs;
+  }
+
+  /**
+   * Answers true if the argument is a ScoreMatrix with the same symbol alphabet
+   * and score values, else false
+   */
+  @Override
+  public boolean equals(Object obj)
+  {
+    if (!(obj instanceof ScoreMatrix))
+    {
+      return false;
+    }
+    ScoreMatrix sm = (ScoreMatrix) obj;
+    if (Arrays.equals(symbols, sm.symbols)
+            && Arrays.deepEquals(matrix, sm.matrix))
+    {
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Returns the alphabet the matrix scores for, as a string of characters
+   * 
+   * @return
+   */
+  String getSymbols()
+  {
+    return new String(symbols);
+  }
+
+  public float getMinimumScore()
+  {
+    return minValue;
+  }
+
+  public float getMaximumScore()
+  {
+    return maxValue;
+  }
+
+  @Override
+  public ScoreModelI getInstance(AlignmentViewPanel avp)
+  {
+    return this;
+  }
+
+  public boolean isSymmetric()
+  {
+    return symmetric;
+  }
 }