added documentation

orbeckst · orbeckst · commit 524afddc4ed5 · 2018-10-05T00:04:06.000-07:00
- partially addresses #4 - uses styles from MDAnalysis and basic organization from alchemistry/alchemtest - added docs for all included datasets
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Changed
 
+### Added
+- documentation (#4)
+
 
 ## [0.2.0] - 2018-10-04
 ### Changed
diff --git a/MDAnalysisData/adk_equilibrium.py b/MDAnalysisData/adk_equilibrium.py
@@ -87,6 +87,7 @@ def fetch_adk_equilibrium(data_home=None, download_if_missing=True):
     dataset.DESCR : string
         Description of the trajectory.
 
+
     See :ref:`adk-equilibrium-dataset` for description.
     """
     name = NAME
diff --git a/MDAnalysisData/adk_transitions.py b/MDAnalysisData/adk_transitions.py
@@ -118,6 +118,7 @@ def fetch_adk_transitions_DIMS(data_home=None, download_if_missing=True):
     dataset.DESCR : string
         Description of the ensemble
 
+
     See :ref:`adk-transitions-DIMS-dataset` for description.
     """
     return _fetch_adk_transitions(METADATA['DIMS'],
@@ -149,6 +150,7 @@ def fetch_adk_transitions_FRODA(data_home=None, download_if_missing=True):
     dataset.DESCR : string
         Description of the ensemble
 
+
     See :ref:`adk-transitions-FRODA-dataset` for description.
     """
     return _fetch_adk_transitions(METADATA['FRODA'],
diff --git a/MDAnalysisData/base.py b/MDAnalysisData/base.py
@@ -83,12 +83,14 @@ def __setstate__(self, state):
 
 
 #: Each remote resource is described by a :class:`RemoteFileMetadata`,
-#: which is a :class:`namedtuple` with fields
+#: which is a :func:`~collections.namedtuple` with fields
+#:
 #: - *filename*: name of the file in the local file system
 #: - *url*: full URL for downloading
 #: - *checksum*: SHA256 (can be generated with :func:`MDAnalysisData.base._sha256`;
 #:   often it is just as convenient to run the downloader during testing and note the
 #:   required SHA256 then)
+#:
 RemoteFileMetadata = namedtuple('RemoteFileMetadata',
                                 ['filename', 'url', 'checksum'])
 
diff --git a/MDAnalysisData/descr/adk_equilibrium.rst b/MDAnalysisData/descr/adk_equilibrium.rst
@@ -1,9 +1,9 @@
 .. -*- coding: utf-8 -*-
+
 .. _`adk-equilibrium-dataset`:
 
-====================================
- AdK equilibrium trajectory dataset
-====================================
+AdK equilibrium trajectory dataset
+==================================
 
 MD trajectory of apo adenylate kinase with CHARMM27 force field and
 simulated with explicit water and ions in NPT at 300 K and 1
diff --git a/MDAnalysisData/descr/adk_transitions_DIMS.rst b/MDAnalysisData/descr/adk_transitions_DIMS.rst
@@ -1,18 +1,18 @@
 .. -*- coding: utf-8 -*-
 .. _`adk-transitions-DIMS-dataset`:
 
-=======================================
- AdK DIMS transitions ensemble dataset
-=======================================
+AdK DIMS transitions ensemble dataset
+=====================================
 
 The macromolecular conformational transition between the closed
 conformation of apo-adenylate kinase from E. coli (EcAdK) to the open
 conformation was sampled with two methods: (1) dynamic importance
-sampling molecular dynamics (DIMS MD), and (2) Framework Rigidity
-Optimized Dynamics Algorithm (FRODA). Each ensemble of independently
-generated paths contains 200 trajectories in the CHARMM DCD format.
+sampling molecular dynamics (DIMS MD) [Perilla2009]_, and (2)
+Framework Rigidity Optimized Dynamics Algorithm (FRODA)
+[Farrell2010]_. Each ensemble of independently generated paths
+contains 200 trajectories in the CHARMM DCD format.
 
-This data set contains the *DIMS* ensemble.
+This data set contains the **DIMS** ensemble.
 
 DIMS AdK (implicit solvent) with dynamic importance sampling MD from
 closed (1AKE) to open (4AKE). CHARMM 22 force field. Topology file:
@@ -34,8 +34,8 @@ Data set characteristics:
  :reference: [Seyler2015]_
     
 
-.. [Seyler2015]  Seyler SL, Kumar A, Thorpe MF, Beckstein O (2015)
-		 Path Similarity Analysis: A Method for Quantifying
-		 Macromolecular Pathways. PLoS Comput Biol 11(10):
-		 e1004568. https://doi.org/10.1371/journal.pcbi.1004568
+[Seyler2015] Seyler SL, Kumar A, Thorpe MF, Beckstein O (2015) Path
+	     Similarity Analysis: A Method for Quantifying
+	     Macromolecular Pathways. PLoS Comput Biol 11(10):
+	     e1004568. https://doi.org/10.1371/journal.pcbi.1004568
 
diff --git a/MDAnalysisData/descr/adk_transitions_FRODA.rst b/MDAnalysisData/descr/adk_transitions_FRODA.rst
@@ -1,16 +1,17 @@
 .. -*- coding: utf-8 -*-
 .. _`adk-transitions-FRODA-dataset`:
 
-========================================
- AdK FRODA transitions ensemble dataset
-========================================
+
+AdK FRODA transitions ensemble dataset
+======================================
 
 The macromolecular conformational transition between the closed
 conformation of apo-adenylate kinase from E. coli (EcAdK) to the open
 conformation was sampled with two methods: (1) dynamic importance
-sampling molecular dynamics (DIMS MD), and (2) Framework Rigidity
-Optimized Dynamics Algorithm (FRODA). Each ensemble of independently
-generated paths contains 200 trajectories in the CHARMM DCD format.
+sampling molecular dynamics (DIMS MD) [Perilla2009]_, and (2)
+Framework Rigidity Optimized Dynamics Algorithm (FRODA)
+[Farrell2010]_. Each ensemble of independently generated paths
+contains 200 trajectories in the CHARMM DCD format.
 
 This data set contains the *FRODA* ensemble.
 
@@ -33,8 +34,8 @@ Data set characteristics:
  :reference: [Seyler2015]_
     
 
-.. [Seyler2015]  Seyler SL, Kumar A, Thorpe MF, Beckstein O (2015)
-		 Path Similarity Analysis: A Method for Quantifying
-		 Macromolecular Pathways. PLoS Comput Biol 11(10):
-		 e1004568. https://doi.org/10.1371/journal.pcbi.1004568
+[Seyler2015] Seyler SL, Kumar A, Thorpe MF, Beckstein O (2015) Path
+	     Similarity Analysis: A Method for Quantifying
+	     Macromolecular Pathways. PLoS Comput Biol 11(10):
+	     e1004568. https://doi.org/10.1371/journal.pcbi.1004568
 
diff --git a/MDAnalysisData/descr/ifabp_water.rst b/MDAnalysisData/descr/ifabp_water.rst
@@ -1,9 +1,9 @@
 .. -*- coding: utf-8 -*-
+
 .. _`ifabp-water-dataset`:
 
-===========================
- I-FABP trajectory dataset
-===========================
+I-FABP in water dataset
+=======================
 
 The trajectory is a short MD run of I-FABP (intestinal fatty acid
 binding protein) in water.
@@ -14,8 +14,8 @@ protein.
 
 There are 500 frames in the trajectory.
 
-It is used as a test case for the
-[hop](https://github.com/Becksteinlab/hop) package.
+It is used as a test case for the `hop
+<https://github.com/Becksteinlab/hop>`_ package.
 
 
 Notes
diff --git a/MDAnalysisData/descr/vesicle_lib.rst b/MDAnalysisData/descr/vesicle_lib.rst
@@ -1,17 +1,17 @@
 .. -*- coding: utf-8 -*-
-.. _`adk-transitions-FRODA-dataset`:
 
-========================================
- Large System Vesicle Benchmark Library
-========================================
+.. _`vesicle-library-dataset`:
+
+Large System Vesicle Benchmark Library
+======================================
 
 Large benchmark systems for MDAnalysis (and other codes)
 
 Coarse-grained (DryMartini force field) vesicle systems were generated
-with the scripts in the
-[vesicle_library](https://github.com/Becksteinlab/vesicle_library) by
-Ian Kenney. All files are in GRO format and contain a static
-system. For further details about the data set see [Kenney2015]_.
+with the scripts in the `vesicle_library
+<https://github.com/Becksteinlab/vesicle_library>`_ by Ian Kenney. All
+files are in GRO format and contain a static system. For further
+details about the data set see [Kenney2015]_.
 
 The files are placed into the Public Domain (made available under the CC0 license).
 
diff --git a/MDAnalysisData/ifabp_water.py b/MDAnalysisData/ifabp_water.py
@@ -94,6 +94,7 @@ def fetch_ifabp_water(data_home=None, download_if_missing=True):
     dataset.DESCR : string
         Description of the trajectory.
 
+
     See :ref:`ifabp-water-dataset` for description.
     """
     name = NAME
diff --git a/MDAnalysisData/vesicles.py b/MDAnalysisData/vesicles.py
@@ -68,6 +68,7 @@ def fetch_vesicle_lib(data_home=None, download_if_missing=True):
     dataset.DESCR : string
         Description of the ensemble
 
+
     See :ref:`vesicle-library-dataset` for description.
     """
     metadata = METADATA['vesicle_lib']
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ Data are locally stored in the **data directory** `~/MDAnalysis_data`
 (i.e., in the user's home directory). This location can be changed by
 setting the environment variable `MDANALYSIS_DATA`, for instance
 ```bash
-MDANALYSIS_DATA=/tmp/MDAnalysis_data
+export MDANALYSIS_DATA=/tmp/MDAnalysis_data
 ```
 
 The location of the data directory can be obtained with
@@ -55,7 +55,7 @@ MDAnalysisData.base.get_data_home()
 
 If the data directory is removed then data are downloaded again. Data
 file integrity is checked with a SHA256 checksum when the file is
-downloaded (but not at later).
+downloaded.
 
 The data directory can we wiped with the function
 ```python
diff --git a/docs/adk_equilibrium.rst b/docs/adk_equilibrium.rst
@@ -0,0 +1,27 @@
+.. -*- coding: utf-8 -*-
+
+.. _adk-equilibrium:
+
+==========================
+ AdK equilibrium dataset
+==========================
+
+.. module:: MDAnalysisData.adk_equilibrium
+
+The :mod:`MDAnalysisData.adk_equilibrium` module contains a 1-µs
+equilibrium MD trajectory of a globular protein with ions included but
+solvent water molecules removed. It can be used to study protein
+dynamics and protein-ion interactions.
+
+.. currentmodule:: MDAnalysisData.adk_equilibrium
+
+.. autosummary::
+
+   fetch_adk_equilibrium
+
+
+.. include:: ../MDAnalysisData/descr/adk_equilibrium.rst
+
+.. autofunction:: fetch_adk_equilibrium
+
+		  
diff --git a/docs/adk_transitions.rst b/docs/adk_transitions.rst
@@ -0,0 +1,58 @@
+.. -*- coding: utf-8 -*-
+
+.. _adk-transitions:
+
+==========================
+ AdK transitions datasets
+==========================
+
+.. module:: MDAnalysisData.adk_transitions
+
+The :mod:`MDAnalysisData.adk_transitions` module contains ensembles of
+trajectories during which the close-to-open transiton of the enzyme
+adenylate kinase [Seyler2014]_ is sampled using different
+computational methods [Seyler2015]_.
+
+.. currentmodule:: MDAnalysisData.adk_transitions
+
+.. autosummary::
+
+   fetch_adk_transitions_DIMS
+   fetch_adk_transitions_FRODA   
+
+
+
+
+.. include:: ../MDAnalysisData/descr/adk_transitions_DIMS.rst
+
+.. autofunction:: fetch_adk_transitions_DIMS
+
+
+
+.. include:: ../MDAnalysisData/descr/adk_transitions_FRODA.rst
+
+.. autofunction:: fetch_adk_transitions_FRODA
+		  
+		  
+
+		  
+.. rubric:: References
+
+.. [Perilla2009] J. R. Perilla, O. Beckstein, E. J. Denning,
+    and T. Woolf. Computing ensembles of transitions from stable
+    states: Dynamic importance sampling. 32(2):186–209, 2011.
+
+.. [Farrell2010] D. W. Farrell, K. Speranskiy,
+    and M. F. Thorpe. Generating stereochemically acceptable protein
+    pathways. Proteins, 78(14):2908–21, Nov 2010.
+
+.. [Seyler2014] S. L. Seyler and O. Beckstein. Sampling of large
+   conformational transitions: Adenylate kinase as a testing
+   ground. Molec. Simul., 40(10–11):855–877, 2014.
+		
+.. [Seyler2015] Seyler SL, Kumar A, Thorpe MF, Beckstein O (2015) Path
+   Similarity Analysis: A Method for Quantifying Macromolecular
+   Pathways. PLoS Comput Biol 11(10): e1004568. doi:
+   `10.1371/journal.pcbi.1004568
+   <https://doi.org/10.1371/journal.pcbi.1004568>`_
+	    
diff --git a/docs/credits.rst b/docs/credits.rst
@@ -0,0 +1,20 @@
+.. -*- coding: utf-8 -*-
+   
+=========
+ Credits
+=========
+
+The **MDAnalysisData** package is modelled after `sklearn.datasets
+<http://scikit-learn.org/stable/modules/classes.html#module-sklearn.datasets>`_
+and uses some of its code (under the `BSD 3-clause license
+<https://github.com/scikit-learn/scikit-learn/blob/master/COPYING>`_).
+
+No data are included in this package; please see the `DESCR` attribute
+for each data set for authorship, citation, and license information
+for the data.
+
+**MDAnalysisData** is made available under the `GNU General Public
+License v3.0`_ (or any later version).
+
+.. _`GNU General Public License v3.0`:
+   https://www.gnu.org/licenses/gpl-3.0.en.html
diff --git a/docs/helpers.rst b/docs/helpers.rst
@@ -0,0 +1,38 @@
+.. _helpers:
+
+=========
+ Helpers
+=========
+
+A small number of functions and classes are included to help organize
+the data.
+
+.. currentmodule:: MDAnalysisData.base
+
+
+
+For users
+=========
+
+.. autoclass:: Bunch
+   :members:
+
+.. autofunction:: get_data_home
+
+.. autofunction:: clear_data_home
+
+
+For developers
+==============
+
+If you want to add your own dataset then you will likely use these
+functions in your code.
+
+
+.. autodata:: RemoteFileMetadata
+   
+.. autofunction:: _sha256
+
+.. autofunction:: _fetch_remote		  
+
+		  
diff --git a/docs/ifabp_water.rst b/docs/ifabp_water.rst
@@ -0,0 +1,28 @@
+.. -*- coding: utf-8 -*-
+
+.. _ifabp-water:
+
+================
+ I-FABP dataset
+================
+
+.. module:: MDAnalysisData.ifabp_water
+
+The :mod:`MDAnalysisData.ifabp_water` module contains a short
+equilibrium MD trajectory of the globular protein intestinal fatty
+acid binding protein (I-FABP) with all the solvent included (water and
+ions).  It can be used to study protein dynamics, protein-ion, and
+protein-water interactions.
+
+.. currentmodule:: MDAnalysisData.ifabp_water
+
+.. autosummary::
+
+   fetch_ifabp_water
+
+
+.. include:: ../MDAnalysisData/descr/ifabp_water.rst
+
+.. autofunction:: fetch_ifabp_water
+
+		  
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/install.rst b/docs/install.rst
diff --git a/docs/usage.rst b/docs/usage.rst
diff --git a/docs/vesicles.rst b/docs/vesicles.rst
