001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 * Created on June 7, 2010
021 * Author: Mark Chapman
022 */
023
024package org.biojava.nbio.core.alignment.template;
025
026import org.biojava.nbio.core.sequence.template.Compound;
027import org.biojava.nbio.core.sequence.template.CompoundSet;
028
029import java.util.Map;
030
031/**
032 * Defines a data structure which holds the score (penalty or bonus) given during alignment for the exchange of one
033 * {@link Compound} in a sequence for another.
034 *
035 * @author Mark Chapman
036 * @author Paolo Pavan
037 * @param <C> each element of the matrix corresponds to a pair of {@link Compound}s of type C
038 */
039public interface SubstitutionMatrix<C extends Compound> {
040
041        /**
042         * Returns the {@link CompoundSet} on which the matrix is defined.
043         *
044         * @return the {@link CompoundSet} on which the matrix is defined
045         */
046        CompoundSet<C> getCompoundSet();
047
048        /**
049         * Returns the description of this matrix.
050         *
051         * @return description
052         */
053        String getDescription();
054
055        /**
056         * Returns entire matrix.
057         *
058         * @return matrix
059         */
060        short[][] getMatrix();
061
062        /**
063         * Returns this matrix as a formatted String with {@link Compound} labels along the axes.
064         *
065         * @return this matrix as a formatted String
066         */
067        String getMatrixAsString();
068
069        /**
070         * Returns the maximum value in this matrix.
071         *
072         * @return the maximum value in this matrix
073         */
074        short getMaxValue();
075
076        /**
077         * Returns the minimum value in this matrix.
078         *
079         * @return the minimum value in this matrix
080         */
081        short getMinValue();
082
083        /**
084         * Returns the name (short description) of this matrix.
085         *
086         * @return name
087         */
088        String getName();
089
090        /**
091         * Returns value in matrix for conversion from first {@link Compound} to the second.  If an argument does not
092         * belong to the {@link CompoundSet}, this could either throw an {@link IllegalArgumentException} or it could
093         * return {@link #getMinValue()}.
094         *
095         * @param from original {@link Compound}
096         * @param to replacement {@link Compound}
097         * @return value in matrix for conversion from first {@link Compound} to the second
098         * @throws IllegalArgumentException possibly, if an argument does not belong to the {@link CompoundSet}
099         */
100        short getValue(C from, C to);
101
102        /**
103         * Rescales the matrix so that to {@link #getMaxValue()} - {@link #getMinValue()} = scale.
104         *
105         * @param scale new normalization scale of this matrix
106         * @throws IllegalArgumentException if scale < 1
107         */
108        SubstitutionMatrix<C> normalizeMatrix(short scale);
109
110        /**
111         * Sets the description of this matrix.
112         *
113         * @param description new description
114         */
115        void setDescription(String description);
116
117        /**
118         * Sets the name (short description) of this matrix.
119         *
120         * @param name new name
121         */
122        void setName(String name);
123
124        Map<C, Short> getRow(C row);
125
126        Map<C, Short> getColumn(C column);
127
128}