## org.biojava.bio.alignment
Class SubstitutionMatrix

    java.lang.Object
      org.biojava.bio.alignment.SubstitutionMatrix

    public class SubstitutionMatrix

extends java.lang.Object

This object is able to read a substitution matrix file and constructs an int matrix to store the matrix. Every single element of the matrix can be accessed by the method `getValueAt` with the parameters being tow biojava symbols. This is why it is not necessary to access the matrix directly. If there is no value for the two specified `Symbol`s an `Exception` is thrown.

Substitution matrix files, are available at The NCBI FTP directory.

Author:
  Andreas Dräger

Field Summary
`protected FiniteAlphabet` `alphabet`
`protected java.util.Map` `colSymbols`
`protected java.lang.String` `description`
`protected int[][]` `matrix`
`protected int` `max`
`protected int` `min`
`protected java.lang.String` `name`
`protected java.util.Map` `rowSymbols`

Constructor Summary
`SubstitutionMatrix(FiniteAlphabet alpha, java.io.File matrixFile)` This constructs a `SubstitutionMatrix`-object that contains two `Map` data structures having biojava symbols as key and the value being the index of the matrix containing the substitution score.
`SubstitutionMatrix(FiniteAlphabet alpha, int match, int replace)` Constructs a SubstitutionMatrix with every Match and every Replace having the same expenses given by the parameters.
`SubstitutionMatrix(FiniteAlphabet alpha, java.lang.String matrixString, java.lang.String name)` With this constructor it is possible to construct a SubstitutionMatrix object from a substitution matrix file.

Method Summary
`FiniteAlphabet` `getAlphabet()` Gives the alphabet used by this matrix.
`java.lang.String` `getDescription()` This gives you the description of this matrix if there is one.
`int` `getMax()` The maximum score in this matrix.
`int` `getMin()` The minimum score of this matrix.
`java.lang.String` `getName()` Every substitution matrix has a name like "BLOSUM30" or "PAM160".
`int` `getValueAt(Symbol row, Symbol col)` There are some substitution matrices containing more columns than lines.
`SubstitutionMatrix` `normalizeMatrix()` With this method you can get a "normalized" `SubstitutionMatrix` object; however, since this implementation uses an int matrix, the normalized matrix will be scaled by ten.
`protected int[][]` `parseMatrix(java.lang.String matString)` Reads a String representing the contents of a substitution matrix file.
`void` `printMatrix()` Just to perform some test.
`void` `setDescription(java.lang.String desc)` Sets the description to the given value.
`java.lang.String` `stringnifyDescription()` Stringnifies the description of the matrix.
`java.lang.String` `stringnifyMatrix()` Creates a `String` representation of this matrix.
`java.lang.String` `toString()` Overides the inherited method.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### rowSymbols

    protected java.util.Map rowSymbols

### colSymbols

    protected java.util.Map colSymbols

### matrix

    protected int[][] matrix

### min

    protected int min

### max

    protected int max

### alphabet

    protected FiniteAlphabet alphabet

### description

    protected java.lang.String description

### name

    protected java.lang.String name

Constructor Detail

### SubstitutionMatrix

    public SubstitutionMatrix(FiniteAlphabet alpha,
                              java.io.File matrixFile)
                       throws java.io.IOException,
                              BioException

  This constructs a `SubstitutionMatrix`-object that contains two `Map` data structures having biojava symbols as key and the value being the index of the matrix containing the substitution score.

  Parameters:
    `alpha` - the alphabet of the matrix (DNA, RNA or PROTEIN, or PROTEIN-TERM)
    `matrixFile` - the file containing the substitution matrix. Lines starting with '`#`' are comments. The line starting with a white space, is the table head. Every line has to start with the one letter representation of the Symbol and then the values for the exchange.
  Throws:
    `java.io.IOException`
    `BioException`

### SubstitutionMatrix

    public SubstitutionMatrix(FiniteAlphabet alpha,
                              java.lang.String matrixString,
                              java.lang.String name)
                       throws BioException

  With this constructor it is possible to construct a SubstitutionMatrix object from a substitution matrix file. The given String contains a number of lines separated by `\n`. Everything else is the same than for the constructor above.

  Parameters:
    `alpha` - The `FiniteAlphabet` to use
    `matrixString` -
    `name` - of the matrix.
  Throws:
    `BioException`

### SubstitutionMatrix

    public SubstitutionMatrix(FiniteAlphabet alpha,
                              int match,
                              int replace)

  Constructs a SubstitutionMatrix with every Match and every Replace having the same expenses given by the parameters. Ambigious symbols are not considered because there might be to many of them (for proteins).

  Parameters:
    `alpha` -
    `match` -
    `replace` -

Method Detail

### parseMatrix

    protected int[][] parseMatrix(java.lang.String matString)
                           throws BioException

  Reads a String representing the contents of a substitution matrix file.

  Parameters:
    `matString` -
  Returns:
    matrix
  Throws:
    `BioException`

### getValueAt

    public int getValueAt(Symbol row,
                          Symbol col)
                   throws BioException

  There are some substitution matrices containing more columns than lines. This has to do with the ambigious symbols. Lines are always good, columns might not contain the whole information. The matrix is supposed to be symmetric anyway, so you can always set the ambigious symbol to be the first argument.

  Parameters:
    `row` - Symbol of the line
    `col` - Symbol of the column
  Returns:
    expenses for the exchange of symbol row and symbol col.
  Throws:
    `BioException`

### getDescription

    public java.lang.String getDescription()

  This gives you the description of this matrix if there is one. Normally substitution matrix files like BLOSUM contain some lines of description.

  Returns:
    the comment of the matrix

### getName

    public java.lang.String getName()

  Every substitution matrix has a name like "BLOSUM30" or "PAM160". This will be returned by this method.

  Returns:
    the name of the matrix.

### getMin

    public int getMin()

  The minimum score of this matrix.

  Returns:
    minimum of the matrix.

### getMax

    public int getMax()

  The maximum score in this matrix.

  Returns:
    maximum of the matrix.

### setDescription

    public void setDescription(java.lang.String desc)

  Sets the description to the given value.

  Parameters:
    `desc` - a description. This doesn't have to start with '#'.

### getAlphabet

    public FiniteAlphabet getAlphabet()

  Gives the alphabet used by this matrix.

  Returns:
    the alphabet of this matrix.

### stringnifyMatrix

    public java.lang.String stringnifyMatrix()

  Creates a `String` representation of this matrix.

  Returns:
    a string representation of this matrix without the description.

### stringnifyDescription

    public java.lang.String stringnifyDescription()

  Stringnifies the description of the matrix.

  Returns:
    Gives a description with approximately 60 letters on every line separated by `\n`. Every line starts with `#`.

### toString

    public java.lang.String toString()

  Overides the inherited method.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    Gives a string representation of the SubstitutionMatrix. This is a valid input for the constructor which needs a matrix string. This String also contains the description of the matrix if there is one.

### printMatrix

    public void printMatrix()

  Just to perform some test. It prints the matrix on the screen.

### normalizeMatrix

    public SubstitutionMatrix normalizeMatrix()

  With this method you can get a "normalized" `SubstitutionMatrix` object; however, since this implementation uses an int matrix, the normalized matrix will be scaled by ten. If you need values between zero and one, you have to devide every value returnd by `getValueAt` by ten.

  Returns:
    a new and normalized `SubstitutionMatrix` object given by this substitution matrix. Because this uses an `int` matrix, all values are skaled by 10.