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 */
021
022/*
023 *    AAindex.java
024 */
025package org.biojava.bio.proteomics.aaindex;
026
027import java.util.HashMap;
028import java.util.Map;
029
030import org.biojava.bio.seq.ProteinTools;
031import org.biojava.bio.symbol.Alphabet;
032import org.biojava.bio.symbol.SimpleSymbolPropertyTable;
033
034/**
035 * Symbol property table based on the Amino Acid Index Database. Each 
036 * <code>AAindex</code> object represents a single entry of an AAindex1 file.
037 * Each entry contains twenty numeric values for the twenty amino acids, e.g.
038 * describing the hydrophobicity of an amino acid. To get this value for a
039 * certain amino acid call the 
040 * {@link org.biojava.bio.symbol.SymbolPropertyTable#getDoubleValue(org.biojava.bio.symbol.Symbol)}
041 * method with the appropriate symbol, e.g. 
042 * <code>aaindex.getDoubleValue(ProteinTools.gln())</code>.
043 * The remaining data fields, i.e. object properties, are fully described in the
044 * <a href="http://www.genome.ad.jp/dbget-bin/show_man?aaindex">AAindex manual
045 * </a>.
046 * <p><b>References:</b></p>
047 * <p><a href="http://www.genome.ad.jp/dbget/aaindex.html">AAindex web 
048 * site</a>.</p>
049 * <p>Kawashima, S. and Kanehisa, M.; AAindex: amino acid index database. 
050 * Nucleic Acids Res. 28, 374 (2000).</p>
051 * <p>Tomii, K. and Kanehisa, M.;  Analysis of amino acid indices and mutation 
052 * matrices for sequence comparison and structure prediction of proteins. 
053 * Protein Eng. 9, 27-36 (1996).</p>
054 * <p>Nakai, K., Kidera, A., and Kanehisa, M.;  Cluster analysis of amino acid 
055 * indices for prediction of protein structure and function.  
056 * Protein Eng. 2, 93-100 (1988)</p>
057 * @author <a href="mailto:Martin.Szugat@GMX.net">Martin Szugat</a>
058 * @version $Revision$
059 */
060public class AAindex extends SimpleSymbolPropertyTable {
061
062    /* PUBLIC CONSTANTS */
063    
064    /**
065     * The alphabet of the symbol property table, that is 
066     * {@linkplain ProteinTools#getAlphabet() protein}.
067     */
068    public static final Alphabet PROTEIN_ALPHABET = ProteinTools.getAlphabet(); 
069
070    /* PRIVATE FIELDS */
071
072    /**
073     * The accession number of the AAindex entry.
074     */
075    private String accessionNumber = null;
076
077    /**
078     * The description of the AAindex entry.
079     */
080    private String description = null;
081
082    /**
083     * Literature database entry numbers for the AAindex entry.
084     */
085    private String[] litdbEntryNumbers = null;
086
087    /**
088     * The authors of the article first explaining this AAindex entry.
089     */
090    private String articleAuthors = null;
091
092    /**
093     * The title of the article.
094     */
095    private String articleTitle = null;
096
097    /**
098     * The reference to the journal which published the article.
099     */
100    private String journalReference = null;
101
102    /**
103     * User commments.
104     */
105    private String comment = null;
106
107    /**
108     * A map of similar AAindex entries with correlation coefficients.
109     */
110    private Map similarEntries = new HashMap();
111    
112    /* PUBLIC CONSTRUCTOR */
113
114    /**
115     * Initializes the AAindex symbol property table.
116     * @param accessionNumber the AAindex accession number (same as the table
117     * name)
118     * @throws NullPointerException if <code>accessionNumber</code> is
119     * <code>null</code>.
120     */
121    public AAindex(String accessionNumber) throws NullPointerException {
122        super(PROTEIN_ALPHABET, accessionNumber);
123        if (accessionNumber == null) {
124            throw new NullPointerException("accessionNumber is null.");
125        }
126        this.accessionNumber = accessionNumber;
127    }
128    
129    /* PUBLIC PROPERTIES */
130
131    /**
132     * Gets the accession number of the AAindex entry.
133     * @return the accession number (same as 
134     * {@link org.biojava.bio.symbol.SymbolPropertyTable#getName()}
135     */
136    public String accessionNumber() {
137        return accessionNumber;
138    }
139
140    /**
141     * Gets the names of the authors which first published an article about the
142     * AAindex entry.
143     * @return a list of names. May be <code>null</code>.
144     */
145    public String getArticleAuthors() {
146        return articleAuthors;
147    }
148
149    /**
150     * Sets the names of the authors which first published an article about the
151     * AAindex entry.
152     * @param articleAuthors May be <code>null</code>.
153     */
154    public void setArticleAuthors(String articleAuthors) {
155        this.articleAuthors = articleAuthors;
156    }
157
158    /**
159     * Gets the user comment for the AAindex entry.
160     * @return free text. May be <code>null</code>.
161     */
162    public String getComment() {
163        return comment;
164    }
165
166    /**
167     * Sets the user comment for the AAindex entry.
168     * @param comment free text. May be <code>null</code>.
169     */
170    public void setComment(String comment) {
171        this.comment = comment;
172    }
173
174    /**
175     * Gets the title of the article which describes the AAindex entry.
176     * @return the article title. May be <code>null</code>.
177     */
178    public String getArticleTitle() {
179        return articleTitle;
180    }
181
182    /**
183     * Sets the title of the article which describes the AAindex entry.
184     * @param articleTitle the article title. May be <code>null</code>.
185     */
186    public void setArticleTitle(String articleTitle) {
187        this.articleTitle = articleTitle;
188    }
189
190    /**
191     * Gets the description for the AAindex entry.
192     * @return a human readable description. May be <code>null</code>.
193     */
194    public String getDescription() {
195        return description;
196    }
197
198    /**
199     * Sets the description for the AAindex entry.
200     * @param description a human readable description. 
201     * May be <code>null</code>.
202     */
203    public void setDescription(String description) {
204        this.description = description;
205    }
206
207    /**
208     * Gets a reference to the journal which published the article about the
209     * AAindex entry.
210     * @return the journal reference. May be <code>null</code>.
211     */
212    public String getJournalReference() {
213        return journalReference;
214    }
215
216    /**
217     * Sets a reference to the journal which published the article about the
218     * AAindex entry.
219     * @param journalReference the journal reference. May be <code>null</code>.
220     */
221    public void setJournalReference(String journalReference) {
222        this.journalReference = journalReference;
223    }
224
225    /**
226     * Gets the list of literature database identifiers for the AAindex entry.
227     * @return a list of identifiers. May be <code>null</code>.
228     */
229    public String[] getLITDBEntryNumbers() {
230        return (litdbEntryNumbers == null ? null 
231                : (String[]) litdbEntryNumbers.clone());
232    }
233
234    /**
235     * Sets the list of literature database identifiers for the AAindex entry.
236     * @param litdbEntryNumbers a list of identifiers
237     */
238    public void setLITDBEntryNumbers(String[] litdbEntryNumbers) {
239        if (litdbEntryNumbers == null) {
240            this.litdbEntryNumbers = null;
241        } else {
242            this.litdbEntryNumbers = (String[]) litdbEntryNumbers.clone();
243        }
244    }
245    
246    /**
247     * Returns a map with the names of similar AAindex entries and its 
248     * correlation coefficients. 
249     * @return a map which keys are the names of the similar AAindex entries and
250     * which values are the corresponding correlation coefficients
251     */
252    public Map similarEntries() {
253        return similarEntries;
254    }
255
256}