src/jalview/analysis/scoremodels/ScoreMatrix.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.analysis.scoremodels;
  22
  23 import jalview.api.analysis.ScoreModelI;
  24
  25 import java.io.BufferedReader;
  26 import java.io.IOException;
  27 import java.io.InputStream;
  28 import java.io.InputStreamReader;
  29 import java.util.Arrays;
  30 import java.util.StringTokenizer;
  31
  32 public class ScoreMatrix extends PairwiseSeqScoreModel implements
  33         ScoreModelI
  34 {
  35   public static final short UNMAPPED = (short) -1;
  36
  37   private static final String DELIMITERS = " ,\t";
  38
  39   private static final String COMMENT_CHAR = "#";
  40
  41   private static final String BAD_ASCII_ERROR = "Unexpected character %s in getPairwiseScore";
  42
  43   private static final int MAX_ASCII = 127;
  44
  45   /*
  46    * the name of the model as shown in menus
  47    */
  48   private String name;
  49
  50   /*
  51    * the characters that the model provides scores for
  52    */
  53   private char[] symbols;
  54
  55   /*
  56    * the score matrix; both dimensions must equal the number of symbols
  57    * matrix[i][j] is the substitution score for replacing symbols[i] with symbols[j]
  58    */
  59   private float[][] matrix;
  60
  61   /*
  62    * quick lookup to convert from an ascii character value to the index
  63    * of the corresponding symbol in the score matrix
  64    */
  65   private short[] symbolIndex;
  66
  67   /*
  68    * true for Protein Score matrix, false for dna score matrix
  69    */
  70   private boolean peptide;
  71
  72   /**
  73    * Constructor
  74    *
  75    * @param name
  76    *          Unique, human readable name for the matrix
  77    * @param alphabet
  78    *          the symbols to which scores apply
  79    * @param matrix
  80    *          Pairwise scores indexed according to the symbol alphabet
  81    */
  82   public ScoreMatrix(String name, char[] alphabet, float[][] matrix)
  83   {
  84     this.matrix = matrix;
  85     this.name = name;
  86     this.symbols = alphabet;
  87
  88     symbolIndex = buildSymbolIndex(alphabet);
  89
  90     /*
  91      * crude heuristic for now...
  92      */
  93     peptide = alphabet.length >= 20;
  94   }
  95
  96   /**
  97    * Returns an array A where A[i] is the position in the alphabet array of the
  98    * character whose value is i. For example if the alphabet is { 'A', 'D', 'X'
  99    * } then A['D'] = A[68] = 1.
 100    * <p>
 101    * Unmapped characters (not in the alphabet) get an index of -1.
 102    * <p>
 103    * Mappings are added automatically for lower case symbols (for non case
 104    * sensitive scoring), unless they are explicitly present in the alphabet (are
 105    * scored separately in the score matrix).
 106    *
 107    * @param alphabet
 108    * @return
 109    */
 110   static short[] buildSymbolIndex(char[] alphabet)
 111   {
 112     short[] index = new short[MAX_ASCII + 1];
 113     Arrays.fill(index, UNMAPPED);
 114     short pos = 0;
 115     for (char c : alphabet)
 116     {
 117       if (c <= MAX_ASCII)
 118       {
 119         index[c] = pos;
 120       }
 121
 122       /*
 123        * also map lower-case character (unless separately mapped)
 124        */
 125       if (c >= 'A' && c <= 'Z')
 126       {
 127         short lowerCase = (short) (c + ('a' - 'A'));
 128         if (index[lowerCase] == UNMAPPED)
 129         {
 130           index[lowerCase] = pos;
 131         }
 132       }
 133       pos++;
 134     }
 135     return index;
 136   }
 137
 138   @Override
 139   public String getName()
 140   {
 141     return name;
 142   }
 143
 144   @Override
 145   public boolean isDNA()
 146   {
 147     return !peptide;
 148   }
 149
 150   @Override
 151   public boolean isProtein()
 152   {
 153     return peptide;
 154   }
 155
 156   @Override
 157   public float[][] getMatrix()
 158   {
 159     return matrix;
 160   }
 161
 162   /**
 163    * Returns the pairwise score for substituting c with d, or zero if c or d is
 164    * an unscored or unexpected character
 165    */
 166   @Override
 167   public float getPairwiseScore(char c, char d)
 168   {
 169     if (c > MAX_ASCII)
 170     {
 171       System.err.println(String.format(BAD_ASCII_ERROR, c));
 172       return 0;
 173     }
 174     if (d > MAX_ASCII)
 175     {
 176       System.err.println(String.format(BAD_ASCII_ERROR, d));
 177       return 0;
 178     }
 179
 180     int cIndex = symbolIndex[c];
 181     int dIndex = symbolIndex[d];
 182     if (cIndex != UNMAPPED && dIndex != UNMAPPED)
 183     {
 184       return matrix[cIndex][dIndex];
 185     }
 186     return 0;
 187   }
 188
 189   /**
 190    * pretty print the matrix
 191    */
 192   @Override
 193   public String toString()
 194   {
 195     return outputMatrix(false);
 196   }
 197
 198   /**
 199    * Print the score matrix, optionally formatted as html, with the alphabet symbols as column headings and at the start of each row
 200    * @param html
 201    * @return
 202    */
 203   public String outputMatrix(boolean html)
 204   {
 205     StringBuilder sb = new StringBuilder(512);
 206
 207     /*
 208      * heading row with alphabet
 209      */
 210     if (html)
 211     {
 212       sb.append("<table border=\"1\">");
 213       sb.append(html ? "<tr><th></th>" : "");
 214     }
 215     for (char sym : symbols)
 216     {
 217       if (html)
 218       {
 219         sb.append("<th>&nbsp;").append(sym).append("&nbsp;</th>");
 220       }
 221       else
 222       {
 223         sb.append("\t").append(sym);
 224       }
 225     }
 226     sb.append(html ? "</tr>\n" : "\n");
 227
 228     /*
 229      * table of scores
 230      */
 231     for (char c1 : symbols)
 232     {
 233       if (html)
 234       {
 235         sb.append("<tr><td>");
 236       }
 237       sb.append(c1).append(html ? "</td>" : "");
 238       for (char c2 : symbols)
 239       {
 240         sb.append(html ? "<td>" : "\t")
 241                 .append(matrix[symbolIndex[c1]][symbolIndex[c2]])
 242                 .append(html ? "</td>" : "");
 243       }
 244       sb.append(html ? "</tr>\n" : "\n");
 245     }
 246     if (html)
 247     {
 248       sb.append("</table>");
 249     }
 250     return sb.toString();
 251   }
 252
 253   /**
 254    * Parse a score matrix from the given input stream and returns a ScoreMatrix
 255    * object. If parsing fails, error messages are written to syserr and null is
 256    * returned. It is the caller's responsibility to close the input stream.
 257    *
 258    * @param is
 259    * @return
 260    */
 261   public static ScoreMatrix parse(InputStream is)
 262   {
 263     ScoreMatrix sm = null;
 264     BufferedReader br = new BufferedReader(new InputStreamReader(is));
 265     int lineNo = 0;
 266     String name = null;
 267     String alphabet = null;
 268     float[][] scores = null;
 269     int size = 0;
 270     int row = 0;
 271
 272     try
 273     {
 274       String data;
 275
 276       while ((data = br.readLine()) != null)
 277       {
 278         lineNo++;
 279         data = data.trim();
 280         if (data.startsWith(COMMENT_CHAR))
 281         {
 282           continue;
 283         }
 284         if (data.toLowerCase().startsWith("scorematrix"))
 285         {
 286           /*
 287            * Parse name from ScoreMatrix <name>
 288            */
 289           if (name != null)
 290           {
 291             System.err
 292                     .println("Warning: 'ScoreMatrix' repeated in file at line "
 293                             + lineNo);
 294           }
 295           StringTokenizer nameLine = new StringTokenizer(data, DELIMITERS);
 296           if (nameLine.countTokens() != 2)
 297           {
 298             System.err
 299                     .println("Format error: expected 'ScoreMatrix <name>', found '"
 300                             + data + "' at line " + lineNo);
 301             return null;
 302           }
 303           nameLine.nextToken();
 304           name = nameLine.nextToken();
 305           continue;
 306         }
 307         else if (name == null)
 308         {
 309           System.err
 310                   .println("Format error: 'ScoreMatrix <name>' should be the first non-comment line");
 311           return null;
 312         }
 313
 314         /*
 315          * next line after ScoreMatrix should be the alphabet of scored symbols
 316          */
 317         if (alphabet == null)
 318         {
 319           alphabet = data;
 320           size = alphabet.length();
 321           scores = new float[size][];
 322           continue;
 323         }
 324
 325         /*
 326          * too much information?
 327          */
 328         if (row >= size && data.length() > 0) {
 329           System.err
 330                   .println("Unexpected extra input line in score model file "
 331                           + data);
 332           return null;
 333         }
 334
 335         /*
 336          * subsequent lines should be the symbol scores
 337          */
 338         StringTokenizer scoreLine = new StringTokenizer(data, DELIMITERS);
 339         if (scoreLine.countTokens() != size)
 340         {
 341           System.err.println(String.format(
 342                   "Expected %d tokens at line %d but found %d", size,
 343                   lineNo, scoreLine.countTokens()));
 344           return null;
 345         }
 346         scores[row] = new float[size];
 347         int col = 0;
 348         String value = null;
 349         while (scoreLine.hasMoreTokens()) {
 350           try {
 351             value = scoreLine.nextToken();
 352             scores[row][col] = Float.valueOf(value);
 353             col++;
 354           } catch (NumberFormatException e)
 355           {
 356             System.err.println(String.format(
 357                     "Invalid score value %s at line %d column %d", value,
 358                     lineNo, col));
 359             return null;
 360           }
 361         }
 362         row++;
 363       }
 364     } catch (IOException e)
 365     {
 366       System.err.println("Error reading score matrix file: "
 367               + e.getMessage() + " at line " + lineNo);
 368     }
 369
 370     /*
 371      * out of data - check we found enough
 372      */
 373     if (row < size)
 374     {
 375       System.err
 376               .println(String
 377                       .format("Expected %d rows of score data in score matrix but only found %d",
 378                               size, row));
 379       return null;
 380     }
 381
 382     /*
 383      * If we get here, then name, alphabet and scores have been parsed successfully
 384      */
 385     sm = new ScoreMatrix(name, alphabet.toCharArray(), scores);
 386     return sm;
 387   }
 388 }