Merge pull request #2 from schwallergroup/checks

Improved typing, returning lists instead of tuples, docstrings, coverage

Author: jwa7

.github/workflows/test.yaml

@@ -0,0 +1,21 @@
+name: Run tests
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox tox-gh-actions
+      - name: Test with tox
+        run: tox

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.3.0
+  hooks:
+  - id: check-added-large-files 
+    args: [--maxkb=5000]
+  - id: check-merge-conflict
+
+# - repo: https://github.com/astral-sh/ruff-pre-commit
+#   rev: v0.3.2
+#   hooks:
+#     - id: ruff
+#       args: [ --fix, --exit-non-zero-on-fix ]
+#     - id: ruff-format

README.md

@@ -1,5 +1,7 @@
 # Rxn-INSIGHT: Fast Chemical Reaction Analysis Using Bond-Electron Matrices
 
+![Coverage Status](coverage-badge.svg)
+
 Rxn-INSIGHT is an open-source algorithm, written in python, to classify and name chemical reactions, and suggest reaction conditions based on similarity and popularity.
 * https://doi.org/10.1186/s13321-024-00834-z: Peer-reviewed publication on Rxn-INSIGHT
 ## 1. Installation
@@ -8,28 +10,45 @@ Rxn-INSIGHT relies on NumPy, Pandas, RDKit, RDChiral, and RXNMapper.
 A virtual environment can be installed with Anaconda as follows:
 
 ```console
-conda env create -f environment.yml
+conda create -n rxn-insight python=3.10
 conda activate rxn-insight
 ```
 
-To add the rxn-insight environment to Jupyter Notebook:
+```
+git clone https://github.com/schwallergroup/Rxn-INSIGHT.git
+cd Rxn-INSIGHT
+pip install .
+```
 
-```console
-python -m ipykernel install --user --name=rxn-insight
+Or, for developing with the optional dependencies, which are required to run the tests
+and build the docs:
+``` 
+pip install -e ".[test,doc]"
+```
+
+All of the test environments can be run using the command `tox` from the top directory.
+Alternatively, individual test environments can be run using the `-e` flag as 
+in `tox -e env-name`. To run the tests, tests with coverage report, style checks, and
+docs build, respectively:
+```
+tox -e py3
+tox -e py3-coverage
+tox -e style
+tox -e docs
 ```
 
 ## 2. Usage
 
 ### Basic Usage
-```console
+```python
 from rxn_insight.reaction import Reaction
 r = "c1ccccc1I.C=CC(=O)OC>>COC(=O)/C=C/c1ccccc1"  # Define a Reaction SMILES identifier
 rxn = Reaction(r)
 ri = rxn.get_reaction_info()
 ```
 
 The reaction info contains most of the information:
-```console
+```python
 {'REACTION': 'C=CC(=O)OC.Ic1ccccc1>>COC(=O)/C=C/c1ccccc1', 
  'MAPPED_REACTION': '[CH3:1][O:2][C:3](=[O:4])[CH:5]=[CH2:6].I[c:7]1[cH:8][cH:9][cH:10][cH:11][cH:12]1>>[CH3:1][O:2][C:3](=[O:4])/[CH:5]=[CH:6]/[c:7]1[cH:8][cH:9][cH:10][cH:11][cH:12]1', 
  'N_REACTANTS': 2, 
@@ -52,13 +71,13 @@ The reaction info contains most of the information:
 
 ### Similarity Search
 A similarity search can be performed when a database with similar reactions is provided as a pandas DataFrame (df in this case). Another Pandas DataFrame is returned.
-```console
+```python
 df_nbs = rxn.find_neighbors(df, fp="MACCS", concatenate=True, threshold=0.5, broaden=True, full_search=False)
 ```
 
 ### Condition Suggestion
 Reaction conditions can be suggested when a Pandas DataFrame is provided.
-```console
+```python
 rxn.suggest_conditions(df)
 suggested_solvents = rxn.suggested_solvent
 suggested_catalysts = rxn.suggested_catalyst

coverage-badge.svg

@@ -0,0 +1,7 @@
+rxn_insight
+===========
+
+.. toctree::
+   :maxdepth: 4
+
+   rxn_insight

docs/source/_static/.gitkeep

@@ -0,0 +1,45 @@
+rxn\_insight package
+====================
+
+Submodules
+----------
+
+rxn\_insight.classification module
+----------------------------------
+
+.. automodule:: rxn_insight.classification
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+rxn\_insight.reaction module
+----------------------------
+
+.. automodule:: rxn_insight.reaction
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+rxn\_insight.representation module
+----------------------------------
+
+.. automodule:: rxn_insight.representation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+rxn\_insight.utils module
+-------------------------
+
+.. automodule:: rxn_insight.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: rxn_insight
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/modules.rst

@@ -0,0 +1,92 @@
+"""Sphinx configuration."""
+
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import shutil
+import sys
+from importlib.metadata import metadata
+
+# -- Path setup
+
+__location__ = os.path.dirname(__file__)
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.join(__location__, "../../src"))
+
+# -- Run sphinx-apidoc
+# This hack is necessary since RTD does not issue `sphinx-apidoc` before running
+# `sphinx-build -b html . _build/html`. See Issue:
+# https://github.com/readthedocs/readthedocs.org/issues/1139
+# DON'T FORGET: Check the box "Install your project inside a virtualenv
+# Additionally it helps us to avoid running apidoc manually
+
+try:  # for Sphinx >= 1.7
+    from sphinx.ext import apidoc
+except ImportError:
+    from sphinx import apidoc
+
+output_dir = os.path.join(__location__, "api")
+module_dir = os.path.join(__location__, "../../src/rxn_insight")
+try:
+    shutil.rmtree(output_dir)
+except FileNotFoundError:
+    pass
+
+try:
+    import sphinx
+
+    cmd_line = f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}"
+
+    args = cmd_line.split(" ")
+    if tuple(sphinx.__version__.split(".")) >= ("1", "7"):
+        # This is a rudimentary parse_version to avoid external dependencies
+        args = args[1:]
+
+    apidoc.main(args)
+except Exception as e:
+    print(f"Running `sphinx-apidoc` failed!\n{e}")
+
+# -- Project information
+
+_metadata = metadata("rxn_insight")
+
+project = _metadata["Name"]
+author = _metadata["Author-email"].split("<", 1)[0].strip()
+copyright = f"2024, {author}"
+
+version = _metadata["Version"]
+release = ".".join(version.split(".")[:2])
+
+
+# -- General configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx.ext.autodoc",
+    # "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+
+exclude_patterns = [
+    "Thumbs.db",
+    ".DS_Store",
+    ".ipynb_checkpoints",
+]
+
+# -- Options for HTML output
+
+html_theme = "furo"
+html_static_path = ["_static"]

docs/source/api/rxn_insight.rst

@@ -0,0 +1,15 @@
+```{include} ../../README.md
+:relative-images:
+```
+
+```{toctree}
+:caption: 'Contents:'
+:maxdepth: 2
+api/modules
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

docs/source/conf.py

@@ -15,7 +15,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from rxn_insight.reaction import *\n",
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "from rxnmapper import RXNMapper\n",
+    "\n",
+    "from rxn_insight.reaction import Reaction\n",
+    "from rxn_insight.utils import draw_chemical_reaction, curate_smirks, get_similarity, get_fp\n",
+    "from IPython.display import SVG, display\n",
     "import time"
    ]
   },
@@ -34,7 +40,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "df_uspto = pd.read_parquet(\"data/example.gzip\")"
+    "df_uspto = pd.read_parquet(\"../data/example.gzip\")"
    ]
   },
   {
@@ -107,6 +113,27 @@
     "rxn.get_reaction_info()"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1eed892f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rxn = '[CH3:1][O:2][C:3](=[O:4])[CH:5]=[CH2:6].I[c:7]1[cH:8][cH:9][cH:10][cH:11][cH:12]1>>[CH3:1][O:2][C:3](=[O:4])/[CH:5]=[CH:6]/[c:7]1[cH:8][cH:9][cH:10][cH:11][cH:12]1'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "91a73156",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rxn2 = Reaction(rxn, keep_mapping=True)\n",
+    "rxn2.get_reaction_info()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "b8a0b8de",
@@ -133,9 +160,9 @@
    "outputs": [],
    "source": [
     "rxn_mapper = RXNMapper()\n",
-    "smirks = pd.read_json(\"src/rxn_insight/json/smirks.json\", orient='records', lines=True)\n",
+    "smirks = pd.read_json(\"../src/rxn_insight/json/smirks.json\", orient='records', lines=True)\n",
     "smirks = curate_smirks(smirks)\n",
-    "fg = pd.read_json(\"src/rxn_insight/json/functional_groups.json\", orient='records', lines=True)"
+    "fg = pd.read_json(\"../src/rxn_insight/json/functional_groups.json\", orient='records', lines=True)"
    ]
   },
   {
@@ -185,7 +212,7 @@
    "outputs": [],
    "source": [
     "# df_analyzed = pd.read_parquet(\"data/uspto.gzip\")\n",
-    "df_analyzed = pd.read_parquet(\"data/1000rxns.gzip\")"
+    "df_analyzed = pd.read_parquet(\"../data/1000rxns.gzip\")"
    ]
   },
   {