Fix issues with dataset API doc (#163)

* Fix formatting error in dataset API doc by removing spaces

* Added links to other dataset descriptions.

* Added DirectionalConvexHull to selection docs.

* Added DCH to scikit-matter intro page.

* set nbsphinx version to 0.8.12 because 0.9 fails


---------

Co-authored-by: alexgo <[email protected]>

Author: victorprincipe

docs/requirements.txt

@@ -1,6 +1,6 @@
 ipykernel
 matplotlib
-nbsphinx
+nbsphinx==0.8.12
 nbconvert
 numpy
 scikit-learn >=0.24.0

docs/source/datasets.rst

@@ -1,7 +1,11 @@
 Datasets
 ========
 
+.. include:: ../../skmatter/datasets/descr/csd-1000r.rst
+
 .. include:: ../../skmatter/datasets/descr/degenerate_CH4_manifold.rst
 
-.. include:: ../../skmatter/datasets/descr/csd-1000r.rst
+.. include:: ../../skmatter/datasets/descr/nice_dataset.rst
+
+.. include:: ../../skmatter/datasets/descr/who_dataset.rst 
 

docs/source/intro.rst

@@ -23,6 +23,7 @@ of computational materials science and chemistry.
    * :ref:`FPS-api`: a common selection technique intended to exploit the diversity of the input space. The selection of the first point is made at random or by a separate metric.
    * :ref:`PCov-FPS-api` extends upon FPS much like PCov-CUR does to CUR.
    * :ref:`Voronoi-FPS-api`: conduct FPS selection, taking advantage of Voronoi tessellations to accelerate selection.
+   * :ref:`DCH-api`: selects samples by constructing a directional convex hull and determining which samples lie on the bounding surface.
 
 - Reconstruction Measures:
    A set of easily-interpretable error measures of the relative information capacity of feature space `F` with respect to feature space `F'`.

docs/source/selection.rst

@@ -292,3 +292,29 @@ spot for Voronoi FPS is when the number of selectable samples is already enough
 to divide the space with Voronoi polyhedrons, but not yet comparable to the total
 number of samples, when the cost of bookkeeping significantly degrades the speed
 of work compared to FPS.
+
+.. _DCH-api:
+
+Directional Convex Hull (DCH)
+#############################
+.. currentmodule:: skmatter.sample_selection._base
+
+.. autoclass :: DirectionalConvexHull
+
+This selector can be instantiated using `skmatter.sample_selection.DirectionalConvexHull`.
+
+.. code-block:: python
+
+    from skmatter.sample_selection import DirectionalConvexHull
+    selector = DirectionalConvexHull(
+                        # Indices of columns of X to use for fitting
+                        # the convex hull
+                        low_dim_idx=[0,1],
+                        )
+    selector.fit(X,y)
+
+    # Get the distance to the convex hull for samples used to fit the
+    # convex hull. This can also be called using other samples (X_new)
+    # and corresponding properties (y_new) that were not used to fit
+    # the hull.
+    Xr = selector.score_samples(X,y)

skmatter/datasets/descr/csd-1000r.rst

@@ -46,10 +46,61 @@ Data Set Characteristics
 References
 ----------
 
-   .. [C1] https://github.com/lab-cosmo/librascal commit ade202a6
-   .. [C2] https://github.com/lab-cosmo/scikit-matter commit 4ed1d92
+.. [C1] https://github.com/lab-cosmo/librascal commit ade202a6
+.. [C2] https://github.com/lab-cosmo/scikit-matter commit 4ed1d92
 
 Reference Code
 --------------
 
-.. literalinclude:: /../../skmatter/datasets/make_csd_1000r.py
+.. code-block:: python
+
+        from skmatter.feature_selection import CUR
+        from skmatter.preprocessing import StandardFlexibleScaler
+        from skmatter.sample_selection import FPS
+        
+        # read all of the frames and book-keep the centers and species
+        filename = "/path/to/CSD-1000R.xyz"
+        frames = np.asarray(
+                read(filename, ":"),
+                dtype=object,
+        )
+
+        n_centers = np.array([len(frame) for frame in frames])
+        center_idx = np.array([i for i, f in enumerate(frames) for p in f])
+        n_env_accum = np.zeros(len(frames) + 1, dtype=int)
+        n_env_accum[1:] = np.cumsum(n_centers)
+
+        numbers = np.concatenate([frame.numbers for frame in frames])
+
+        # compute radial soap vectors as first pass
+        hypers = dict(
+            soap_type="PowerSpectrum",
+            interaction_cutoff=2.5,
+            max_radial=6,
+            max_angular=0,
+            gaussian_sigma_type="Constant",
+            gaussian_sigma_constant=0.4,
+            cutoff_smooth_width=0.5,
+            normalize=False,
+            global_species=[1, 6, 7, 8],
+            expansion_by_species_method="user defined",
+        )
+        soap = SOAP(**hypers)
+
+        X_raw = StandardFlexibleScaler(column_wise=False).fit_transform(
+            soap.transform(frames).get_features(soap)
+        )
+
+        # rank the environments in terms of diversity
+        n_samples = 500
+        i_selected = FPS(n_to_select=n_samples, initialize=0).fit(X_raw).selected_idx_
+
+        # book-keep which frames these samples belong in
+        f_selected = center_idx[i_selected]
+        reduced_f_selected = list(sorted(set(f_selected)))
+        frames_selected = frames[f_selected].copy()
+        ci_selected = i_selected - n_env_accum[f_selected]
+
+        properties_select = [
+            frames[fi].arrays["CS_local"][ci] for fi, ci in zip(f_selected, ci_selected)
+        ]

skmatter/datasets/descr/degenerate_CH4_manifold.rst

@@ -49,5 +49,7 @@ The SOAP bispectrum features were in addition reduced to 12 features with princi
 References
 ----------
 
-   .. [D1] https://github.com/lab-cosmo/librascal commit 8d9ad7a
-   .. [D2] https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html
+.. [D1] https://github.com/lab-cosmo/librascal commit 8d9ad7a
+.. [D2] https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html
+
+=======

skmatter/datasets/descr/nice_dataset.rst

@@ -1,7 +1,7 @@
 .. _nice-dataset:
 
 NICE dataset
-##########
+############
 This is a toy dataset containing NICE[1, 4](N-body Iterative Contraction of Equivariants) features for first 500 configurations of the dataset[2, 3] with randomly displaced methane configurations. 
 
 Function Call

skmatter/datasets/descr/who_dataset.rst

@@ -1,7 +1,7 @@
 .. _who:
 
-who_data
-#########
+WHO dataset
+###########
 
 `who_dataset.csv` is a compilation of multiple publically-available datasets
 through data.worldbank.org. Specifically, the following versioned datasets are used: