New visualization options (#59)

### Added

- A new Escher binding independent of the original one [Escher-custom]
  - This integration is independent of the original and, therefore, does not have the same version conflicts.
- A new Visualization option that displays cobra Objects as a Force Directed Graph
- Introduced [Galata](https://github.com/jupyterlab/jupyterlab/tree/main/galata) as a new test suite
  - Galata automates the testing of visualization as it can compare reference images with outputs created in Jupyter Notebooks

### Changed

- cobramod.pathway
  - The visualization function now includes the possibility to choose between different visualization options
- Type checks
  - Reintroduced MyPy as Ruff does not check types according to [ruff's FAQ](https://docs.astral.sh/ruff/faq/#how-does-ruff-compare-to-mypy-or-pyright-or-pyre)
- GitHub Actions
  - GitHub Actions now run tests on Windows and macOS once again 
  - New workflow for the creation of Galata reference images
  - GitHub Action has been divided into smaller sections to provide a better overview of failed steps
- Documentation
  - Now uses [Furo](https://github.com/pradyunsg/furo?tab=readme-ov-file) as a theme
  - Provides additional live examples of the new visualization options
- Tests
  - Tests no longer check for specific database versions; this is only done in a controlled manner for the db_version module
  - Tests for visualization using Escher now use Escher-Custom
  - Several visualization tests were replaced by an equivalent test using Galata
- environment.yml
  - Some dependencies now use their conda-forge package to reduce build time
  - 'sphinx-autoapi' was set to a dev version to be able to create the documentation using Python 3.12
- Maintenance
  - Several adjustments due to announced deprecations

.github/workflows/test-build-and-publish.yml

@@ -11,58 +11,133 @@ on:
       - master
 
 jobs:
-  lint-format-unittest:
+  lint-format:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: python -m pip install tox
+      - name: Linter
+        run: python -m tox -e lint
+      - name: Format
+        run: python -m tox -e format
+
+  types:
+    needs: [ lint-format ]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12" ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: python -m pip install tox
+      - name: Run type-checking
+        run: python -m tox -e types
+
+  build:
+    needs: [ types ]
+    runs-on: ubuntu-latest
+    outputs:
+      file-path: ${{ steps.path.outputs.file-path }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "pip"
+
+      - name: Set up JS & build js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools wheel build
+          yarn install
+
+      - name: Build JS
+        run: yarn run vite build
+      - name: Build package
+        run: python -m build
+
+      - name: Get file name
+        id: path
+
+        run: echo "file-path=$(cd dist && find . -type f -name cobramod-*.whl)" >> "$GITHUB_OUTPUT"
+
+      - name: Archive package as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cobramod-dist
+          path: |
+            dist
+
 
+  unittest:
+    needs: [build]
+    strategy:
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        python-version: [ "3.10", "3.11", "3.12" ]
+    runs-on: ${{ matrix.os}}
+    steps:
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
 
       - name: Display Python version
         run: python -c "import sys; print(sys.version)"
 
-      - name: Install dependencies
-        run: python -m pip install .
+      - name: Download package as artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: cobramod-dist
 
       - name: Install tox
         run: python -m pip install tox-gh>=1.2
 
-      - name: Setup test suite
-        run: tox -vv --notest
-
       - name: Credentials
         run: echo "${{ secrets.BIOCYC_USER }}\n${{ secrets.BIOCYC_PASS }}" >> credentials.txt
 
+      - name: Setup test suite
+        run: tox -vv --notest --installpkg ${{ needs.build.outputs.file-path }}
+
       - name: Run test suite
         run: tox --skip-pkg-install
 
   build-publish:
-    needs: [lint-format-unittest]
-    name: Build and publish the package to TestPyPI
+    needs: [unittest]
+    name: Build and publish the package to PyPI
     if: github.event.pull_request.merged == true && github.event_name != 'schedule'
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: "3.10"
-        cache: "pip"
 
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip setuptools wheel twine build
+    - name: Download package as artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: cobramod-dist
+        path: |
+          dist    
 
-    - name: Build package
-      run: python -m build
     - name: Check the package
       run: twine check dist/*
+
     - name: Publish to PyPI
       env:
         TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}

.github/workflows/update_galata_references.yaml

@@ -0,0 +1,62 @@
+# Based on the action of jupyterlab team https://raw.githubusercontent.com/jupyterlab/jupyterlab/main/.github/workflows/galata-update.yml
+name: Update Playwright Snapshots
+
+on:
+  workflow_dispatch:
+  issue_comment:
+    types: [created, edited]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-galata-snapshots:
+    name: Update Galata References
+    if: ${{ github.event.issue.pull_request && (contains(github.event.comment.body, 'please update galata snapshots') || contains(github.event.comment.body, 'please update snapshots')) }}
+    timeout-minutes: 80
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure git to use https
+        run: git config --global hub.protocol https
+
+      - name: Checkout the branch from the PR that triggered the job
+        run: hub pr checkout ${{ github.event.issue.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up JS & build js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          yarn install
+
+      - name: Build JS
+        run: yarn run vite build
+
+      - name: Install package
+        run: pip install .
+
+      - uses: jupyterlab/maintainer-tools/.github/actions/update-snapshots@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          start_server_script: start
+          server_url: http-get://localhost:8888/lab
+          test_folder: ui-tests
+          artifact_name: updated-galata-snapshots
+          report_name: update-galata-report
+
+      - name: Comment back on the PR
+        run: |
+          hub api repos/${{ github.repository }}/issues/${{ github.event.issue.number }}/comments --raw-field 'body=Galata snapshots updated.'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -12,3 +12,10 @@ docs/source/summary.txt
 
 # All non-essential files created/used by tox
 .tox
+
+# node_modules
+node_modules/
+
+# ui test results
+ui-tests/playwright-report
+ui-tests/test-results

.readthedocs.yml

@@ -3,7 +3,13 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "miniconda3-4.7"
+    python: "mambaforge-22.9"
+    nodejs: "latest"
+  jobs:
+      pre_create_environment:
+        - npm install --global yarn
+        - yarn install
+        - yarn run vite build
 
 conda:
   environment: environment.yml

CHANGELOG.md

@@ -8,6 +8,37 @@
 - Visualization with other tools than Escher
 - Deprecation of SolCyc
 - Deprecation of PairDictionary
+- Deprecation of Escher's official binding 
+
+## [1.3.0]
+
+### Added
+
+- A new Escher binding independent of the original one [Escher-custom]
+- A new Visualization option that displays cobra Objects as a Force Directed Graph
+- Introduced [Galata](https://github.com/jupyterlab/jupyterlab/tree/main/galata) as a new test suite
+  - Galata automates testing of visualisation as it can compare reference images with outpus created in Jupyter Notebooks
+
+### Changed
+
+- Type checks
+  - Reintroduced MyPy as Ruff does not check types according to [ruff's FAQ](https://docs.astral.sh/ruff/faq/#how-does-ruff-compare-to-mypy-or-pyright-or-pyre)
+- GitHub Actions
+  - GitHub Actions now run tests on Windows and macOS once again 
+  - New workflow for the creation of Galata reference images
+  - GitHub Action has been divided into smaller sections to provide a better overview of failed steps
+- Documentation
+  - Now uses [Furo](https://github.com/pradyunsg/furo?tab=readme-ov-file) as a theme
+  - Provides additional live examples of the new visualization options
+- Tests
+  - Tests no longer check for specific database versions, this is only done in a controlled manner for the db_version module
+  - Tests for visualization using Escher now use Escher-Custom
+  - Several visualization tests were replaced by an equivalent test using Galata
+- environment.yml
+  - Some dependencies now use their conda-forge package to reduce build time
+  - 'sphinx-autoapi' was set to a dev version to be able to create the documentation using python 3.12
+- Maintenance
+  - Several adjustments due to announced deprecations
 
 ## [1.2.0]
 

CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+title: CobraMod
+message: >-
+  If you use this software, please cite it as below.
+type: software
+authors:
+    - given-names: Stefano
+      family-names: Camborda La Cruz
+    - given-names: Jan-Niklas
+      family-names: Weder
+    - given-names: Nadine
+      family-names: Töpfer
+repository-code: 'https://github.com/Toepfer-Lab/cobramod'
+url: 'https://cobramod.readthedocs.io/en/latest/'
+license: GPL-3.0
+preferred-citation:
+    type: article
+    authors:
+      - given-names: Stefano
+        family-names: Camborda La Cruz
+      - given-names: Jan-Niklas
+        family-names: Weder
+      - given-names: Nadine
+        family-names: Töpfer
+    doi: "10.1093/bioinformatics/btac119"
+    journal: "Bioinformatics"
+    start: 2654
+    end: 2656
+    title: "CobraMod: a pathway-centric curation tool for constraint-based metabolic models"
+    url: "https://doi.org/10.1093/bioinformatics/btac119"
+    eprint: "https://academic.oup.com/bioinformatics/article-pdf/38/9/2654/43481008/btac119.pdf"
+    volume: 38
+    number: 9
+    issn: "1367-4803"
+    month: 02
+    year: 2022

README.md

@@ -1,22 +1,28 @@
+<div align="center">
+
 ![Static Badge](https://img.shields.io/badge/python-3.10%7C3.11%7C3.12-%20blue)
 ![GitHub](https://img.shields.io/github/license/Toepfer-Lab/cobramod)
+[![Downloads](https://img.shields.io/pepy/dt/cobramod
+)](https://pepy.tech/project/cobramod)
+
+![Version](https://img.shields.io/pypi/v/cobramod?label=version)
 ![Read the Docs (version)](https://img.shields.io/readthedocs/cobramod/latest)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Toepfer-lab/cobramod/test-build-and-publish.yml)
-![Version](https://img.shields.io/pypi/v/cobramod?label=version)
-[![Downloads](https://pepy.tech/badge/cobramod)](https://pepy.tech/project/cobramod)
-
+![Coverage Status](./docs/source/img/coverage.svg)
 
 CobraMod: A pathway-centric curation tool for constraint-based metabolic models
 ===============================================================================
 
+
 ![image](https://raw.githubusercontent.com/Toepfer-Lab/cobramod/master/docs/source/img/logo.png)
+</div>
 
 CobraMod is a Python 3 open-source package for pathway-centric curation of
-genome-scale metabolic models (GEMs). It builds upon the [COBRApy toolbox]
-(https://opencobra.github.io/cobrapy/) and offers a comprehensible set of
-functions for semi-automated network extension, curation and visualization.
-CobraMod supports all databases from the [BioCyc collection](https://
-biocyc.org/), the [KEGG database](https://www.genome.jp/kegg/), and the [BiGG
+genome-scale metabolic models (GEMs). It builds upon the 
+[COBRApy toolbox](https://opencobra.github.io/cobrapy/) and offers a 
+comprehensible set of functions for semi-automated network extension, curation and visualization.
+CobraMod supports all databases from the [BioCyc collection](https://biocyc.org/), 
+the [KEGG database](https://www.genome.jp/kegg/), and the [BiGG
 Models repository](http://bigg.ucsd.edu/). It optionally can interact with
 Escher for pathway and flux visualization.
 
@@ -94,6 +100,25 @@ for more information.
 
 Development
 -----------
+CobraMod consists of a Python and JavaScript/TypeScript part. 
+The following briefly describes all the commands to build a local 
+version from the source files.
+
+### JavaScript
+
+Since we need Node modules to build the Jupyter integrations con CobraMod, 
+a package.json is included in the project. All dependencies contained 
+in it can be made available locally using [yarn](https://yarnpkg.com/). The foiling command can be used for this:
+
+    yarn install
+
+We use [Vite](https://vitejs.dev/) to build the Javascript part of the Jupyter integrations. So, we can use the following command to build a bundled version of the integrations.
+
+    yarn run vite build
+
+This creates bundled JavaScript files under '/src/cobramod/static'.
+
+### Python
 
 You can contribute to CobraMod by cloning the repository and installing it in
 developer mode and using the `dev` dependency group via pip: