Finish documentation for module

package/MDAnalysis/analysis/contacts.py

@@ -17,12 +17,6 @@
 """Native contacts analysis --- :mod:`MDAnalysis.analysis.contacts`
 ================================================================
 
-    Notes
-    -----
-    Suggested cutoff distances for different simulations
-    * For all-atom simulations, cutoff = 4.5 A
-    * For coarse-grained simulations, cutoff = 6.0 A
-
 
 Analysis of native contacts *Q* over a trajectory. Native contacts of a
 conformation are contacts that exist in a reference structure and in the
@@ -100,23 +94,76 @@
 .. AdK_zipper_cartoon.avi:
    http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2803350/bin/NIHMS150766-supplement-03.avi
 
+Notes
+-----
+Suggested cutoff distances for different simulations
+* For all-atom simulations, cutoff = 4.5 A
+* For coarse-grained simulations, cutoff = 6.0 A
+
 Two-dimensional contact analysis (q1-q2)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Analyze a single DIMS transition of AdK between its closed and open
 conformation and plot the trajectory projected on q1-q2::
 
-  import MDAnalysis.analysis.contacts
-  from MDAnalysis.tests.datafiles import PSF, DCD
-  C = MDAnalysis.analysis.contacts.ContactAnalysis(PSF, DCD)
-  C.run()
-  C.plot()
+
+>>> import MDAnalysis as mda
+>>> from MDAnalysis.analysis import contacts
+>>> from MDAnalysisTests.datafiles import PSF, DCD
+>>> u = mda.Universe(PSF, DCD)
+>>> q1q2 = contacts.q1q2(u, 'name CA', radius=8)
+>>> q1q2.run()
+>>>
+>>> f, ax = plt.subplots(1, 2, figsize=plt.figaspect(0.5))
+>>> ax[0].plot(q1q2.timeseries[:, 0], q1q2.timeseries[:, 1], label='q1')
+>>> ax[0].plot(q1q2.timeseries[:, 0], q1q2.timeseries[:, 2], label='q2')
+>>> ax[0].legend(loc='best')
+>>> ax[1].plot(q1q2.timeseries[:, 1], q1q2.timeseries[:, 2], '.-')
+>>> f.show()
 
 Compare the resulting pathway to the `MinActionPath result for AdK`_.
 
 .. _MinActionPath result for AdK:
    http://lorentz.dynstr.pasteur.fr/joel/adenylate.php
 
+Writing your own contact analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ..class:`Contacts` has been designed to be extensible for your own
+analysis. As an example we will analysis when the acidic and basic groups of
+are in contact which each other, this means that at least one of the contacts
+formed in the reference is closer then 2.5 Angstrom. For this we define a new
+method to determine if any contact is closer then 2.5 Angström that implements
+the API ..class:`Contacts` except.
+
+The first to parameters `r` and `r0` are provided by ..class:`Contacts` the
+others can be passed as keyword args using the `kwargs` parameter in
+..class:`Contacts`.
+
+>>> def is_any_closer(r, r0, dist=2.5):
+>>>     return np.any(r < dist)
+
+Next we are creating an instance of the Constants class and use the
+`is_any_closer` function as an argument to `method` and run the analysus
+
+>>> nc = contacts.Contacts(u, selection=(sel_acidic, sel_basic),
+>>>                        method=is_any_closer,
+>>>                        refgroup=(acidic, basic), kwargs={'dist': 2.5})
+>>>
+>>> nc.run()
+>>>
+>>> folded = nc.timeseries[:, 1]
+>>> bound = nc.timeseries[:, 0]
+>>>
+>>> f, ax = plt.subplots()
+>>>
+>>> ax.plot(frames, bound, '.')
+>>> ax.set(xlabel='frame', ylabel='is Bound',
+>>>        ylim=(-0.1, 1.1))
+>>>
+>>> f.show()
+
+
 Classes
 -------
 
@@ -287,7 +334,7 @@ class Contacts(AnalysisBase):
         list containing *Q* for all refgroup pairs and analyzed frames
 
     """
-    def __init__(self, u, selection, refgroup, method="cutoff", radius=4.5,
+    def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
                  kwargs=None, start=None, stop=None, step=None,):
         """Initialization
 
@@ -316,7 +363,7 @@ def __init__(self, u, selection, refgroup, method="cutoff", radius=4.5,
             Step between frames to analyse, Default: 1
 
         """
-        if method == 'hard_cutf':
+        if method == 'hard_cut':
             self.fraction_contacts = hard_cut_q
         elif method == 'soft_cut':
             self.fraction_contacts = soft_cut_q