duecredits

.coveragerc

@@ -6,6 +6,7 @@ omit =
     */visualization/*
     */MDAnalysis/tests/*
     */legacy/*
+    */due.py
 
 [report]
 exclude_lines =

.travis.yml

@@ -31,6 +31,7 @@ env:
     - CONDA_DEPENDENCIES="${CONDA_MIN_DEPENDENCIES} seaborn>=0.7.0 clustalw=2.1 netcdf4 scikit-learn coveralls"
     - CONDA_CHANNELS='biobuilds conda-forge'
     - CONDA_CHANNEL_PRIORITY=True
+    - PIP_DEPENDENCIES="duecredit"
     - NUMPY_VERSION=stable
     - INSTALL_HOLE="true"
 

package/AUTHORS

@@ -100,7 +100,7 @@ Chronological list of authors
   - Mateusz Bieniek
   - Navya Khare
   - Johannes Zeman
-
+  - Ayush Suhane
 
 External code
 -------------

package/CHANGELOG

@@ -14,7 +14,7 @@ The rules for this file:
 
 ------------------------------------------------------------------------------
 mm/dd/18 richardjgowers, palnabarun, bieniekmateusz, kain88-de, orbeckst,
-         xiki-tempula, navyakhare, zemanj
+         xiki-tempula, navyakhare, zemanj, ayushsuhane
 
   * 0.17.1
 
@@ -31,6 +31,8 @@ Enhancements
     to specify what is on each line.  Eg atom_style = 'id type charge x y z'
     (Issue #1791)
   * Added periodic boundary condition option to HydrogenBondAnalysis (Issue #1188)
+  * Added duecredit to prepare a summary of the citations, when a user
+    uses MDAnalysis (Issue #412)
 
 Fixes
   * Fixed MPI fork() warning when importing MDAnalysis in an Infiniband-enabled

package/MDAnalysis/__init__.py

@@ -200,3 +200,36 @@
 from .coordinates.MMTF import fetch_mmtf
 
 from .migration.ten2eleven import ten2eleven
+
+from .due import due, Doi, BibTeX
+
+due.cite(BibTeX((
+            "@inproceedings{gowers2016, "
+            "title={MDAnalysis: A Python package for the rapid analysis "
+            "of molecular dynamics simulations}, "
+            "author={R. J. Gowers and M. Linke and "
+            "J. Barnoud and T. J. E. Reddy and M. N. Melo "
+            "and S. L. Seyler and D. L. Dotson and J. Domanski, and "
+            "S. Buchoux and I. M. Kenney and O. Beckstein},"
+            "journal={Proceedings of the 15th Python in Science Conference}, "
+            "pages={102-109}, "
+            "year={2016}, "
+            "editor={S. Benthall and S. Rostrup}, "
+            "note={Austin, TX, SciPy.} "
+            "}"
+            )),
+         description=
+         "Description of recent updates and new functionality "
+         "in MDAnalysis since release 0.7.2 (March 2011) up to "
+         "release 0.16.0 (April 2017). Please cite together with "
+         "Michaud-Agrawal et al 2011. ",
+         path="MDAnalysis/", cite_module=True)
+due.cite(Doi("10.1002/jcc.21787"),
+         description=
+         "Description of MDAnalysis up to release 0.7.2 (March 2011), "
+         "including the basic philosophy of the library and the "
+         "LeafletFinder algorithm. Please cite together with "
+         "Gowers et al 2016. ",
+         path="MDAnalysis/", cite_module=True)
+
+del Doi, BibTeX

package/MDAnalysis/due.py

@@ -0,0 +1,99 @@
+# emacs: at the end of the file
+# ex: set sts=4 ts=4 sw=4 et:
+# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### #
+"""Stub file for a guaranteed safe import of duecredit constructs:  if duecredit
+is not available.
+
+To use it, place it into your project codebase to be imported, e.g. copy as
+
+    cp stub.py /path/tomodule/module/due.py
+
+Note that it might be better to avoid naming it duecredit.py to avoid shadowing
+installed duecredit.
+
+Then use in your code as
+
+    from .due import due, Doi, BibTeX
+
+See  https://github.com/duecredit/duecredit/blob/master/README.md for examples.
+
+Origin:     Originally a part of the duecredit
+Copyright:  2015-2016  DueCredit developers
+License:    BSD-2
+
+Modified for MDAnalysis to avoid calls to fork which raises cryptic
+warning under MPI(see PR #1794 for rationale)
+
+"""
+
+__version__ = '0.0.5'
+
+
+class InactiveDueCreditCollector(object):
+    """Just a stub at the Collector which would not do anything"""
+    def _donothing(self, *args, **kwargs):
+        """Perform no good and no bad"""
+        pass
+
+    def dcite(self, *args, **kwargs):
+        """If I could cite I would"""
+        def nondecorating_decorator(func):
+            return func
+        return nondecorating_decorator
+
+    cite = load = add = _donothing
+
+    def __repr__(self):
+        return self.__class__.__name__ + '()'
+
+
+def _donothing_func(*args, **kwargs):
+    """Perform no good and no bad"""
+    pass
+
+
+try:
+    # Avoid call of fork inside duecredit; see
+    # https://github.com/MDAnalysis/mdanalysis/pull/1822#issuecomment-373009050
+    import sys
+    import os
+    if sys.version_info >= (3, 7):
+        import duecredit
+    else:
+        from mock import patch
+        if sys.version_info <= (2, ):
+            from contextlib import nested
+            with nested(patch('os.fork'), patch('os.popen')) \
+                 as (os_dot_fork, os_dot_popen):
+                import duecredit
+        else:
+            with patch('os.fork') as os_dot_fork, patch('os.popen') as os_dot_popen:
+                import duecredit
+
+    from duecredit import due, BibTeX, Doi, Url
+    if 'due' in locals() and not hasattr(due, 'cite'):
+        raise RuntimeError(
+            "Imported due lacks .cite. DueCredit is now disabled")
+except Exception as err:
+    if not isinstance(err, ImportError):
+        import logging
+        import warnings
+        errmsg = "Failed to import duecredit due to {}".format(str(err))
+        warnings.warn(errmsg)
+        logging.getLogger("duecredit").error(
+            "Failed to import duecredit due to {}".format(str(err)))
+    else:
+        # for debugging
+        import warnings
+        warnings.warn(str(err))
+    # Initiate due stub
+    due = InactiveDueCreditCollector()
+    BibTeX = Doi = Url = _donothing_func
+
+# Emacs mode definitions
+# Local Variables:
+# mode: python
+# py-indent-offset: 4
+# tab-width: 4
+# indent-tabs-mode: nil
+# End:

package/doc/sphinx/source/documentation_pages/references.rst

@@ -112,6 +112,46 @@ If you use the streamline visualization in
 .. _`10.1039/c3fd00145h`: https://doi.org/10.1039/c3fd00145h
 
 
-Thanks!
+Citations using Duecredit
+=========================
 
+Citations can be automatically generated using duecredit_, depending on the
+packages used. Duecredit is easy to install via ``pip``. Simply type:
+
+.. code-block:: bash
+
+   pip install duecredit
+
+duecredit_ will remain an optional dependency, i.e. any code using
+MDAnalysis will work correctly even without duecredit installed.
+
+A list of citations for ``yourscript.py`` can be obtained using simple
+commands.
+
+.. code-block:: bash
+
+   cd /path/to/yourmodule
+   python -m duecredit yourscript.py
+
+or set the environment variable :envvar:`DUECREDIT_ENABLE`
+
+.. code-block:: bash
+
+   DUECREDIT-ENABLE=yes python yourscript.py
+
+Once the citations have been extracted (to a hidden file in the
+current directory), you can use the :program:`duecredit` program to
+export them to different formats. For example, one can display them in
+BibTeX format, using:
+
+.. code-block:: bash
+
+   duecredit summary --format=bibtex 
+
+
+**Please cite your use of MDAnalysis and the packages and algorithms
+that it uses. Thanks!**
+
+
+.. _duecredit: https://github.com/duecredit/duecredit
 

package/setup.py

@@ -519,6 +519,7 @@ def dynamic_author_list():
               'joblib',
               'scipy>=1.0.0',
               'matplotlib>=1.5.1',
+              'mock',
           ],
           # extras can be difficult to install through setuptools and/or
           # you might prefer to use the version available through your

testsuite/AUTHORS

@@ -80,8 +80,11 @@ Chronological list of authors
   - Ruggero Cortini
   - Sören von Bülow
   - Mateusz Bieniek
+
 2018
   - Johannes Zeman
+  - Ayush Suhane
+
 
 External code
 -------------

testsuite/MDAnalysisTests/__init__.py

@@ -102,6 +102,15 @@
 import os
 import sys
 
+# To test duecredit in utils/test_duecredits.py.
+#
+# Note that the test environment on travis should have duecredit installed
+# (put it in PIP_DEPENDENCIES). Setting DUECREDIT_ENABLE to yes triggers
+# collection of citations on the first `import MDAnalysis` so the environment
+# variable *must* come before MDAnalysis is imported the first time. See
+# issue #412 https://github.com/MDAnalysis/mdanalysis/issues/412 and PR #1822.
+os.environ['DUECREDIT_ENABLE'] = 'yes'
+
 # Any tests that plot with matplotlib need to run with the simple agg backend because
 # on Travis there is no DISPLAY set
 try:

testsuite/MDAnalysisTests/utils/test_duecredits.py

@@ -0,0 +1,47 @@
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 fileencoding=utf-8
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the GNU Public Licence, v2 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+from __future__ import absolute_import
+import os
+import pytest
+
+# environment variable DUECREDIT_ENABLE is set to yes in MDAnalysisTests/__init__.py
+# (if set to 'no', the tests will be SKIPPED; has to be yes, true, or 1 for duecredit
+# to work; duecredit must also be installed)
+import MDAnalysis as mda
+
+
+@pytest.mark.skipif((os.environ.get('DUECREDIT_ENABLE', 'yes').lower()
+                     in ('no', '0', 'false')),
+                    reason=
+                    "duecredit is explicitly disabled with DUECREDIT_ENABLE=no")
+class TestDuecredits(object):
+
+    def test_duecredit_active(self):
+        assert mda.due.active == True
+
+
+    def test_duecredit_collector_citations(self):
+
+        assert mda.due.citations[('MDAnalysis/',
+                                  'gowers2016')].cites_module == True
+        assert mda.due.citations[('MDAnalysis/',
+                                  '10.1002/jcc.21787')].cites_module == True