[WIP] Analysis

.gitignore

@@ -26,14 +26,22 @@ doc/build
 
 # ignore generated files
 *.vmd
+*.crd
 *.dcd
 *.xyz
 *.pdb
 *.trr
 *.ndx
 *.xtc
+*.pkl
+*.dat
 
 # example files
-doc/source/examples/*
-!doc/source/examples/*.ipynb
-!doc/source/examples/analysis/*.ipynb
+doc/source/examples/**/*.*
+!doc/source/examples/**/*.ipynb
+!doc/source/examples/**/*.rst
+!doc/source/examples/**/*.gif
+
+# backup files
+doc/source/examples/**/.*.ipynb
+

doc/source/conf.py

@@ -53,7 +53,8 @@
     'nbsphinx',
     'sphinx_rtd_theme',
     'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive'
+    'IPython.sphinxext.ipython_directive',
+    'sphinxcontrib.bibtex',
 ]
 
 pygments_style = 'default'
@@ -70,7 +71,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.ipynb_checkpoints', '**/.ipynb_checkpoints', 'scripts']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.ipynb_checkpoints', '**/.ipynb_checkpoints', 'scripts', '.*.ipynb']
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -111,7 +112,7 @@
     # Toc options
     'collapse_navigation': True,
     'sticky_navigation': True,
-    'navigation_depth': 5,
+    'navigation_depth': 4,
     'includehidden': True,
     'titles_only': False,
 }

doc/source/examples/README.rst

@@ -0,0 +1,29 @@
+
+========
+Examples
+========
+
+MDAnalysis maintains a collection of Jupyter notebooks as examples of what the code can do. Each notebook can be downloaded from the source repository to run on your own computer, or viewed as an online tutorial on the user guide.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: General
+
+   constructing_universe
+   transformations/README
+   parmed_sim
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Analysis
+
+   analysis/alignment_and_rms/README
+   analysis/distances_and_contacts/README
+   analysis/trajectory_similarity/README
+   analysis/hydrogen_bonding/README
+   analysis/structure/README
+   analysis/reduced_dimensions/README
+   analysis/polymers_and_membranes/README
+   analysis/volumetric/README
+

doc/source/examples/analysis/README.rst

@@ -0,0 +1,54 @@
+.. -*- coding: utf-8 -*-
+.. _analysis:
+
+========
+Analysis
+========
+
+The :mod:`~MDAnalysis.analysis` module of MDAnalysis provides the tools needed to analyse your data. 
+Several analyses are included with the package. These range from standard algorithms 
+(e.g. :ref:`calculating root mean squared quantities <alignment-and-rms>`) to unique algorithms such as 
+the `path similarity analysis <examples/analysis/trajectory_similarity/psa.ipynb>`__.
+
+Generally these bundled analyses are contributed by various researchers who use the code for their own work. 
+Please refer to the individual module documentation or relevant user guide tutorials for additional 
+references and citation information.
+
+If you need functionality that is not already provided in MDAnalysis, there are 
+`several ways to write your own analysis <examples/analysis/custom_trajectory_analysis.ipynb>`__.
+
+
+
+Imports and dependencies
+========================
+
+Analysis modules are not imported by default. In order to use them, you will need to import 
+them separately, e.g.::
+
+    from MDAnalysis.analysis import align
+
+.. note::
+
+    Several modules in :mod:`MDAnalysis.analysis` require additional Python packages. 
+    For example, :mod:`~MDAnalysis.analysis.encore` makes use of `scikit-learn <http://scikit-learn.org/>`__. 
+    The Python packages are not automatically installed with `pip`, although they are with `conda`.
+
+    Other modules require external programs. For example, :mod:`~MDAnalysis.analysis.hole` requires 
+    the `HOLE <http://www.holeprogram.org/>`_ programs. You will need to install these yourself.
+
+
+.. include:: /examples/analysis/alignment_and_rms/README.rst
+
+.. include:: /examples/analysis/distances_and_contacts/README.rst
+
+.. include:: /examples/analysis/trajectory_similarity/README.rst
+
+.. include:: /examples/analysis/hydrogen_bonding/README.rst
+
+.. include:: /examples/analysis/structure/README.rst
+
+.. include:: /examples/analysis/volumetric/README.rst
+
+.. include:: /examples/analysis/reduced_dimensions/README.rst
+
+.. include:: /examples/analysis/polymers_and_membranes/README.rst

doc/source/examples/analysis/alignment_and_rms/README.rst

@@ -0,0 +1,26 @@
+.. -*- coding: utf-8 -*-
+
+.. _alignment-and-rms:
+
+==========================
+Alignments and RMS fitting
+==========================
+
+The :mod:`MDAnalysis.analysis.align` and :mod:`MDAnalysis.analysis.rms` modules contain the functions used for aligning structures, aligning trajectories, and calculating root mean squared quantities. 
+
+.. note::
+
+    These modules use the fast QCP algorithm to calculate the root mean
+    square distance (RMSD) between two coordinate sets :cite:`theobald_rapid_2005` and
+    the rotation matrix *R* that minimizes the RMSD :cite:`liu_fast_2009`. Please
+    cite these references when using these modules.
+
+.. toctree::
+   :maxdepth: 1
+
+   /examples/analysis/alignment_and_rms/aligning_structure_to_another
+   /examples/analysis/alignment_and_rms/aligning_trajectory_to_first_frame
+   /examples/analysis/alignment_and_rms/aligning_trajectory
+   /examples/analysis/alignment_and_rms/rmsd
+   /examples/analysis/alignment_and_rms/pairwise_rmsd
+   /examples/analysis/alignment_and_rms/rmsf