Standardize atomicdistances to use results

package/AUTHORS

@@ -277,6 +277,7 @@ Chronological list of authors
   - Ayush Agarwal
   - Parth Uppal
   - Olivier Languin--Cattoën
+  - Charity Grey
 
 External code
 -------------

package/CHANGELOG

@@ -22,6 +22,7 @@ The rules for this file:
  * 2.11.0
 
 Fixes
+ * `MDAnalysis.analysis.atomicdistances.AtomicDistances` results are now consistent with expected `analysis` documentation data type = Results (Issue #4819, PR #5347) Note: This fix is backwards-incompatible.
  * Fix mixed-case atom types in guess_bonds (Issue #5342, PR #5343)
  * Fixes msd for non-linear frames, when non_linear is not explicitly
    provided (Issue #5100, PR #5254)
@@ -38,7 +39,7 @@ Fixes
    incomprehensible broadcasting error at execution time (Issue #5046, PR #5163)
  * Fixes the verbose=False in EinsteinMSD, and only shows progress bar when
    verbose=True (Issue #5144, PR #5153)
- * Fix incorrect assignment of topology_format to format (and vice versa)
+ * Fix incorrect assignment of topology_format to format (and vexice versa)
    when a parsing class is provided to either (Issue #5147, PR #5148)
  * Fix incorrect TPR file parsing for GROMACS topologies produced prior
    to version 5.1.0 (Issue #5145, PR #5146)

package/MDAnalysis/analysis/atomicdistances.py

@@ -74,10 +74,10 @@
    >>> ag2 = u.atoms[4000:4005]
 
 We can run the calculations using any variable of choice such as
-``my_dists`` and access our results using ``my_dists.results``: ::
+``my_dists`` and access our results using ``my_dists.results.distances``: ::
 
    >>> my_dists = ad.AtomicDistances(ag1, ag2).run()
-   >>> my_dists.results
+   >>> my_dists.results.distances
    array([[37.80813681, 33.2594864 , 34.93676414, 34.51183299, 34.96340209],
           [27.11746625, 31.19878079, 31.69439435, 32.63446126, 33.10451345],
           [23.27210749, 30.38714688, 32.48269361, 31.91444505, 31.84583838],
@@ -94,7 +94,7 @@
 in this case: ::
 
    >>> my_dists_nopbc = ad.AtomicDistances(ag1, ag2, pbc=False).run()
-   >>> my_dists_nopbc.results
+   >>> my_dists_nopbc.results.distances
    array([[37.80813681, 33.2594864 , 34.93676414, 34.51183299, 34.96340209],
           [27.11746625, 31.19878079, 31.69439435, 32.63446126, 33.10451345],
           [23.27210749, 30.38714688, 32.482695  , 31.91444505, 31.84583838],
@@ -108,9 +108,13 @@
 
 """
 
+
 import numpy as np
 
 from MDAnalysis.lib.distances import calc_bonds
+from MDAnalysis.analysis.results import (
+    Results,
+)
 
 import logging
 from .base import AnalysisBase
@@ -134,7 +138,7 @@ class AtomicDistances(AnalysisBase):
 
     Attributes
     ----------
-    results : :class:`numpy.ndarray`
+    results.distances : :class:`numpy.ndarray`
         The distances :math:`|ag1[i] - ag2[i]|` for all :math:`i`
         from :math:`0` to `n_atoms` :math:`- 1` for each frame over
         the trajectory.
@@ -145,6 +149,14 @@ class AtomicDistances(AnalysisBase):
 
 
     .. versionadded:: 2.5.0
+    .. versionchanged:: 2.11.0
+       Distance data are now made available in :attr:`results.distances` instead
+       of :attr:`results` and :attr:`results` is now a 
+       :class:`~MDAnalysis.analysis.results.Results` instance; this fixes an API issue 
+       (see `Issue #4819`_) in a *backwards-incompatible* manner.
+
+    .. _Issue #4819`: https://github.com/MDAnalysis/mdanalysis/issues/4819
+
     """
 
     def __init__(self, ag1, ag2, pbc=True, **kwargs):
@@ -167,11 +179,12 @@ def __init__(self, ag1, ag2, pbc=True, **kwargs):
 
     def _prepare(self):
         # initialize NumPy array of frames x distances for results
-        self.results = np.zeros((self.n_frames, self._ag1.atoms.n_atoms))
+        distances = np.zeros((self.n_frames, self._ag1.atoms.n_atoms))
+        self.results = Results(distances=distances)
 
     def _single_frame(self):
         # if PBCs considered, get box size
         box = self._ag1.dimensions if self._pbc else None
         self.results[self._frame_index] = calc_bonds(
             self._ag1.positions, self._ag2.positions, box
-        )
+        )

testsuite/MDAnalysisTests/analysis/test_atomicdistances.py

@@ -27,6 +27,7 @@
 import MDAnalysis.analysis.atomicdistances as ad
 from MDAnalysis.lib.distances import calc_bonds
 import MDAnalysis.transformations.boxdimensions as bd
+from MDAnalysis.analysis.results import Results
 
 from numpy.testing import assert_allclose
 import numpy as np
@@ -121,15 +122,19 @@ def test_ad_pairwise_dist(self, ad_ag1, ad_ag2, expected_dist):
         correctly calculated without PBCs."""
         pairwise_no_pbc = ad.AtomicDistances(ad_ag1, ad_ag2, pbc=False).run()
         actual = pairwise_no_pbc.results
-
+        assert isinstance(actual, Results)
+
+        distances = actual.distances
         # compare with expected values from dist()
-        assert_allclose(actual, expected_dist)
+        assert_allclose(distances, expected_dist)
 
     def test_ad_pairwise_dist_pbc(self, ad_ag1, ad_ag2, expected_pbc_dist):
         """Ensure that pairwise distances between atoms are
         correctly calculated with PBCs."""
         pairwise_pbc = ad.AtomicDistances(ad_ag1, ad_ag2).run()
         actual = pairwise_pbc.results
+        assert isinstance(actual, Results)
 
+        distances = actual.distances
         # compare with expected values from dist()
-        assert_allclose(actual, expected_pbc_dist)
+        assert_allclose(distances, expected_pbc_dist)