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}