Generated on Wed Apr 29 2015 11:51:40 for GGL-4.1.2 by doxygen 1.8.3.1
ChemRule.hh
Go to the documentation of this file.
1 #ifndef GGL_CHEM_CHEMRULE_HH_
2 #define GGL_CHEM_CHEMRULE_HH_
3 
4 #include "ggl/Rule.hh"
5 #include "ggl/chem/Molecule.hh"
6 #include "ggl/chem/MoleculeUtil.hh"
7 #include <map>
8 #include <iostream>
9 
10 namespace ggl {
11 namespace chem {
12 
13 ////////////////////////////////////////////////////////////////////////////////
14 
15  /*! @brief Consistency codes and constants
16  *
17  * A helper class that holds the standard ChemRule constants that are
18  * independent of any template parameter.
19  *
20  * @author Martin Mann (c) 2009 http://www.bioinf.uni-freiburg.de/~mmann/
21  */
22  class ChemRule_Constants : public Rule_ConCodes {
23  public:
24  //! consistency code : everything fine
25  using Rule_ConCodes::C_Consistent;
26  //! consistency code : no rule ID is present
27  using Rule_ConCodes::C_NoID;
28 
29  //! consistency code : at least one node is created or destroyed
30  static const size_t C_NodeInsertDeletion;
31  //! consistency code : at least for one bond too many edges are given
32  static const size_t C_EdgeMultiplicity;
33  //! consistency code : an atom label is not SMILES conform
34  static const size_t C_AtomLabelInvalid;
35  //! consistency code : a bond label is not SMILES conform
36  static const size_t C_BondLabelInvalid;
37  //! consistency code : the valence/electron change of an atom is not
38  //! balanced
39  static const size_t C_UnbalancedElectrons;
40  //! consistency code : at least one atom label is complex and contains
41  //! implicit H atoms, this is currently not supported
42  static const size_t C_AtomComplexWithH;
43  //! consistency code : at least one atom label is complex and contains
44  //! implicit H atoms, this is currently not supported
45  static const size_t C_BondLoop;
46 
47 
48  };
49 
50 
51 ////////////////////////////////////////////////////////////////////////////////
52 
53 
54  /*! @brief Chemical graph grammar rule
55  *
56  * A description of a graph grammar rule with left and righ rule side and
57  * context description. It describes a chemical reaction as well as its
58  * transition state etc.
59  *
60  * @author Martin Mann (c) 2009 http://www.bioinf.uni-freiburg.de/~mmann/
61  *
62  */
63  class ChemRule
64  : public ggl::Rule
65  , public ChemRule_Constants
66  {
67 
68  public:
69  ///////////////// PUBLIC ////////////////////////////////
70 
71  //! Access to the super class type
72  typedef ggl::Rule SuperClass;
73 
74  //! Access to the CoreGraph template argument.
75  typedef SuperClass::CoreGraph CoreGraph;
76  //! Access to the NODE_INDEX_PROPERTY template argument.
77  typedef SuperClass::NodeIndexProperty NodeIndexProperty;
78  //! Access to the NODE_RULE_CONTEXT_PROPERTY template argument.
79  typedef SuperClass::NodeContextProperty NodeContextProperty;
80  //! Access to the EDGE_RULE_CONTEXT_PROPERTY template argument.
81  typedef SuperClass::EdgeContextProperty EdgeContextProperty;
82  //! Access to the NODE_LABEL_PROPERTY template argument.
83  typedef SuperClass::NodeLabelProperty NodeLabelProperty;
84  //! Access to the NODE_RIGHT_LABEL_PROPERTY template argument.
85  typedef SuperClass::NodeRightLabelProperty NodeRightLabelProperty;
86  //! Access to the EDGE_LABEL_PROPERTY template argument.
87  typedef SuperClass::EdgeLabelProperty EdgeLabelProperty;
88  //! A container that stores the information of a context side of
89  //! a graph grammar rule like left, right, and context.
90  typedef SuperClass::RuleSide RuleSide;
91  //! Cut-and-paste operation definition
92  typedef SuperClass::RuleCnP RuleCnP;
93  //! Cut-and-paste operation container
94  typedef SuperClass::CopyAndPasteOperations CopyAndPasteOperations;
95 
96 
97  ///////////////// CONSISTENCY TYPEDEFS /////////////////////////
98 
99  //! consistency code : everything fine
100  using ChemRule_Constants::C_Consistent;
101  //! consistency code : at least one node is created or destroyed
102  using ChemRule_Constants::C_NodeInsertDeletion;
103  //! consistency code : at least for one bond too many edges are given
104  using ChemRule_Constants::C_EdgeMultiplicity;
105  //! consistency code : no rule/reaction ID is present
106  using ChemRule_Constants::C_NoID;
107  //! consistency code : an atom label is not SMILES conform
108  using ChemRule_Constants::C_AtomLabelInvalid;
109  //! consistency code : a bond label is not SMILES conform
110  using ChemRule_Constants::C_BondLabelInvalid;
111  //! consistency code : the valence/electron change of an atom is not
112  //! balanced
113  using ChemRule_Constants::C_UnbalancedElectrons;
114  //! consistency code : an atom forms a bond with itself
115  using ChemRule_Constants::C_BondLoop;
116 
117  ///////////////// CONSTRUCTION ////////////////////////////////
118 
119  /*! Construction of a rule based on the given boost graph based core
120  * description.
121  * @param core the boost graph that describes the graph grammar rule
122  * @param id the identifier or description of the graph grammar rule
123  */
124  ChemRule ( const CoreGraph & core
125  , const std::string& id = std::string("") );
126 
127  /*! Construction of a rule based on the given boost graph based core
128  * description.
129  * @param core the boost graph that describes the graph grammar rule
130  * @param id the identifier or description of the graph grammar rule
131  * @param constraints the additional constraints for the
132  * matching of the left side of the rule
133  * @param copyAndPaste the Cut-and-Paste operations to perform
134  */
135  ChemRule ( const CoreGraph & core
136  , const std::string& id
137  , const std::vector< sgm::Pattern_Interface::Match_Constraint* > & constraints
138  , const CopyAndPasteOperations & copyAndPaste );
139 
140  /*! Construction of a rule based on the given boost graph based core
141  * description.
142  * @param core the boost graph that describes the graph grammar rule
143  * @param id the identifier or description of the graph grammar rule
144  * @param constraints the additional constraints for the
145  * matching of the left side of the rule
146  */
147  ChemRule ( const CoreGraph & core
148  , const std::string& id
149  , const std::vector< sgm::Pattern_Interface::Match_Constraint* > & constraints );
150 
151  //! Copy construction.
152  //! @param toCopy the ChemRule to make this a copy of
153  ChemRule ( const ChemRule & toCopy );
154 
155  //! Construction from a normal graph grammar rule.
156  //! @param toCopy the ChemRule to make this a copy of
157  ChemRule ( const ggl::Rule & toCopy );
158 
159  //! Destruction
160  virtual
161  ~ChemRule();
162 
163  //! Assignment operator
164  //! @param toCopy the ChemRule to make this a copy of
165  //! @return *this
166  ChemRule &
167  operator =( const ChemRule & toCopy );
168 
169  /*! Checks whether or not this rule is a consistent one. If not, a
170  * combination of according error codes is given.
171  * @return the value is either C_Consistent, or a product of all other
172  * consistency error codes encountered
173  */
174  virtual
175  size_t
176  isConsistent( void ) const;
177 
178  /*!
179  * Writes a description of the consistency status or errors, encoded
180  * in a consistency code produced by isConsistent*(...), to a given
181  * outstream. The function returns whether or not an error occured.
182  *
183  * @param consistencyCode the error code to parse, produced by
184  * a call to isConsistent(...)
185  * @param errorStream the output stream to write the error decription
186  * to
187  * @param completeCheck if true: tries to decode the whole
188  * consistencyCode and reports an error message if this is
189  * not possible. if false: decodes and reports only the
190  * known error codes from consistencyCode
191  * @return true if no error is encoded; false otherwise
192  */
193  virtual
194  bool
195  decodeConsistencyStatus( const size_t consistencyCode
196  , std::ostream& errorStream
197  , const bool completeCheck = true ) ;
198 
199 
200  /*!
201  * Replaces all nodes with group labels with the according molecule
202  * component if present in groups. If the group label is unknown, the
203  * method returns false; true otherwise.
204  *
205  * NOTE: The node replacement is NOT recursive to avoid infinite
206  * replacement chains.
207  *
208  * @param core the rule core graph to alter
209  * @param groups the list of known groups to be inserted
210  *
211  * @return true if all group labels have been replaced; false
212  * otherwise
213  *
214  * @throw std::runtime_error if a group is
215  * to be insert for a non-context node
216  */
217  static
218  bool
219  insertGroups( CoreGraph & core
220  , const GroupMap & groups
221  ) throw(std::runtime_error);
222 
223 
224 
225  /*!
226  * Access to the chemical wildcard string to use for left side
227  * pattern matching
228  * @return the wildcard label MoleculeUtil::AtomLabelWildcard
229  */
230  virtual
231  const std::string*
232  getUsedWildcard(void) const;
233 
234 
235  /*!
236  * Overwrites and disables the wildcard setup. This function does
237  * NOT change the wildcard, since the wildcard is fixed to
238  * MoleculeUtil::AtomLabelWildcard for chemical rules. Thus, this
239  * method is a dummy overwrite.
240  * @param wildcardToUse ignored parameter
241  */
242  virtual
243  void
244  setUsedWildcard( const std::string* const wildcardToUse );
245 
246 
247 
248  public:
249  ///////////// TRANSITION STATE HANDLING ///////////////////////////
250 
251  /*! Encodes the minimal transition state of a chemical reaction
252  * that is encoded by a (chemical) graph grammar rule.
253  *
254  * Therein, valence changes (!=0) for each atom are identified and
255  * appended to the class information. All such values show a leading
256  * "000" to make them distinguishable from previously present class
257  * information (which will be the leading number in front of the "000"
258  * separator.
259  *
260  */
261  class TransitionState
262  {
263 
264  protected:
265 
266  /*! Default construction which is only accessible for subclasses
267  */
268  TransitionState();
269 
270  public:
271  ///////////////// PUBLIC ////////////////////////////////
272 
273  /*! Derives a transition state graph from a given graph grammar rule.
274  *
275  * @param rule the graph grammar rule that encodes the transition state
276  */
277  TransitionState( const ChemRule& rule );
278 
279  /*! Copy construction
280  *
281  * @param toCopy the object to make this a copy of
282  */
283  TransitionState( const TransitionState& toCopy );
284 
285  //! destruction
286  virtual
287  ~TransitionState();
288 
289 
290  ///////////////// ACCESS MEMBERS ////////////////////////////////
291 
292  /*! Allows access to the graph encoding of the transition state.
293  * @return the graph encoding of the transition state
294  */
295  const Molecule&
296  getGraph( void ) const;
297 
298  /*! Allows access to the SMILES encoding of the transition state.
299  * @return the SMILES encoding of the transition state
300  */
301  const std::string &
302  getSMILES( void ) const;
303 
304  protected:
305  ///////////////// PROTECTED ////////////////////////////////
306 
307  //! the graph encoding of the transition state
308  Molecule tState;
309 
310  //! SMILES representation of the transition state
311  mutable std::string tStateSMILES;
312 
313  protected:
314 
315  //! mapping of vertices to valence change internally used to sum over
316  //! edge valence increases
317  typedef std::map< CoreGraph::vertex_descriptor, size_t >
318  ValChangeMap;
319 
320  /*! Initializes the transition state graph from a given graph
321  * grammar rule.
322  *
323  * @param rule the graph grammar rule that encodes the transition state
324  */
325  void
326  initializeTransitionState( const CoreGraph& rule );
327 
328  /*! Updates a given ValChangeMap : the according entry is increased
329  * with the given valence change value.
330  *
331  * @param node the entry key to update
332  * @param valChange the value to add to the current value
333  * @param toUpdate the mapping to update within
334  */
335  static
336  void
337  updateMap( const CoreGraph::vertex_descriptor& node
338  , const size_t valChange
339  , ValChangeMap & toUpdate );
340 
341  /*! Copies a (modified) rule graph into a molecule object. Only the
342  * primary node and edge label is copied, all other rule information
343  * is ignored.
344  *
345  * @param rule the rule to copy from
346  * @param mol the molecule to fill / copy to (NOTE: is assumed to be
347  * a new/empty graph)
348  */
349  static
350  void
351  copyRuleToMol( const CoreGraph & rule
352  , Molecule & mol );
353 
354  };
355 
356 
357  /*! Access to the minimal transition state of the chemical reaction
358  * covered by this chemical graph grammar rule.
359  * @return the minimal transition state for this rule
360  */
361  const TransitionState&
362  getTransitionState() const;
363 
364 
365  protected:
366  ///////////////// PROTECTED ////////////////////////////////
367 
368  //! the boost graph that is encoding the graph grammar rule
369  using SuperClass::core;
370  //! the information describing the left side pattern of the Rule
371  using SuperClass::LeftSide;
372  //! the information describing the right side (result) of the Rule
373  using SuperClass::RightSide;
374  //! the information describing the invariant context of the Rule
375  using SuperClass::Context;
376  //! the encoding of the minimal transition state of this reaction
377  //! which is generated on demand (initially not calculated)
378  mutable TransitionState* transitionState;
379 
380  protected:
381 
382  /*! Adds no edge constraints for all edges that are right side context
383  * only, to avoid the appearance of parallel edges within molecule
384  * graphs.
385  *
386  * @param toUpdate the ChemRule instance to update
387  */
388  static
389  void
390  addImplicitNoEdgeConstraints( ChemRule & toUpdate );
391 
392  /*! Checks that no node in the graph is created or destroyed, i.e.
393  * if all nodes in the given rule core graph are part of the
394  * context or undergo a label change
395  *
396  * @param coreGraph the rule core graph to check
397  * @return true if no node is created/destroyed, false otherwise
398  */
399  static
400  bool
401  checkNodeInDel( const CoreGraph & coreGraph );
402 
403  /*! Checks that all bonds in the molecule graph are defined by the
404  * correct number of edges. That is either a single context, left, or
405  * right edge, or the combination of a left and right edge. Otherwise,
406  * no single bond between two atoms are defined by the rule.
407  *
408  * @param coreGraph the rule core graph to check
409  * @return true if all bond definitions are correct, false otherwise
410  */
411  static
412  bool
413  checkEdgeInDel( const CoreGraph & coreGraph );
414 
415  /*! Checks if the atom (node) labels are SMILES conform. This is
416  * checked for input and output of the rule (left/right side).
417  *
418  * @param coreGraph the rule core graph to check
419  * @return true if all atom/node label are ok, false otherwise
420  */
421  static
422  bool
423  checkAtomLabel( const CoreGraph & coreGraph );
424 
425  /*! Checks if any complex node label (in any context) contains
426  * implicit H atoms.
427  * This is currently not supported by the library.
428  *
429  * @param coreGraph the rule core graph to check
430  * @return true if all atom/node labels are ok, false otherwise
431  */
432  static
433  bool
434  checkAtomComplexWithH( const CoreGraph & coreGraph );
435 
436  /*! Checks if the bond (edge) labels are SMILES conform. This is
437  * checked for input and output of the rule (left/right side).
438  *
439  * @param coreGraph the rule core graph to check
440  * @return true if all bond/edge label are ok, false otherwise
441  */
442  static
443  bool
444  checkBondLabel( const CoreGraph & coreGraph );
445 
446  /*! Checks if an atom forms a bond with itself, i.e. a loop bond.
447  *
448  * @param coreGraph the rule core graph to check
449  * @return true iff all bond labels are ok; false otherwise
450  */
451  static
452  bool
453  checkBondLoop( const CoreGraph & coreGraph );
454 
455  /*! Checks for each atom, if the electron changes of the adjacent
456  * bonds and the atom label are balanced.
457  *
458  * NOTE: for aromatic atoms, the an unbalanced electron change of 1
459  * is tolerated due to the flexibility of the involved electrons
460  * within the aromatic ring.
461  *
462  * @param coreGraph the rule core graph to check
463  * @return true if all electron changes are ok, false otherwise
464  */
465  static
466  bool
467  checkElectronChange( const CoreGraph & coreGraph );
468 
469  };
470 
471 ////////////////////////////////////////////////////////////////////////////////
472 ////////////////////////////////////////////////////////////////////////////////
473 
474  } // namespace chem
475 } // namespace ggl
476 
477 
478 
479 // implementation
480 #include "ggl/chem/ChemRule.icc"
481 
482 #endif /*GGL_RULE_HH_*/