From 3c784c97e771e9e40e6b730b776a0815d52573ef Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Tue, 2 Jul 2024 14:56:05 +0200 Subject: [PATCH] docs improvements --- README.rst | 23 +++++++++++-------- docs/src/index.rst | 10 +++++--- examples/README.rst | 4 ++-- src/skmatter/_selection.py | 16 ++++++------- src/skmatter/datasets/descr/who_dataset.rst | 4 ++-- src/skmatter/preprocessing/_data.py | 2 +- src/skmatter/sample_selection/_base.py | 4 ++-- src/skmatter/sample_selection/_voronoi_fps.py | 4 ++-- src/skmatter/utils/_orthogonalizers.py | 14 +++++------ tox.ini | 2 +- 10 files changed, 45 insertions(+), 38 deletions(-) diff --git a/README.rst b/README.rst index 555041f6e..9c86d60a7 100644 --- a/README.rst +++ b/README.rst @@ -2,8 +2,8 @@ scikit-matter ============= |tests| |codecov| |pypi| |conda| |docs| |doi| -A collection of scikit-learn compatible utilities that implement methods born out of the -materials science and chemistry communities. +A collection of ``scikit-learn`` compatible utilities that implement methods born out of +the materials science and chemistry communities. For details, tutorials, and examples, please have a look at our `documentation`_. @@ -72,7 +72,7 @@ Writing code is not the only way to contribute to the project. You can also: .. _`examples and tutorials`: https://scikit-matter.readthedocs.io/en/latest/contributing.html#contributing-new-examples .. _`new datasets`: https://scikit-matter.readthedocs.io/en/latest/contributing.html#contributing-datasets -.. marker-contributors +.. marker-citing Citing scikit-matter -------------------- @@ -81,7 +81,11 @@ If you use *scikit-matter* for your work, please cite: Goscinski A, Principe VP, Fraux G et al. scikit-matter : A Suite of Generalisable Machine Learning Methods Born out of Chemistry and Materials Science. Open Res Europe 2023, 3:81. -`10.12688/openreseurope.15789.2 `_ +`10.12688/openreseurope.15789.2`_ + +.. _`10.12688/openreseurope.15789.2`: https://doi.org/10.12688/openreseurope.15789.2 + +.. marker-contributors Contributors ------------ @@ -90,10 +94,9 @@ Thanks goes to all people that make scikit-matter possible: .. image:: https://contrib.rocks/image?repo=scikit-learn-contrib/scikit-matter :target: https://github.com/scikit-learn-contrib/scikit-matter/graphs/contributors -.. |tests| image:: https://github.com/scikit-learn-contrib/scikit-matter/workflows/Test/badge.svg +.. |tests| image:: https://github.com/scikit-learn-contrib/scikit-matter/workflows/Tests/badge.svg :alt: Github Actions Tests Job Status - :target: (https://github.com/scikit-learn-contrib/scikit-matter/\ - actions?query=workflow%3ATests) + :target: action_ .. |codecov| image:: https://codecov.io/gh/scikit-learn-contrib/scikit-matter/branch/main/graph/badge.svg?token=UZJPJG34SM :alt: Code coverage @@ -101,7 +104,7 @@ Thanks goes to all people that make scikit-matter possible: .. |docs| image:: https://img.shields.io/badge/documentation-latest-sucess :alt: Python - :target: https://scikit-matter.readthedocs.io + :target: documentation_ .. |pypi| image:: https://img.shields.io/pypi/v/skmatter.svg :alt: Latest PYPI version @@ -113,4 +116,6 @@ Thanks goes to all people that make scikit-matter possible: .. |doi| image:: https://img.shields.io/badge/DOI-10.12688-blue :alt: ORE Paper - :target: https://doi.org/10.12688/openreseurope.15789.2 + :target: `10.12688/openreseurope.15789.2`_ + +.. _`action`: https://github.com/scikit-learn-contrib/scikit-matter/actions?query=branch%3Amain diff --git a/docs/src/index.rst b/docs/src/index.rst index ad9b5274c..2095eab22 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -74,6 +74,13 @@ :start-after: marker-issues :end-before: marker-contributing +.. include:: ../../README.rst + :start-after: marker-citing + :end-before: marker-contributors + +If you would like to contribute to scikit-matter, check out our :ref:`contributing` +page! + .. toctree:: :hidden: @@ -84,6 +91,3 @@ contributing changelog bibliography - -If you would like to contribute to scikit-matter, check out our :ref:`contributing` -page! diff --git a/examples/README.rst b/examples/README.rst index 62f7d24b3..539ac085c 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -1,11 +1,11 @@ Examples ======== -For a thorough tutorial of the methods introduced in `scikit-matter`, we +For a thorough tutorial of the methods introduced in ``scikit-matter``, we suggest you check out the pedagogic notebooks in our companion project `kernel-tutorials `_. -For running the examples locally install `scikit-matter` with the ``examples`` +For running the examples locally install ``scikit-matter`` with the ``examples`` optional dependencies. .. code-block:: bash diff --git a/src/skmatter/_selection.py b/src/skmatter/_selection.py index b9ae07ea7..6869a2235 100644 --- a/src/skmatter/_selection.py +++ b/src/skmatter/_selection.py @@ -592,19 +592,17 @@ def _compute_pi(self, X, y=None): the squares of the first :math:`k` components of the right singular vectors .. math:: - \\pi_j = - \\sum_i^k \\left(\\mathbf{U}_\\mathbf{C}\\right)_{ij}^2. + \pi_j = \sum_i^k \left(\mathbf{U}_\mathbf{C}\right)_{ij}^2. - where :math:`\\mathbf{C} = \\mathbf{X}^T\\mathbf{X}`. + where :math:`\mathbf{C} = \mathbf{X}^T\mathbf{X}`. - For sample selection, the importance score :math:`\\pi` is the sum over the + For sample selection, the importance score :math:`\pi` is the sum over the squares of the first :math:`k` components of the right singular vectors .. math:: - \\pi_j = - \\sum_i^k \\left(\\mathbf{U}_\\mathbf{K}\\right)_{ij}^2. + \pi_j = \sum_i^k \left(\mathbf{U}_\mathbf{K}\right)_{ij}^2. - where :math:`\\mathbf{K} = \\mathbf{X}\\mathbf{X}^T`. + where :math:`\mathbf{K} = \mathbf{X}\mathbf{X}^T`. Parameters ---------- @@ -615,7 +613,7 @@ def _compute_pi(self, X, y=None): Returns ------- pi : numpy.ndarray of (n_to_select_from_) - :math:`\\pi` importance for the given samples or features + :math:`\pi` importance for the given samples or features """ svd_kwargs = dict(k=self.k, random_state=self.random_state) if self._axis == 0: @@ -941,7 +939,7 @@ def get_distance(self): For sample selection, this is a row-wise Euclidean distance, which can be expressed in terms of the Gram matrix - :math:`\\mathbf{K} = \mathbf{X} \\mathbf{X} ^ T` + :math:`\mathbf{K} = \mathbf{X} \mathbf{X} ^ T` .. math:: \operatorname{d}_r(i, j) = K_{ii} - 2 K_{ij} + K_{jj}. diff --git a/src/skmatter/datasets/descr/who_dataset.rst b/src/skmatter/datasets/descr/who_dataset.rst index 78ef7ea20..6df0e330b 100644 --- a/src/skmatter/datasets/descr/who_dataset.rst +++ b/src/skmatter/datasets/descr/who_dataset.rst @@ -3,7 +3,7 @@ WHO dataset ########### -`who_dataset.csv` is a compilation of multiple publically-available datasets +``who_dataset.csv`` is a compilation of multiple publically-available datasets through data.worldbank.org. Specifically, the following versioned datasets are used: - NY.GDP.PCAP.CD (v2_4770383) [1]_ @@ -17,7 +17,7 @@ through data.worldbank.org. Specifically, the following versioned datasets are u - SP.DYN.LE00.IN (v2_4770556) [9]_ - SP.POP.TOTL (v2_4770385) [10]_ -where the corresponding file names are `API_{dataset}_DS2_excel_en_{version}.xls`. +where the corresponding file names are ``API_{dataset}_DS2_excel_en_{version}.xls``. This dataset, intended only for demonstration, contains 2020 country-year pairings and the corresponding values above. diff --git a/src/skmatter/preprocessing/_data.py b/src/skmatter/preprocessing/_data.py index 9eb904dbc..ad329ac28 100644 --- a/src/skmatter/preprocessing/_data.py +++ b/src/skmatter/preprocessing/_data.py @@ -225,7 +225,7 @@ class KernelNormalizer(KernelCenterer): where :math:`\phi` is a function mapping x to a Hilbert space. KernelNormalizer centers (i.e., normalize to have zero mean) the data without explicitly computing :math:`\phi(x)`. - It is equivalent to centering and scaling :math:`\\phi(x)` with + It is equivalent to centering and scaling :math:`\phi(x)` with sklearn.preprocessing.StandardScaler(with_std=False). Parameters diff --git a/src/skmatter/sample_selection/_base.py b/src/skmatter/sample_selection/_base.py index da658a66f..f5531d897 100644 --- a/src/skmatter/sample_selection/_base.py +++ b/src/skmatter/sample_selection/_base.py @@ -147,7 +147,7 @@ class PCovFPS(_PCovFPS): ---------- mixing: float, default=0.5 The PCovR mixing parameter, as described in PCovR as - :math:`{\\alpha}` + :math:`{\alpha}` initialize: int or 'random', default=0 Index of the first selection. If 'random', picks a random value when fit starts. n_to_select : int or float, default=None @@ -350,7 +350,7 @@ class PCovCUR(_PCovCUR): Parameters ---------- mixing: float, default=0.5 - The PCovR mixing parameter, as described in PCovR as :math:`{\\alpha}`. Stored + The PCovR mixing parameter, as described in PCovR as :math:`{\alpha}`. Stored in :py:attr:`self.mixing`. recompute_every : int number of steps after which to recompute the pi score defaults to 1, if 0 no diff --git a/src/skmatter/sample_selection/_voronoi_fps.py b/src/skmatter/sample_selection/_voronoi_fps.py index 6cd871a6c..aeedbce97 100644 --- a/src/skmatter/sample_selection/_voronoi_fps.py +++ b/src/skmatter/sample_selection/_voronoi_fps.py @@ -111,14 +111,14 @@ def score(self, X=None, y=None): def get_distance(self): r"""Traditional FPS employs a column-wise Euclidean distance for feature selection, which can be expressed using the covariance matrix - :math:`\\mathbf{C} = \\mathbf{X} ^ T \\mathbf{X}`. + :math:`\mathbf{C} = \mathbf{X} ^ T \mathbf{X}`. .. math:: \operatorname{d}_c(i, j) = C_{ii} - 2 C_{ij} + C_{jj}. For sample selection, this is a row-wise Euclidean distance, which can be expressed in terms of the Gram matrix - :math:`\\mathbf{K} = \\mathbf{X} \\mathbf{X} ^ T` + :math:`\mathbf{K} = \mathbf{X} \mathbf{X} ^ T` .. math:: \operatorname{d}_r(i, j) = K_{ii} - 2 K_{ij} + K_{jj}. diff --git a/src/skmatter/utils/_orthogonalizers.py b/src/skmatter/utils/_orthogonalizers.py index 023747ed7..c027bb70e 100644 --- a/src/skmatter/utils/_orthogonalizers.py +++ b/src/skmatter/utils/_orthogonalizers.py @@ -87,15 +87,15 @@ def Y_feature_orthogonalizer(y, X, tol=1e-12, copy=True): def Y_sample_orthogonalizer(y, X, y_ref, X_ref, tol=1e-12, copy=True): - r"""Orthogonalizes a matrix of targets :math:`{\\mathbf{Y}}` given a reference - feature matrix :math:`{\\mathbf{X}_r}` and reference target matrix - :math:`{\\mathbf{Y}_r}`: + r"""Orthogonalizes a matrix of targets :math:`{\mathbf{Y}}` given a reference + feature matrix :math:`{\mathbf{X}_r}` and reference target matrix + :math:`{\mathbf{Y}_r}`: .. math:: - \\mathbf{Y} \\leftarrow \\mathbf{Y} - - \\mathbf{X} \\left(\\mathbf{X}_{\\mathbf{r}}^T - \\mathbf{X}_{\\mathbf{r}}\\right)^{-1}\\mathbf{X}_{\\mathbf{r}}^T - \\mathbf{Y}_{\\mathbf{r}} + \mathbf{Y} \leftarrow \mathbf{Y} - + \mathbf{X} \left(\mathbf{X}_{\mathbf{r}}^T + \mathbf{X}_{\mathbf{r}}\right)^{-1}\mathbf{X}_{\mathbf{r}}^T + \mathbf{Y}_{\mathbf{r}} Parameters ---------- diff --git a/tox.ini b/tox.ini index a004f8484..2c5c64764 100644 --- a/tox.ini +++ b/tox.ini @@ -65,7 +65,7 @@ commands = black --check --diff {[tox]lint_folders} blackdoc --check --diff {[tox]lint_folders} isort --check-only --diff {[tox]lint_folders} - sphinx-lint --enable line-too-long --max-line-length 88 \ + sphinx-lint --enable all --max-line-length 88 \ -i "{toxinidir}/docs/src/examples" \ {[tox]lint_folders} "{toxinidir}/README.rst"