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}