From 1ff2b3939ca11cb7a2a63065bb48448f25b66924 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Fri, 3 Nov 2023 14:57:25 -0700 Subject: [PATCH 1/6] Cleaning up API docs --- docs/source/api.rst | 51 +++++++++++++++++-- docs/source/encore/bootstrap.rst | 6 +++ docs/source/encore/clustering.rst | 24 +++++++++ docs/source/encore/confdistmatrix.rst | 6 +++ docs/source/encore/covariance.rst | 6 +++ .../encore/dimensionality_reduction.rst | 18 +++++++ docs/source/encore/similarity.rst | 2 + docs/source/encore/utils.rst | 8 +++ docs/source/index.rst | 2 +- mdaencore/clustering/cluster.py | 6 ++- mdaencore/similarity.py | 7 ++- 11 files changed, 127 insertions(+), 9 deletions(-) create mode 100644 docs/source/encore/bootstrap.rst create mode 100644 docs/source/encore/clustering.rst create mode 100644 docs/source/encore/confdistmatrix.rst create mode 100644 docs/source/encore/covariance.rst create mode 100644 docs/source/encore/dimensionality_reduction.rst create mode 100644 docs/source/encore/similarity.rst create mode 100644 docs/source/encore/utils.rst diff --git a/docs/source/api.rst b/docs/source/api.rst index a1ca7f4..e6e33be 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -1,10 +1,51 @@ +================= API Documentation ================= -This documentation details the modules, classes, and functions in ``mdaencore``. +The package contains implementations of similarity measures between protein +ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and examples +are described in :footcite:p:`Tiberti2015`. + +The module includes facilities for handling ensembles and trajectories through +the :class:`Universe` class, performing clustering or dimensionality reduction +of the ensemble space, estimating multivariate probability distributions from +the input data, and more. ENCORE can be used to compare experimental and +simulation-derived ensembles, as well as estimate the convergence of +trajectories from time-dependent simulations. + +ENCORE includes three different methods for calculations of similarity measures +between ensembles implemented in individual functions: + + ++ **Harmonic Ensemble Similarity** : :func:`~mdaencore.similarity.hes` ++ **Clustering Ensemble Similarity** : :func:`~mdaencore.similarity.ces` ++ **Dimensional Reduction Ensemble Similarity** : :func:`mdaencore.similarity.dres` + +as well as two methods to evaluate the convergence of trajectories: + ++ **Clustering based convergence evaluation** : :func:`mdaencore.similarity.ces_convergence` ++ **Dimensionality-reduction based convergence evaluation** : :func:`mdaencore.similarity.dres_convergence` + + +When using this module in published work please cite :footcite:p:`Tiberti2015`. + + +Modules +------- + +.. toctree:: + :maxdepth: 1 + + encore/similarity + encore/clustering + encore/dimensionality_reduction + encore/confdistmatrix + encore/covariance + encore/bootstrap + encore/utils + -.. autosummary:: - :toctree: autosummary - :recursive: +References +---------- - mdaencore \ No newline at end of file +.. footbibliography:: diff --git a/docs/source/encore/bootstrap.rst b/docs/source/encore/bootstrap.rst new file mode 100644 index 0000000..b9908d9 --- /dev/null +++ b/docs/source/encore/bootstrap.rst @@ -0,0 +1,6 @@ +=================================================== +Bootstrap procedures --- :mod:`mdaencore.bootstrap` +=================================================== + +.. automodule:: mdaencore.bootstrap + :members: diff --git a/docs/source/encore/clustering.rst b/docs/source/encore/clustering.rst new file mode 100644 index 0000000..343944e --- /dev/null +++ b/docs/source/encore/clustering.rst @@ -0,0 +1,24 @@ +============ + Clustering +============ + +.. automodule:: mdaencore.clustering.cluster + :members: + +.. automodule:: mdaencore.clustering.ClusterCollection + :members: + +.. automodule:: mdaencore.clustering.ClusteringMethod + :members: + + +Clustering algorithms +===================== + +The following clustering algorithms are always available: + +.. automodule:: mdaencore.clustering.affinityprop + :members: + + + diff --git a/docs/source/encore/confdistmatrix.rst b/docs/source/encore/confdistmatrix.rst new file mode 100644 index 0000000..810a080 --- /dev/null +++ b/docs/source/encore/confdistmatrix.rst @@ -0,0 +1,6 @@ +================================================================ +Distance matrix calculations --- :mod:`mdaencore.confdistmatrix` +================================================================ + +.. automodule:: mdaencore.confdistmatrix + :members: diff --git a/docs/source/encore/covariance.rst b/docs/source/encore/covariance.rst new file mode 100644 index 0000000..bcccd55 --- /dev/null +++ b/docs/source/encore/covariance.rst @@ -0,0 +1,6 @@ +====================================================== +Covariance calculation --- :mod:`mdaencore.covariance` +====================================================== + +.. automodule:: mdaencore.covariance + :members: diff --git a/docs/source/encore/dimensionality_reduction.rst b/docs/source/encore/dimensionality_reduction.rst new file mode 100644 index 0000000..e022750 --- /dev/null +++ b/docs/source/encore/dimensionality_reduction.rst @@ -0,0 +1,18 @@ +========================== + Dimensionality reduction +========================== + +.. automodule:: mdaencore.dimensionality_reduction.reduce_dimensionality + :members: + +.. automodule:: mdaencore.dimensionality_reduction.DimensionalityReductionMethod + :members: + +Dimensionality reduction algorithms +=================================== + +The following dimensionality reduction algorithms are always natively +available: + +.. automodule:: mdaencore.dimensionality_reduction.stochasticproxembed + :members: diff --git a/docs/source/encore/similarity.rst b/docs/source/encore/similarity.rst new file mode 100644 index 0000000..aa99f0a --- /dev/null +++ b/docs/source/encore/similarity.rst @@ -0,0 +1,2 @@ +.. automodule:: mdaencore.similarity + :members: diff --git a/docs/source/encore/utils.rst b/docs/source/encore/utils.rst new file mode 100644 index 0000000..136d979 --- /dev/null +++ b/docs/source/encore/utils.rst @@ -0,0 +1,8 @@ +============================== + Utility functions for ENCORE +============================== + +.. automodule:: mdaencore.utils + :members: + +.. autofunction:: mdaencore.cutils.PureRMSD diff --git a/docs/source/index.rst b/docs/source/index.rst index 0073cb7..22a598d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,7 +7,7 @@ Welcome to mdaencore's documentation! ========================================================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: :hidden: diff --git a/mdaencore/clustering/cluster.py b/mdaencore/clustering/cluster.py index a1682c5..350dd29 100644 --- a/mdaencore/clustering/cluster.py +++ b/mdaencore/clustering/cluster.py @@ -20,7 +20,11 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""The module defines a function serving as front-end for various clustering +"""\ +clustering frontend --- :mod:`mdaencore.clustering.cluster` +============================================================================ + +The module defines a function serving as front-end for various clustering algorithms, wrapping them to allow them to be used interchangably. """ import numpy as np diff --git a/mdaencore/similarity.py b/mdaencore/similarity.py index bfc1765..4ea4a98 100644 --- a/mdaencore/similarity.py +++ b/mdaencore/similarity.py @@ -20,7 +20,11 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -"""\ +""" +================================================================ +Ensemble Similarity Calculations --- :mod:`mdaencore.similarity` +================================================================ + The module contains implementations of similarity measures between protein ensembles. @@ -50,7 +54,6 @@ When using this module in published work please cite :footcite:p:`Tiberti2015`. -.. _Examples: Examples ======== From 410ab4ac1c9b203ba4e7fa9c5388bea54c3ed398 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Fri, 3 Nov 2023 15:08:20 -0700 Subject: [PATCH 2/6] Moved section heading out of docstring --- docs/source/encore/similarity.rst | 4 ++++ mdaencore/similarity.py | 6 +----- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/encore/similarity.rst b/docs/source/encore/similarity.rst index aa99f0a..2fe6dbe 100644 --- a/docs/source/encore/similarity.rst +++ b/docs/source/encore/similarity.rst @@ -1,2 +1,6 @@ +================================================================ +Ensemble Similarity Calculations --- :mod:`mdaencore.similarity` +================================================================ + .. automodule:: mdaencore.similarity :members: diff --git a/mdaencore/similarity.py b/mdaencore/similarity.py index 4ea4a98..8be3c97 100644 --- a/mdaencore/similarity.py +++ b/mdaencore/similarity.py @@ -20,11 +20,7 @@ # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787 # -""" -================================================================ -Ensemble Similarity Calculations --- :mod:`mdaencore.similarity` -================================================================ - +"""\ The module contains implementations of similarity measures between protein ensembles. From 83690e5082884541f78bf21f07ff9ea89f475a25 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Mon, 6 Nov 2023 12:57:41 -0700 Subject: [PATCH 3/6] Moved the package overview from API to index --- docs/source/api.rst | 29 ++--------------------------- docs/source/index.rst | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 27 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index e6e33be..0754cbe 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -2,33 +2,8 @@ API Documentation ================= -The package contains implementations of similarity measures between protein -ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and examples -are described in :footcite:p:`Tiberti2015`. - -The module includes facilities for handling ensembles and trajectories through -the :class:`Universe` class, performing clustering or dimensionality reduction -of the ensemble space, estimating multivariate probability distributions from -the input data, and more. ENCORE can be used to compare experimental and -simulation-derived ensembles, as well as estimate the convergence of -trajectories from time-dependent simulations. - -ENCORE includes three different methods for calculations of similarity measures -between ensembles implemented in individual functions: - - -+ **Harmonic Ensemble Similarity** : :func:`~mdaencore.similarity.hes` -+ **Clustering Ensemble Similarity** : :func:`~mdaencore.similarity.ces` -+ **Dimensional Reduction Ensemble Similarity** : :func:`mdaencore.similarity.dres` - -as well as two methods to evaluate the convergence of trajectories: - -+ **Clustering based convergence evaluation** : :func:`mdaencore.similarity.ces_convergence` -+ **Dimensionality-reduction based convergence evaluation** : :func:`mdaencore.similarity.dres_convergence` - - -When using this module in published work please cite :footcite:p:`Tiberti2015`. - +This section contains an overview of the ``mdaencore`` API. +For higher level examples of how to use the software, see the `ENCORE section `_ of the MDAnalysis User Guide. Modules ------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 22a598d..a1cc98d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,30 @@ Welcome to mdaencore's documentation! getting_started api +The package contains implementations of similarity measures between protein +ensembles described in :footcite:p:`LindorffLarsen2009`. The implementation and examples +are described in :footcite:p:`Tiberti2015`. + +The module includes facilities for handling ensembles and trajectories through +the :class:`Universe` class, performing clustering or dimensionality reduction +of the ensemble space, estimating multivariate probability distributions from +the input data, and more. ENCORE can be used to compare experimental and +simulation-derived ensembles, as well as estimate the convergence of +trajectories from time-dependent simulations. + +ENCORE includes three different methods for calculations of similarity measures +between ensembles implemented in individual functions: + ++ **Harmonic Ensemble Similarity** : :func:`~mdaencore.similarity.hes` ++ **Clustering Ensemble Similarity** : :func:`~mdaencore.similarity.ces` ++ **Dimensional Reduction Ensemble Similarity** : :func:`mdaencore.similarity.dres` + +as well as two methods to evaluate the convergence of trajectories: + ++ **Clustering based convergence evaluation** : :func:`mdaencore.similarity.ces_convergence` ++ **Dimensionality-reduction based convergence evaluation** : :func:`mdaencore.similarity.dres_convergence` + +When using this module in published work please cite :footcite:p:`Tiberti2015`. The `mdaencore` MDAKit moves the functionality of integrated ENCORE module out of the MDAnalysis core library, thereby deprecating it in MDAnalysis release 2.7.0 with a planned removal in release 3.0.0. The original authors for the MDAnalysis implementation of ENCORE are Matteo Tiberti, Wouter Boomsma, Tone Bengtsen, as well as those listed in ``AUTHORS.md``. From 60f151dcedf3022e86274d81c32ff060b8c0eb70 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Mon, 6 Nov 2023 13:32:31 -0700 Subject: [PATCH 4/6] Updated CHANGELOG --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 635dbc0..1bdfc78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,12 +22,13 @@ The rules for this file: - IAlibay - lilyminium - orbeckst +- ianmkenney ### Added - wheel deployment workflow (#22) ### Fixed -- documentation fixes (#13, #18) +- documentation fixes (#13, #18, #49) ### Changed From 756e551e222f3478ba1a27a01408a227ba8bf378 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Mon, 6 Nov 2023 13:39:25 -0700 Subject: [PATCH 5/6] Added a note on imports --- docs/source/api.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/api.rst b/docs/source/api.rst index 0754cbe..3ebda84 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -4,6 +4,8 @@ API Documentation This section contains an overview of the ``mdaencore`` API. For higher level examples of how to use the software, see the `ENCORE section `_ of the MDAnalysis User Guide. +Note that the user guide imports the ENCORE implementation in the core library, as the current version of MDAnalysis still has this functionality. +To use these examples, import ``mdaencore`` rather than ``MDAnalysis.analysis.encore``. Modules ------- From 0577d58a6d55e5c906eeb77c3d9f6fca2c094065 Mon Sep 17 00:00:00 2001 From: Ian Kenney Date: Wed, 8 Nov 2023 09:33:43 -0700 Subject: [PATCH 6/6] Use seealso directive --- docs/source/api.rst | 3 --- docs/source/index.rst | 11 +++++++++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index 3ebda84..9fa7fa6 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -3,9 +3,6 @@ API Documentation ================= This section contains an overview of the ``mdaencore`` API. -For higher level examples of how to use the software, see the `ENCORE section `_ of the MDAnalysis User Guide. -Note that the user guide imports the ENCORE implementation in the core library, as the current version of MDAnalysis still has this functionality. -To use these examples, import ``mdaencore`` rather than ``MDAnalysis.analysis.encore``. Modules ------- diff --git a/docs/source/index.rst b/docs/source/index.rst index a1cc98d..4540722 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,6 +39,12 @@ as well as two methods to evaluate the convergence of trajectories: When using this module in published work please cite :footcite:p:`Tiberti2015`. +.. seealso:: + + For higher level examples of how to use the software, see the `ENCORE section `_ of the MDAnalysis User Guide. + Note that the user guide imports the ENCORE implementation in the core library, as the current version of MDAnalysis still has this functionality. + To use these examples, import ``mdaencore`` rather than ``MDAnalysis.analysis.encore``. + The `mdaencore` MDAKit moves the functionality of integrated ENCORE module out of the MDAnalysis core library, thereby deprecating it in MDAnalysis release 2.7.0 with a planned removal in release 3.0.0. The original authors for the MDAnalysis implementation of ENCORE are Matteo Tiberti, Wouter Boomsma, Tone Bengtsen, as well as those listed in ``AUTHORS.md``. @@ -48,3 +54,8 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +References +---------- + +.. footbibliography::