Merge pull request #6 from mtdhuynh/docs

UNIQUE v0.2.2
Novartis · Oct 4, 2024 · afe98da · afe98da
2 parents d0b96e1 + 4bfb69b
commit afe98da
Show file tree

Hide file tree

Showing 11 changed files with 127 additions and 45 deletions.
diff --git a/Makefile b/Makefile
@@ -30,7 +30,6 @@ print-info:
 # Install environment
 env:
 	conda env create -f unique-environment.yml -p ${CONDA_ENV}
-	conda config --append envs_dirs ${CONDA_ENV}
 
 jupyter-kernel:
 	${PYTHON} -m ipykernel install --sys-prefix --name unique --display-name unique

diff --git a/README.md b/README.md
@@ -1,13 +1,15 @@
 <figure>
-  <img src=./docs/source/_static/unique_logo_blue.png alt="UNIQUE Logo">
+  <img src="https://github.com/Novartis/UNIQUE/raw/main/docs/source/_static/unique_logo_blue.png" alt="UNIQUE Logo">
   <figcaption align=center><u><b>UN</b></u>certa<u><b>I</b></u>nty <u><b>QU</b></u>antification b<u><b>E</b></u>nchmark: a Python library for benchmarking uncertainty estimation and quantification methods for Machine Learning models predictions.</figcaption>
 </figure>
 
 [![Python](https://img.shields.io/pypi/pyversions/unique-uncertainty?label=Python)](https://pypi.org/project/unique-uncertainty/)
-[![version](https://img.shields.io/pypi/v/unique-uncertainty?color=green&label=PyPI)](https://pypi.org/project/unique-uncertainty/)
-[![PyPI downloads](https://img.shields.io/pypi/dm/unique-uncertainty?label=Downloads)](https://pypi.org/project/unique-uncertainty/)
+[![PyPI version](https://img.shields.io/pypi/v/unique-uncertainty?color=green&label=PyPI)](https://pypi.org/project/unique-uncertainty/)
+[![Conda version](https://img.shields.io/conda/vn/conda-forge/unique-uncertainty?color=green&label=conda-forge)](https://anaconda.org/conda-forge/unique-uncertainty)
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-red)](https://opensource.org/licenses/BSD-3-Clause)
 [![chemRxiv](https://img.shields.io/badge/chemRxiv-10.26434%2Fchemrxiv--2024--fmbgk-yellow)](https://doi.org/10.26434/chemrxiv-2024-fmbgk)
+[![PyPI downloads](https://img.shields.io/pypi/dm/unique-uncertainty?color=yellowgreen&label=PyPI%20downloads)](https://pypi.org/project/unique-uncertainty/)
+[![Conda downloads](https://img.shields.io/conda/dn/conda-forge/unique-uncertainty?color=yellowgreen&label=conda%20downloads)](https://anaconda.org/conda-forge/unique-uncertainty)
 [![Docs](https://github.com/Novartis/UNIQUE/actions/workflows/docs.yml/badge.svg?branch=main)](https://opensource.nibr.com/UNIQUE/)
 [![Build](https://github.com/Novartis/UNIQUE/actions/workflows/build.yml/badge.svg?branch=main)](https://pypi.org/project/unique-uncertainty/)
 
@@ -19,16 +21,18 @@
 `UNIQUE` is a model-agnostic tool, meaning that it does not depend on any specific ML model building platform or provides any  ML model training functionality. It is lightweight, because it only requires the user to input their model's inputs and predictions.
 
 <figure>
-  <img src=./docs/source/_static/schema_high_level.png alt="UNIQUE High Level Schema">
+  <img src="https://github.com/Novartis/UNIQUE/raw/main/docs/source/_static/schema_high_level.png" alt="UNIQUE High Level Schema">
   <figcaption align=center>High-level schema of <code>UNIQUE</code>'s components.</figcaption>
 </figure>
 
 
 ## Installation
 
 [![Python](https://img.shields.io/pypi/pyversions/unique-uncertainty?label=Python)](https://pypi.org/project/unique-uncertainty/)
-[![version](https://img.shields.io/pypi/v/unique-uncertainty?color=green&label=PyPI)](https://pypi.org/project/unique-uncertainty/)
-[![PyPI downloads](https://img.shields.io/pypi/dm/unique-uncertainty?label=Downloads)](https://pypi.org/project/unique-uncertainty/)
+[![PyPI version](https://img.shields.io/pypi/v/unique-uncertainty?color=green&label=PyPI)](https://pypi.org/project/unique-uncertainty/)
+[![Conda version](https://img.shields.io/conda/vn/conda-forge/unique-uncertainty?color=green&label=conda-forge)](https://anaconda.org/conda-forge/unique-uncertainty)
+[![PyPI downloads](https://img.shields.io/pypi/dm/unique-uncertainty?color=yellowgreen&label=PyPI%20downloads)](https://pypi.org/project/unique-uncertainty/)
+[![Conda downloads](https://img.shields.io/conda/dn/conda-forge/unique-uncertainty?color=yellowgreen&label=conda%20downloads)](https://anaconda.org/conda-forge/unique-uncertainty)
 [![Build](https://github.com/Novartis/UNIQUE/actions/workflows/build.yml/badge.svg?branch=main)](https://pypi.org/project/unique-uncertainty/)
 
 `UNIQUE` is currently compatible with Python 3.8 through 3.12.1. To install the latest release and use the package as is, run the following in a compatible environment of choice:
@@ -37,6 +41,13 @@
 pip install unique-uncertainty
 ```
 
+or:
+
+```bash
+conda install -c conda-forge unique-uncertainty
+# mamba install -c conda-forge unique-uncertainty
+```
+
 Check out the [docs](https://opensource.nibr.com/UNIQUE/installation.html#installation) for more installation instructions.
 
 
@@ -87,11 +98,15 @@ Please note that we have a [Code of Conduct](./CODE_OF_CONDUCT.md) in place to e
 
 ## License
 
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-red)](https://opensource.org/licenses/BSD-3-Clause)
+
 `UNIQUE` is licensed under the BSD 3-Clause License. See the [LICENSE](./LICENSE.md) file.
 
 
 ## Cite Us
 
+[![chemRxiv](https://img.shields.io/badge/chemRxiv-10.26434%2Fchemrxiv--2024--fmbgk-yellow)](https://doi.org/10.26434/chemrxiv-2024-fmbgk)
+
 If you find `UNIQUE` helpful for your work and/or research, please consider citing our work:
 
 ```bibtex
@@ -115,4 +130,4 @@ For any questions or further details about the project, please get in touch with
 * **[Raquel Rodríguez-Pérez](mailto:[email protected]?subject=UNIQUE)**
 
 
-![Novartis Logo](./docs/source/_static/novartis_logo.png)
+![Novartis Logo](https://github.com/Novartis/UNIQUE/raw/main/docs/source/_static/novartis_logo.png)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -13,9 +13,31 @@
 author = "Novartis Pharma AG"
 # author = 'Minh Tam Davide Huynh, Gaetano Scebba, Jessica Lanini, Raquel Rodriguez-Perez'
 
-version_badge_url = (
-    "https://img.shields.io/pypi/v/unique-uncertainty?label=PyPI&color=green"
+
+## URLs
+chemrxiv_doi = "https://doi.org/10.26434/chemrxiv-2024-fmbgk"
+conda_url = "https://anaconda.org/conda-forge/unique-uncertainty"
+docs_url = "https://opensource.nibr.com/UNIQUE/"
+license_url = "https://opensource.org/licenses/BSD-3-Clause"
+pypi_url = "https://pypi.org/project/unique-uncertainty"
+
+## Badges
+chemrxiv_doi_badge_url = (
+    "https://img.shields.io/badge/chemRxiv-10.26434%2Fchemrxiv--2024--fmbgk-yellow"
+)
+conda_version_badge_url = "https://img.shields.io/conda/vn/conda-forge/unique-uncertainty?color=green&label=conda-forge"
+conda_downloads_badge_url = "https://img.shields.io/conda/dn/conda-forge/unique-uncertainty?color=yellowgreen&label=conda%20downloads"
+github_build_badge_url = "https://github.com/Novartis/UNIQUE/actions/workflows/build.yml/badge.svg?branch=main"
+github_docs_badge_url = "https://github.com/Novartis/UNIQUE/actions/workflows/docs.yml/badge.svg?branch=main"
+license_badge_url = "https://img.shields.io/badge/License-BSD_3--Clause-red"
+pypi_version_badge_url = (
+    "https://img.shields.io/pypi/v/unique-uncertainty?color=green&label=PyPI"
 )
+pypi_downloads_badge_url = "https://img.shields.io/pypi/dm/unique-uncertainty?color=yellowgreen&label=PyPI%20downloads"
+python_versions_badge_url = (
+    "https://img.shields.io/pypi/pyversions/unique-uncertainty?label=Python"
+)
+
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -25,6 +47,7 @@
     # "autodoc2",  # Instead of 'sphinx.ext.autodoc',
     "myst_nb",
     "sphinx_copybutton",
+    "sphinx_design",
     # "sphinx.ext.autodoc",
     # "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
@@ -51,10 +74,15 @@
 myst_heading_anchors = 3
 
 myst_substitutions = {
-    "pypi_build_badge": "[![PyPI build](https://github.com/Novartis/UNIQUE/actions/workflows/build.yml/badge.svg?branch=main)](https://pypi.org/project/unique-uncertainty)",
-    "pypi_downloads_badge": "[![PyPI downloads](https://img.shields.io/pypi/dm/unique-uncertainty?label=Downloads)](https://pypi.org/project/unique-uncertainty)",
-    "pypi_version_badge": "[![PyPI version](https://img.shields.io/pypi/v/unique-uncertainty?label=PyPI&color=green)](https://pypi.org/project/unique-uncertainty)",
-    "python_versions_badge": "![Python versions](https://img.shields.io/pypi/pyversions/unique-uncertainty?label=Python)",
+    "chemrxiv_badge": f"[![ChemRxiv DOI]({chemrxiv_doi_badge_url})]({chemrxiv_doi})",
+    "conda_downloads_badge": f"[![Conda downloads]({conda_downloads_badge_url})]({conda_url})",
+    "conda_version_badge": f"[![Conda version]({conda_version_badge_url})]({conda_url})",
+    "docs_badge": f"[![Documentation build]({github_docs_badge_url})]({docs_url})",
+    "license_badge": f"[![License]({license_badge_url})]({license_url})",
+    "pypi_build_badge": f"[![PyPI build]({github_build_badge_url})]({pypi_url})",
+    "pypi_downloads_badge": f"[![PyPI downloads]({pypi_downloads_badge_url})]({pypi_url})",
+    "pypi_version_badge": f"[![PyPI version]({pypi_version_badge_url})]({pypi_url})",
+    "python_versions_badge": f"![Python versions]({python_versions_badge_url})",
 }
 
 source_suffix = {
@@ -139,16 +167,28 @@
     "icon_links": [
         {
             "name": "PyPI Version",
-            "url": "https://pypi.org/project/unique-uncertainty",
-            "icon": version_badge_url,
+            "url": pypi_url,
+            "icon": pypi_version_badge_url,
+            "type": "url",
+        },
+        {
+            "name": "Conda Version",
+            "url": conda_url,
+            "icon": conda_version_badge_url,
+            "type": "url",
+        },
+        {
+            "name": "chemRxiv DOI",
+            "url": chemrxiv_doi,
+            "icon": chemrxiv_doi_badge_url,
             "type": "url",
-        }
+        },
     ],
     "logo": {
         "alt_text": "UNIQUE's Documentation - Home",
         "image_dark": "_static/unique_logo_dark_blue.png",
     },
-    "repository_branch": "master",
+    "repository_branch": "main",
     "repository_provider": "github",
     "repository_url": "https://github.com/Novartis/UNIQUE",
     "path_to_docs": "./docs/source",

diff --git a/docs/source/development/contacts.md b/docs/source/development/contacts.md
@@ -10,6 +10,8 @@ For any questions or further details about the project, please get in touch with
 
 ## Cite Us
 
+{{chemrxiv_badge}}
+
 If you find `UNIQUE` helpful for your work and/or research, please consider citing our work:
 
 ```bibtex

diff --git a/docs/source/indepth/error_models.md b/docs/source/indepth/error_models.md
@@ -3,6 +3,7 @@ myst:
    substitutions:
       error_model_schema: |
          :::{figure} ../_static/error_model_schema.png
+         :target: _images/error_model_schema.png
          :alt: UNIQUE Error Model Schema
          :align: center
          :class: dark-light

diff --git a/docs/source/indepth/overview.md b/docs/source/indepth/overview.md
@@ -3,6 +3,7 @@ myst:
    substitutions:
       low_level_schema: |
          ```{figure} ../_static/schema_low_level.png
+         :target: _images/schema_low_level.png
          :alt: UNIQUE Low Level Schema
          :class: dark-light
 

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -18,24 +18,9 @@ myst:
 
          {{description}}
          :::
-      # See: https://github.com/executablebooks/MyST-Parser/issues/279#issuecomment-752948379
-      license_badge: |
-         :::{image} https://img.shields.io/badge/License-BSD_3--Clause-red
-         :alt: License
-         :target: https://opensource.org/licenses/BSD-3-Clause
-         :::
-      article_badge: |
-         :::{image} https://img.shields.io/badge/chemRxiv-10.26434%2Fchemrxiv--2024--fmbgk-yellow
-         :alt: Paper's DOI
-         :target: https://doi.org/10.26434/chemrxiv-2024-fmbgk
-         :::
-      docs_badge: |
-         :::{image} https://github.com/Novartis/UNIQUE/actions/workflows/docs.yml/badge.svg?branch=main
-         :alt: Documentation build status
-         :target: https://opensource.nibr.com/UNIQUE/
-         :::
       high_level_schema: |
          :::{figure} _static/schema_high_level.png
+         :target: _images/schema_high_level.png
          :alt: UNIQUE High-Level Schema
          :align: center
          :class: dark-light
@@ -46,7 +31,7 @@ myst:
 
 # Welcome to `UNIQUE`'s documentation!
 
-{{python_versions_badge}} {{pypi_version_badge}} {{license_badge}} {{article_badge}} {{docs_badge}} {{pypi_build_badge}} {{pypi_downloads_badge}}
+{{python_versions_badge}} {{pypi_version_badge}} {{conda_version_badge}} {{license_badge}} {{chemrxiv_badge}} {{pypi_downloads_badge}} {{conda_downloads_badge}} {{docs_badge}} {{pypi_build_badge}}
 
 {{logo_light}} {{logo_dark}}
 
@@ -62,8 +47,13 @@ myst:
 
 {{high_level_schema}}
 
+
+Check out [Installation](./installation.md) to get started!
+
 ## Cite Us
 
+{{chemrxiv_badge}}
+
 If you find `UNIQUE` helpful for your work and/or research, please consider citing our work:
 
 ```bibtex

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -10,21 +10,42 @@ myst:
 ---
 # Installation
 
-{{python_versions_badge}} {{pypi_version_badge}} {{pypi_downloads_badge}} {{pypi_build_badge}}
+{{python_versions_badge}} {{pypi_version_badge}} {{conda_version_badge}} {{pypi_downloads_badge}} {{conda_downloads_badge}} {{pypi_build_badge}}
 
-`UNIQUE` is currently compatible with Python 3.8 through 3.12.1. To install the latest release and use the package as is, run the following in a compatible environment of choice:
+`UNIQUE` is currently compatible with Python 3.8 through 3.12.1. To install the latest release, run the following in a compatible environment of choice:
+
+::::{tab-set}
+
+:::{tab-item} `pip`
 
 ```bash
 pip install unique-uncertainty
 ```
+:::
+
+:::{tab-item} `conda`
+
+```bash
+conda install -c conda-forge unique-uncertainty
+```
+:::
+
+:::{tab-item} `mamba`
+
+```bash
+mamba install -c conda-forge unique-uncertainty
+```
+:::
+
+::::
 
 :::{tip}
 To create a dedicated virtual environment for `UNIQUE` using `conda`/`mamba` with all the required and compatible dependencies, check out: [For Developers](#for-developers).
 :::
 
 ## For Developers
 
- {{precommit}} {{codestyle}}
+ {{license_badge}} {{precommit}} {{codestyle}}
 
 :::{seealso}
 If you wish to work on the codebase itself, check first [how to best contribute to `UNIQUE`](./development/contributing.md).
@@ -43,22 +64,29 @@ cd unique
 
 The project uses [`conda`](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) and/or [`mamba`](https://mamba.readthedocs.io/en/latest/index.html) for dependencies management.
 
-To set the project up, run:
+Install first the `conda` dependencies and the Jupyter kernel needed to run the examples:
 
 ```bash
 # Install conda environment and jupyter kernel locally
 make env && make jupyter-kernel
 conda activate .conda/unique
+```
 
+Next, enable the pre-commit hooks for automatic code formatting/linting:
+
+```bash
 # Setup precommit hooks
 make pre-commit
+```
 
-# Install UNIQUE
+Lastly, install `UNIQUE` from source:
+
+```bash
 pip install -e .
 # Use `pip install -e .[dev]` to also install optional dependencies
 ```
 
-In this way, you will have access to the `UNIQUE` codebase and be able to make local modifications to the source code, within the `.conda/unique` environment that contains all the required dependencies.
+In this way, you will have access to the `UNIQUE` codebase and be able to make local modifications to the source code, within the `./.conda/unique` local environment that contains all the required dependencies.
 
 Additionally, if you use Jupyter Notebooks, the `unique` kernel will be available in the "Select kernel" menu of the JupyterLab/JupyterNotebook UI.
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -12,7 +12,7 @@ authors = [
 ]
 readme = "README.md"
 classifiers = [
-	"Development Status :: 3 - Alpha",
+	"Development Status :: 4 - Beta",
 	"Intended Audience :: Developers",
 	"Intended Audience :: Education",
 	"Intended Audience :: Science/Research",
@@ -32,9 +32,9 @@ classifiers = [
 	"Topic :: Software Development :: Libraries",
 	"Topic :: Software Development :: Libraries :: Python Modules",
 ]
-version = "0.2.1"
+version = "0.2.2"
 license = {file="LICENSE.md"}
-description = "UNIQUE is a Python package for uncertainty quantification and benchmarking of ML models' predictions."
+description = "UNIQUE is a Python package for benchmarking uncertainty estimation and quantification methods for Machine Learning models predictions."
 requires-python = ">=3.8,<=3.12.1"
 dependencies = [
 	"colorcet>=3.0,<=3.0.1",
@@ -77,6 +77,7 @@ dev = [
 	"sphinx-autodoc2>=0.5.0",
 	"sphinx-book-theme>=1.1.2",
     "sphinx-copybutton==0.5.2",
+	"sphinx-design>=0.5,<0.7",
 	"tox>=3.27,<=4.12.1",
     "tox-conda>=0.10,<=0.10.2",
 ]

diff --git a/unique-environment.yml b/unique-environment.yml
@@ -26,6 +26,7 @@ dependencies:
     - sphinx-autodoc2 >=0.5.0
     - sphinx-book-theme >=1.1.2
     - sphinx-copybutton ==0.5.2
+    - sphinx-design >=0.5,<0.7
   - pre-commit >=3.6.2, <=3.7
   - pyarrow <=16.1.0
   - python >=3.8,<=3.12.1

diff --git a/unique/pipeline.py b/unique/pipeline.py
@@ -1113,7 +1113,11 @@ def evaluate_uq_metrics(
                     ).reset_index(drop=True)
             if (i + 1) % np.floor(len(self.all_metrics) / 3) == 0:
                 self.logger.info(
-                    f"Evaluated {i + 1} UQ methods out of {len(self.all_metrics)}..."
+                    f"Evaluated {i + 1} UQ methods out of {len(self.all_metrics)}{'...' if i+1<len(self.all_metrics) else '.'}"
+                )
+            elif (i + 1) >= len(self.all_metrics):
+                self.logger.info(
+                    f"Evaluated {i + 1} UQ methods out of {len(self.all_metrics)}."
                 )
 
         if self._bootstrap: