Changes encore.hes() details output (#2484)

* Fixes #2465
* Removed arrayfication of `encore.hes` details.
* changed hes so it always returns details (instead of needing to use `details=True` 
   This is more consistent with the behaviour  of `ces` and `dres`. Previously, `None` 
   was returned instead if the details flag was `False`.
* removed `details` kwarg from `hes()`
* updated docstrings;
* updated `encore.similarity` docs to Python 3 syntax
* added changes to CHANGELOG

Author: mtiberti

package/CHANGELOG

@@ -86,6 +86,9 @@ Enhancements
   * Improve the distance search in water bridge analysis with capped_distance (PR #2480)
 
 Changes
+  * encore.hes() doesn't accept the details keyword anymore, it always returns
+    the relevant details instead, consistently with ces() and dres(), in the
+    form of a dictionary (Issue #2465)
   * Removed instant selectors on Universe and Group objects (e.g. AtomGroup.C,
     Segment.r1, Universe.s4AKE).  Use select_atoms instead (Issue #1377)
   * Calling Universe() now raises a TypeError advising you to use Universe.empty.

package/MDAnalysis/analysis/encore/similarity.py

@@ -76,17 +76,16 @@
     >>> import MDAnalysis.analysis.encore as encore
     >>> from MDAnalysis.tests.datafiles import PSF, DCD, DCD2
 
-
 To calculate the Harmonic Ensemble Similarity (:func:`hes`)
 two ensemble objects are first created and then used for calculation: ::
 
     >>> ens1 = Universe(PSF, DCD)
     >>> ens2 = Universe(PSF, DCD2)
-    >>> print encore.hes([ens1, ens2])
-    (array([[        0.        ,  38279683.95892926],
-            [ 38279683.95892926,         0.        ]]), None)
+    >>> HES, details = encore.hes([ens1, ens2])
+    >>> print(HES)
+    [[        0.        ,  38279683.95892926],
+    [ 38279683.95892926,         0.        ]]
 
-Here None is returned in the array as the default details parameter is False.
 HES can assume any non-negative value, i.e. no upper bound exists and the
 measurement can therefore be used as an absolute scale.
 
@@ -100,7 +99,7 @@
     >>> ens1 = Universe(PSF, DCD)
     >>> ens2 = Universe(PSF, DCD2)
     >>> CES, details = encore.ces([ens1, ens2])
-    >>> print CES
+    >>> print(CES)
     [[ 0.          0.68070702]
     [ 0.68070702  0.        ]]
 
@@ -133,7 +132,7 @@
 
     >>> DRES,details = encore.dres([ens1, ens2],
                                    distance_matrix = rmsd_matrix)
-    >>> print DRES
+    >>> print(DRES)
     [[ 0.        ,   0.67453198]
      [  0.67453198,  0.        ]]
 
@@ -721,7 +720,6 @@ def hes(ensembles,
         cov_estimator="shrinkage",
         weights='mass',
         align=False,
-        details=False,
         estimate_error=False,
         bootstrapping_samples=100,
         calc_diagonal=False):
@@ -747,9 +745,6 @@ def hes(ensembles,
         Note: this changes the ensembles in-place, and will thus leave your
         ensembles in an altered state.
         (default is False)
-    details : bool, optional
-        Save the mean and covariance matrix for each
-        ensemble in a numpy array (default is False).
     estimate_error : bool, optional
         Whether to perform error estimation (default is False).
     bootstrapping_samples : int, optional
@@ -762,8 +757,9 @@ def hes(ensembles,
 
     Returns
     -------
-    numpy.array (bidimensional)
-        Harmonic similarity measurements between each pair of ensembles.
+    hes, details : numpy.array, dictionary
+        Harmonic similarity measurements between each pair of ensembles,
+        and dict containing mean and covariance matrix for each ensemble
 
     Notes
     -----
@@ -804,7 +800,7 @@ def hes(ensembles,
         >>> ens1 = Universe(PSF, DCD)
         >>> ens2 = Universe(PSF, DCD2)
         >>> HES, details = encore.hes([ens1, ens2])
-        >>> print HES
+        >>> print(HES)
         [[        0.          38279683.95892926]
          [ 38279683.95892926         0.        ]]
 
@@ -813,7 +809,7 @@ def hes(ensembles,
     align everything to the current timestep in the first ensemble. Note that
     this changes the ens1 and ens2 objects:
 
-        >>> print encore.hes([ens1, ens2], align=True)[0]
+        >>> print(encore.hes([ens1, ens2], align=True)[0])
         [[    0.          6880.34140106]
         [ 6880.34140106     0.        ]]
 
@@ -823,9 +819,14 @@ def hes(ensembles,
         >>> from MDAnalysis.analysis import align
         >>> align.AlignTraj(ens1, ens1, select="name CA", in_memory=True).run()
         >>> align.AlignTraj(ens2, ens1, select="name CA", in_memory=True).run()
-        >>> print encore.hes([ens1, ens2])[0]
+        >>> print(encore.hes([ens1, ens2])[0])
         [[    0.          7032.19607004]
          [ 7032.19607004     0.        ]]
+
+    .. versionchanged:: 1.0.0
+       hes doesn't accept the *details* argument anymore, it always returns the
+       details of the calculation instead, in the form of a dictionary
+
     """
 
     if not isinstance(weights, (list, tuple, np.ndarray)) and weights == 'mass':
@@ -937,15 +938,10 @@ def hes(ensembles,
         values[j, i] = value
 
     # Save details as required
-    if details:
-        kwds = {}
-        for i in range(out_matrix_eln):
-            kwds['ensemble{0:d}_mean'.format(i + 1)] = xs[i]
-            kwds['ensemble{0:d}_covariance_matrix'.format(i + 1)] = sigmas[i]
-        details = np.array(kwds)
-
-    else:
-        details = None
+    details = {}
+    for i in range(out_matrix_eln):
+        details['ensemble{0:d}_mean'.format(i + 1)] = xs[i]
+        details['ensemble{0:d}_covariance_matrix'.format(i + 1)] = sigmas[i]
 
     return values, details
 
@@ -1060,8 +1056,8 @@ def ces(ensembles,
 
         >>> ens1 = Universe(PSF, DCD)
         >>> ens2 = Universe(PSF, DCD2)
-        >>> CES,details = encore.ces([ens1,ens2])
-        >>> print CES
+        >>> CES, details = encore.ces([ens1,ens2])
+        >>> print(CES)
         [[ 0.          0.68070702]
          [ 0.68070702  0.        ]]
 
@@ -1073,10 +1069,10 @@ def ces(ensembles,
         >>> CES, details = encore.ces([ens1,ens2],
                                       clustering_method = [encore.DBSCAN(eps=0.45),
                                                            encore.DBSCAN(eps=0.50)])
-        >>> print "eps=0.45: ", CES[0]
+        >>> print("eps=0.45: ", CES[0])
         eps=0.45:  [[ 0.          0.20447236]
         [ 0.20447236  0.        ]]
-        >>> print "eps=0.5: ", CES[1]
+        >>> print("eps=0.5: ", CES[1])
         eps=0.5:  [[ 0.          0.25331629]
         [ 0.25331629  0.        ]]"
 
@@ -1336,7 +1332,7 @@ def dres(ensembles,
         >>> ens1 = Universe(PSF,DCD)
         >>> ens2 = Universe(PSF,DCD2)
         >>> DRES, details = encore.dres([ens1,ens2])
-        >>> print DRES
+        >>> print(DRES)
         [[ 0.          0.67996043]
          [ 0.67996043  0.        ]]
 
@@ -1352,7 +1348,7 @@ def dres(ensembles,
 
         >>> DRES, details = encore.dres([ens1,ens2],
                                         dimensionality_reduction_method = encore.PrincipalComponentAnalysis(dimension=2))
-        >>> print DRES
+        >>> print(DRES)
         [[ 0.          0.69314718]
          [ 0.69314718  0.        ]]
 
@@ -1549,7 +1545,7 @@ def ces_convergence(original_ensemble,
 
         >>> ens1 = Universe(PSF,DCD)
         >>> ces_conv = encore.ces_convergence(ens1, 10)
-        >>> print ces_conv
+        >>> print(ces_conv)
         [[ 0.48194205]
         [ 0.40284672]
         [ 0.31699026]
@@ -1658,7 +1654,7 @@ def dres_convergence(original_ensemble,
 
         >>> ens1 = Universe(PSF,DCD)
         >>> dres_conv = encore.dres_convergence(ens1, 10)
-        >>> print dres_conv
+        >>> print(dres_conv)
         [[ 0.5295528 ]
          [ 0.40716539]
          [ 0.31158669]