This module provides classes that represent PDB (Protein Data Bank) files and configurations contained in PDB files. It provides access to PDB files on two levels: low-level (line by line) and high-level (chains, residues, and atoms).
Caution: The PDB file format has been heavily abused, and it is probably impossible to write code that can deal with all variants correctly. This modules tries to read the widest possible range of PDB files, but gives priority to a correct interpretation of the PDB format as defined by the Brookhaven National Laboratory.
A special problem are atom names. The PDB file format specifies that the first two letters contain the right-justified chemical element name. A later modification allowed the initial space in hydrogen names to be replaced by a digit. Many programs ignore all this and treat the name as an arbitrary left-justified four-character name. This makes it difficult to extract the chemical element accurately; most programs write the "CA" for C_alpha in such a way that it actually stands for a calcium atom! For this reason a special element field has been added later, but only few files use it.
The low-level routines in this module do not try to deal with the atom name problem; they return and expect four-character atom names including spaces in the correct positions. The high-level routines use atom names without leading or trailing spaces, but provide and use the element field whenever possible. For output, they use the element field to place the atom name correctly, and for input, they construct the element field content from the atom name if no explicit element field is found in the file.
Except where indicated, numerical values use the same units and conventions as specified in the PDB format description.
Example:
conf = Structure('example.pdb')
print conf
for residue in conf.residues:
for atom in residue:
print atom
A subclass of Atom, which differs only in the return value of the method type().
Constructor: HetAtom(name, position, **properties).
This is an abstract base class. Instances can be created using one of the subclasses (Molecule, AminoAcidResidue, NucleotideResidue).
Group objects permit iteration over atoms with for-loops, as well as extraction of atoms by indexing with the atom name.
Methods:Adds atom (an Atom object) to the group.
Removes atom (an Atom object) from the group. An exception will be raised if atom is not part of the group.
Removes all hydrogen atoms.
Sets the PDB residue name to name.
Writes the group to file (a PDBFile object or a string containing a file name).
This is an abstract base class. Instances can be created using one of the subclasses (PeptideChain, NucleotideChain).
Chain objects respond to len() and return their residues by indexing with integers.
Methods:Returns the list of residue names.
Add residue at the end of the chain.
Remove residues starting from first up to (but not including) last. If last is None, remove everything starting from first.
Removes all hydrogen atoms.
Writes the chain to file (a PDBFile object or a string containing a file name).
A subclass of Group.
Constructor: Molecule(name, atoms=None, number=None), where name is the PDB residue name. An optional list of atoms can be specified, otherwise the molecule is initially empty. The optional number is the PDB residue number.
Note: In PDB files, non-chain molecules are treated as residues, there is no separate molecule definition. This modules defines every residue as a molecule that is not an amino acid residue or a nucleotide residue.
Constructor: PDBFile(filename, mode="r"), where filename is the file name and mode is "r" for reading and "w" for writing, The low-level file access is handled by the module Scientific.IO.TextFile, therefore compressed files and URLs (for reading) can be used as well.
Methods:Returns the contents of the next non-blank line (= record). The return value is a tuple whose first element (a string) contains the record type. For supported record types (HEADER, ATOM, HETATM, ANISOU, TERM, MODEL, CONECT), the items from the remaining fields are put into a dictionary which is returned as the second tuple element. Most dictionary elements are strings or numbers; atom positions are returned as a vector, and anisotropic temperature factors are returned as a rank-2 tensor, already multiplied by 1.e-4. White space is stripped from all strings except for atom names, whose correct interpretation can depend on an initial space. For unsupported record types, the second tuple element is a string containing the remaining part of the record.
Writes a line using record type and data dictionary in the same format as returned by readLine(). Default values are provided for non-essential information, so the data dictionary need not contain all entries.
Writes text into one or several comment lines. Each line of the text is prefixed with REMARK and written to the file.
Writes an ATOM or HETATM record using the name, occupancy, temperature and element information supplied. The residue and chain information is taken from the last calls to the methods nextResidue() and nextChain().
Signals the beginning of a new residue, starting with the next call to writeAtom(). The residue name is name, and a number can be supplied optionally; by default residues in a chain will be numbered sequentially starting from 1. The value of terminus can be None, "C", or "N"; it is passed to export filters that can use this information in order to use different atom or residue names in terminal residues.
Signals the beginning of a new chain. A chain identifier (string of length one) can be supplied as chain_id, by default consecutive letters from the alphabet are used. The equally optional segment_id defaults to an empty string.
Signals the end of a chain.
Closes the file. This method must be called for write mode because otherwise the file will be incomplete.
Constructor: Atom(name, position, **properties), where name is the PDB atom name (a string), position is a atom position (a vector), and properties can include any of the other items that can be stored in an atom record.
The properties can be obtained or modified using indexing, as for Python dictionaries.
Methods:Returns the six-letter record type, ATOM or HETATM.
Writes an atom record to file (a PDBFile object or a string containing a file name).
A subclass of Group.
Constructor: AminoAcidResidue(name, atoms=None, number=None), where name is the PDB residue name. An optional list of atoms can be specified, otherwise the residue is initially empty. The optional number is the PDB residue number.
Methods:Returns 1 if the residue is in C-terminal configuration, i.e. if it has a second oxygen bound to the carbon atom of the peptide group.
Returns 1 if the residue is in N-terminal configuration, i.e. if it contains more than one hydrogen bound to be nitrogen atom of the peptide group.
A subclass of Group.
Constructor: NucleotideResidue(name, atoms=None, number=None), where name is the PDB residue name. An optional list of atoms can be specified, otherwise the residue is initially empty. The optional number is the PDB residue number.
Methods:Returns 1 if the residue has an atom named O2*.
Returns 1 if the residue has no atom named O2*.
Returns 1 if the residue has a phosphate group.
Returns 1 if the residue has a 3-terminal H atom.
A subclass of Chain.
Constructor: PeptideChain(residues=None, chain_id=None, segment_id=None), where chain_id is a one-letter chain identifier and segment_id is a multi-character chain identifier, both are optional. A list of AminoAcidResidue objects can be passed as residues; by default a peptide chain is initially empty.
Methods:Returns 1 if the last residue is in C-terminal configuration.
A subclass of Chain.
Constructor: NucleotideChain(residues=None, chain_id=None, segment_id=None), where chain_id is a one-letter chain identifier and segment_id is a multi-character chain identifier, both are optional. A list of NucleotideResidue objects can be passed as residues; by default a nucleotide chain is initially empty.
Most PDB residue numbers are simple integers, but when insertion codes are used a number can consist of an integer plus a letter. Such compound residue numbers are represented by this class.
Constructor: ResidueNumber(number, insertion_code)
Constructor: Structure(filename, model=0, alternate_code="A"), where filename is the name of the PDB file. Compressed files and URLs are accepted, as for class PDBFile. The two optional arguments specify which data should be read in case of a multiple-model file or in case of a file that contains alternative positions for some atoms.
The components of a system can be accessed in several ways (s is an instance of this class):
s.residues is a list of all PDB residues, in the order in which they occurred in the file.
s.peptide_chains is a list of PeptideChain objects, containing all peptide chains in the file in their original order.
s.nucleotide_chains is a list of NucleotideChain objects, containing all nucleotide chains in the file in their original order.
s.molecules is a list of all PDB residues that are neither amino acid residues nor nucleotide residues, in their original order.
s.objects is a list of all high-level objects (peptide chains, nucleotide chains, and molecules) in their original order.
An iteration over a Structure instance by a for-loop is equivalent to an iteration over the residue list.
Methods:Removes all hydrogen atoms.
Splits the peptide chain indicated by number (0 being the first peptide chain in the PDB file) after the residue indicated by position (0 being the first residue of the chain). The two chain fragments remain adjacent in the peptide chain list, i.e. the numbers of all following nucleotide chains increase by one.
Splits the nucleotide chain indicated by number (0 being the first nucleotide chain in the PDB file) after the residue indicated by position (0 being the first residue of the chain). The two chain fragments remain adjacent in the nucleotide chain list, i.e. the numbers of all following nucleotide chains increase by one.
Join the two peptide chains indicated by first and second into one peptide chain. The new chain occupies the position first; the chain at second is removed from the peptide chain list.
Join the two nucleotide chains indicated by first and second into one nucleotide chain. The new chain occupies the position first; the chain at second is removed from the nucleotide chain list.
Renumber all atoms sequentially starting with 1.
Writes all objects to file (a PDBFile object or a string containing a file name).