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