Difference between revisions of "Python"

From Open Babel
Jump to: navigation, search
(Info on using double_array())
m
 
(41 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Accessing Open Babel with Python =
+
This page provides links to all the information you need to use OpenBabel from the Python programming language.
  
There are two ways to access the Open Babel library using Python:
+
* '''[http://openbabel.org/docs/current/UseTheLibrary/Python.html Documentation]''' on using Open Babel from Python, including:
# The <code>[[#The openbabel module|openbabel]]</code> module, a direct binding of the Open Babel C++ library, created using the SWIG package.
+
** '''[http://openbabel.org/docs/current/UseTheLibrary/PythonInstall.html Installation]'''
# <code>[[#Pybel|Pybel]]</code>, a set of convenience functions and classes that simplifies access to the <code>openbabel</code> module. (Only available with OpenBabel >= 2.0.3)
+
** Using the '''[http://openbabel.org/docs/current/UseTheLibrary/PythonDoc.html openbabel module]'''
 +
** Using '''[http://openbabel.org/docs/current/UseTheLibrary/Python_Pybel.html Pybel]''' and its '''[http://openbabel.org/docs/current/UseTheLibrary/Python_PybelAPI.html API]'''
 +
** '''[http://openbabel.org/docs/current/UseTheLibrary/PythonExamples.html Examples]''' of use
  
For more examples of using Open Babel from Python, see the [[Developer:Python_Tutorial| developer Python tutorial]].
+
* If you have any problems or questions, '''[mailto:[email protected] send an email]''' to [email protected]
 +
* Read the '''[http://dx.doi.org/10.1186/1752-153X-2-5 Pybel paper]''' for background and examples of use. Don't forget to '''cite the Pybel paper''' if you use Pybel to obtain results for publication:
 +
: N. M. O'Boyle, C. Morley and G. R. Hutchison. [http://dx.doi.org/10.1186/1752-153X-2-5 Pybel: a Python wrapper for the OpenBabel cheminformatics toolkit] ''Chem. Cent. J.'' '''2008''', ''2'', 5.
  
== The openbabel module ==
+
If you find Pybel useful, you may also be interested in '''[http://cinfony.googlecode.com Cinfony]''' which allows you to access several cheminformatics toolkits using the same Python API as Pybel, from both regular Python and Jython.
 
+
The <code>openbabel</code> module provides direct access to the C++ Open Babel library from Python. This binding is generated using the SWIG package and provides access to almost all of the Open Babel interfaces via Python, including the base classes OBMol, OBAtom, OBBond, and OBResidue, as well as the conversion framework OBConversion. As such, essentially any call in the C++ API is available to Python scripts with very little difference in syntax.
+
 
+
This guide is designed to give examples of common Python syntax for the <code>openbabel</code> module and pointers to the appropriate sections of the API documentation.
+
 
+
The example script below creates atoms and bonds one-by-one using the OBMol, OBAtom, and OBBond classes.
+
 
+
<pre>
+
import openbabel
+
 
+
mol = openbabel.OBMol()
+
print 'Should print 0 (atoms)'
+
print mol.NumAtoms()
+
 
+
a = mol.NewAtom()
+
a.SetAtomicNum(6)  # carbon atom
+
a.SetVector(0.0, 1.0, 2.0) # coordinates
+
 
+
b = mol.NewAtom()
+
mol.AddBond(1, 2, 1)  # atoms indexed from 1
+
print 'Should print 2 (atoms)'
+
print mol.NumAtoms()
+
print 'Should print 1 (bond)'
+
print mol.NumBonds()
+
 
+
mol.Clear();
+
</pre>
+
 
+
More commonly, Open Babel can be used to read in molecules using the OBConversion framework. The following script reads in molecular information (a SMI file) from a string, adds hydrogens, and writes out an MDL file as a string.
+
 
+
<pre>
+
import openbabel
+
 
+
obConversion = openbabel.OBConversion()
+
obConversion.SetInAndOutFormats("smi", "mdl")
+
+
mol = openbabel.OBMol()
+
obConversion.ReadString(mol, "C1=CC=CS1")
+
 
+
print 'Should print 5 (atoms)'
+
print mol.NumAtoms()
+
 
+
mol.AddHydrogens()
+
print 'Should print 9 (atoms) after adding hydrogens'
+
print mol.NumAtoms()
+
 
+
outMDL = obConversion.WriteString(mol)
+
</pre>
+
 
+
The following script writes out a file using a filename, rather than reading and writing to a Python string.
+
 
+
<pre>
+
import openbabel
+
 
+
obConversion = openbabel.OBConversion()
+
obConversion.SetInAndOutFormats("pdb", "mol2")
+
 
+
mol = openbabel.OBMol()
+
obConversion.ReadFile(mol, "1ABC.pdb.gz")  # Open Babel will uncompress automatically
+
 
+
mol.AddHydrogens()
+
 
+
print mol.NumAtoms()
+
print mol.NumBonds()
+
print mol.NumResidues()
+
 
+
obConversion.WriteFile(mol, '1abc.mol2')
+
</pre>
+
 
+
That's it! There's more information on particular calls in the [http://openbabel.sourceforge.net/api/ library API]. Feel free to address questions to the [mailto:[email protected] openbabel-scripting] mailing list.
+
 
+
==== Calling a method requiring an array of C doubles ====
+
 
+
Some Open Babel toolkit methods, for example OBMol::Rotate(), require an array of doubles. It's not possible to directly use a list of floats when calling such a function from Python. Instead, you need to first explicitly create a C array using the ''double_array()'' function (not available in OB < 2.0.3):
+
<pre>
+
obMol.Rotate([1.0, -54.7, 3])
+
# Error!
+
myarray = openbabel.double_array([1.0, -54.7, 3])
+
obMol.Rotate(myarray)
+
# Works!
+
</pre>
+
 
+
== Pybel ==
+
 
+
Pybel provides convenience functions and classes that make it simpler to use the Open Babel libraries from Python, especially for file input/output and for accessing the attributes of atoms and molecules. The Atom and Molecule classes used by Pybel can be converted to and from the OBAtom and OBMol used by the <code>openbabel</code> module. These features are discussed in more detail below.
+
 
+
Information on the Pybel API can be found at the interactive Python prompt using the <code>help()</code> function, and is also available here: [http://openbabel.sourceforge.net/pybel.html Pybel API].
+
 
+
To use Pybel, use "<code>import pybel</code>" or "<code>from pybel import *</code>".
+
 
+
=== Atoms and Molecules ===
+
 
+
A [http://openbabel.sourceforge.net/pybel.html#Molecule Molecule] can be created in any of four ways:
+
# From an OBMol, using <code>Molecule(myOBMol)</code>
+
# By reading from a file (see [[#Input/Output | Input/Output]] below)
+
# By reading from a string (see [[#Input/Output | Input/Output]] below)
+
# An empty Molecule can be created using <code>Molecule()</code>
+
 
+
An [http://openbabel.sourceforge.net/pybel.html#Atom Atom] can be created in three different ways:
+
# From an OBAtom, using <code>Atom(myOBAtom)</code>
+
# By accessing the <code>.atoms</code> attribute of a Molecule
+
# An empty Atom can be created using <code>Atom()</code>
+
 
+
It is always possible to access the OBMol or OBAtom on which a Molecule or Atom is based, by accessing the appropriate attribute, either <code>.OBMol</code> or <code>.OBAtom</code>. In this way, it is easy to combine the convenience of <code>pyopenbabel</code> with the many additional capabilities present in <code>openbabel</code>. See [[#Combining Pybel with openbabel.py | Combining Pybel with openbabel.py]] below.
+
 
+
Molecules have the following attributes: atoms, charge, dim, energy, exactmass, flags, formula, mod, molwt, spin, sssr, title. The <code>.atoms</code> attribute provides a list of the Atoms in a Molecule. The remaining attributes correspond directly to attributes of OBMols: e.g. <code>Molecule.formula</code> is equivalent to <code>OBMol.GetFormula()</code>. For more information on what these attributes are, please see the Open Babel Library documentation for OBMol.
+
 
+
Molecules have a <code>[http://openbabel.sourceforge.net/pybel.html#Molecule-write .write()]</code> method that writes a representation of a Molecule to a file or to a string. See [[#Input/Output | Input/Output]] below.
+
 
+
For convenience, a Molecule provides an iterator over its Atoms. This is used as follows:
+
<pre>
+
for atom in myMolecule:
+
  # do something with atom
+
</pre>
+
 
+
Atoms have the following attributes: atomicmass, atomicnum, cidx, coords, coordidx, exactmass, formatcharge, heavyvalence, heterovalence, hyb, idx, implicitvalence, index, isotope, partialcharge, spin, type, valence, vector. The <code>.coords</code> attribute provides a tuple (x, y, z) of the atom's coordinates. The remaining attributes are as for OBAtom, and more information can be found in the Open Babel Library documentation.
+
 
+
=== Input/Output ===
+
 
+
Pybel greatly simplifies the process of reading and writing molecules to and from strings or files. There are two functions for reading Molecules:
+
# <code>[http://openbabel.sourceforge.net/pybel.html#-readstring readstring(format, string)]</code> reads a Molecule from a string
+
# <code>[http://openbabel.sourceforge.net/pybel.html#-readfile readfile(format, filename)]</code> provides an iterator over the Molecules in a file
+
 
+
Here are some examples of their use. Note in particular the use of <code>.next()</code> to access the first (and possibly only) molecule in a file:
+
<pre>
+
>>> mymol = readstring("smi", "CCCC")
+
>>> print mymol.molwt()
+
45
+
>>> for mymol in readfile("sdf", "largeSDfile.sdf")
+
... print mymol.molwt()
+
>>> singlemol = readfile("pdb", "1CRN.pdb").next()
+
</pre>
+
 
+
If a single molecule is to be written to a molecule or string, the <code>[http://openbabel.sourceforge.net/pybel.html#Molecule-write .write()]</code> method of the Molecule should be used:
+
# <code>mymol.write(format)</code> returns a string
+
# <code>mymol.write(format, filename)</code> writes the Molecule to a file. An optional additional parameter, <code>overwrite</code>, should be set to <code>True</code> if you wish to overwrite an existing file.
+
 
+
For files containing multiple molecules, the [http://openbabel.sourceforge.net/pybel.html#Outputfile Outputfile] class should be used instead. This is initialised with a format and filename (and optional <code>overwrite</code> parameter). To write a Molecule to the file, the <code>[http://openbabel.sourceforge.net/pybel.html#Outputfile-write .write()]</code> method of the Outputfile is called with the Molecule as a parameter. When all molecules have been written, the <code>[http://openbabel.sourceforge.net/pybel.html#Outputfile-close .close()]</code> method of the Outputfile should be called.
+
 
+
Here are some examples of output using the Pybel methods and classes:
+
<pre>
+
>>> print mymol.write("smi")
+
'CCCC'
+
>>> mymol.write("smi", "outputfile.txt")
+
>>> largeSDfile = Outputfile("sdf", "multipleSD.sdf")
+
>>> largeSDfile.write(mymol)
+
>>> largeSDfile.write(myothermol)
+
>>> largeSDfile.close()
+
</pre>
+
 
+
=== SMARTS matching ===
+
 
+
Pybel also provides a simplified API to the Open Babel SMARTS pattern matcher. A [http://openbabel.sourceforge.net/pybel.html#Smarts Smarts] object is created, and the <code>[http://openbabel.sourceforge.net/pybel.html#Smarts-findall .findall()]</code> method is then used to return a list of the matches to a given Molecule.
+
 
+
Here is an example of its use:
+
<pre>
+
>>> mol = readstring("smi","CCN(CC)CC") # triethylamine
+
>>> smarts = Smarts("[#6][#6]") # Matches an ethyl group
+
>>> print smarts.findall(mol)
+
[(1, 2), (4, 5), (6, 7)]
+
</pre>
+
 
+
=== Combining Pybel with openbabel.py ===
+
 
+
It is easy to combine the ease of use of Pybel, with the comprehensive coverage of the Open Babel toolkit that <code>openbabel.py</code> provides. Pybel is really a wrapper around <code>openbabel.py</code>, with the result that the OBAtom and OBMol used by openbabel.py can be interconverted to the Atom and Molecule used by Pybel.
+
 
+
The following example shows how to read a molecule from a PDB file using Pybel, and then how to use openbabel.py to add hydrogens. It also illustrates how to find out information on what methods and classes are available, while at the interactive Python prompt.
+
<pre>
+
>>> import pybel
+
>>> mol = pybel.readfile("pdb", "1PYB").next()
+
>>> help(mol)
+
Help on Molecule in module pybel object:
+
...
+
|  Attributes:
+
|    atoms, charge, dim, energy, exactmass, flags, formula,
+
|    mod, molwt, spin, sssr, title.
+
...
+
|  The original Open Babel molecule can be accessed using the attribute:
+
|    OBMol
+
...
+
>>> print len(mol.atoms), mol.molwt
+
3430 49315.2
+
>>> dir(mol.OBMol) # Show the list of methods provided by openbabel.py
+
['AddAtom', 'AddBond', 'AddConformer', 'AddHydrogens', 'AddPolarHydrogens', ... ]
+
>>> mol.OBMol.AddHydrogens()
+
>>> print len(mol.atoms), mol.molwt
+
7244 49406.0
+
</pre>
+
 
+
The next example is an extension of one of the <code>openbabel.py</code> examples at the top of this page. It shows how a molecule could be created using <code>openbabel.py</code>, and then written to a file using Pybel:
+
<pre>
+
import openbabel, pybel
+
 
+
mol = openbabel.OBMol()
+
a = mol.NewAtom()
+
a.SetAtomicNum(6)  # carbon atom
+
a.SetVector(0.0, 1.0, 2.0) # coordinates
+
b = mol.NewAtom()
+
mol.AddBond(1, 2, 1)  # atoms indexed from 1
+
 
+
pybelmol = pybel.Molecule(mol)
+
pybelmol.write("sdf", "outputfile.sdf")
+
</pre>
+
  
 
[[Category:Developer]]
 
[[Category:Developer]]

Latest revision as of 00:08, 11 October 2012

This page provides links to all the information you need to use OpenBabel from the Python programming language.

  • If you have any problems or questions, send an email to [email protected]
  • Read the Pybel paper for background and examples of use. Don't forget to cite the Pybel paper if you use Pybel to obtain results for publication:
N. M. O'Boyle, C. Morley and G. R. Hutchison. Pybel: a Python wrapper for the OpenBabel cheminformatics toolkit Chem. Cent. J. 2008, 2, 5.

If you find Pybel useful, you may also be interested in Cinfony which allows you to access several cheminformatics toolkits using the same Python API as Pybel, from both regular Python and Jython.