updated CHANGES and EnsembleAnalysis docs

CHANGES

@@ -5,7 +5,7 @@ CHANGES for MDPOW
 Add summary of changes for each release. Use ISO dates. Reference
 GitHub issues numbers and PR numbers.
 
-2021-??-??    0.8.0
+2021-12-29    0.8.0
 ALescoulie, orbeckst
 
 Changes
@@ -18,18 +18,17 @@ Changes
 
 Enhancements
 
+* new Ensemble and EnsembleAtomGroup objects for loading set of system
+  simulations (issue #168, PR #179)
+* new EnsembleAnalysis framework for collecting data from MDPOW simulations 
+  (issue #168, PR #179)
+* new EnsembleAnalysis: dihedrals (#190, PR #193)    
+* new EnsembleAnalysis: solvation shell (#195, PR #196)  
 * new exception config.NoSectionError to indicate missing section
   ("protocol") in the YAML run input file (PR #187)
 * new config.NoOptionWarning when undefined options are used (with
   default None) and POWConfigParser.get() now logs when an option is used
   at level DEBUG (PR #187)
-* new Ensemble and EnsembleAtomGroup objects for loading set of system
-  simulations (issue #168, PR #179)
-* new EnsembleAnalysis framework for collecting data from MDPOW simulations 
-  (issue #168, PR #179)
-* new SolvationAnalysis for quantifing the number of solvent molecules
-  within a given distance (#195)
-
 
 Fixes
 

doc/sphinx/source/analysis.txt

@@ -1,21 +1,59 @@
-==================
-Analysis Submodule
-==================
+========
+Analysis
+========
 
 .. versionadded:: 0.8.0
 
-MDPOW module for analyzing simulations. The :doc:`analysis/ensemble` objects
-and :doc:`analysis/ensemble_analysis` allow for the construction the simplified of analyses.
+The :mod:`mdpow.analysis` module contains tools for analyzing whole
+sets (ensembles) of FEP simulations and a framework to write new
+analysis tools [Lescoulie2021]_.
 
-The :doc:`analysis/ensemble` and :doc:`analysis/ensemble_analysis` sections
-assumes a basic understanding of object oriented programming in python and
-are for users who wish to construct their own analyses.
+.. _tools:
 
+Analysis tools
+--------------
+
+MDPOW analysis tools are based on the :ref:`framework`. They generally
+take as an input the top level directory of a complete FEP run and
+then collect individual simulations and run a specific analysis over
+all FEP simulations. They then make data available (typically, as a
+:class:`pandas.DataFrame`).
 
 .. toctree::
    :maxdepth: 1
 
-   analysis/ensemble
-   analysis/ensemble_analysis
    analysis/solvation
-   analysis/dihedral
+   analysis/dihedral
+
+
+.. _framework:   
+
+Ensemble Analysis Framework
+---------------------------
+
+The *Ensemble Analysis framework* [Lescoulie2021]_ allows for the
+construction analysis tools that work with whole sets (ensembles) of
+FEP simulations. They generally follow (and can use) standard
+MDAnalysis analysis classes.
+
+The :ref:`ensemble-objects` and :ref:`ensembleanalysis-base` sections
+assume a basic understanding of object oriented programming in Python
+and are for users who wish to construct their own analyses. The code
+in the :ref:`tools` serves as example implementations and is described
+in more detail in [Lescoulie2021]_.
+
+.. toctree::
+   :maxdepth: 1
+
+   analysis/ensemble_analysis	      
+   analysis/ensemble
+
+
+References
+----------
+.. [Lescoulie2021] A. Lescoulie, "SPIDAL Summer REU 2021: Upgrading MDPOW and
+		   adding analysis functionality," Technical Report, Arizona
+		   State University, Tempe, AZ, 2021. doi:
+		   `10.6084/m9.figshare.17156018`_
+
+.. _`10.6084/m9.figshare.17156018`: https://doi.org/10.6084/m9.figshare.17156018 		   

doc/sphinx/source/analysis/dihedral.txt

@@ -2,8 +2,9 @@
 Dihedral Analysis
 =================
 
-Analyzes selected dihedral angles over a multi-system simulation. Built using the :doc:`analysis/ensemble_analysis`
-Framework to run over a collection of systems contained in an :class:`~mdpow.analysis.ensemble.Ensemble` .
+Analyzes selected dihedral angles over a multi-system
+simulation. Built using the :ref:`framwework` to run over a collection
+of systems contained in an :class:`~mdpow.analysis.ensemble.Ensemble`.
 
 .. versionadded:: 0.8.0
 

doc/sphinx/source/analysis/ensemble.txt

@@ -1,11 +1,13 @@
+.. _ensemble-objects:
+
 ================
 Ensemble Objects
 ================
 
 .. versionadded:: 0.8.0
 
 Ensemble
-________
+--------
 
 The :class:`~mdpow.analysis.ensemble.Ensemble` object is a collection
 of :class:`MDAnalysis.Universe <MDAnalysis.core.groups.universe.Universe>` objects.
@@ -30,7 +32,7 @@ can also be built by manually adding and popping universes into an empty instanc
     .. automethod:: _load_universe_from_dir
 
 EnsembleAtomGroup
-_________________
+-----------------
 
 The :class:`~mdpow.analysis.ensemble.EnsembleAtomGroup` is created by running
 the  on an :class:`~mdpow.analysis.ensemble.Ensemble`

doc/sphinx/source/analysis/ensemble_analysis.txt

@@ -1,22 +1,18 @@
-============================
- Ensemble Analysis Framework
-============================
+.. _ensembleanalysis-base:
+
+==============================
+ Ensemble Analysis base class
+==============================
 
 .. versionadded:: 0.8.0
 
 The Analysis modules help in the implementation analyses of
 MDPOW simulations. To simplify the process of analyzing
 a collection of systems generated by a free energy simulation
-the objects in :doc:`analysis/ensemble` allow for a molecule directory's
+the objects in :ref:`ensemble-objects` allow for a molecule directory's
 systems to be loaded into `MDAnalysis <https://mdanalysis.org>`_
 Universes and be analyzed as a group.
 
-Ensemble Analysis Framework
-===========================
-
-EnsembleAnalysis
-----------------
-
 :class:`~mdpow.analysis.ensemble.EnsembleAnalysis` is a class inspired by the
 :class:`AnalysisBase <MDAnalysis.analysis.base.AnalysisBase>` from MDAnalysis which
 iterates over the systems in the ensemble and the frames in the systems. It sets up both iterations between

doc/sphinx/source/analysis/solvation.txt

@@ -2,11 +2,12 @@
 Solvation Shell Analysis
 ========================
 
-Analyzes the number of solvent molecules within given distances of the solute.
+Analyzes the number of solvent molecules within given distances of the
+solute. The solvation tool is built with the :ref:`framwework`.
 
 .. versionadded:: 0.8.0
 
 .. autoclass:: mdpow.analysis.solvation.SolvationAnalysis
     :members:
 
-    .. automethod:: run
+    .. automethod:: run

doc/sphinx/source/index.txt

@@ -139,9 +139,9 @@ For current issues and open feature requests please look through the
    scripts
    equil
    fep
+   analysis   
    utilities
    forcefields
-   analysis
 
 .. rubric:: Indices and tables