create wrapper class for Energy (#160)

* sort imports

* fix docs error short underline

* add energy source code

* fix tutorials not rendering

* add more detail to compute distance and kernel

docs/conf.py

@@ -13,8 +13,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-import sys
 import shutil
+import sys
 
 sys.path.insert(0, os.path.abspath(".."))
 sys.path.insert(0, os.path.abspath("sphinxext"))

docs/reference/ksample.rst

@@ -6,3 +6,7 @@
 Nonpar MANOVA via Independence Testing
 --------------------------------------
 .. autoclass:: KSample
+
+Energy
+------
+.. autoclass:: Energy

docs/reference/tools.rst

@@ -120,7 +120,7 @@ Misc
 ----
 
 Kernel Matrix Computation
-""""""""""""""""""
+"""""""""""""""""""""""""
 .. autofunction:: compute_kern
 
 Distance Matrix Computation

docs/requirements.txt

@@ -1,7 +1,7 @@
 sphinx==1.8.5
 sphinx_rtd_theme>=0.4.2
 sphinxcontrib-rawfiles
-nbsphinx>=0.4.2
+nbsphinx>=0.8.0
 ipython>=7.4.0
 ipykernel>=5.1.0
 numpydoc==0.9.2

docs/sphinxext/github_link.py

@@ -1,9 +1,9 @@
-from operator import attrgetter
 import inspect
-import subprocess
 import os
+import subprocess
 import sys
 from functools import partial
+from operator import attrgetter
 
 REVISION_CMD = "git rev-parse --short HEAD"
 

docs/tutorials.rst

@@ -1,7 +1,7 @@
 Tutorials
 *********
 
-.. _tut_package:
+.. _indep_tutorials:
 
 Independence Tests
 ------------------
@@ -25,6 +25,8 @@ the algorithms included against each other.
     tutorials/independence/indep_alg_speed
 
 
+.. _ksamp_tutorials:
+
 *K*-sample Tests
 ------------------
 The *k*-sample testing problem is generalized as follows: consider random variables
@@ -43,6 +45,7 @@ This tutorial overview how to use *k*-sample tests in ``hyppo``.
 
     tutorials/ksample/ksample
 
+.. _ts_tutorials:
 
 Time-Series Tests
 -----------------
@@ -70,6 +73,8 @@ This tutorial overview how to use time_series based tests in ``hyppo``.
     tutorials/time_series/time_series
 
 
+.. _sims_tutorials:
+
 Sims
 ----
 To evaluate existing implmentations and benchmark against other packages,

docs/tutorials/independence/__init__.py

@@ -1,3 +1,3 @@
-from .power import power_sample, power_dim
+from .power import power_dim, power_sample
 
 __all__ = ["power_sample", "power_dim"]

hyppo/__init__.py

@@ -1,7 +1,7 @@
+import hyppo.discrim
 import hyppo.independence
 import hyppo.ksample
 import hyppo.time_series
 import hyppo.tools
-import hyppo.discrim
 
 __version__ = "0.1.3"

hyppo/discrim/_utils.py

@@ -1,13 +1,7 @@
 import numpy as np
-
 from sklearn.metrics import pairwise_distances
 
-from ..tools import (
-    contains_nan,
-    check_ndarray_xy,
-    convert_xy_float64,
-    check_reps,
-)
+from ..tools import check_ndarray_xy, check_reps, contains_nan, convert_xy_float64
 
 
 class _CheckInputs:

hyppo/discrim/base.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+
 import numpy as np
 
 

hyppo/discrim/discrim_one_samp.py

@@ -1,8 +1,9 @@
-from ._utils import _CheckInputs
 import numpy as np
-from .base import DiscriminabilityTest
 from scipy._lib._util import MapWrapper
 
+from ._utils import _CheckInputs
+from .base import DiscriminabilityTest
+
 
 class DiscrimOneSample(DiscriminabilityTest):
     r"""

hyppo/discrim/discrim_two_samp.py

@@ -1,9 +1,10 @@
-from ._utils import _CheckInputs
 import numpy as np
 from numba import njit
-from .base import DiscriminabilityTest
 from scipy._lib._util import MapWrapper
 
+from ._utils import _CheckInputs
+from .base import DiscriminabilityTest
+
 
 class DiscrimTwoSample(DiscriminabilityTest):
     r"""

hyppo/discrim/tests/test_discrim_one_samp.py

@@ -1,6 +1,7 @@
-import pytest
 import numpy as np
-from numpy.testing import assert_almost_equal, assert_warns, assert_raises
+import pytest
+from numpy.testing import assert_almost_equal, assert_raises, assert_warns
+
 from .. import DiscrimOneSample
 
 

hyppo/discrim/tests/test_discrim_two_samp.py

@@ -1,6 +1,7 @@
-import pytest
 import numpy as np
-from numpy.testing import assert_almost_equal, assert_warns, assert_raises
+import pytest
+from numpy.testing import assert_almost_equal, assert_raises, assert_warns
+
 from .. import DiscrimTwoSample
 
 

hyppo/independence/__init__.py

@@ -1,9 +1,9 @@
-from .rv import RV
 from .cca import CCA
-from .hhg import HHG
 from .dcorr import Dcorr
+from .hhg import HHG
 from .hsic import Hsic
-from .mgc import MGC
 from .kmerf import KMERF
+from .mgc import MGC
+from .rv import RV
 
 __all__ = [s for s in dir()]  # add imported tests to __all__

hyppo/independence/_utils.py

@@ -1,11 +1,6 @@
 import numpy as np
 
-from ..tools import (
-    contains_nan,
-    check_ndarray_xy,
-    convert_xy_float64,
-    check_reps,
-)
+from ..tools import check_ndarray_xy, check_reps, contains_nan, convert_xy_float64
 
 
 class _CheckInputs:

hyppo/independence/base.py

@@ -9,13 +9,26 @@ class IndependenceTest(ABC):
 
     Parameters
     ----------
-    compute_distance : callable(), optional (default: euclidean)
-        A function that computes the distance or similarity among the samples
-        within each data matrix. Set to `None` if `x` and `y` are already
-        distance matrices. To call a custom function, either create the
-        distance matrix before-hand or create a function of the form
-        ``compute_distance(x)`` where `x` is the data matrix for which
-        pairwise distances are calculated.
+    compute_distance : callable(), optional (default: None)
+        A function that computes the distance among the samples within each
+        data matrix.
+        Valid strings for ``metric`` are, as defined in
+        ``sklearn.metrics.pairwise_distances``,
+
+            - From scikit-learn: [‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’,
+              ‘manhattan’] See the documentation for scipy.spatial.distance for details
+              on these metrics.
+            - From scipy.spatial.distance: [‘braycurtis’, ‘canberra’, ‘chebyshev’,
+              ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’,
+              ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’,
+              ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’] See the
+              documentation for scipy.spatial.distance for details on these metrics.
+
+        Set to `None` or `precomputed` if `x` and `y` are already distance
+        matrices. To call a custom function, either create the distance matrix
+        before-hand or create a function of the form ``metric(x, **kwargs)``
+        where `x` is the data matrix for which pairwise distances are
+        calculated and kwargs are extra arguements to send to your custom function.
     """
 
     def __init__(self, compute_distance=None, **kwargs):

hyppo/independence/cca.py

@@ -1,7 +1,7 @@
 import numpy as np
 
-from .base import IndependenceTest
 from ._utils import _CheckInputs
+from .base import IndependenceTest
 
 
 class CCA(IndependenceTest):
@@ -42,17 +42,17 @@ class CCA(IndependenceTest):
     References
     ----------
     .. [#1CCA] Härdle, W. K., & Simar, L. (2015). Canonical correlation
-               analysis. In *Applied multivariate statistical analysis* (pp.
+               analysis. In Applied multivariate statistical analysis (pp.
                443-454). Springer, Berlin, Heidelberg.
     .. [#2CCA] Knapp, T. R. (1978). Canonical correlation analysis: A general
                parametric significance-testing system. *Psychological
                Bulletin*, 85(2), 410.
     .. [#3CCA] Hotelling, H. (1992). Relations between two sets of variates.
-               In *Breakthroughs in statistics* (pp. 162-190). Springer, New
+               In Breakthroughs in statistics (pp. 162-190). Springer, New
                York, NY.
     .. [#4CCA] Hardoon, D. R., Szedmak, S., & Shawe-Taylor, J. (2004).
                Canonical correlation analysis: An overview with application to
-               learning methods. *Neural computation*, 16(12), 2639-2664.
+               learning methods. Neural computation, 16(12), 2639-2664.
     """
 
     def __init__(self):

hyppo/independence/dcorr.py

@@ -1,9 +1,9 @@
 import numpy as np
 from numba import njit
 
-from ..tools import compute_dist, chi2_approx, check_perm_blocks_dim
-from .base import IndependenceTest
+from ..tools import check_perm_blocks_dim, chi2_approx, compute_dist
 from ._utils import _CheckInputs
+from .base import IndependenceTest
 
 
 class Dcorr(IndependenceTest):
@@ -16,13 +16,26 @@ class Dcorr(IndependenceTest):
 
     Parameters
     ----------
-    compute_distance : callable(), optional (default: euclidean)
+    compute_distance : callable(), optional (default: "euclidean")
         A function that computes the distance among the samples within each
-        data matrix. Set to `None` if `x` and `y` are already distance
+        data matrix.
+        Valid strings for ``metric`` are, as defined in
+        ``sklearn.metrics.pairwise_distances``,
+
+            - From scikit-learn: [‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’,
+              ‘manhattan’] See the documentation for scipy.spatial.distance for details
+              on these metrics.
+            - From scipy.spatial.distance: [‘braycurtis’, ‘canberra’, ‘chebyshev’,
+              ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’,
+              ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’,
+              ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’] See the
+              documentation for scipy.spatial.distance for details on these metrics.
+
+        Set to `None` or `precomputed` if `x` and `y` are already distance
         matrices. To call a custom function, either create the distance matrix
-        before-hand or create a function of the form ``compute_distance(x)``
+        before-hand or create a function of the form ``metric(x, **kwargs)``
         where `x` is the data matrix for which pairwise distances are
-        calculated.
+        calculated and kwargs are extra arguements to send to your custom function.
     bias : bool (default: False)
         Whether or not to use the biased or unbiased test statistics.
 
@@ -89,10 +102,10 @@ class Dcorr(IndependenceTest):
     ----------
     .. [#1Dcor] Székely, G. J., Rizzo, M. L., & Bakirov, N. K. (2007).
                 Measuring and testing dependence by correlation of distances.
-                *The annals of statistics*, 35(6), 2769-2794.
+                The annals of statistics, 35(6), 2769-2794.
     .. [#2Dcor] Székely, G. J., & Rizzo, M. L. (2014). Partial distance
-                correlation with methods for dissimilarities. *The Annals of
-                Statistics*, 42(6), 2382-2412.
+                correlation with methods for dissimilarities. The Annals of
+                Statistics, 42(6), 2382-2412.
     """
 
     def __init__(self, compute_distance="euclidean", bias=False, **kwargs):

hyppo/independence/hhg.py

@@ -2,8 +2,8 @@
 from numba import njit
 
 from ..tools import compute_dist
-from .base import IndependenceTest
 from ._utils import _CheckInputs
+from .base import IndependenceTest
 
 
 class HHG(IndependenceTest):
@@ -18,13 +18,26 @@ class HHG(IndependenceTest):
 
     Parameters
     ----------
-    compute_distance : callable(), optional (default: euclidean)
+    compute_distance : callable(), optional (default: "euclidean")
         A function that computes the distance among the samples within each
-        data matrix. Set to `None` if `x` and `y` are already distance
+        data matrix.
+        Valid strings for ``metric`` are, as defined in
+        ``sklearn.metrics.pairwise_distances``,
+
+            - From scikit-learn: [‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’,
+              ‘manhattan’] See the documentation for scipy.spatial.distance for details
+              on these metrics.
+            - From scipy.spatial.distance: [‘braycurtis’, ‘canberra’, ‘chebyshev’,
+              ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’,
+              ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’,
+              ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’] See the
+              documentation for scipy.spatial.distance for details on these metrics.
+
+        Set to `None` or `precomputed` if `x` and `y` are already distance
         matrices. To call a custom function, either create the distance matrix
-        before-hand or create a function of the form ``compute_distance(x)``
+        before-hand or create a function of the form ``metric(x, **kwargs)``
         where `x` is the data matrix for which pairwise distances are
-        calculated.
+        calculated and kwargs are extra arguements to send to your custom function.
 
     See Also
     --------
@@ -84,7 +97,7 @@ class HHG(IndependenceTest):
     ----------
     .. [#1HHG] Heller, R., Heller, Y., & Gorfine, M. (2012). A consistent
                multivariate test of association based on ranks of distances.
-               *Biometrika*, 100(2), 503-510.
+               Biometrika, 100(2), 503-510.
     """
 
     def __init__(self, compute_distance="euclidean", **kwargs):