+The {\tt PERMISSIVE} flag indicates that a number of common problems (see \ref{problem structures}) associated with PDB files will be ignored (but note that some atoms and/or residues will be missing). If the flag is not present a {\tt PDBConstructionException} will be generated if any problems are detected during the parse operation.

+

+The Structure object is then produced by letting the \texttt{PDBParser} object parse a PDB file (the PDB file in this case is called 'pdb1fat.ent', '1fat' is a user defined name for the structure):

+

+\begin{verbatim}

+>>> structure_id = "1fat"

+>>> filename = "pdb1fat.ent"

+>>> s = p.get_structure(structure_id, filename)

+\end{verbatim}

+

+You can extract the header and trailer (simple lists of strings) of the PDB

+file from the PDBParser object with the {\tt get\_header} and {\tt get\_trailer}

+methods. Note however that many PDB files contain headers with

+incomplete or erroneous information. Many of the errors have been

+fixed in the equivalent mmCIF files. \emph{Hence, if you are interested

+in the header information, it is a good idea to extract information

+from mmCIF files using the} \texttt{\emph{MMCIF2Dict}} \emph{tool

+described below, instead of parsing the PDB header. }

+

+Now that is clarified, let's return to parsing the PDB header. The

+structure object has an attribute called \texttt{header} which is

+a Python dictionary that maps header records to their values.

+

+Example:

+

+\begin{verbatim}

+>>> resolution = structure.header['resolution']

+>>> keywords = structure.header['keywords']

+\end{verbatim}

+The available keys are \verb+name+, \verb+head+, \verb+deposition_date+, \verb+release_date+, \verb+structure_method+, \verb+resolution+, \verb+structure_reference+ (which maps to a list of references), \verb+journal_reference+, \verb+author+, and \verb+compound+ (which maps to a dictionary with various information about the crystallized compound).

+

+The dictionary can also be created without creating a \texttt{Structure}

+object, ie. directly from the PDB file:

+

+\begin{verbatim}

+>>> file = open(filename,'r')

+>>> header_dict = parse_pdb_header(file)

+>>> file.close()

+\end{verbatim}

+

+\subsection{Reading an mmCIF file}

+

+Similarly to the case the case of PDB files, first create an \texttt{MMCIFParser} object:

+

+\begin{verbatim}

+>>> from Bio.PDB.MMCIFParser import MMCIFParser

+>>> parser = MMCIFParser()

+\end{verbatim}

+Then use this parser to create a structure object from the mmCIF file:

+\begin{verbatim}

+>>> structure = parser.get_structure('1fat', '1fat.cif')

+\end{verbatim}

+

+To have some more low level access to an mmCIF file, you can use the \verb+MMCIF2Dict+ class to create a Python dictionary that maps all mmCIF

+tags in an mmCIF file to their values. If there are multiple values

+(like in the case of tag \verb+_atom_site.Cartn_y+, which holds

+the $y$ coordinates of all atoms), the tag is mapped to a list of values.

+The dictionary is created from the mmCIF file as follows:

+

+\begin{verbatim}

+>>> from Bio.PDB.MMCIF2Dict import MMCIF2Dict

+>>> mmcif_dict = MMCIF2Dict('1FAT.cif')

+\end{verbatim}

+

+Example: get the solvent content from an mmCIF file:

+\begin{verbatim}

+>>> sc = mmcif_dict['_exptl_crystal.density_percent_sol']

+\end{verbatim}

+

+Example: get the list of the $y$ coordinates of all atoms

+\begin{verbatim}

+>>> y_list = mmcif_dict['_atom_site.Cartn_y']

+\end{verbatim}

+

+\subsection{Reading files in the PDB XML format}

+

+That's not yet supported, but we are definitely planning to support that

+in the future (it's not a lot of work). Contact the Biopython developers

+(\mailto{biopython-dev@biopython.org}) if you need this).

+

+\subsection{Writing PDB files}

+

+Use the PDBIO class for this. It's easy to write out specific parts

+of a structure too, of course.

+

+Example: saving a structure

+

+\begin{verbatim}

+>>> io = PDBIO()

+>>> io.set_structure(s)

+>>> io.save('out.pdb')

+\end{verbatim}

+If you want to write out a part of the structure, make use of the

+\texttt{Select} class (also in \texttt{PDBIO}). Select has four methods:

+is included in the output). By subclassing \texttt{Select} and returning

+0 when appropriate you can exclude models, chains, etc. from the output.

+Cumbersome maybe, but very powerful. The following code only writes

+out glycine residues:

+

+\begin{verbatim}

+>>> class GlySelect(Select):

+... def accept_residue(self, residue):

+... if residue.get_name()=='GLY':

+... return True

+... else:

+... return False

+...

+>>> io = PDBIO()

+>>> io.set_structure(s)

+>>> io.save('gly_only.pdb', GlySelect())

+\end{verbatim}

+If this is all too complicated for you, the \texttt{Dice} module contains

+a handy \texttt{extract} function that writes out all residues in

+a chain between a start and end residue.

+

\section{Structure representation}

The overall layout of a \texttt{Structure} object follows the so-called SMCRA

-(Structure/Model/Chain/Residue/Atom) architecture :

+(Structure/Model/Chain/Residue/Atom) architecture:

\begin{itemize}

\item A structure consists of models

@@ -8827,142 +8961,6 @@ \subsection{Structure}

of several models. Disorder in crystal structures of large parts of molecules

can also result in several models.

-\subsubsection{Constructing a Structure object from a PDB file}

-

-First we create a \texttt{PDBParser} object:

-

-\begin{verbatim}

->>> from Bio.PDB.PDBParser import PDBParser

->>> p = PDBParser(PERMISSIVE=1)

-\end{verbatim}

-

-The {\tt PERMISSIVE} flag indicates that a number of common problems (see \ref{problem structures}) associated with PDB files will be ignored (but note that some atoms and/or residues will be missing). If the flag is not present a {\tt PDBConstructionException} will be generated during the parse operation.

-

-The Structure object is then produced by letting the \texttt{PDBParser} object parse a PDB file (the PDB file in this case is called 'pdb1fat.ent', '1fat' is a user defined name for the structure):

-

-\begin{verbatim}

->>> structure_id = "1fat"

->>> filename = "pdb1fat.ent"

->>> s = p.get_structure(structure_id, filename)

-\end{verbatim}

-

-You can extract the header and trailer (simple lists of strings) of the PDB

-file from the PDBParser object with the {\tt get\_header} and {\tt get\_trailer}

-methods. Note however that many PDB files contain headers with

-incomplete or erroneous information. Many of the errors have been

-fixed in the equivalent mmCIF files. \emph{Hence, if you are interested

+The \texttt{get\_vector} method returns a \texttt{Vector} object representation of the coordinates of the \texttt{Atom} object, allowing you to do vector operations on atomic coordinates. \texttt{Vector} implements the full set of 3D vector operations, matrix multiplication (left and right) and some advanced rotation-related operations as well.

+

+As an example of the capabilities of Bio.PDB's \texttt{Vector} module,

+suppose that you would like to find the position of a Gly residue's C$\beta$

+atom, if it had one. Rotating the N atom of

+the Gly residue along the C$\alpha$-C bond over -120 degrees roughly

+puts it in the position of a virtual C$\beta$ atom. Here's how to

+do it, making use of the \texttt{rotaxis} method (which can be used

+to construct a rotation around a certain axis) of the \texttt{Vector}

+module:

+

+\begin{verbatim}

+# get atom coordinates as vectors

+>>> n = residue['N'].get_vector()

+>>> c = residue['C'].get_vector()

+>>> ca = residue['CA'].get_vector()

+# center at origin

+>>> n = n - ca

+>>> c = c - ca

+# find rotation matrix that rotates n

+# -120 degrees along the ca-c vector

+>>> rot = rotaxis(-pi * 120.0/180.0, c)

+# apply rotation to ca-n vector

+>>> cb_at_origin = n.left_multiply(rot)

+# put on top of ca atom

+>>> cb = cb_at_origin+ca

+\end{verbatim}

+This example shows that it's possible to do some quite nontrivial

+vector operations on atomic data, which can be quite useful. In addition