Add notebooks to document modules

.github/workflows/ci.yml

@@ -97,6 +97,7 @@ jobs:
         run: |
           python -m pip install matplotlib
           pytest --no-cov -v --nbmake $(find examples -name '*.ipynb' ! -name 'hpopting.ipynb')
+          pytest --no-cov -v --nbmake $(find docs/source/tutorial/python -name "*.ipynb")
       - name: Test hpopting.ipynb (Python 3.11 only)
         if: ${{ matrix.python-version == '3.11' }}
         shell: bash -l {0}

docs/source/index.rst

@@ -24,6 +24,7 @@ If you use Chemprop to train or develop a model in your own work, we would appre
     quickstart
     installation
     tutorial/cli/index
+    tutorial/python/index
     notebooks
     cmd
 

docs/source/notebooks.rst

@@ -1,7 +1,7 @@
 .. _notebooks:
 
-Jupyter Notebook Tutorials
-==========================
+Jupyter Notebook Examples
+=========================
 
 Chemprop's usage within Python scripts is also illustrated by the Jupyter notebooks on the following pages.
 
@@ -17,5 +17,4 @@ Chemprop's usage within Python scripts is also illustrated by the Jupyter notebo
     training_regression_reaction
     predicting_regression_reaction
     mpnn_fingerprints
-    extra_features_from_featurizer
     convert_v1_to_v2

docs/source/tutorial/cli/index.rst

@@ -1,7 +1,7 @@
 .. _tutorial:
 
-Command Line Tutorial
-=====================
+Command Line Tutorials
+======================
 
 .. note::
     Chemprop recently underwent a ground-up rewrite and new major release (v2.0.0). A helpful transition guide from Chemprop v1 to v2 can be found `here <https://docs.google.com/spreadsheets/u/3/d/e/2PACX-1vRshySIknVBBsTs5P18jL4WeqisxDAnDE5VRnzxqYEhYrMe4GLS17w5KeKPw9sged6TmmPZ4eEZSTIy/pubhtml>`_. This includes a side-by-side comparison of CLI argument options, a list of which arguments will be implemented in later versions of v2, and a list of changes to default hyperparameters.

docs/source/tutorial/python/activation.ipynb

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Activation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from chemprop.nn.utils import Activation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Activation functions\n",
+    "\n",
+    "The following activation functions are available in Chemprop."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "relu\n",
+      "leakyrelu\n",
+      "prelu\n",
+      "tanh\n",
+      "selu\n",
+      "elu\n"
+     ]
+    }
+   ],
+   "source": [
+    "for activation in Activation:\n",
+    "    print(activation)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Custom"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Custom activation functions require editing the source code in `chemprop.nn.utils.py`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from enum import auto\n",
+    "from torch import nn\n",
+    "\n",
+    "from chemprop.utils.utils import EnumMapping\n",
+    "\n",
+    "\n",
+    "class Activation(EnumMapping):\n",
+    "    RELU = auto()\n",
+    "    LEAKYRELU = auto()\n",
+    "    PRELU = auto()\n",
+    "    TANH = auto()\n",
+    "    SELU = auto()\n",
+    "    ELU = auto()\n",
+    "    GELU = auto()  # example edited source code\n",
+    "\n",
+    "\n",
+    "def get_activation_function(activation: str | Activation) -> nn.Module:\n",
+    "    \"\"\"Gets an activation function module given the name of the activation.\n",
+    "\n",
+    "    See :class:`~chemprop.v2.models.utils.Activation` for available activations.\n",
+    "\n",
+    "    Parameters\n",
+    "    ----------\n",
+    "    activation : str | Activation\n",
+    "        The name of the activation function.\n",
+    "\n",
+    "    Returns\n",
+    "    -------\n",
+    "    nn.Module\n",
+    "        The activation function module.\n",
+    "    \"\"\"\n",
+    "    match Activation.get(activation):\n",
+    "        case Activation.RELU:\n",
+    "            return nn.ReLU()\n",
+    "        case Activation.LEAKYRELU:\n",
+    "            return nn.LeakyReLU(0.1)\n",
+    "        case Activation.PRELU:\n",
+    "            return nn.PReLU()\n",
+    "        case Activation.TANH:\n",
+    "            return nn.Tanh()\n",
+    "        case Activation.SELU:\n",
+    "            return nn.SELU()\n",
+    "        case Activation.ELU:\n",
+    "            return nn.ELU()\n",
+    "        case Activation.GELU:  # example edited source code\n",
+    "            return nn.GELU()  # example edited source code\n",
+    "        case _:\n",
+    "            raise RuntimeError(\"unreachable code reached!\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "chemprop",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}