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 2011.05.09 by kohchuanhock 021 * 022 */ 023package org.biojava.nbio.aaproperties; 024 025import org.biojava.nbio.aaproperties.xml.AminoAcidCompositionTable; 026import org.biojava.nbio.core.sequence.ProteinSequence; 027import org.biojava.nbio.core.sequence.compound.AminoAcidCompound; 028 029import javax.xml.bind.JAXBException; 030import java.io.File; 031import java.io.FileNotFoundException; 032import java.util.Map; 033 034 035/** 036 * An interface to generate some basic physico-chemical properties of protein sequences.<br/> 037 * The following properties could be generated: 038 * <p/> 039 * Molecular weight<br/> 040 * Absorbance<br/> 041 * Extinction coefficient<br/> 042 * Instability index<br/> 043 * Apliphatic index<br/> 044 * Average hydropathy value<br/> 045 * Isoelectric point<br/> 046 * Net charge at pH 7<br/> 047 * Composition of specified amino acid<br/> 048 * Composition of the 20 standard amino acid<br/> 049 * @author kohchuanhock 050 * @version 2011.05.09 051 * @see PeptideProperties 052 */ 053public interface IPeptideProperties{ 054 /** 055 * Returns the molecular weight of sequence. The sequence argument must be a protein sequence consisting of only non-ambiguous characters. 056 * This method will sum the molecular weight of each amino acid in the 057 * sequence. Molecular weights are based on <a href="http://web.expasy.org/findmod/findmod_masses.html">here</a>. 058 * 059 * @param sequence 060 * a protein sequence consisting of non-ambiguous characters only 061 * @return the total molecular weight of sequence + weight of water molecule 062 * @see ProteinSequence 063 */ 064 public double getMolecularWeight(ProteinSequence sequence); 065 066 /** 067 * Returns the molecular weight of sequence. The sequence argument must be a protein sequence consisting of only non-ambiguous characters. 068 * This method will sum the molecular weight of each amino acid in the 069 * sequence. Molecular weights are based on the input files. These input files must be XML using the defined schema. 070 * Note that it assumes that ElementMass.xml file can be found in default location. 071 * 072 * @param sequence 073 * a protein sequence consisting of non-ambiguous characters only 074 * xml file that details the mass of each elements and isotopes 075 * @param aminoAcidCompositionFile 076 * xml file that details the composition of amino acids 077 * @return the total molecular weight of sequence + weight of water molecule 078 * @throws JAXBException 079 * thrown if unable to properly parse either elementMassFile or aminoAcidCompositionFile 080 * @throws FileNotFoundException 081 * thrown if either elementMassFile or aminoAcidCompositionFile are not found 082 */ 083 public double getMolecularWeight(ProteinSequence sequence, File aminoAcidCompositionFile) throws JAXBException, FileNotFoundException; 084 085 /** 086 * Returns the molecular weight of sequence. The sequence argument must be a protein sequence consisting of only non-ambiguous characters. 087 * This method will sum the molecular weight of each amino acid in the 088 * sequence. Molecular weights are based on the input files. These input files must be XML using the defined schema. 089 * 090 * @param sequence 091 * a protein sequence consisting of non-ambiguous characters only 092 * @param elementMassFile 093 * xml file that details the mass of each elements and isotopes 094 * @param aminoAcidCompositionFile 095 * xml file that details the composition of amino acids 096 * @return the total molecular weight of sequence + weight of water molecule 097 * @throws JAXBException 098 * thrown if unable to properly parse either elementMassFile or aminoAcidCompositionFile 099 * @throws FileNotFoundException 100 * thrown if either elementMassFile or aminoAcidCompositionFile are not found 101 */ 102 public double getMolecularWeight(ProteinSequence sequence, File elementMassFile, File aminoAcidCompositionFile) 103 throws JAXBException, FileNotFoundException; 104 105 /** 106 * Returns the molecular weight of sequence. The sequence argument must be a protein sequence consisting of only non-ambiguous characters. 107 * This method will sum the molecular weight of each amino acid in the 108 * sequence. Molecular weights are based on the AminoAcidCompositionTable. 109 * Those input files must be XML using the defined schema. 110 * 111 * @param sequence 112 * a protein sequence consisting of non-ambiguous characters only 113 * @param aminoAcidCompositionTable 114 * a amino acid composition table obtained by calling IPeptideProperties.obtainAminoAcidCompositionTable 115 * @return the total molecular weight of sequence + weight of water molecule 116 */ 117 public double getMolecularWeightBasedOnXML(ProteinSequence sequence, AminoAcidCompositionTable aminoAcidCompositionTable); 118 119 /** 120 * This method would initialize amino acid composition table based on the input xml files and stores the table for usage in future calls to 121 * IPeptideProperties.getMolecularWeightBasedOnXML(ProteinSequence, AminoAcidCompositionTable). 122 * Note that ElementMass.xml is assumed to be able to be seen in default location. 123 * 124 * @param aminoAcidCompositionFile 125 * xml file that details the composition of amino acids 126 * @return the initialized amino acid composition table 127 * @throws JAXBException 128 * thrown if unable to properly parse either elementMassFile or aminoAcidCompositionFile 129 * @throws FileNotFoundException 130 * thrown if either elementMassFile or aminoAcidCompositionFile are not found 131 */ 132 public AminoAcidCompositionTable obtainAminoAcidCompositionTable(File aminoAcidCompositionFile) 133 throws JAXBException, FileNotFoundException; 134 135 /** 136 * This method would initialize amino acid composition table based on the input xml files and stores the table for usage in future calls to 137 * IPeptideProperties.getMolecularWeightBasedOnXML(ProteinSequence, AminoAcidCompositionTable). 138 * 139 * @param elementMassFile 140 * xml file that details the mass of each elements and isotopes 141 * @param aminoAcidCompositionFile 142 * xml file that details the composition of amino acids 143 * @return the initialized amino acid composition table 144 * @throws JAXBException 145 * thrown if unable to properly parse either elementMassFile or aminoAcidCompositionFile 146 * @throws FileNotFoundException 147 * thrown if either elementMassFile or aminoAcidCompositionFile are not found 148 */ 149 public AminoAcidCompositionTable obtainAminoAcidCompositionTable(File elementMassFile, File aminoAcidCompositionFile) 150 throws JAXBException, FileNotFoundException; 151 152 /** 153 * Returns the extinction coefficient of sequence. The sequence argument 154 * must be a protein sequence consisting of only non-ambiguous characters. 155 * The extinction coefficient indicates how much light a protein absorbs at 156 * a certain wavelength. It is useful to have an estimation of this 157 * coefficient for following a protein which a spectrophotometer when 158 * purifying it. The computation of extinction coefficient follows the 159 * documentation in <a href="http://web.expasy.org/protparam/protparam-doc.html">here</a>. 160 * 161 * @param sequence 162 * a protein sequence consisting of non-ambiguous characters only 163 * @param assumeCysReduced 164 * true if Cys are assumed to be reduced and false if Cys are 165 * assumed to form cystines 166 * @return the extinction coefficient of sequence 167 * @see ProteinSequence 168 */ 169 public double getExtinctionCoefficient(ProteinSequence sequence, boolean assumeCysReduced); 170 171 /** 172 * Returns the absorbance (optical density) of sequence. The sequence argument 173 * must be a protein sequence consisting of only non-ambiguous characters. 174 * The computation of absorbance (optical density) follows the 175 * documentation in <a href="http://web.expasy.org/protparam/protparam-doc.html">here</a>. 176 * 177 * @param sequence 178 * a protein sequence consisting of non-ambiguous characters only 179 * @param assumeCysReduced 180 * true if Cys are assumed to be reduced and false if Cys are 181 * assumed to form cystines 182 * @return the absorbance (optical density) of sequence 183 * @see ProteinSequence 184 */ 185 public double getAbsorbance(ProteinSequence sequence, boolean assumeCysReduced); 186 187 /** 188 * Returns the instability index of sequence. The sequence argument must be 189 * a protein sequence consisting of only non-ambiguous characters. 190 * The instability index provides an estimate of the stability of your 191 * protein in a test tube. The computation of instability index follows the 192 * documentation in <a href="http://web.expasy.org/protparam/protparam-doc.html">here</a>. 193 * 194 * @param sequence 195 * a protein sequence consisting of non-ambiguous characters only 196 * @return the instability index of sequence 197 * @see ProteinSequence 198 */ 199 public double getInstabilityIndex(ProteinSequence sequence); 200 201 /** 202 * Returns the apliphatic index of sequence. The sequence argument must be a 203 * protein sequence consisting of only non-ambiguous characters. 204 * The aliphatic index of a protein is defined as the relative volume 205 * occupied by aliphatic side chains (alanine, valine, isoleucine, and 206 * leucine). It may be regarded as a positive factor for the increase of 207 * thermostability of globular proteins. The computation of aliphatic index 208 * follows the documentation in <a href="http://web.expasy.org/protparam/protparam-doc.html">here</a>. 209 * A protein whose instability index is smaller than 40 is predicted as stable, a value above 40 predicts that the protein may be unstable. 210 * 211 * @param sequence 212 * a protein sequence consisting of non-ambiguous characters only 213 * @return the aliphatic index of sequence 214 * @see ProteinSequence 215 */ 216 public double getApliphaticIndex(ProteinSequence sequence); 217 218 /** 219 * Returns the average hydropathy value of sequence. The sequence argument 220 * must be a protein sequence consisting of only non-ambiguous characters. 221 * The average value for a sequence is calculated as the sum of hydropathy 222 * values of all the amino acids, divided by the number of residues in the 223 * sequence. Hydropathy values are based on (Kyte, J. and Doolittle, R.F. 224 * (1982) A simple method for displaying the hydropathic character of a 225 * protein. J. Mol. Biol. 157, 105-132). 226 * 227 * @param sequence 228 * a protein sequence consisting of non-ambiguous characters only 229 * @return the average hydropathy value of sequence 230 * @see ProteinSequence 231 */ 232 public double getAvgHydropathy(ProteinSequence sequence); 233 234 /** 235 * Returns the isoelectric point of sequence. The sequence argument must be 236 * a protein sequence consisting of only non-ambiguous characters. 237 * The isoelectric point is the pH at which the protein carries no net 238 * electrical charge. The isoelectric point will be computed based on 239 * approach stated in 240 * <a href="http://www.innovagen.se/custom-peptide-synthesis/peptide-property-calculator/peptide-property-calculator-notes.asp#PI">here</a> 241 * 242 * pKa values used will be either 243 * those used by Expasy which referenced "Electrophoresis 1994, 15, 529-539" 244 * OR 245 * A.Lehninger, Principles of Biochemistry, 4th Edition (2005), Chapter 3, page78, Table 3-1. 246 * @param sequence 247 * a protein sequence consisting of non-ambiguous characters only 248 * @param useExpasyValues 249 * whether to use Expasy values (Default) or Innovagen values 250 * @return the isoelectric point of sequence 251 * @see ProteinSequence 252 */ 253 public double getIsoelectricPoint(ProteinSequence sequence, boolean useExpasyValues); 254 255 public double getIsoelectricPoint(ProteinSequence seuqence); 256 257 /** 258 * Returns the net charge of sequence at pH 7. The sequence argument must be 259 * a protein sequence consisting of only non-ambiguous characters. 260 * The net charge will be computed using the approach stated in 261 * <a href="http://www.innovagen.se/custom-peptide-synthesis/peptide-property-calculator/peptide-property-calculator-notes.asp#NetCharge>here</a> 262 * 263 * pKa values used will be either 264 * those used by Expasy which referenced "Electrophoresis 1994, 15, 529-539" 265 * OR 266 * A.Lehninger, Principles of Biochemistry, 4th Edition (2005), Chapter 3, page78, Table 3-1. 267 * 268 * @param sequence 269 * a protein sequence consisting of non-ambiguous characters only 270 * @param useExpasyValues 271 * whether to use Expasy values (Default) or Innovagen values 272 * @param pHPoint 273 * the pH value to use for computation of the net charge. Default at 7. 274 * @return the net charge of sequence at given pHPoint 275 * @see ProteinSequence 276 */ 277 public double getNetCharge(ProteinSequence sequence, boolean useExpasyValues, double pHPoint); 278 279 public double getNetCharge(ProteinSequence sequence, boolean useExpasyValues); 280 281 public double getNetCharge(ProteinSequence sequence); 282 283 /** 284 * Returns the composition of specified amino acid in the sequence. The 285 * sequence argument must be a protein sequence consisting of only 286 * non-ambiguous characters. The aminoAcidCode must be a non-ambiguous 287 * character. 288 * The composition of an amino acid is the total number of its occurrence, 289 * divided by the total length of the sequence. 290 * 291 * @param sequence 292 * a protein sequence consisting of non-ambiguous characters only 293 * @param aminoAcidCode 294 * the code of the amino acid to compute 295 * @return the composition of specified amino acid in the sequence 296 * @see ProteinSequence 297 * @see AminoAcidCompound 298 */ 299 public double getEnrichment(ProteinSequence sequence, AminoAcidCompound aminoAcidCode); 300 301 /** 302 * Returns the composition of the 20 standard amino acid in the sequence. 303 * The sequence argument must be a protein sequence consisting of only 304 * non-ambiguous characters. 305 * The composition of an amino acid is the total number of its occurrence, 306 * divided by the total length of the sequence. 307 * 308 * @param sequence 309 * a protein sequence consisting of non-ambiguous characters only 310 * @return the composition of the 20 standard amino acid in the sequence 311 * @see ProteinSequence 312 * @see AminoAcidCompound 313 */ 314 public Map<AminoAcidCompound, Double> getAAComposition(ProteinSequence sequence); 315}