Standardize atomicdistances to use results

package/AUTHORS

@@ -279,6 +279,7 @@ Chronological list of authors
   - Olivier Languin--Cattoën
   - Amarendra Mohan
   - Shubham Mittal  
+  - Charity Grey
 
 External code
 -------------

package/CHANGELOG

@@ -17,11 +17,15 @@ The rules for this file:
 ??/??/?? IAlibay, orbeckst, marinegor, tylerjereddy, ljwoods2, marinegor,
          spyke7, talagayev, tanii1125, BradyAJohnston, hejamu, jeremyleung521,
          harshitgajjela-droid, kunjsinha, aygarwal, jauy123, Dreamstick9,
-         ollyfutur, Amarendra22
+         ollyfutur, Amarendra22, charity-g
 
  * 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.
  * DSSP now correctly handles periodic boundary conditions in hydrogen bond
    detection; previously, hydrogen bonds across periodic boundaries were
    missed (PR #5182)

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],
@@ -111,6 +111,7 @@
 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 +135,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 +146,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 +176,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.results.distances[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,17 @@ 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)

testsuite/MDAnalysisTests/coordinates/test_trc.py

@@ -227,7 +227,7 @@ def test_trc_distances(self, TRC_U):
         dist_B = (
             atomicdistances.AtomicDistances(ag1, ag2, pbc=True)
             .run()
-            .results[0]
+            .results.distances[0]
         )
 
         assert_allclose(