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