src/jalview/io/ScoreMatrixFile.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.io;
  22
  23 import java.io.IOException;
  24 import java.util.StringTokenizer;
  25
  26 import jalview.analysis.scoremodels.ScoreMatrix;
  27 import jalview.analysis.scoremodels.ScoreModels;
  28 import jalview.datamodel.SequenceI;
  29
  30 /**
  31  * A class that can parse a file containing a substitution matrix and register
  32  * it for use in Jalview
  33  * <p>
  34  * Accepts 'NCBI' format (e.g.
  35  * https://www.ncbi.nlm.nih.gov/Class/FieldGuide/BLOSUM62.txt), with the
  36  * addition of a header line to provide a matrix name, e.g.
  37  *
  38  * <pre>
  39  * ScoreMatrix BLOSUM62
  40  * </pre>
  41  *
  42  * Also accepts 'AAindex' format (as described at
  43  * http://www.genome.jp/aaindex/aaindex_help.html) with the minimum data
  44  * required being
  45  *
  46  * <pre>
  47  * H accession number (used as score matrix identifier in Jalview)
  48  * D description (used for tooltip in Jalview)
  49  * M rows = symbolList
  50  * and the substitution scores
  51  * </pre>
  52  */
  53 public class ScoreMatrixFile extends AlignFile
  54         implements AlignmentFileReaderI
  55 {
  56   // first non-comment line identifier - also checked in IdentifyFile
  57   public static final String SCOREMATRIX = "SCOREMATRIX";
  58
  59   private static final String DELIMITERS = " ,\t";
  60
  61   private static final String COMMENT_CHAR = "#";
  62
  63   private String matrixName;
  64
  65   /*
  66    * aaindex format has scores for diagonal and below only
  67    */
  68   boolean isLowerDiagonalOnly;
  69
  70   /*
  71    * ncbi format has symbols as first column on score rows
  72    */
  73   boolean hasGuideColumn;
  74
  75   /**
  76    * Constructor
  77    *
  78    * @param source
  79    * @throws IOException
  80    */
  81   public ScoreMatrixFile(FileParse source) throws IOException
  82   {
  83     super(false, source);
  84   }
  85
  86   @Override
  87   public String print(SequenceI[] sqs, boolean jvsuffix)
  88   {
  89     return null;
  90   }
  91
  92   /**
  93    * Parses the score matrix file, and if successful registers the matrix so it
  94    * will be shown in Jalview menus. This method is not thread-safe (a separate
  95    * instance of this class should be used by each thread).
  96    */
  97   @Override
  98   public void parse() throws IOException
  99   {
 100     ScoreMatrix sm = parseMatrix();
 101
 102     ScoreModels.getInstance().registerScoreModel(sm);
 103   }
 104
 105   /**
 106    * Parses the score matrix file and constructs a ScoreMatrix object. If an
 107    * error is found in parsing, it is thrown as FileFormatException. Any
 108    * warnings are written to syserr.
 109    *
 110    * @return
 111    * @throws IOException
 112    */
 113   public ScoreMatrix parseMatrix() throws IOException
 114   {
 115     ScoreMatrix sm = null;
 116     int lineNo = 0;
 117     String name = null;
 118     char[] alphabet = null;
 119     float[][] scores = null;
 120     int size = 0;
 121     int row = 0;
 122     String err = null;
 123     String data;
 124     isLowerDiagonalOnly = false;
 125
 126     while ((data = nextLine()) != null)
 127     {
 128       lineNo++;
 129       data = data.trim();
 130       if (data.startsWith(COMMENT_CHAR) || data.length() == 0)
 131       {
 132         continue;
 133       }
 134       // equivalent to data.startsWithIgnoreCase(SCOREMATRIX)
 135       if (data.regionMatches(true, 0, SCOREMATRIX, 0, SCOREMATRIX.length()))
 136       {
 137         /*
 138          * Parse name from ScoreMatrix <name>
 139          * we allow any delimiter after ScoreMatrix then take the rest of the line
 140          */
 141         if (name != null)
 142         {
 143           throw new FileFormatException(
 144                   "Error: 'ScoreMatrix' repeated in file at line "
 145                           + lineNo);
 146         }
 147         StringTokenizer nameLine = new StringTokenizer(data, DELIMITERS);
 148         if (nameLine.countTokens() < 2)
 149         {
 150           err = "Format error: expected 'ScoreMatrix <name>', found '"
 151                   + data + "' at line " + lineNo;
 152           throw new FileFormatException(err);
 153         }
 154         nameLine.nextToken(); // 'ScoreMatrix'
 155         name = nameLine.nextToken(); // next field
 156         name = data.substring(1).substring(data.substring(1).indexOf(name));
 157         continue;
 158       }
 159       else if (data.startsWith("H ") && name == null)
 160       {
 161         /*
 162          * AAindex identifier
 163          */
 164         return parseAAIndexFormat(lineNo, data);
 165       }
 166       else if (name == null)
 167       {
 168         err = "Format error: 'ScoreMatrix <name>' should be the first non-comment line";
 169         throw new FileFormatException(err);
 170       }
 171
 172       /*
 173        * next non-comment line after ScoreMatrix should be the
 174        * column header line with the alphabet of scored symbols
 175        */
 176       if (alphabet == null)
 177       {
 178         StringTokenizer columnHeadings = new StringTokenizer(data,
 179                 DELIMITERS);
 180         size = columnHeadings.countTokens();
 181         alphabet = new char[size];
 182         int col = 0;
 183         while (columnHeadings.hasMoreTokens())
 184         {
 185           alphabet[col++] = columnHeadings.nextToken().charAt(0);
 186         }
 187         scores = new float[size][];
 188         continue;
 189       }
 190
 191       /*
 192        * too much information
 193        */
 194       if (row >= size)
 195       {
 196         err = "Unexpected extra input line in score model file: '" + data
 197                 + "'";
 198         throw new FileFormatException(err);
 199       }
 200
 201       parseValues(data, lineNo, scores, row, alphabet);
 202       row++;
 203     }
 204
 205     /*
 206      * out of data - check we found enough
 207      */
 208     if (row < size)
 209     {
 210       err = String.format(
 211               "Expected %d rows of score data in score matrix but only found %d",
 212               size, row);
 213       throw new FileFormatException(err);
 214     }
 215
 216     /*
 217      * If we get here, then name, alphabet and scores have been parsed successfully
 218      */
 219     sm = new ScoreMatrix(name, alphabet, scores);
 220     matrixName = name;
 221
 222     return sm;
 223   }
 224
 225   /**
 226    * Parse input as AAIndex format, starting from the header line with the
 227    * accession id
 228    *
 229    * @param lineNo
 230    * @param data
 231    * @return
 232    * @throws IOException
 233    */
 234   protected ScoreMatrix parseAAIndexFormat(int lineNo, String data)
 235           throws IOException
 236   {
 237     String name = data.substring(2).trim();
 238     String description = null;
 239
 240     float[][] scores = null;
 241     char[] alphabet = null;
 242     int row = 0;
 243     int size = 0;
 244
 245     while ((data = nextLine()) != null)
 246     {
 247       lineNo++;
 248       data = data.trim();
 249       if (skipAAindexLine(data))
 250       {
 251         continue;
 252       }
 253       if (data.startsWith("D "))
 254       {
 255         description = data.substring(2).trim();
 256       }
 257       else if (data.startsWith("M "))
 258       {
 259         alphabet = parseAAindexRowsColumns(lineNo, data);
 260         size = alphabet.length;
 261         scores = new float[size][size];
 262       }
 263       else if (scores == null)
 264       {
 265         throw new FileFormatException(
 266                 "No alphabet specified in matrix file");
 267       }
 268       else if (row >= size)
 269       {
 270         throw new FileFormatException("Too many data rows in matrix file");
 271       }
 272       else
 273       {
 274         parseValues(data, lineNo, scores, row, alphabet);
 275         row++;
 276       }
 277     }
 278
 279     ScoreMatrix sm = new ScoreMatrix(name, description, alphabet, scores);
 280     matrixName = name;
 281
 282     return sm;
 283   }
 284
 285   /**
 286    * Parse one row of score values, delimited by whitespace or commas. The line
 287    * may optionally include the symbol from which the scores are defined. Values
 288    * may be present for all columns, or only up to the diagonal (in which case
 289    * upper diagonal values are set symmetrically).
 290    *
 291    * @param data
 292    *          the line to be parsed
 293    * @param lineNo
 294    * @param scores
 295    *          the score matrix to add data to
 296    * @param row
 297    *          the row number / alphabet index position
 298    * @param alphabet
 299    * @return
 300    * @throws exception
 301    *           if invalid, or too few, or too many values
 302    */
 303   protected void parseValues(String data, int lineNo, float[][] scores,
 304           int row, char[] alphabet) throws FileFormatException
 305   {
 306     String err;
 307     int size = alphabet.length;
 308     StringTokenizer scoreLine = new StringTokenizer(data, DELIMITERS);
 309
 310     int tokenCount = scoreLine.countTokens();
 311
 312     /*
 313      * inspect first row to see if it includes the symbol in the first column,
 314      * and to see if it is lower diagonal values only (i.e. just one score)
 315      */
 316     if (row == 0)
 317     {
 318       if (data.startsWith(String.valueOf(alphabet[0])))
 319       {
 320         hasGuideColumn = true;
 321       }
 322       if (tokenCount == (hasGuideColumn ? 2 : 1))
 323       {
 324         isLowerDiagonalOnly = true;
 325       }
 326     }
 327
 328     if (hasGuideColumn)
 329     {
 330       /*
 331        * check 'guide' symbol is the row'th letter of the alphabet
 332        */
 333       String symbol = scoreLine.nextToken();
 334       if (symbol.length() > 1 || symbol.charAt(0) != alphabet[row])
 335       {
 336         err = String.format(
 337                 "Error parsing score matrix at line %d, expected '%s' but found '%s'",
 338                 lineNo, alphabet[row], symbol);
 339         throw new FileFormatException(err);
 340       }
 341       tokenCount = scoreLine.countTokens(); // excluding guide symbol
 342     }
 343
 344     /*
 345      * check the right number of values (lower diagonal or full format)
 346      */
 347     if (isLowerDiagonalOnly && tokenCount != row + 1)
 348     {
 349       err = String.format(
 350               "Expected %d scores at line %d: '%s' but found %d", row + 1,
 351               lineNo, data, tokenCount);
 352       throw new FileFormatException(err);
 353     }
 354
 355     if (!isLowerDiagonalOnly && tokenCount != size)
 356     {
 357       err = String.format(
 358               "Expected %d scores at line %d: '%s' but found %d", size,
 359               lineNo, data, scoreLine.countTokens());
 360       throw new FileFormatException(err);
 361     }
 362
 363     /*
 364      * parse and set the values, setting the symmetrical value
 365      * as well if lower diagonal format data
 366      */
 367     scores[row] = new float[size];
 368     int col = 0;
 369     String value = null;
 370     while (scoreLine.hasMoreTokens())
 371     {
 372       try
 373       {
 374         value = scoreLine.nextToken();
 375         scores[row][col] = Float.valueOf(value);
 376         if (isLowerDiagonalOnly)
 377         {
 378           scores[col][row] = scores[row][col];
 379         }
 380         col++;
 381       } catch (NumberFormatException e)
 382       {
 383         err = String.format("Invalid score value '%s' at line %d column %d",
 384                 value, lineNo, col);
 385         throw new FileFormatException(err);
 386       }
 387     }
 388   }
 389
 390   /**
 391    * Parse the line in an aaindex file that looks like
 392    *
 393    * <pre>
 394    * M rows = ARNDCQEGHILKMFPSTWYV, cols = ARNDCQEGHILKMFPSTWYV
 395    * </pre>
 396    *
 397    * rejecting it if rows and cols do not match. Returns the string of
 398    * characters in the row/cols alphabet.
 399    *
 400    * @param lineNo
 401    * @param data
 402    * @return
 403    * @throws FileFormatException
 404    */
 405   protected char[] parseAAindexRowsColumns(int lineNo, String data)
 406           throws FileFormatException
 407   {
 408     String err = "Unexpected aaIndex score matrix data at line " + lineNo
 409             + ": " + data;
 410
 411     try
 412     {
 413       String[] toks = data.split(",");
 414       String rowsAlphabet = toks[0].split("=")[1].trim();
 415       String colsAlphabet = toks[1].split("=")[1].trim();
 416       if (!rowsAlphabet.equals(colsAlphabet))
 417       {
 418         throw new FileFormatException("rows != cols");
 419       }
 420       return rowsAlphabet.toCharArray();
 421     } catch (Throwable t)
 422     {
 423       throw new FileFormatException(err + " " + t.getMessage());
 424     }
 425   }
 426
 427   /**
 428    * Answers true if line is one we are not interested in from AAindex format
 429    * file
 430    *
 431    * @param data
 432    * @return
 433    */
 434   protected boolean skipAAindexLine(String data)
 435   {
 436     if (data.startsWith(COMMENT_CHAR) || data.length() == 0)
 437     {
 438       return true;
 439     }
 440     if (data.startsWith("*") || data.startsWith("R ")
 441             || data.startsWith("A ") || data.startsWith("T ")
 442             || data.startsWith("J ") || data.startsWith("//"))
 443     {
 444       return true;
 445     }
 446     return false;
 447   }
 448
 449   public String getMatrixName()
 450   {
 451     return matrixName;
 452   }
 453 }