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 05.03.2004 021 * @author Andreas Prlic 022 * 023 */ 024package org.biojava.nbio.structure; 025 026import org.biojava.nbio.structure.io.mmcif.model.ChemComp; 027 028import java.io.Serializable; 029import java.util.Iterator; 030import java.util.List; 031import java.util.Map; 032 033/** 034 * 035 * This is the data structure for a single Group of atoms. A protein 036 * sequence ({@link Chain} in PDB file) is represented as a list of Groups. 037 * There are 3 types of Groups: 038 * 039 * <ul> 040 * <li>{@link AminoAcid}</li> 041 * <li>{@link HetatomImpl Hetatom}</li> 042 * <li>{@link NucleotideImpl Nucleotide}</li> 043 * </ul> 044 * 045 * 046 * @see HetatomImpl 047 * @see AminoAcidImpl 048 * @see NucleotideImpl 049 * @author Andreas Prlic 050 * @author Horvath Tamas 051 * @since 1.4 052 * @version %I% %G% 053 * 054 */ 055public interface Group extends Serializable { 056 057 /** Group property key for secondary structure annotation */ 058 public static final String SEC_STRUC = "secstruc"; 059 060 /** 061 * Get number of atoms. 062 * @return number of atoms of this Group 063 */ 064 public int size(); 065 066 /** 067 * Return true or false, depending if this group has 3D coordinates or not. 068 * 069 * @return true if Group has 3D coordinates 070 */ 071 public boolean has3D (); 072 073 /** 074 * Flag if group has 3D data . 075 * 076 * @param flag true to set flag that this Group has 3D coordinates 077 */ 078 public void setPDBFlag(boolean flag); 079 080 /** 081 * Get Type of group, one of {@link GroupType#AMINOACID}, {@link GroupType#HETATM} 082 * or {@link GroupType#NUCLEOTIDE} 083 * 084 * @return a String representing the type value 085 */ 086 public GroupType getType(); 087 088 /** 089 * Add an atom to this group. 090 * 091 * @param atom an Atom object 092 */ 093 public void addAtom(Atom atom); 094 095 /** 096 * Get list of atoms. 097 * 098 * @return a List object representing the atoms 099 * @see #setAtoms(List) 100 */ 101 public List<Atom> getAtoms() ; 102 103 104 /** 105 * Set the atoms of this group. 106 * @see {@link Atom} 107 * @param atoms a list of atoms 108 */ 109 public void setAtoms(List<Atom> atoms); 110 111 /** Remove all atoms from this group. 112 * 113 */ 114 public void clearAtoms(); 115 116 /** 117 * Get an atom given its PDB name. 118 * Beware that some PDB atom names are ambiguous (e.g. CA, which means C-alpha or Calcium), 119 * ambiguities should not occur within the same group though. To solve these ambiguities 120 * one would need to check the atom returned for the required element with {@link Atom#getElement()} 121 * 122 * @param name a trimmed String representing the atom's PDB name, e.g. "CA" 123 * @return an Atom object or null if no such atom exists within this group 124 */ 125 public Atom getAtom(String name) ; 126 127 128 /** 129 * Get at atom by position. 130 * 131 * @param position an int 132 * @return an Atom object or null if no Atom exists for given position 133 */ 134 public Atom getAtom(int position) ; 135 136 /** 137 * Tell whether a particular atom exists within this group. 138 * Beware that some PDB atom names are ambiguous (e.g. CA, which means C-alpha or Calcium), 139 * ambiguities should not occur within the same group though. 140 * 141 * @param name a trimmed String representing the atom's PDB name, e.g. "CA" 142 * @return true if Atom with name exists within this group 143 */ 144 public boolean hasAtom(String name); 145 146 /** 147 * Get the PDB 3-letter name for this group. (e.g. ALA) 148 * 149 * @return a String representing the PDBName value 150 * @see #setPDBName 151 */ 152 public String getPDBName(); 153 154 /** 155 * Set the PDB 3-letter name for this group. (e.g. ALA) 156 * 157 * @param s a String specifying the PDBName value 158 * @see #getPDBName 159 */ 160 public void setPDBName(String s) ; 161 162 163 /** 164 * Calculate if this group has all atoms required for an amino acid backbone. 165 * This allows to include chemically modified amino acids that 166 * are labeled hetatoms into some computations, the usual way 167 * to identify if a group is an amino acid is {@link #getType()} 168 * <p> 169 * amino atoms are : N, CA, C, O 170 * </p> 171 * 172 * Example: 1DW9 chain A first group is a Selenomethionine, provided as HETATM, but here returns true. 173 * <pre> 174 * HETATM 1 N MSE A 1 11.720 20.973 1.584 0.00 0.00 N 175 * HETATM 2 CA MSE A 1 10.381 20.548 1.139 0.00 0.00 C 176 * HETATM 3 C MSE A 1 9.637 20.037 2.398 0.00 0.00 C 177 * HETATM 4 O MSE A 1 10.198 19.156 2.985 0.00 0.00 O 178 * HETATM 5 CB MSE A 1 10.407 19.441 0.088 0.00 0.00 C 179 * </pre> 180 * 181 * @return true if all Atoms required for an AminoAcid are available (N, CA, C, O) 182 * @see #getType 183 */ 184 public boolean hasAminoAtoms() ; 185 186 187 /** 188 * Check if this group is a polymeric group, from the definition in Chemical Component Dictionary 189 * 190 * @return true if a polymeric group 191 */ 192 public boolean isPolymeric(); 193 194 195 /** 196 * Check if this group is an aminoacid group, from the definition in Chemical Component Dictionary 197 * 198 * @return true if an amino acid 199 */ 200 public boolean isAminoAcid(); 201 202 203 /** 204 * Check if this group is a nucleotide group, from the definition in Chemical Component Dictionary 205 * 206 * @return true if a nucleotide 207 */ 208 public boolean isNucleotide(); 209 210 211 212 /** 213 * Properties of this amino acid. Currently available properties are: 214 * phi 215 * psi 216 * secstruc 217 * 218 * @param properties a Map object specifying the properties value 219 * @see #getProperties 220 */ 221 public void setProperties(Map<String,Object> properties) ; 222 223 /** 224 * Return properties. 225 * @see #setProperties 226 * 227 * @return a HashMap object representing the properties value 228 */ 229 public Map<String,Object> getProperties() ; 230 231 /** 232 * Set a single property . 233 * 234 * @param key a String 235 * @param value an Object 236 * @see #getProperty 237 */ 238 public void setProperty(String key, Object value) ; 239 240 /** 241 * Get a single property . 242 * 243 * @param key a String 244 * @return an Object 245 * @see #setProperty 246 */ 247 public Object getProperty(String key) ; 248 249 /** 250 * Get an Atom Iterator. 251 * 252 * @return an Iterator object 253 */ 254 public Iterator<Atom> iterator() ; 255 256 257 /** 258 * Returns and identical copy of this Group object . 259 * @return and identical copy of this Group object 260 */ 261 public Object clone(); 262 263 /** 264 * Sets the back-reference to its parent Chain. 265 * @param chain the parent Chain 266 * @see #getChain() 267 * @since 3.0 268 */ 269 public void setChain(Chain chain); 270 271 /** 272 * Returns the parent Chain of the Group. 273 * 274 * @return Chain the Chain object that contains the Group 275 * @see #setChain(Chain) 276 * @since 3.0 277 */ 278 public Chain getChain() ; 279 280 /** 281 * Returns a dynamically created ResidueNumber for the group - this 282 * contains the chainId, resNum and insCode of the group. 283 * @see ResidueNumber 284 * @return ResidueNumber for the group. 285 * @since 3.0 286 */ 287 public ResidueNumber getResidueNumber(); 288 289 290 /** 291 * Sets the ResidueNumber for this Group 292 * 293 * @param residueNumber the PDB residueNumber 294 */ 295 public void setResidueNumber(ResidueNumber residueNumber); 296 297 /** 298 * Utility method to temporarily set a chainID for a group, if a parent chain object does not exist yet. 299 * Not recommended for general use other than parsing. 300 * 301 * @param chainId 302 * @param residueNumber 303 * @param iCode 304 */ 305 public void setResidueNumber(String chainId, Integer residueNumber, Character iCode); 306 307 /** 308 * Utility method for returning the chainId of the Group or null if no 309 * Chain has been set. This is equivalent to calling getChain().getId() 310 * 311 * Prior to version 5.0 this method returned the chain name. 312 * @since 3.0 313 * @return the ID of the chain 314 */ 315 public String getChainId(); 316 317 /** 318 * Set the Chemical Component that closer describes this group. 319 * 320 * @param cc the chemical component 321 */ 322 public void setChemComp(ChemComp cc); 323 324 /** 325 * Get the chemical component that closer describes this group. If the information does not exist yet, fetches the information from PDB web site. 326 * 327 * @return the Chemical Component definition for this Group. 328 */ 329 public ChemComp getChemComp(); 330 331 332 /** 333 * Check if this group has alternate location groups. 334 * 335 * @return boolean flag if there are alternate locations. 336 * @see #getAltLocs() 337 */ 338 public boolean hasAltLoc(); 339 340 341 /** 342 * Get the list of other alternate location groups. 343 * <p> 344 * The main group (this group) will contain the first altloc (be it the default '.' or 'A' or a mix of '.' and 'A'). 345 * <p> 346 * This method will return the altloc groups that are not the main group, e.g.: 347 * 348 * <li> if '.' (default), 'A' and 'B' altlocs are present in file, the main group will contain 349 * the default '.' and this method will return 2 altloc groups 350 * </li> 351 * 352 * <li> if 'A' and 'B' are present in file without a default '.' group, then the main group will contain the 'A' 353 * location whilst this method will return only 1 altloc group with the 'B' location 354 * </li> 355 * 356 * <p> 357 * Note that atoms with the default altloc (.) are included in all groups. Atoms with other altlocs (typically A, B, etc) 358 * will be sorted into groups by altloc. 359 * <p> 360 * Thus it can happen that an altloc group duplicate the contents of the main group. 361 * 362 * @return List of other groups that are on alternate locations 363 */ 364 public List<Group> getAltLocs(); 365 366 /** 367 * Add a group that is an alternate location for this group. 368 * 369 * @param g the altloc group to add 370 */ 371 public void addAltLoc(Group g); 372 373 /** 374 * Determines if this group is water. 375 * 376 * @see GroupType#WATERNAMES 377 * @return true if it's water, false otherwise. 378 */ 379 public boolean isWater(); 380 381 /** 382 * Gets the alternate location group to this group that has the alt-loc character code passed. 383 * 384 * @param altLoc the alternate location code of the group desired 385 * @return the alternate location group if found, or null otherwise 386 */ 387 public Group getAltLocGroup(Character altLoc); 388 389 390 /** 391 * Attempts to reduce the memory imprint of this group by trimming 392 * all internal Collection objects to the required size. 393 * 394 */ 395 public void trimToSize(); 396 397 /** 398 * Function to get the Group as an MDL molblock 399 * @return the string of the MDL molblock 400 */ 401 public String toSDF(); 402 403 /** 404 * Tells whether the group is annotated as HETATM in the file. 405 * To be used only at parsing time to be able to infer that a 406 * polymeric group is in a ligand chain or not. 407 * @return 408 */ 409 public boolean isHetAtomInFile(); 410 411 /** 412 * Sets the field isHetAtomInFile which is intented only for 413 * helping in infering if a polymeric group is in a ligand chain 414 * or in a polymeric chain. 415 * @param isHetAtomInFile 416 */ 417 public void setHetAtomInFile(boolean isHetAtomInFile); 418}