Repository: scipy/scipy
Pull request: DOC: stats.energy_distance: disambiguate definition vs squared energy distance
#### Reference issue
Closes gh-14161

#### What does this implement/fix?
The quantity returned by `stats.energy_distance` is the square root of a quantity also referred to as the "energy distance". However, only the square root version (as used by SciPy) satisfies all axioms of a distance function / metric. This PR adds a note to disambiguate between the two versions.

Problem statement:
energy_distance is the squared value
The `energy_distance` function does not compute the energy distance (as defined by Székely and used in the scientific literature). Instead it computes the **square root** of that distance (which is a metric, as the original energy distance does not verify the triangle inequality, but its square root does).

Thus, either the code should be changed to use the right definition, or a warning should be placed in the documentation to explain that the definition used is not the original one.

Hints from issue discussion:
It depends on the reference which quantity is called "the energy distance". Our references 1 and 3, at least, label the metric quantity as "the energy distance", but some others label the square of the metric quantity as "the energy distance" (reference 4 notes the variability). The variability in the literature is worth noting in the docstring, but I wouldn't say that we are using a wrong definition.
Well, the Wikipedia should not be a primary source, but I agree that in the third reference the authors seem to have changed their mind and call "energy distance" to the square root of the original definition, either because its metric properties or by analogy with the distance covariance. However most scientific literature still uses the old name. Note that even recent work (such as https://doi.org/10.1016/j.jspi.2020.11.001) from the original authors uses the original definition. Maybe we should ask directly to @mariarizzo the rationale for that.

In coding the `dcor` package (which is mine) uses the original definition, and `energy` (the R package of the original authors) does not even have a function to compute the energy distance (the function `edist` computes a statistic based on the squared definition instead).

I am not sure if changing the implementation is appropriate, but I think that at least a warning in the documentation could help to clarify everything.
In scipy, we try to reserve "distance" for those with metric properties and use "divergence" or "dissimilarity" for others. Since the literature gives us an option here, I'm inclined to leave the name and implementation alone, but I welcome the addition of a note (but not a warning) about the variability in the naming.

Commit message: Update scipy/stats/_stats_py.py

[skip ci]

Patch to review:
diff --git a/scipy/stats/_stats_py.py b/scipy/stats/_stats_py.py
index 6d01a4eb6f37..1aac83c9f57a 100644
--- a/scipy/stats/_stats_py.py
+++ b/scipy/stats/_stats_py.py
@@ -8567,6 +8567,10 @@ def energy_distance(u_values, v_values, u_weights=None, v_weights=None):
     independent random variables whose probability distribution is :math:`u`
     (resp. :math:`v`).
 
+    Sometimes the square of this quantity is referred to as the "energy
+    distance" (e.g. in [2]_, [4]_), but as noted in [1]_ and [3]_, this square
+    root version satisfies the axioms of a distance function (metric).
+
     As shown in [2]_, for one-dimensional real-valued variables, the energy
     distance is linked to the non-distribution-free version of the Cramér-von
     Mises distance:
@@ -8587,12 +8591,12 @@ def energy_distance(u_values, v_values, u_weights=None, v_weights=None):
 
     References
     ----------
-    .. [1] "Energy distance", https://en.wikipedia.org/wiki/Energy_distance
+    .. [1] Rizzo, Szekely "Energy distance." Wiley Interdisciplinary Reviews:
+           Computational Statistics, 8(1):27-38 (2015).
     .. [2] Szekely "E-statistics: The energy of statistical samples." Bowling
            Green State University, Department of Mathematics and Statistics,
            Technical Report 02-16 (2002).
-    .. [3] Rizzo, Szekely "Energy distance." Wiley Interdisciplinary Reviews:
-           Computational Statistics, 8(1):27-38 (2015).
+    .. [3] "Energy distance", https://en.wikipedia.org/wiki/Energy_distance
     .. [4] Bellemare, Danihelka, Dabney, Mohamed, Lakshminarayanan, Hoyer,
            Munos "The Cramer Distance as a Solution to Biased Wasserstein
            Gradients" (2017). :arXiv:`1705.10743`.


Code review comments:
diff_hunk: @@ -8567,6 +8567,10 @@ def energy_distance(u_values, v_values, u_weights=None, v_weights=None):
     independent random variables whose probability distribution is :math:`u`
     (resp. :math:`v`).
 
+    Sometimes the square of this quantity is referred to as the "energy
+    distance" (e.g. in [2]_, [4]_), but as noted in [1]_ and [3]_, this square
+    root version satisfies the axioms of a distance function (metric).
path: scipy/stats/_stats_py.py
text: @author:
```suggestion
    distance" (e.g. in [2]_, [4]_), but as noted in [1]_ and [3]_, only the
    definition above satisfies the axioms of a distance function (metric).
```
I think this is needed if we remove "square root" from the previous sentence.

@user1:
Sure.

@author:
If you're happy with it, care to commit this and merge @user1? I could call someone else in if it's important, but I avoid self-merging just so it's clear in the commit history that the work was reviewed.