Merge pull request #26 from DeepRank/update_paper_doc

Update paper doc

Author: NicoRenaud

docs/source/index.rst

@@ -30,6 +30,7 @@ Python API
     Interface <pdb2sql.interface>
     Structure Similarity <pdb2sql.StructureSimilarity>
     Structure Transformation <pdb2sql.transform>
+    Utilities <pdb2sql.utils>
 
 .. :caption: Python API
 ..

docs/source/pdb2sql.utils.rst

@@ -0,0 +1,17 @@
+=========
+Utilities
+=========
+.. currentmodule:: pdb2sql.utils
+
+PDB Tools
+~~~~~~~~~
+.. autosummary::
+    :toctree: api/
+
+    fetch
+
+..
+    .. automodule:: pdb2sql.transform
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/tutorial.rst

@@ -11,16 +11,30 @@
 
 This is a short introduction to pdb2sql.
 
-First, we import as follows:
+
+Download PDB files
+------------------
+
+A handy tool `fetch` is provided to download PDB files from `PDB <https://www.rcsb.org>`_ website.
 
 .. ipython:: python
 
-    from pdb2sql import pdb2sql
+    from pdb2sql import fetch
+    fetch('3CRO', './pdb/')
+    ls ./pdb
 
+For clear illustration, some `dummy PDB files <https://github.com/DeepRank/pdb2sql/tree/master/docs/pdb>`_
+are used in the following examples.
 
 Get and set data
 ----------------
 
+First, we import as follows:
+
+.. ipython:: python
+
+    from pdb2sql import pdb2sql
+
 Create a SQL database instance:
 
 .. ipython:: python

paper/paper.md

@@ -123,6 +123,19 @@ atoms = pdb.get_contact_atoms(cutoff=6.0)
 res = pdb.get_contact_residues(cutoff=6.0)
 ```
 
+It is also possible to directly create an ``interface`` instance with a ``pdb2sql`` instance as input. In this case, all the changes in the ``pdb2sql`` instance before creating the new ``interface`` instance will be kept in the ``interface`` instance; afterwards, the two instances will be independent, which means changes in one will not affect the other.
+
+```python
+from pdb2sql import pdb2sql
+from pdb2sql import interface
+
+pdb = pdb2sql('1AK4.pdb')
+pdbitf = interface(pdb)
+atoms = pdbitf.get_contact_atoms(cutoff=6.0)
+res = pdbitf.get_contact_residues(cutoff=6.0)
+```
+
+
 ## Computing Structure Similarity
 
 The ``StructureSimilarity`` class allows to compute similarity measures between two protein-protein complexes. Several popular measures used to classify qualities of protein complex structures in the CAPRI (Critical Assessment of PRedicted Interactions) challenges [@capri] have been implemented: interface rmsd, ligand rmsd,  fraction of native contacts and DockQ[@dockq]. The approach implemented to compute the interface rmsd and ligand rmsd is identical to the well-known package ``ProFit`` [@profit]. All the methods required to superimpose structures have been implemented in the ``transform`` class and therefore relies on no external dependencies. The following snippet shows how to compute these measures: