[WIP] Analysis

.gitignore

@@ -26,14 +26,23 @@ 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
+!doc/source/examples/**/*.png
+
+# backup files
+doc/source/examples/**/.*.ipynb
+

doc/source/conf.py

@@ -13,6 +13,7 @@
 # import os
 # import sys
 
+from collections import OrderedDict
 import MDAnalysis as mda
 # import subprocess
 import sphinx_rtd_theme
@@ -28,11 +29,11 @@
 # Get Travis to regenerate txt tables by re-running scripts
 # before deploying docs.
 # Turned off for now as 0.21.0 not released yet.
-# This allows us to gitignore .txt files as well as 
+# This allows us to gitignore .txt files as well as
 # auto-recreate tables for each deployment.
-# Turn off if using sphinx_autobuild as this will autobuild 
+# Turn off if using sphinx_autobuild as this will autobuild
 # to infinity.
-# 
+#
 # subprocess.call('./scripts/generate_all.sh')
 
 # -- General configuration ---------------------------------------------------
@@ -53,7 +54,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 +72,10 @@
 # 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', '.*.ipynb']
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store',
+                    '.ipynb_checkpoints', '**/.ipynb_checkpoints', 'scripts', '.*.ipynb']
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -90,9 +95,8 @@
 color = {'orange': '#FF9200',
          'gray': '#808080',
          'white': '#FFFFFF',
-         'black': '#000000',}
+         'black': '#000000', }
 
-from collections import OrderedDict
 extra_nav_links = OrderedDict()
 extra_nav_links['MDAnalysis'] = 'http://mdanalysis.org'
 extra_nav_links['docs'] = 'http://docs.mdanalysis.org'
@@ -107,11 +111,11 @@
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
-    'style_nav_header_background': 'white', #'#e76900', # dark orange
+    'style_nav_header_background': 'white',  # '#e76900', # dark orange
     # Toc options
     'collapse_navigation': True,
     'sticky_navigation': True,
-    'navigation_depth': 5,
+    'navigation_depth': 4,
     'includehidden': True,
     'titles_only': False,
 }
@@ -120,14 +124,14 @@
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 html_favicon = "_static/logos/mdanalysis-logo.ico"
-html_logo =  '_static/logos/user_guide.png'
+html_logo = '_static/logos/user_guide.png'
 
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-html_css_files = ['custom.css']#, 'readable.css']
+html_css_files = ['custom.css']  # , 'readable.css']
 
 # Custom sidebar templates, maps document names to template names.
 # alabaster sidebars
@@ -150,14 +154,25 @@
 
 # nbsphinx
 html_js_files = [
-    'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js',
-    DEFAULT_EMBED_REQUIREJS_URL,
+    # 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js',
+    # DEFAULT_EMBED_REQUIREJS_URL,
 ]
 
+nbsphinx_prolog = r"""
+.. raw:: html
+
+    <script src='http://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js'></script>
+    <script>require=requirejs;</script>
+
+
+"""
+
+ipython_warning_is_error = False
+
 # substitutions
-MDAnalysis_version = '0.20.1'
+MDAnalysis_version = '1.0.0'
 
 # rst-epilog implements substitutions
 rst_epilog = """
 .. |MDAnalysis_version| replace:: {0}
-""".format(MDAnalysis_version)
+""".format(MDAnalysis_version)

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