Add basic documentation

docs/src/conf.py

@@ -54,7 +54,7 @@
     "sphinx_toggleprompt",
 ]
 
-example_subdirs = ["pcovr", "selection", "regression", "reconstruction"]
+example_subdirs = ["pcovr", "selection", "regression", "reconstruction", "neighbors"]
 sphinx_gallery_conf = {
     "filename_pattern": "/*",
     "examples_dirs": [f"../../examples/{p}" for p in example_subdirs],

docs/src/references/index.rst

@@ -12,5 +12,6 @@ API Reference
   linear_models
   decomposition
   metrics
+  neighbors
   datasets
   utils

docs/src/references/metrics.rst

@@ -40,3 +40,18 @@ Component-wise Prediction Rigidity
 ----------------------------------
 
 .. autofunction:: skmatter.metrics.componentwise_prediction_rigidity
+
+
+.. _pairwise-euclidian-api:
+
+Pairwise Euclidean Distances
+----------------------------
+
+.. autofunction:: pairwise_euclidean_distances
+
+.. _pairwise-mahalanobis-api:
+
+Pairwise Mahalanobis distance
+-----------------------------
+
+.. autofunction:: skmatter.metrics.pairwise_mahalanobis_distances

docs/src/references/neighbors.rst

@@ -0,0 +1,11 @@
+Neighbors
+=========
+
+.. automodule:: skmatter.neighbors
+
+.. _sparse-kde-api:
+
+Sparse Kernel Density Estimation
+--------------------------------
+
+.. autoclass:: skmatter.neighbors.SparseKDE

docs/src/references/utils.rst

@@ -30,3 +30,9 @@ Random Partitioning with Overlaps
 ---------------------------------
 
 .. autofunction:: skmatter.model_selection.train_test_split
+
+
+Nearest Grid Assigner
+---------------------
+
+.. autoclass:: skmatter.utils.NearestGridAssigner

docs/src/tutorials.rst

@@ -6,3 +6,4 @@
   examples/selection/index
   examples/regression/index
   examples/reconstruction/index
+  examples/neighbors/index

examples/neighbors/README.rst

@@ -0,0 +1,2 @@
+Neighbors
+=========

examples/neighbors/sparse-kde.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+"""
+Sparse KDE examples
+====================================
+
+We start by importing our modules
+"""
+# %%
+#
+
+import numpy as np
+
+from skmatter.datasets import load_roy_dataset  # TODO add a dataset
+
+
+# %%
+#
+# After importing we start with the actual calculations and examples.
+
+roy_data = load_roy_dataset()
+
+a = np.array(2)
+print(a)

src/skmatter/metrics/__init__.py

@@ -37,6 +37,12 @@
   kernel model.
 * :ref:`CPR-api` (CPR) computes the component-wise prediction rigidity of a
   linear or kernel model.
+
+TODO: Add some explanation what the pairwise metrics do.
+
+* :ref:`pairwise-euclidian-api` computes TODO
+* :ref:`pairwise-mahalanobis-api` computes TODO
+  linear or kernel model.
 """
 
 from ._reconstruction_measures import (
@@ -55,7 +61,7 @@
     componentwise_prediction_rigidity,
 )
 
-from .pairwise import (
+from ._pairwise import (
     pairwise_euclidean_distances,
     pairwise_mahalanobis_distances,
 )

src/skmatter/metrics/pairwise.py → src/skmatter/metrics/_pairwise.py

@@ -14,20 +14,23 @@ def pairwise_euclidean_distances(
     """
     Compute the pairwise distance matrix between each pair from a vector array X and Y.
 
+    .. math::
+        d = XXX
+
     For efficiency reasons, the euclidean distance between a pair of row
     vector x and y is computed as::
 
         dist(x, y) = sqrt(dot(x, x) - 2 * dot(x, y) + dot(y, y))
 
-    This formulation has two advantages over other ways of computing distances.
-    First, it is computationally efficient when dealing with sparse data.
-    Second, if one argument varies but the other remains unchanged, then
-    `dot(x, x)` and/or `dot(y, y)` can be pre-computed.
+    This formulation has two advantages over other ways of computing distances. First,
+    it is computationally efficient when dealing with sparse data. Second, if one
+    argument varies but the other remains unchanged, then `dot(x, x)` and/or `dot(y, y)`
+    can be pre-computed.
 
-    However, this is not the most precise way of doing this computation,
-    because this equation potentially suffers from "catastrophic cancellation".
-    Also, the distance matrix returned by this function may not be exactly
-    symmetric as required by, e.g., ``scipy.spatial.distance`` functions.
+    However, this is not the most precise way of doing this computation, because this
+    equation potentially suffers from "catastrophic cancellation". Also, the distance
+    matrix returned by this function may not be exactly symmetric as required by, e.g.,
+    ``scipy.spatial.distance`` functions.
 
     Read more in the :ref:`User Guide <metrics>`.
 
@@ -68,7 +71,8 @@ def pairwise_euclidean_distances(
 
     See Also
     --------
-    paired_distances : Distances between pairs of elements of X and Y.
+    :func:`sklearn.metrics.pairwise.paired_distance` : Distances between pairs of
+        elements of X and Y.
 
     Notes
     -----
@@ -143,6 +147,9 @@ def pairwise_mahalanobis_distances(
     """
     Calculate the pairwise Mahalanobis distance between two arrays.
 
+    .. math::
+        d = XXX
+
     Parameters:
         x : np.ndarray
             The first input array.

src/skmatter/neighbors/__init__.py

@@ -1,3 +1,10 @@
-from ._sparsekde import SparseKDE, covariance, effdim, oas
+"""
+Some introduction what the neighbors directory is about.
+Get some inspiration form sklearn.
 
-__all__ = ["SparseKDE", "covariance", "effdim", "oas"]
+* :ref:`sparse-kde-api` TODO
+"""
+
+from ._sparsekde import SparseKDE
+
+__all__ = ["SparseKDE"]

src/skmatter/neighbors/_sparsekde.py

@@ -7,7 +7,7 @@
 from sklearn.utils.validation import check_is_fitted, check_random_state
 from tqdm import tqdm
 
-from ..metrics.pairwise import (
+from ..metrics._pairwise import (
     pairwise_euclidean_distances,
     pairwise_mahalanobis_distances,
 )
@@ -105,8 +105,8 @@ class SparseKDE(BaseEstimator):
            [ 4.08667637,  3.42457743]]),
               fpoints=0.5, qs=0.85,
               weights=array([5.e-05, 5.e-05, 5.e-05, ..., 5.e-05, 5.e-05, 5.e-05]))
-    >>> estimator.score(result)
-    2.7671739267690363
+    >>> round(estimator.score(result), 3)
+    2.767
     >>> estimator.sample()
     array([[3.32383366, 3.51779084]])
     """

src/skmatter/utils/__init__.py

@@ -19,6 +19,18 @@
     no_progress_bar,
 )
 
+from ._sparsekde import (
+    NearestGridAssigner,
+    GaussianMixtureModel,
+    covariance,
+    local_population,
+    effdim,
+    oas,
+    quick_shift,
+    get_gabriel_graph,
+    rij,
+)
+
 __all__ = [
     "get_progress_bar",
     "no_progress_bar",
@@ -29,4 +41,13 @@
     "X_orthogonalizer",
     "Y_sample_orthogonalizer",
     "Y_feature_orthogonalizer",
+    "NearestGridAssigner",
+    "GaussianMixtureModel",
+    "covariance",
+    "local_population",
+    "effdim",
+    "oas",
+    "quick_shift",
+    "get_gabriel_graph",
+    "rij",
 ]

src/skmatter/utils/_sparsekde.py

@@ -8,9 +8,7 @@
 
 
 class NearestGridAssigner:
-    """NearestGridAssigner Class
-    Assign descriptor to its nearest grid. This is an auxilirary class.
-
+    """Assign descriptor to its nearest grid. This is an auxilirary class.
 
     Parameters
     ----------