<a name="Module:Scientific.IO.PDB"><h1>Module Scientific.IO.PDB</h1></a>

<p>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).</p>

<p>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.</p>

<p>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 <tt>"CA"</tt> 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.</p>

<p>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.</p>

<p>Except where indicated, numerical values use the same units and
conventions as specified in the PDB format description.</p>

Example:

<pre>
conf = Structure('example.pdb')
print conf
for residue in conf.residues:
    for atom in residue:
        print atom
</pre>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.HetAtom"><h2>Class HetAtom: HetAtom in a PDB structure</h2></a>

<p>A subclass of Atom, which differs only in the return value
of the method type().</p>

<p>Constructor: HetAtom(<i>name</i>, <i>position</i>, <i>**properties</i>).
</p>

<hr width=70%>
<a name="Class:Scientific.IO.PDB.Group"><h2>Class Group: Atom group (residue or molecule) in a PDB file</h2></a>

<p>This is an abstract base class. Instances can be created using
one of the subclasses (Molecule, AminoAcidResidue, NucleotideResidue).</p>

<p>Group objects permit iteration over atoms with for-loops,
as well as extraction of atoms by indexing with the
atom name.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>addAtom</i></b>(<i>atom</i>)
<p>Adds <i>atom</i> (an Atom object) to the group.</p>

<li> <b><i>deleteAtom</i></b>(<i>atom</i>)
<p>Removes <i>atom</i> (an Atom object) from the group. An exception
will be raised if <i>atom</i> is not part of the group.
</p>

<li> <b><i>deleteHydrogens</i></b>()
<p>Removes all hydrogen atoms.</p>

<li> <b><i>changeName</i></b>(<i>name</i>)
<p>Sets the PDB residue name to <i>name</i>.</p>

<li> <b><i>writeToFile</i></b>(<i>file</i>)
<p>Writes the group to <i>file</i> (a PDBFile object or a
string containing a file name).
</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.Chain"><h2>Class Chain: Chain of PDB residues</h2></a>

<p>This is an abstract base class. Instances can be created using
one of the subclasses (PeptideChain, NucleotideChain).</p>

<p>Chain objects respond to len() and return their residues
by indexing with integers.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>sequence</i></b>()
<p>Returns the list of residue names.</p>

<li> <b><i>addResidue</i></b>(<i>residue</i>)
<p>Add <i>residue</i> at the end of the chain.</p>

<li> <b><i>removeResidues</i></b>(<i>first</i>, <i>last</i>)
<p>Remove residues starting from <i>first</i> up to (but not
including) <i>last</i>. If <i>last</i> is <tt>None</tt>, remove everything
starting from <i>first</i>.
</p>

<li> <b><i>deleteHydrogens</i></b>()
<p>Removes all hydrogen atoms.</p>

<li> <b><i>writeToFile</i></b>(<i>file</i>)
<p>Writes the chain to <i>file</i> (a PDBFile object or a
string containing a file name).
</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.Molecule"><h2>Class Molecule: Molecule in a PDB file</h2></a>

<p>A subclass of Group.</p>

<p>Constructor: Molecule(<i>name</i>, <i>atoms</i>=<tt>None</tt>, <i>number</i>=None),
where <i>name</i> is the PDB residue name. An optional list
of <i>atoms</i> can be specified, otherwise the molecule is initially
empty. The optional <i>number</i> is the PDB residue number.</p>

<p>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.
</p>

<hr width=70%>
<a name="Class:Scientific.IO.PDB.PDBFile"><h2>Class PDBFile: PDB file with access at the record level</h2></a>

<p>Constructor: PDBFile(<i>filename</i>, <i>mode</i>=<tt>"r"</tt>), where <i>filename</i>
is the file name and <i>mode</i> is <tt>"r"</tt> for reading and <tt>"w"</tt> 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.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>readLine</i></b>()
<p>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.
</p>

<li> <b><i>writeLine</i></b>(<i>type</i>, <i>data</i>)
<p>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.
</p>

<li> <b><i>writeComment</i></b>(<i>text</i>)
<p>Writes <i>text</i> into one or several comment lines.
Each line of the text is prefixed with <tt>REMARK</tt> and written
to the file.
</p>

<li> <b><i>writeAtom</i></b>(<i>name</i>, <i>position</i>, <i>occupancy</i>=<tt>0.0</tt>, <i>temperature_factor</i>=<tt>0.0</tt>, <i>element</i>=<tt>''</tt>)
<p>Writes an ATOM or HETATM record using the <i>name</i>, <i>occupancy</i>,
<i>temperature</i> and <i>element</i> information supplied. The residue and
chain information is taken from the last calls to the methods
nextResidue() and nextChain().
</p>

<li> <b><i>nextResidue</i></b>(<i>name</i>, <i>number</i>=<tt>None</tt>, <i>terminus</i>=<tt>None</tt>)
<p>Signals the beginning of a new residue, starting with the
next call to writeAtom(). The residue name is <i>name</i>, and a
<i>number</i> can be supplied optionally; by default residues in a
chain will be numbered sequentially starting from 1. The
value of <i>terminus</i> can be <tt>None</tt>, <tt>"C"</tt>, or <tt>"N"</tt>; it is passed
to export filters that can use this information in order to
use different atom or residue names in terminal residues.
</p>

<li> <b><i>nextChain</i></b>(<i>chain_id</i>=<tt>None</tt>, <i>segment_id</i>=<tt>''</tt>)
<p>Signals the beginning of a new chain. A chain identifier
(string of length one) can be supplied as <i>chain_id</i>, by
default consecutive letters from the alphabet are used.
The equally optional <i>segment_id</i> defaults to an empty string.
</p>

<li> <b><i>terminateChain</i></b>()
<p>Signals the end of a chain.</p>

<li> <b><i>close</i></b>()
<p>Closes the file. This method <i>must</i> be called for write mode
because otherwise the file will be incomplete.
</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.Atom"><h2>Class Atom: Atom in a PDB structure</h2></a>

<p>Constructor: Atom(<i>name</i>, <i>position</i>, <i>**properties</i>),
where <i>name</i> is the PDB atom name (a string),
<i>position</i> is a atom position (a vector), and
<i>properties</i> can include any of the other items that
can be stored in an atom record.</p>

<p>The properties can be obtained or modified using
indexing, as for Python dictionaries.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>type</i></b>()
<p>Returns the six-letter record type, ATOM or HETATM.</p>

<li> <b><i>writeToFile</i></b>(<i>file</i>)
<p>Writes an atom record to <i>file</i> (a PDBFile object or a
string containing a file name).</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.AminoAcidResidue"><h2>Class AminoAcidResidue: Amino acid residue in a PDB file</h2></a>

<p>A subclass of Group.</p>

<p>Constructor: AminoAcidResidue(<i>name</i>, <i>atoms</i>=<tt>None</tt>, <i>number</i>=None),
where <i>name</i> is the PDB residue name. An optional list
of <i>atoms</i> can be specified, otherwise the residue is initially
empty. The optional <i>number</i> is the PDB residue number.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>isCTerminus</i></b>()
<p>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.
</p>

<li> <b><i>isNTerminus</i></b>()
<p>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.
</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.NucleotideResidue"><h2>Class NucleotideResidue: Nucleotide residue in a PDB file</h2></a>

<p>A subclass of Group.</p>

<p>Constructor: NucleotideResidue(<i>name</i>, <i>atoms</i>=<tt>None</tt>, <i>number</i>=None),
where <i>name</i> is the PDB residue name. An optional list
of <i>atoms</i> can be specified, otherwise the residue is initially
empty. The optional <i>number</i> is the PDB residue number.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>hasRibose</i></b>()
<p>Returns 1 if the residue has an atom named O2*.</p>

<li> <b><i>hasDesoxyribose</i></b>()
<p>Returns 1 if the residue has no atom named O2*.</p>

<li> <b><i>hasPhosphate</i></b>()
<p>Returns 1 if the residue has a phosphate group.</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.PeptideChain"><h2>Class PeptideChain: Peptide chain in a PDB file</h2></a>

<p>A subclass of Chain.</p>

<p>Constructor: PeptideChain(<i>residues</i>=<tt>None</tt>, <i>chain_id</i>=<tt>None</tt>,
                          <i>segment_id</i>=<tt>None</tt>), where <i>chain_id</i>
is a one-letter chain identifier and <i>segment_id</i> is
a multi-character chain identifier, both are optional. A list
of AminoAcidResidue objects can be passed as <i>residues</i>; by
default a peptide chain is initially empty.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>isTerminated</i></b>()
<p>Returns 1 if the last residue is in C-terminal configuration.</p>

</ul>
<hr width=70%>
<a name="Class:Scientific.IO.PDB.NucleotideChain"><h2>Class NucleotideChain: Nucleotide chain in a PDB file</h2></a>

<p>A subclass of Chain.</p>

<p>Constructor: NucleotideChain(<i>residues</i>=<tt>None</tt>, <i>chain_id</i>=<tt>None</tt>,
                             <i>segment_id</i>=<tt>None</tt>), where <i>chain_id</i>
is a one-letter chain identifier and <i>segment_id</i> is
a multi-character chain identifier, both are optional. A list
of NucleotideResidue objects can be passed as <i>residues</i>; by
default a nucleotide chain is initially empty.
</p>

<hr width=70%>
<a name="Class:Scientific.IO.PDB.ResidueNumber"><h2>Class ResidueNumber: PDB residue number</h2></a>

<p>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.</p>

<p>Constructor: ResidueNumber(<i>number</i>, <i>insertion_code</i>)
</p>

<hr width=70%>
<a name="Class:Scientific.IO.PDB.Structure"><h2>Class Structure: A high-level representation of the contents of a PDB file</h2></a>

<p>Constructor: Structure(<i>filename</i>, <i>model</i>=<tt>0</tt>, <i>alternate_code</i>=<tt>"A"</tt>),
where <i>filename</i> 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.</p>

<p>The components of a system can be accessed in several ways
(<tt>s</tt> is an instance of this class):</p>

<ul>
<li> <p>

<tt>s.residues</tt> is a list of all PDB residues, in the order in
  which they occurred in the file.</p><li> <p>

<tt>s.peptide_chains</tt> is a list of PeptideChain objects, containing
  all peptide chains in the file in their original order.</p><li> <p>

<tt>s.nucleotide_chains</tt> is a list of NucleotideChain objects, containing
  all nucleotide chains in the file in their original order.</p><li> <p>

<tt>s.molecules</tt> is a list of all PDB residues that are neither
  amino acid residues nor nucleotide residues, in their original
  order.</p><li> <p>

<tt>s.objects</tt> is a list of all high-level objects (peptide chains,
  nucleotide chains, and molecules) in their original order.</p></ul>
<p>An iteration over a Structure instance by a for-loop is equivalent
to an iteration over the residue list.
</p>

<b>Methods:</b><br>
<ul>
<li> <b><i>deleteHydrogens</i></b>()
<p>Removes all hydrogen atoms.</p>

<li> <b><i>splitPeptideChain</i></b>(<i>number</i>, <i>position</i>)
<p>Splits the peptide chain indicated by <i>number</i> (0 being
the first peptide chain in the PDB file) after the residue indicated
by <i>position</i> (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.
</p>

<li> <b><i>splitNucleotideChain</i></b>(<i>number</i>, <i>position</i>)
<p>Splits the nucleotide chain indicated by <i>number</i> (0 being
the first nucleotide chain in the PDB file) after the residue indicated
by <i>position</i> (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.
</p>

<li> <b><i>joinPeptideChains</i></b>(<i>first</i>, <i>second</i>)
<p>Join the two peptide chains indicated by <i>first</i> and <i>second</i>
into one peptide chain. The new chain occupies the position
<i>first</i>; the chain at <i>second</i> is removed from the peptide
chain list.
</p>

<li> <b><i>joinNucleotideChains</i></b>(<i>first</i>, <i>second</i>)
<p>Join the two nucleotide chains indicated by <i>first</i> and <i>second</i>
into one nucleotide chain. The new chain occupies the position
<i>first</i>; the chain at <i>second</i> is removed from the nucleotide
chain list.
</p>

<li> <b><i>renumberAtoms</i></b>()
<p>Renumber all atoms sequentially starting with 1.</p>

<li> <b><i>writeToFile</i></b>(<i>file</i>)
<p>Writes all objects to <i>file</i> (a PDBFile object or a
string containing a file name).
</p>

</ul>