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