BACKGROUND
the increasing number of high-resolution protein structures available in the protein database  <cit>  allows knowledge based approaches  <cit>  by comparing structural features throughout non-redundant protein data sets  <cit> .
such knowledge based approaches can help to identify key parameters in e.g.
ligand binding  <cit>  or can be used to estimate favourable structural configurations that are important for de novo protein design or prediction of protein folding  <cit> .
however, such approaches require a rapid development of new structural bioinformatic tools that are adapted to the questions asked, which in turn requires a robust framework or module.
p3d is such a module for the python scripting language .
although similar modules exist as part of the biopython project  <cit>  or part of the biskit package  <cit> , p3d was developed in order to offer a python module that is powerful and fast, yet intuitive to use.
the simplicity of p3d is due to a) the usage of object oriented programming , b) the implementation of a query parser that translates queries written in human readable language into a combination of algebra set operations and c) the fact that no additional python packages are necessary.
the speed is due to the usage of a binary space partitioning  tree which allows very fast queries in 3d  <cit> .
the additional strength is obtained by the flexible combination of both speed and complexity in the intuitive and thus natural queries to the structural data.
the combination of these factors makes p3d the optimal module to rapidly develop new and powerful bioinformatic tools that follow the python philosophy of making the source code readable.
implementation
p3d is written in python  <dig>  and compatible with the upcoming new standard python  <dig> .
pdb files are read into the p3d structure, schematically illustrated in figure  <dig>  during pdb loading each atom is converted into an atom object, which inherits all properties form the vector class .
these objects are stored into a list and linked to their proper sets, which will be used by the query function.
figure  <dig> shows some sets and how they intersect.
queries can therefore be directly translated into algebraic set operations, e.g.
"select all atoms that are oxygens, belong to the residue name atp and have a residue id smaller than 20".
for fast queries in 3d a binary space partitioning  tree is generated automatically.
there, the structure is divided into small subspaces.
figure  <dig> illustrates the recursive divisions performed on an aquaporin structure  during tree initialisation.
the implemented query functions allow the combination of all sets, of the bsp tree neighbor search and of custom user defined vectors or atoms.
thus very complex queries can be formulated in a human readable syntax .
RESULTS
p3d offers an intuitive and robust interface between the python scripting language and the complex nature of protein structure files.
the input files can be in pdb format or the compressed gzip versions.
all following examples, indicated with ">>>" are within the python idle console, but can equally be incorporated into standalone scripts.
a more detailed documentation for all modules and functions can be found online  <cit> .
loading a protein structure is done via:
>>> from p3d.protein import protein
>>> pdb = protein
all atoms are treated as vector objects and can be rapidly accessed via hash tables, algebra of sets, lists, the bsp-tree class and any combination of those.
for example all atoms are stored in the list pdb.atoms and the hash table can be found in the dictionary pdb.hash.
detailed information of how the structural data can be directly accessed can be found in the online documentation  <cit> .
an easier and more intuitive access to the structural information is offered via the query() or lookupatom() functions.
these functions try to return a set of atoms or one atom object, respectively.
the usage for the query function is e.g.
:
>>> atoms = pdb.query
this will return all atoms that are part of chain a and have a residue id from  <dig> to  <dig>  the returned list of atom objects can then directly be used in another query  or can be treated like vectors.
the complete syntax of the query-string can be found in the online documentation  <cit> .
such a generalised approach brings a lot of flexibility and robustness.
as a result, a lot of exceptions in pdb files can be handled without additional precautions, for example: a) multiple models/structures , b) alternative side-chain conformers  or alternative main chain tracings , c) disordered residues ) and d) non amino acid residues, e.g.
dna .
benchmarking biopython's pdb module against p3d showed that both modules have their strengths and weaknesses and, as usual, the results depend on the choice of the testing routines.
for example, biopython's pdb module performs a faster neighbour search since it calls a subroutine written in c from a different biopython module whereas p3d relays on its bsp tree that is written in python and is as such slower.
p3d is however faster in selecting wanted atoms due to its implementation of sets whereas biopython's pdb module requires looping and unfolding over all entities.
as a result p3d performs better if a neighbour search is connected with a complex query, such as all protein oxygen atoms within  <dig> Å of atp simply because biopython's pdb module requires a neighbour search for each atp atom and additional checking if the found atom is part of the protein.
from a programming point of view, another clear advantage of p3d is its intuitive and simple usage, e.g.
during benchmarking sample scripts written in p3d required one line using the query function while biopythons pdb module required  <dig> lines including  <dig> loops over all pdb structure entities.
another advantage of p3d is that each atom is treated as one object and no additional conversions or translations have to taken into account.
the atom objects are created from each line in the pdb files.
each created atom object holds all information regarding its properties, i.e.
the cartesian coordinates , the atom type, the residue name and number, the peptide chain and parent protein it is part of.
therefore simple recursive queries through a protein structure can be performed, e.g.
:
>>> atom = pdb.lookupatom
>>> chainatoms = atom.allatomsofsamechain()
>>> residueatoms = atom.allatomsofsameresidue()
additionally the atom information of the alternative conformer labels, the model number  and the beta and user value are part of the atom class, e.g.
:
>>> atom.x; atom.beta; atom.atype; atom.resid; atom.chain; atom.model
since the atom object inherits its properties form the vector object, simple vector operations, such as addition, subtraction, length, dot and cross product are possible at the atom level without any additional overhead, e.g.
:
>>> o = pdb.lookupatom
>>> n = pdb.lookupatom
>>> v = o + n; v = o - n; v = o.dot; v.length(); v = o.cross
the history of vector operations on atoms is stored in the atom.desc property, thus allowing to keep a record on the performed transformations.
other implemented vector operations can be found in the online manual.
the vector class can also be used to define new objects, new points of interest in space.
those can then be used as part of the query function.
this interchangeability between structural data and user-defined vectors is unique to p3d.
the user can therefore query protein surroundings by defined coordinates in a simple way, e.g.
>>> v = p3d.vector.vector
>>> atomsaroundv = pdb.query
the current version of p3d features two additional classes based on vector operations.
these are the transformationmatrix  class and the plane class.
both are part of the p3d.geo module.
the tm class returns a matrix object when two sets of three vectors  are given.
vectors or atoms that are multiplied with the matrix will be transformed from the source space into destination space.
this can be used e.g.
to align structures with only a few lines of source code:
>>> alignatoms =
>>> sourceatoms =
>>> targetatoms =
>>> for atom in alignatoms:
>>> sourceatoms.append)
>>> targetatoms.append)
>>> tm = p3d.geo.transformationmatrix
>>> for atom in pdb <dig> atoms:
>>> print .output()
the complete script can be found on the p3d web site  <cit> .
the plane class allows e.g.
calculations of dihedral angles,
>>> p3d.geo.dihedral
>>> alpha = pdb.lookupatom
>>> alpha.calcphipsi()
furthermore, the plane class can for example also be used to calculate orientations of ligands over flat co-factors if three atoms of the co-factor are used to define the plane.
this was used to calculated the orientation of histidine heme ligands relative to the heme by projecting a vector that represents the ligand orientation,  onto the heme plane, i.e.
heme.projectionofvector  <cit> .
a basic example for this usage is:
>>> a = p3d.vector.vector
>>> b = p3d.vector.vector
>>> c = p3d.vector.vector
>>> plane = p3d.geo.plane
>>> k = p3d.vector.vector
>>> plane.projectionofvector.info
all atom properties can be changed and the altered protein can be easily saved to a new file, e.g:
>>> for atom in pdb.atoms:
... atom.translateby
... atom.beta =  <dig>
>>> pdb.writetofile
the implementation of a bsp tree accelerates queries in space.
the query functions allow the combination of spatial, i.e.
bsp tree queries and set theory, thus very complex queries can be formulated at ease, e.g.
:
>>> atps = pdb.query
>>> surrounding = pdb.query
example scripts shown online  <cit>  illustrate furthermore the simplicity of python scripts that use the p3d module.
these are for example a script that analyses the distribution of phi and psi angles in a non-redundant protein set similar to the work of hovmöller et al.
<cit> .
by using p3d this analysis can be performed using only  <dig> lines of code.
another example is a script that determines the distances between different protein chains, which can be written with  <dig> lines of code, documentation included.
this data can be used to plot the contact map between different protein chains.
overall these features and their intuitive usage highlight the possibility to develop tools for structural bioinformatics rapidly.
future development
p3d will be kept updated and user requests might be implemented into the source code.
overall p3d will be maintained by the authors and hopefully other programmers will join this open source project.
two future aims will be a) to implement a faster bsptree, eventually written in c/c++ and b) to add the syntax for spatial queries, e.g.
select all "proteins and x-coordinates < 40".
furthermore p3d's website will expand with scripts that are posted by the users/readers.
CONCLUSIONS
the p3d package extends the python scripting language with a robust and powerful interface to investigate and manipulate protein structure files.
the object oriented approach of p3d, the treatment of atoms as vectors, the usage of sets, the implementation of a bsp tree and the combination of all these factors into a query interface that uses human readable language make p3d a very fast and versatile module that allows rapid development of high throughput tools for structural bioinformatics.
availability and requirements
project name: p3d
project home page:
operating systems: platform independent
programming language: python  <dig> + and  <dig>  ready
other requirements: none
license: gnu gpl v2
any restrictions to use by non-academics: none
authors' contributions
cf, concept, design, manuscript, coding of the protein, atom, vector, geo, protein, library and tree submodules and online manual.
ms important contributions to the code design and coding of the query and geo module.
all authors read and approved the final manuscript.

 the increasing number of high-resolution protein structures available in the protein database allows knowledge based approaches by comparing structural features throughout non-redundant protein data sets. such knowledge based approaches can help to identify key parameters in e.g. ligand binding or can be used to estimate favourable structural configurations that are important for de novo protein design or prediction of protein folding. however, such approaches require a rapid development of new structural bioinformatic tools that are adapted to the questions asked, which in turn requires a robust framework or module. p3d is such a module for the python scripting language. although similar modules exist as part of the biopython project or part of the biskit package, p3d was developed in order to offer a python module that is powerful and fast, yet intuitive to use. the simplicity of p3d is due to a) the usage of object oriented programming, b) the implementation of a query parser that translates queries written in human readable language into a combination of algebra set operations and c) the fact that no additional python packages are necessary. the speed is due to the usage of a binary space partitioning tree which allows very fast queries in 3d. the additional strength is obtained by the flexible combination of both speed and complexity in the intuitive and thus natural queries to the structural data. the combination of these factors makes p3d the optimal module to rapidly develop new and powerful bioinformatic tools that follow the python philosophy of making the source code readable. implementation p3d is written in python and compatible with the upcoming new standard python. pdb files are read into the p3d structure, schematically illustrated in figure during pdb loading each atom is converted into an atom object, which inherits all properties form the vector class. these objects are stored into a list and linked to their proper sets, which will be used by the query function. figure shows some sets and how they intersect. queries can therefore be directly translated into algebraic set operations, e.g. "select all atoms that are oxygens, belong to the residue name atp and have a residue id smaller than 20". for fast queries in 3d a binary space partitioning tree is generated automatically. there, the structure is divided into small subspaces. figure illustrates the recursive divisions performed on an aquaporin structure during tree initialisation. the implemented query functions allow the combination of all sets, of the bsp tree neighbor search and of custom user defined vectors or atoms. thus very complex queries can be formulated in a human readable syntax.  p3d offers an intuitive and robust interface between the python scripting language and the complex nature of protein structure files. the input files can be in pdb format or the compressed gzip versions. all following examples, indicated with ">>>" are within the python idle console, but can equally be incorporated into standalone scripts. a more detailed documentation for all modules and functions can be found online. loading a protein structure is done via: >>> from p3d.protein import protein >>> pdb = protein all atoms are treated as vector objects and can be rapidly accessed via hash tables, algebra of sets, lists, the bsp-tree class and any combination of those. for example all atoms are stored in the list pdb.atoms and the hash table can be found in the dictionary pdb.hash. detailed information of how the structural data can be directly accessed can be found in the online documentation. an easier and more intuitive access to the structural information is offered via the query() or lookupatom() functions. these functions try to return a set of atoms or one atom object, respectively. the usage for the query function is e.g.: >>> atoms = pdb.query this will return all atoms that are part of chain a and have a residue id from to the returned list of atom objects can then directly be used in another query or can be treated like vectors. the complete syntax of the query-string can be found in the online documentation. such a generalised approach brings a lot of flexibility and robustness. as a result, a lot of exceptions in pdb files can be handled without additional precautions, for example: a) multiple models/structures, b) alternative side-chain conformers or alternative main chain tracings, c) disordered residues ) and d) non amino acid residues, e.g. dna. benchmarking biopython's pdb module against p3d showed that both modules have their strengths and weaknesses and, as usual, the results depend on the choice of the testing routines. for example, biopython's pdb module performs a faster neighbour search since it calls a subroutine written in c from a different biopython module whereas p3d relays on its bsp tree that is written in python and is as such slower. p3d is however faster in selecting wanted atoms due to its implementation of sets whereas biopython's pdb module requires looping and unfolding over all entities. as a result p3d performs better if a neighbour search is connected with a complex query, such as all protein oxygen atoms within Å of atp simply because biopython's pdb module requires a neighbour search for each atp atom and additional checking if the found atom is part of the protein. from a programming point of view, another clear advantage of p3d is its intuitive and simple usage, e.g. during benchmarking sample scripts written in p3d required one line using the query function while biopythons pdb module required lines including loops over all pdb structure entities. another advantage of p3d is that each atom is treated as one object and no additional conversions or translations have to taken into account. the atom objects are created from each line in the pdb files. each created atom object holds all information regarding its properties, i.e. the cartesian coordinates, the atom type, the residue name and number, the peptide chain and parent protein it is part of. therefore simple recursive queries through a protein structure can be performed, e.g.: >>> atom = pdb.lookupatom >>> chainatoms = atom.allatomsofsamechain() >>> residueatoms = atom.allatomsofsameresidue() additionally the atom information of the alternative conformer labels, the model number and the beta and user value are part of the atom class, e.g.: >>> atom.x; atom.beta; atom.atype; atom.resid; atom.chain; atom.model since the atom object inherits its properties form the vector object, simple vector operations, such as addition, subtraction, length, dot and cross product are possible at the atom level without any additional overhead, e.g.: >>> o = pdb.lookupatom >>> n = pdb.lookupatom >>> v = o + n; v = o - n; v = o.dot; v.length(); v = o.cross the history of vector operations on atoms is stored in the atom.desc property, thus allowing to keep a record on the performed transformations. other implemented vector operations can be found in the online manual. the vector class can also be used to define new objects, new points of interest in space. those can then be used as part of the query function. this interchangeability between structural data and user-defined vectors is unique to p3d. the user can therefore query protein surroundings by defined coordinates in a simple way, e.g. >>> v = p3d.vector.vector >>> atomsaroundv = pdb.query the current version of p3d features two additional classes based on vector operations. these are the transformationmatrix class and the plane class. both are part of the p3d.geo module. the tm class returns a matrix object when two sets of three vectors are given. vectors or atoms that are multiplied with the matrix will be transformed from the source space into destination space. this can be used e.g. to align structures with only a few lines of source code: >>> alignatoms = >>> sourceatoms = >>> targetatoms = >>> for atom in alignatoms: >>> sourceatoms.append) >>> targetatoms.append) >>> tm = p3d.geo.transformationmatrix >>> for atom in pdb atoms: >>> print.output() the complete script can be found on the p3d web site. the plane class allows e.g. calculations of dihedral angles, >>> p3d.geo.dihedral >>> alpha = pdb.lookupatom >>> alpha.calcphipsi() furthermore, the plane class can for example also be used to calculate orientations of ligands over flat co-factors if three atoms of the co-factor are used to define the plane. this was used to calculated the orientation of histidine heme ligands relative to the heme by projecting a vector that represents the ligand orientation, onto the heme plane, i.e. heme.projectionofvector. a basic example for this usage is: >>> a = p3d.vector.vector >>> b = p3d.vector.vector >>> c = p3d.vector.vector >>> plane = p3d.geo.plane >>> k = p3d.vector.vector >>> plane.projectionofvector.info all atom properties can be changed and the altered protein can be easily saved to a new file, e.g: >>> for atom in pdb.atoms:... atom.translateby... atom.beta = >>> pdb.writetofile the implementation of a bsp tree accelerates queries in space. the query functions allow the combination of spatial, i.e. bsp tree queries and set theory, thus very complex queries can be formulated at ease, e.g.: >>> atps = pdb.query >>> surrounding = pdb.query example scripts shown online illustrate furthermore the simplicity of python scripts that use the p3d module. these are for example a script that analyses the distribution of phi and psi angles in a non-redundant protein set similar to the work of hovmöller et al.. by using p3d this analysis can be performed using only lines of code. another example is a script that determines the distances between different protein chains, which can be written with lines of code, documentation included. this data can be used to plot the contact map between different protein chains. overall these features and their intuitive usage highlight the possibility to develop tools for structural bioinformatics rapidly. future development p3d will be kept updated and user requests might be implemented into the source code. overall p3d will be maintained by the authors and hopefully other programmers will join this open source project. two future aims will be a) to implement a faster bsptree, eventually written in c/c++ and b) to add the syntax for spatial queries, e.g. select all "proteins and x-coordinates < 40". furthermore p3d's website will expand with scripts that are posted by the users/readers.  the p3d package extends the python scripting language with a robust and powerful interface to investigate and manipulate protein structure files. the object oriented approach of p3d, the treatment of atoms as vectors, the usage of sets, the implementation of a bsp tree and the combination of all these factors into a query interface that uses human readable language make p3d a very fast and versatile module that allows rapid development of high throughput tools for structural bioinformatics. availability and requirements project name: p3d project home page: operating systems: platform independent programming language: python + and ready other requirements: none license: gnu gpl v2 any restrictions to use by non-academics: none authors' contributions cf, concept, design, manuscript, coding of the protein, atom, vector, geo, protein, library and tree submodules and online manual. ms important contributions to the code design and coding of the query and geo module. all authors read and approved the final manuscript. 
p3d is an object oriented python module that adds a simple yet powerful interface to the python interpreter to process and analyse three dimensional protein structure files. p3d's strength arises from the combination of a) very fast spatial access to the structural data due to the implementation of a binary space partitioning tree, b) set theory and c) functions that allow to combine a and b and that use human readable language in the search queries rather than complex computer language. high-throughput bioinformatic analysis tools are needed to mine the large amount of structural data via knowledge based approaches. the development of such tools requires a robust interface to access the structural data in an easy way. p3d is the perfect tool to quickly develop tools for structural bioinformatics using the python scripting language. all these factors combined facilitate the rapid development of bioinformatic tools that can perform quick and complex analyses of protein structures.
 high-throughput bioinformatic analysis tools are needed to mine the large amount of structural data via knowledge based approaches. the development of such tools requires a robust interface to access the structural data in an easy way. for this the python scripting language is the optimal choice since its philosophy is to write an understandable source code.  p3d is an object oriented python module that adds a simple yet powerful interface to the python interpreter to process and analyse three dimensional protein structure files. p3d's strength arises from the combination of a) very fast spatial access to the structural data due to the implementation of a binary space partitioning tree, b) set theory and c) functions that allow to combine a and b and that use human readable language in the search queries rather than complex computer language. all these factors combined facilitate the rapid development of bioinformatic tools that can perform quick and complex analyses of protein structures.  p3d is the perfect tool to quickly develop tools for structural bioinformatics using the python scripting language. 