From 9c6d125e75db47b9f834e0fc504db024e8254204 Mon Sep 17 00:00:00 2001
From: Sam Ireland <sam.ireland.uk@gmail.com>
Date: Sat, 26 Aug 2017 13:48:14 +0100
Subject: [PATCH] 0.4 docs

---
 docs/source/changelog.rst |  11 ++++
 docs/source/overview.rst  | 106 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
index cae4454b..808659fa 100644
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@@ -1,6 +1,17 @@
 Changelog
 ---------
 
+Release 0.4.0
+~~~~~~~~~~~~~
+
+`26 August 2017`
+
+* Added PDB parsing.
+* Added PDB saving.
+* Gave atoms ability to get specific bond with other atom.
+* Added bond angle calculation.
+* Added ability to filter out water molecules.
+
 Release 0.3.0
 ~~~~~~~~~~~~~
 
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
index 1d02200e..3eecd097 100644
--- a/docs/source/overview.rst
+++ b/docs/source/overview.rst
@@ -20,6 +20,17 @@ The :py:class:`.Xyz` object you get has a :py:meth:`~.Xyz.comment` property,
 which describes the file, and a :py:meth:`~.Xyz.model` property, which returns
 the :py:class:`.Model` the file describes.
 
+From .pdb
+~~~~~~~~~
+
+A .pdb can also be loaded from a file, but they can also be fetched directly
+from the RCSB over the internet using the PDB code:
+
+  >>> pdb = atomium.pdb_from_file("1LOL.pdb")
+  >>> pdb2 = atomium.fetch("5HVD")
+  >>> pdb2.model()
+  <Model (2156 atoms)>
+
 The Model
 ~~~~~~~~~
 
@@ -85,6 +96,8 @@ Atoms can be bonded to one another using the :py:meth:`~.Atom.bond` method:
   {"<C-O Bond>"}
   >>> atom.bonded_atoms()
   {<O Atom at (37.441, 29.265, 52.113)>}
+  >>> atom.bond_with(other_atom)
+  <C-O Bond>
   >>> atom.unbond(other_atom)
   >>> atom.bonds()
   {}
@@ -92,14 +105,105 @@ Atoms can be bonded to one another using the :py:meth:`~.Atom.bond` method:
   {}
 
 
+Sub-Structures
+~~~~~~~~~~~~~~
+
+Molecules
+#########
+
+PDB files contain descriptions of the various molecular units within the model.
+The simplest way to access these is to get the :py:class:`.Molecule` objects in
+the model:
+
+  >>> pdb.model().molecules(water=False)
+  {<Molecule A2001 (XMP, 24 atoms)>, <Molecule B5002 (BU2, 6 atoms)>, <Molecule A5
+  001 (BU2, 6 atoms)>, <Chain (204 residues)>, <Molecule B2002 (XMP, 24 atoms)>, <
+  Chain (214 residues)>}
+  >>> pdb.model().molecules(water=False, generic=True)
+  {<Molecule B2002 (XMP, 24 atoms)>, <Molecule B5002 (BU2, 6 atoms)>, <Molecule A2
+  001 (XMP, 24 atoms)>, <Molecule A5001 (BU2, 6 atoms)>}
+
+In the first case all molecules (excluding water molecules) are returned - these
+include generic :py:class:`.Molecule` objects, used to represent the small
+molecules in the PDB, and also :py:class:`.Chain` objects, which are the main
+macromolecular unit of the PDB.
+
+Other criteria can be used:
+
+  >>> pdb.model().molecules(name="XMP")
+  {<Molecule B2002 (XMP, 24 atoms)>, <Molecule A2001 (XMP, 24 atoms)>}
+  >>> pdb.model().molecule(name="XMP")
+  <Molecule B2002 (XMP, 24 atoms)>
+  >>> pdb.model().molecule("B5002")
+  <Molecule B5002 (BU2, 6 atoms)>
+
+Here, all XMP molecules are returned, then the first matching XMP molecule, then
+the molecule with ID 'B5002'.
+
+Chains
+######
+
+You can specifically get chains in much the same way:
+
+  >>> pdb.model().chains()
+  {<Chain (214 residues)>, <Chain (204 residues)>}
+  >>> pdb.model().chain("A")
+  <Chain (204 residues)>
+  >>> pdb.model().chain("B")
+  <Chain (214 residues)>
+
+A :py:class:`.Chain` is a useful object in its own right:
+
+  >>> pdb.model().chain("A").length()
+  204
+
+Residues
+########
+
+Both models and chains are :py:class:`.ResidueStructure` objects, which allows
+you to access their :py:class:`.Residue` objects:
+
+  >>> pdb.model().residues(name="SER")
+  {<Residue B1221 (SER, 6 atoms)>, <Residue B1204 (SER, 6 atoms)>, <Residue B112
+  7 (SER, 6 atoms)>, <Residue A221 (SER, 6 atoms)>, <Residue A204 (SER, 6 atoms)
+  >, <Residue A179 (SER, 6 atoms)>, <Residue B1165 (SER, 6 atoms)>, <Residue B11
+  75 (SER, 6 atoms)>, <Residue A127 (SER, 6 atoms)>, <Residue B1050 (SER, 6 atom
+  s)>, <Residue B1158 (SER, 6 atoms)>, <Residue A158 (SER, 6 atoms)>, <Residue B
+  1105 (SER, 6 atoms)>, <Residue A165 (SER, 6 atoms)>, <Residue A175 (SER, 6 ato
+  ms)>, <Residue A50 (SER, 6 atoms)>, <Residue B1179 (SER, 6 atoms)>, <Residue A
+  105 (SER, 6 atoms)>}
+  >>> pdb.model().residue("A23")
+  <Residue A23 (ASN, 8 atoms)>
+
+Residues are also a kind of Molecule, and have other useful properties:
+
+  >>> pdb.model().residue("A23").name()
+  'ASN'
+  >>> pdb.model().residue("A23").chain()
+  <Chain (204 residues)>
+  >>> pdb.model().residue("A23").next()
+  <Residue A24 (ARG, 11 atoms)>
+  >>> pdb.model().residue("A23").previous()
+  <Residue A22 (MET, 8 atoms)>
+  
+
 Saving
 ~~~~~~
 
 A model can be saved to file using:
 
   >>> model.save("new.xyz", description="Modifed glucose")
+  >>> model.save("new.pdb")
+
+Any structure can be saved in this way, so you can save chains or molecules to
+their own seperate files if you so wish.
+
+  >>> model.chain("A").save("chainA.pdb")
+  >>> model.chain("B").save("chainB.pdb")
+  >>> model.molecule(name="XMP").save("ligand.xyz")
 
-The ``Xyz`` object itself can also be saved:
+The ``Xyz`` or ``Pdb`` object itself can also be saved:
 
   >>> glucose.comment("Modified glucose")
   >>> glucose.save("new.xyz")
+  >>> pdb.save("new.pdb")