1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<title>Working with Generic Data</title>
<link href="/site.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="search/search.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!--#include file="header.html" -->
<!-- Generated by Doxygen 1.7.5.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.shtml"><span>Main Page</span></a></li>
<li class="current"><a href="pages.shtml"><span>Related Pages</span></a></li>
<li><a href="modules.shtml"><span>Modules</span></a></li>
<li><a href="namespaces.shtml"><span>Namespaces</span></a></li>
<li><a href="annotated.shtml"><span>Classes</span></a></li>
<li><a href="files.shtml"><span>Files</span></a></li>
<li><a href="examples.shtml"><span>Examples</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Working with Generic Data </div> </div>
</div>
<div class="contents">
<div class="textblock"><dl class="since"><dt><b>Since:</b></dt><dd>2.3</dd></dl>
<h2><a class="anchor" id="generic_data_intro"></a>
Introduction</h2>
<p>Generic data is a concept used in <a class="el" href="namespaceOpenBabel.shtml" title="Global namespace for all Open Babel code.">OpenBabel</a> to store additional information in objects. The objects are usually molecules, atoms or bonds (<a class="el" href="classOpenBabel_1_1OBMol.shtml" title="Molecule Class.">OBMol</a>, <a class="el" href="classOpenBabel_1_1OBAtom.shtml" title="Atom class.">OBAtom</a> and <a class="el" href="classOpenBabel_1_1OBBond.shtml" title="Bond class.">OBBond</a>). The data can literally be anything since <a class="el" href="classOpenBabel_1_1OBPairTemplate.shtml" title="Used to store arbitrary attribute/value relationsips of any type.">OBPairTemplate</a> allows any datatype (classes have to be copyable though) to be stored. For example, a file format contains some strings or numbers (e.g. QM energy, biological activity, chemical supplier & price, ...) for each molecule and these can be stored in the <a class="el" href="classOpenBabel_1_1OBMol.shtml" title="Molecule Class.">OBMol</a> object. When the file format is used to read a file, the program can access and use this data. A concrete example is the PDB file format which specifies a large number of protein specific data types. All data which cannot be stored using the API is stored as strings in the <a class="el" href="classOpenBabel_1_1OBMol.shtml" title="Molecule Class.">OBMol</a> object. The program (e.g. a 3D molecular viewer) can retrieve the data (e.g. secondary structure) and use it. It would not be possible to add API methods for all this.</p>
<h2><a class="anchor" id="generic_data_design"></a>
Design</h2>
<p>There are two abstract classes defining the interfaces. The <a class="el" href="classOpenBabel_1_1OBGenericData.shtml" title="Base class for generic data.">OBGenericData</a> interface makes it possible to work with derived classes without knowing anything about the data itself. It contains methods (<a class="el" href="classOpenBabel_1_1OBGenericData.shtml#aae3d15983201a2a115701b2c538fef77">OBGenericData::SetAttribute</a> and <a class="el" href="classOpenBabel_1_1OBGenericData.shtml#ac72c28db8b5bb8911845ada56220a1e0">OBGenericData::GetAttribute</a>) for associating the data with a name. To use std::map<std::string, T> analogy, the attribute is the key for the data T. GetValue always returns a std::string and derived classes should convert their data to a string when possible. Returning an empty string is acceptable though. The second <a class="el" href="classOpenBabel_1_1OBBase.shtml" title="Base Class.">OBBase</a> class defines an interface to store/retrieve/remove <a class="el" href="classOpenBabel_1_1OBGenericData.shtml" title="Base class for generic data.">OBGenericData</a> objects by attribute, type or source. To use std::map analogy again, classes derived from <a class="el" href="classOpenBabel_1_1OBBase.shtml" title="Base Class.">OBBase</a> are the map.</p>
<h2><a class="anchor" id="generic_data_str_num"></a>
Storing strings and numbers</h2>
<p>In many cases storing strings and numbers is all you need. Strings can be stored using the <a class="el" href="classOpenBabel_1_1OBPairData.shtml" title="Used to store arbitrary text attribute/value relationships.">OBPairData</a> class. For numbers there is OBPairInteger and OBPairFloatingPoint. Although the interface is almost the same for these classes multiple examples are given to make it easier to copy/paste.</p>
<p>Storing and retrieving a string: </p>
<div class="fragment"><pre class="fragment"> <span class="comment">// storing a string</span>
OBPairData *supplier = <span class="keyword">new</span> OBPairData;
supplier->SetAttribute(<span class="stringliteral">"supplier"</span>); <span class="comment">// the name or key for the data</span>
supplier->SetValue(<span class="stringliteral">"some supplier name/id"</span>); <span class="comment">// reading from a file for example</span>
mol.SetData(supplier);
<span class="comment">// retrieve the string by attribute</span>
<span class="keywordflow">if</span> (mol.HasData(<span class="stringliteral">"supplier"</span>)) {
OBPairData *supplier = <span class="keyword">dynamic_cast<</span>OBPairData*<span class="keyword">></span>(mol.GetData(<span class="stringliteral">"supplier"</span>));
cout << <span class="stringliteral">"supplier: "</span> << supplier->GetValue() << endl;
}
</pre></div><p> Storing and retrieving an integer: </p>
<div class="fragment"><pre class="fragment"> <span class="comment">// storing an integer</span>
<a class="code" href="namespaceOpenBabel.shtml#a0bdf8334aad62a6bb7ad50f58060c9b6" title="Store arbitrary key/value integer data like OBPairData.">OBPairInteger</a> *data = <span class="keyword">new</span> <a class="code" href="namespaceOpenBabel.shtml#a0bdf8334aad62a6bb7ad50f58060c9b6" title="Store arbitrary key/value integer data like OBPairData.">OBPairInteger</a>;
data->SetAttribute(<span class="stringliteral">"numAromRings"</span>); <span class="comment">// the name or key for the data</span>
data->SetValue(numAromRings); <span class="comment">// computed before</span>
mol.SetData(data);
<span class="comment">// retrieve the integer by attribute</span>
<span class="keywordflow">if</span> (mol.HasData(<span class="stringliteral">"numAromRings"</span>)) {
<a class="code" href="namespaceOpenBabel.shtml#a0bdf8334aad62a6bb7ad50f58060c9b6" title="Store arbitrary key/value integer data like OBPairData.">OBPairInteger</a> *data = <span class="keyword">dynamic_cast<</span><a class="code" href="namespaceOpenBabel.shtml#a0bdf8334aad62a6bb7ad50f58060c9b6" title="Store arbitrary key/value integer data like OBPairData.">OBPairInteger</a>*<span class="keyword">></span>(mol.GetData(<span class="stringliteral">"numAromRings"</span>));
cout << <span class="stringliteral">"number of aromatic rings: "</span> << data->GetGenericValue() << endl;
}
</pre></div><p>There is a small difference between strings and numbers. The main reason is that GetValue always returns a string. OBPairInteger and OBPairFloatingPoint are actually typedefs for <a class="el" href="classOpenBabel_1_1OBPairTemplate.shtml" title="Used to store arbitrary attribute/value relationsips of any type.">OBPairTemplate</a> which defines the appropriate GetGenericValue method to return the numeric data type.</p>
<p>Storing and retrieving a floating point value: </p>
<div class="fragment"><pre class="fragment"> <span class="comment">// storing an integer</span>
<a class="code" href="namespaceOpenBabel.shtml#a5ba6d4475315df1100427dc98074c087" title="Store arbitrary key/value floating point data like OBPairData.">OBPairFloatingPoint</a> *data = <span class="keyword">new</span> <a class="code" href="namespaceOpenBabel.shtml#a5ba6d4475315df1100427dc98074c087" title="Store arbitrary key/value floating point data like OBPairData.">OBPairFloatingPoint</a>;
data->SetAttribute(<span class="stringliteral">"activity"</span>); <span class="comment">// the name or key for the data</span>
data->SetValue(8.3); <span class="comment">// computed before</span>
mol.SetData(data);
<span class="comment">// retrieve the integer by attribute</span>
<span class="keywordflow">if</span> (mol.HasData(<span class="stringliteral">"activity"</span>)) {
<a class="code" href="namespaceOpenBabel.shtml#a5ba6d4475315df1100427dc98074c087" title="Store arbitrary key/value floating point data like OBPairData.">OBPairFloatingPoint</a> *data = <span class="keyword">dynamic_cast<</span><a class="code" href="namespaceOpenBabel.shtml#a5ba6d4475315df1100427dc98074c087" title="Store arbitrary key/value floating point data like OBPairData.">OBPairFloatingPoint</a>*<span class="keyword">></span>(mol.GetData(<span class="stringliteral">"activity"</span>));
cout << <span class="stringliteral">"biological activity: "</span> << data->GetGenericValue() << endl;
}
</pre></div><h2><a class="anchor" id="generic_data_template"></a>
Truly generic data using OBPairTemplate</h2>
<p>Although there are a number of classes for specific data types, using <a class="el" href="classOpenBabel_1_1OBPairTemplate.shtml" title="Used to store arbitrary attribute/value relationsips of any type.">OBPairTemplate</a> the same can be accomplished with less code. The second example illustrates this but a simpler example is given first.</p>
<p>Storing a list of suppliers in an <a class="el" href="classOpenBabel_1_1OBMol.shtml" title="Molecule Class.">OBMol</a> object: </p>
<div class="fragment"><pre class="fragment"> <span class="keyword">typedef</span> OBPairTemplate< std::vector<std::string> > SupplierData;
<span class="comment">// storing the supplier list</span>
SupplierData *data = <span class="keyword">new</span> SupplierData;
data->SetAttribute(<span class="stringliteral">"suppliers"</span>);
data->SetValue(suppliers);
mol.SetData(data);
<span class="comment">// retrieve the supplier list</span>
<span class="keywordflow">if</span> (mol.HasData(<span class="stringliteral">"suppliers"</span>)) {
SupplierData *data = <span class="keyword">dynamic_cast<</span>SupplierData*<span class="keyword">></span>(mol.GetData(<span class="stringliteral">"suppliers"</span>));
std::vector<std::string> &suppliers = data->GetGenericData();
<span class="keywordflow">for</span> (<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i = 0; i < suppliers.size(); ++i)
cout << suppliers[i] << endl;
}
</pre></div><p>Storing complex data in an <a class="el" href="classOpenBabel_1_1OBMol.shtml" title="Molecule Class.">OBMol</a> object: </p>
<div class="fragment"><pre class="fragment"> <span class="comment">// data representation struct</span>
<span class="keyword">struct </span>MyDataRepr {
<span class="keywordtype">double</span> value, error;
<span class="keywordtype">string</span> unit;
};
<span class="keyword">typedef</span> OBPairTemplate< MyDataRepr > MyData;
<span class="comment">// storing the supplier list</span>
MyData *data = <span class="keyword">new</span> MyData;
data->SetAttribute(<span class="stringliteral">"mydata"</span>);
MyDataRepr repr;
repr.value = 5.3;
repr.error = 0.3;
repr.unit = <span class="stringliteral">"kJ/mol"</span>;
data->SetValue(repr);
mol.SetData(data);
<span class="comment">// retrieve the supplier list</span>
<span class="keywordflow">if</span> (mol.HasData(<span class="stringliteral">"mydata"</span>)) {
MyData *data = <span class="keyword">dynamic_cast<</span>MyData*<span class="keyword">></span>(mol.GetData(<span class="stringliteral">"mydata"</span>));
MyDataRepr &repr = data->GetGenericData();
cout << repr.value << <span class="stringliteral">" +/- "</span> << repr.error << <span class="stringliteral">" "</span> << repr.unit << endl;
}
</pre></div><h2><a class="anchor" id="generic_data_specific"></a>
Specific data types</h2>
<p>A number of specific <a class="el" href="classOpenBabel_1_1OBGenericData.shtml" title="Base class for generic data.">OBGenericData</a> subclasses are provided for frequently used data types: <a class="el" href="classOpenBabel_1_1AliasData.shtml" title="Indicate atoms as aliases for larger functional groups.">AliasData</a>, <a class="el" href="classOpenBabel_1_1OBAngleData.shtml" title="Used to hold all angles in a molecule as generic data for OBMol.">OBAngleData</a>, <a class="el" href="classOpenBabel_1_1OBAtomClassData.shtml" title="Handle atom classes in reaction SMILES/SMIRKS.">OBAtomClassData</a>, <a class="el" href="classOpenBabel_1_1OBChiralData.shtml" title="Used to hold chiral inforamtion about the atom as OBGenericData.">OBChiralData</a>, <a class="el" href="classOpenBabel_1_1OBCommentData.shtml" title="Used to store a comment string (can be multiple lines long)">OBCommentData</a>, <a class="el" href="classOpenBabel_1_1OBConformerData.shtml" title="Used to hold data on conformers or geometry optimization steps.">OBConformerData</a>, <a class="el" href="classOpenBabel_1_1OBDOSData.shtml" title="Used to hold density of states information.">OBDOSData</a>, <a class="el" href="classOpenBabel_1_1OBElectronicTransitionData.shtml" title="Used to hold information about electronic transitions.">OBElectronicTransitionData</a>, <a class="el" href="classOpenBabel_1_1OBExternalBondData.shtml" title="Used to store information on external bonds (e.g., in SMILES fragments)">OBExternalBondData</a>, <a class="el" href="classOpenBabel_1_1OBGridData.shtml" title="Store values for numeric grids such as orbitals or electrostatic potential.">OBGridData</a>, <a class="el" href="classOpenBabel_1_1OBMatrixData.shtml" title="Used to hold a 3x3 matrix item (e.g., a quadrupole moment)">OBMatrixData</a>, <a class="el" href="classOpenBabel_1_1OBNasaThermoData.shtml" title="Thermodynamic data in old style NASA polynomial form for OBMol.">OBNasaThermoData</a>, OBOrbitalEnergyData, <a class="el" href="classOpenBabel_1_1OBPairData.shtml" title="Used to store arbitrary text attribute/value relationships.">OBPairData</a>, <a class="el" href="classOpenBabel_1_1OBRateData.shtml" title="Holds rate constant data for OBReaction.">OBRateData</a>, <a class="el" href="classOpenBabel_1_1OBRingData.shtml" title="Used to store the SSSR set (filled in by OBMol::GetSSSR())">OBRingData</a>, <a class="el" href="classOpenBabel_1_1OBRotamerList.shtml" title="Supports a set of rotamer coordinate sets for some number of potentially rotatable bonds...">OBRotamerList</a>, <a class="el" href="classOpenBabel_1_1OBRotationData.shtml" title="Used to hold the rotational constants and symmetry numbers.">OBRotationData</a>, <a class="el" href="classOpenBabel_1_1OBSerialNums.shtml" title="Defines a map between serial numbers (e.g., in a PDB file) and OBAtom objects inside a molecule...">OBSerialNums</a>, <a class="el" href="classOpenBabel_1_1OBSetData.shtml" title="Used to store arbitrary attribute/set relationships. Should be used to store a set of OBGenericData b...">OBSetData</a>, <a class="el" href="classOpenBabel_1_1OBStereoBase.shtml" title="Base class for all stereochemistry classes.">OBStereoBase</a>, <a class="el" href="classOpenBabel_1_1OBSymmetryData.shtml" title="Used to hold the point-group and/or space-group symmetry.">OBSymmetryData</a>, <a class="el" href="classOpenBabel_1_1OBTorsionData.shtml" title="Used to hold torsions as generic data for OBMol.">OBTorsionData</a>, <a class="el" href="classOpenBabel_1_1OBUnitCell.shtml" title="Used for storing information about periodic boundary conditions with conversion to/from translation v...">OBUnitCell</a>, <a class="el" href="classOpenBabel_1_1OBVectorData.shtml" title="Used to hold a 3D vector item (e.g., a dipole moment)">OBVectorData</a>, <a class="el" href="classOpenBabel_1_1OBVibrationData.shtml" title="Used to hold the normal modes of a molecule, etc.">OBVibrationData</a>, <a class="el" href="classOpenBabel_1_1OBVirtualBond.shtml" title="Used to temporarily store bonds that reference an atom that has not yet been added to a molecule...">OBVirtualBond</a>. Consult the documentation for these classes for more information.</p>
<h2><a class="anchor" id="generic_data_formats"></a>
Generic data & file formats</h2>
<p>Various file formats read and write generic data. This section contains an overview of the data used by file formats. When adding or extending a file format it is highly recommended to update this section.</p>
<h3><a class="anchor" id="generic_data_specific_by_data"></a>
Read data ordered by data type</h3>
<p>This section only contains information on data types used in a similar way by at least two file formats.</p>
<p><a class="el" href="classOpenBabel_1_1OBUnitCell.shtml" title="Used for storing information about periodic boundary conditions with conversion to/from translation v...">OBUnitCell</a>: </p>
<ul>
<li><b>cacaoformat:</b> *.caccrt </li>
<li><b>carformat:</b> *.car *.arc</li>
</ul>
<h3><a class="anchor" id="generic_data_specific_by_format"></a>
Read data ordered by format</h3>
<p><b>adfformat:</b> *.adfout </p>
<ul>
<li>Attribute: "Dipole Moment", Type: <a class="el" href="classOpenBabel_1_1OBVectorData.shtml" title="Used to hold a 3D vector item (e.g., a dipole moment)">OBVectorData</a>, Value: dipile moment vector </li>
<li>Attribute: "PartialCharges", Type: <a class="el" href="classOpenBabel_1_1OBPairData.shtml" title="Used to store arbitrary text attribute/value relationships.">OBPairData</a>, Value: "Mulliken" </li>
<li>Attribute: "GridData", Type: <a class="el" href="classOpenBabel_1_1OBGridData.shtml" title="Store values for numeric grids such as orbitals or electrostatic potential.">OBGridData</a>, Value: ??, Multiple</li>
</ul>
<p><b>cacaoformat:</b> *.caccrt </p>
<ul>
<li>Attribute: "", Type: <a class="el" href="classOpenBabel_1_1OBUnitCell.shtml" title="Used for storing information about periodic boundary conditions with conversion to/from translation v...">OBUnitCell</a>, Value: the unit cell data</li>
</ul>
<p><b>carformat:</b> *.car *.arc </p>
<ul>
<li>Attribute: "", Type: <a class="el" href="classOpenBabel_1_1OBUnitCell.shtml" title="Used for storing information about periodic boundary conditions with conversion to/from translation v...">OBUnitCell</a>, Value: the unit cell data</li>
</ul>
<p><b>chemkinformat:</b> *.ck </p>
<ul>
<li>Attribute: "Rate data", Type: <a class="el" href="classOpenBabel_1_1OBRateData.shtml" title="Holds rate constant data for OBReaction.">OBRateData</a>, Value: the reaction rate data </li>
</ul>
</div></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- end content -->
<!--#include file="footer.html" -->
<div id="footer">
<hr size="1">
<img src="http://openbabel.org/babel256.png" width="136" height="127" alt="" style="float: left;" />
<p>This file is part of the documentation for <a href="http://openbabel.org/wiki/">Open Babel</a>, version 2.3.</p>
<div class="bottom">
Documentation copyright © 1998-2007, the <a href="http://openbabel.org/wiki/THANKS">Open Babel Developers</a>.<br>
Open Babel is hosted by: <a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=40728"
width="88" height="31" border="0" alt="SourceForge Logo"></a><br>
Generated on Thu Oct 13 2011 16:08:08 by <a href="http://www.doxygen.org/"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.7.5.1.
</div>
</body>
</html>
|
