Codespace for tutorial based on Dockerfile

.devcontainer/devcontainer.json

@@ -0,0 +1,18 @@
+{
+  "name": "Codespace for dingo tutorial",
+  "build": {
+    "dockerfile": "../Dockerfile",
+    "context": ".."
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-toolsai.jupyter",
+        "james-yu.latex-workshop"
+      ]
+    }
+  },
+  "features": {},
+  "postCreateCommand": "bash .devcontainer/post_create.sh"
+}

.devcontainer/post_create.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+set -e  # stop on any error
+
+apt-get update
+apt-get install -y \
+    libnss3 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libxkbcommon0 \
+    libpango-1.0-0 \
+    libcairo2 \
+    libasound2
+
+pip install --upgrade nbformat kaleido
+echo y | plotly_get_chrome

.gitignore

@@ -11,5 +11,4 @@ volestipy.egg-info
 .vscode
 venv
 lp_solve_5.5/
-.devcontainer/
 .github/dependabot.yml

Dockerfile

@@ -0,0 +1,52 @@
+# Use the Gurobi Docker image as a base
+FROM gurobi/python
+
+# Install any additional dependencies for dingo
+RUN apt-get update && apt-get install -y \
+	cmake \
+	lp-solve \
+	git \
+	wget \
+	vim \
+	bzip2 \
+	g++ \
+	&& rm -rf /var/lib/apt/lists/*
+
+# Install dependencies
+RUN apt-get update && apt-get install -y libsuitesparse-dev
+RUN pip install sparseqr \
+	Cython \
+	cobra \ 
+	kaleido
+
+# Get PySQR
+RUN apt-get install libsuitesparse-dev
+
+# Install Python dependencies
+RUN pip install matplotlib \
+	plotly \
+	networkx \
+	pyoptinterface[highs]
+
+# Get dingo
+WORKDIR /workspaces/dingo
+COPY . .
+
+# Get submodules
+RUN git submodule update --init
+
+# Get lp-solve
+RUN wget https://sourceforge.net/projects/lpsolve/files/lpsolve/5.5.2.11/lp_solve_5.5.2.11_source.tar.gz &&\
+	tar xzvf lp_solve_5.5.2.11_source.tar.gz &&\
+	rm lp_solve_5.5.2.11_source.tar.gz
+
+# Get boost library
+RUN wget -O boost_1_76_0.tar.bz2 https://archives.boost.io/release/1.76.0/source/boost_1_76_0.tar.bz2 &&\
+	tar xjf boost_1_76_0.tar.bz2 &&\
+	rm boost_1_76_0.tar.bz2
+
+# Set environmental variable gurobi license path
+ENV GRB_LICENSE_FILE=/opt/gurobi/gurobi.lic
+
+# Install dingo
+RUN ["python", "setup.py", "install", "--user"]

README.md

@@ -11,44 +11,80 @@ metabolic network, namely Flux Balance Analysis and Flux Variability Analysis.
 
 `dingo` is part of [GeomScale](https://geomscale.github.io/) project.
 
-[![unit-tests](https://github.com/GeomScale/dingo/workflows/dingo-ubuntu/badge.svg)](https://github.com/GeomScale/dingo/actions?query=workflow%3Adingo-ubuntu)
-[![Tutorial In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/GeomScale/dingo/blob/develop/tutorials/dingo_tutorial.ipynb)
-[![Chat](https://badges.gitter.im/geomscale.png)](https://gitter.im/GeomScale/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
+<a href="https://github.com/GeomScale/dingo/actions?query=workflow%3Adingo-ubuntu">
+  <img src="https://github.com/GeomScale/dingo/workflows/dingo-ubuntu/badge.svg" height="20">
+</a>
+<a href="https://codespaces.new/GeomScale/dingo?quickstart=1">
+  <img src="https://github.com/codespaces/badge.svg" height="20">
+</a>
+<a href="https://gitter.im/GeomScale/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link">
+  <img src="https://badges.gitter.im/geomscale.png" height="20">
+</a>
 
 
-## Installation
+## Installation 
+
+### LP solver (optional, probably better performance)
+
+`dingo` makes use of [`pyoptinterface`](https://metab0t.github.io/PyOptInterface/) to interface with a range of linear programming solvers. 
+
+The default solver is [`highs`](https://highs.dev/#get-started). 
+
+However, one may switch to other solvers that `pyoptinterface` supports, for example the commonly used [`gurobi`](https://www.gurobi.com/). 
+Yet, in that case a Gurobi license is required. 
+
+> **Get a Gurobi license**
+> 
+> If you are affiliated in an academic insitute, you can generate a **free academic license**.
+> 
+> First, register and/or login to your [Gurobi account](https://portal.gurobi.com/iam/login/), and 
+> 
+> * if you are about to use `dingo` as a container, get a [**Web License Service (WLS) academic license**](https://support.gurobi.com/hc/en-us/articles/13210193318033-What-is-an-Academic-WLS-license)
+> * otherwise, you should go for the typical [**free academic license**](https://www.gurobi.com/academics)
+>  
+> 🔴 In both cases, make sure you are connected to the internet of an academic institution.
+
+
+### Installation (on Linux)
 
 **Note:** Python version should be 3.8.x. You can check this by running the following command in your terminal:
 ```bash
 python --version
 ```
-If you have a different version of Python installed, you'll need to install it ([start here](https://linuxize.com/post/how-to-install-python-3-8-on-ubuntu-18-04/)) and update-alternatives ([start here](https://linuxhint.com/update_alternatives_ubuntu/))
 
-**Note:** If you are using `GitHub Codespaces`. Start [here](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces) to set the python version. Once your Python version is `3.8.x` you can start following the below instructions.
+If you have a different version of Python installed, you'll need to install it ([start here](https://linuxize.com/post/how-to-install-python-3-8-on-ubuntu-18-04/))
+and update-alternatives ([start here](https://linuxhint.com/update_alternatives_ubuntu/)).
+
+Clone the `dingo` repo by 
 
+```
+git clone https://github.com/GeomScale/dingo.git
+```
 
 
-To load the submodules that dingo uses, run
+and load the submodules that `dingo` uses:
 
 ````bash
+cd dingo
 git submodule update --init
 ````
 
-You will need to download and unzip the Boost library:
+You will then need to download and unzip the [Boost C++](https://www.boost.org/) library:
 ```
 wget -O boost_1_76_0.tar.bz2 https://archives.boost.io/release/1.76.0/source/boost_1_76_0.tar.bz2
 tar xjf boost_1_76_0.tar.bz2
 rm boost_1_76_0.tar.bz2
 ```
 
-You will also need to download and unzip the lpsolve library:
+You will also need to download and unzip the [`lpsolve`](https://lpsolve.sourceforge.net/5.5/) library:
 ```
 wget https://sourceforge.net/projects/lpsolve/files/lpsolve/5.5.2.11/lp_solve_5.5.2.11_source.tar.gz
 tar xzvf lp_solve_5.5.2.11_source.tar.gz
 rm lp_solve_5.5.2.11_source.tar.gz
 ```
 
-Then, you need to install the dependencies for the PySPQR library; for Debian/Ubuntu Linux, run
+Then, you need to install the dependencies for the [PySPQR](https://github.com/yig/PySPQR) library; 
+for this, you will most likely need `sudo` rights:
 
 ```bash
 sudo apt-get update -y
@@ -57,48 +93,97 @@ sudo apt-get install -y libsuitesparse-dev
 
 To install the Python dependencies, `dingo` is using [Poetry](https://python-poetry.org/),
 ```
-curl -sSL https://install.python-poetry.org | python3 - --version 1.3.2
+curl -sSL https://install.python-poetry.org | python - --version 1.3.2
 poetry shell
 poetry install
 ```
 
-You can install the [Gurobi solver](https://www.gurobi.com/) for faster linear programming optimization. Run
+otherwise, you may try:
+
+```
+python setup.py install --user
+```
+
+
+Last, in case you are about to use Gurobi, remember to install the Python interface of Gurobi, [`gurobipy`](https://www.gurobi.com/resources/faq/gurobipy):
+
+```
+pip install -i https://pypi.gurobi.com gurobipy
+```
+
+
+
+## Using `dingo` as a Docker container
+
+To use `dingo` as a container, you need to [install Docker](https://docs.docker.com/engine/install/), 
+or [Docker desktop](https://docs.docker.com/desktop/), first.
+
+Then you can clone the `dingo` repo and build its Docker image:
+
+```
+git clone https://github.com/GeomScale/dingo.git
+cd dingo 
+docker build -f Dockerfile -t dingo .
+```
+
+Once the image is built, you may run:
 
 ```
-pip3 install -i https://pypi.gurobi.com gurobipy
+docker run --rm -it -v <path_to_your_model>:/data dingo
 ```
 
-Then, you will need a [license](https://www.gurobi.com/downloads/end-user-license-agreement-academic/). For more information, we refer to the Gurobi [download center](https://www.gurobi.com/downloads/).
+or, if you are using Gurobi, you may run:
+
+```
+docker run --rm -it -v <path_to_WLS_license>:/opt/gurobi/gurobi.lic -v <path_to_your_model>:/data dingo
+```
 
+> **Remember!** in this case, where `dingo` is run in a containerized environment and Gurobi is used as the solver, a standard node-locked Gurobi license would not work; a WLS license is typically required instead.
+> 
+> This would look something like this:
+>
+> ```
+> # Gurobi WLS license file
+> # Your credentials are private and should not be shared or copied to public repositories.
+> # Visit https://license.gurobi.com/manager/doc/overview for more information.
+> WLSACCESSID=d5419c87-0d36-4a93-9385-773f5483b3c1
+> WLSSECRET=afa5d95f-ad0b-4a38-9550-a8913aacb7c0
+> LICENSEID=000000
+>```
 
 
 
 ## Unit tests
 
 Now, you can run the unit tests by the following commands (with the default solver `highs`):
 ```
-python3 tests/fba.py
-python3 tests/full_dimensional.py
-python3 tests/max_ball.py
-python3 tests/scaling.py
-python3 tests/rounding.py
-python3 tests/sampling.py
+python tests/fba.py
+python tests/full_dimensional.py
+python tests/max_ball.py
+python tests/scaling.py
+python tests/rounding.py
+python tests/sampling.py
 ```
 
-If you have installed Gurobi successfully, then run
+Or, assuming you have installed Gurobi successfully, or an other `pyoptinterface`-supported solver, you may run:
 ```
-python3 tests/fba.py gurobi
-python3 tests/full_dimensional.py gurobi
-python3 tests/max_ball.py gurobi
-python3 tests/scaling.py gurobi
-python3 tests/rounding.py gurobi
-python3 tests/sampling.py gurobi
+python tests/fba.py gurobi
+python tests/full_dimensional.py gurobi
+python tests/max_ball.py gurobi
+python tests/scaling.py gurobi
+python tests/rounding.py gurobi
+python tests/sampling.py gurobi
 ```
 
 ## Tutorial
 
-You can have a look at our [Google Colab notebook](https://colab.research.google.com/github/GeomScale/dingo/blob/develop/tutorials/dingo_tutorial.ipynb)
-on how to use `dingo`.
+You may check out `dingo`'s main features through a GitHub codespace.
+To do this, you may click [here](https://github.com/codespaces/new?repo=GeomScale/dingo&ref=main) and fire a new codespace
+by clicking on the "Create codespace" button. 
+
+This will take a few minutes (~5'). 
+
+Once the codespace is ready, you may try to follow the [`dingo_tutorial`](./tutorials/dingo_tutorial.ipynb) Jupyter notebook. 
 
 
 ## Documentation
@@ -191,14 +276,17 @@ The MCMC methods that dingo (through `volesti` library) provides are the followi
 
 #### Switch the linear programming solver
 
-We use `pyoptinterface` to interface with the linear programming solvers. To switch the solver that `dingo` uses, you can use the `set_default_solver` function. The default solver is `highs` and you can switch to `gurobi` by running,
+We use `pyoptinterface` to interface with the linear programming solvers. 
+To switch the solver that `dingo` uses, you can use the `set_default_solver` function. 
+The default solver is `highs` and you can switch to `gurobi` by running:
 
 ```python
 from dingo import set_default_solver
 set_default_solver("gurobi")
 ```
 
-You can also switch to other solvers that `pyoptinterface` supports, but we recommend using `highs` or `gurobi`. If you have issues with the solver, you can check the `pyoptinterface` [documentation](https://metab0t.github.io/PyOptInterface/getting_started.html).
+You can also switch to other solvers that `pyoptinterface` supports, but we recommend using `highs` or `gurobi`. 
+If you have issues with the solver, you can check the `pyoptinterface` [documentation](https://metab0t.github.io/PyOptInterface/getting_started.html).
 
 ### Apply FBA and FVA methods
 

dingo/illustrations.py

@@ -14,7 +14,7 @@
 import plotly.figure_factory as ff
 from scipy.cluster import hierarchy
 
-def plot_copula(data_flux1, data_flux2, n = 5, width = 900 , height = 600, export_format = "svg"):
+def plot_copula(data_flux1, data_flux2, n = 5, width = 900 , height = 600, save = True, export_format = "svg"):
     """A Python function to plot the copula between two fluxes
 
     Keyword arguments:
@@ -59,17 +59,21 @@ def plot_copula(data_flux1, data_flux2, n = 5, width = 900 , height = 600, expor
     )
 
     fig.update_layout(scene_camera=camera)
-    fig.to_image(format = export_format, engine="kaleido")
-    pio.write_image(fig, fig_name, scale=2)
+
+    if save:
+        fig.to_image(format = export_format, engine="kaleido")
+        pio.write_image(fig, fig_name, scale=2)
 
 
-def plot_histogram(reaction_fluxes, reaction, n_bins=40):
+def plot_histogram(reaction_fluxes, reaction, n_bins = 40, save = False, export_format = "png"):
     """A Python function to plot the histogram of a certain reaction flux.
 
     Keyword arguments:
     reaction_fluxes -- a vector that contains sampled fluxes of a reaction
     reaction -- a string with the name of the reacion
     n_bins -- the number of bins for the histogram
+    save -- save plot to a file
+    export_format -- file format to save the plot
     """
 
     plt.figure(figsize=(7, 7))
@@ -84,10 +88,14 @@ def plot_histogram(reaction_fluxes, reaction, n_bins=40):
     plt.title("Reaction: " + reaction, fontweight="bold", fontsize=18)
     plt.axis([np.amin(reaction_fluxes), np.amax(reaction_fluxes), 0, np.amax(n) * 1.2])
 
+    if save:
+        plt.savefig(reaction + "." + export_format, dpi = 150, bbox_inches = "tight", format = export_format)
+
     plt.show()
 
 
 
+
 def plot_corr_matrix(corr_matrix, reactions, removed_reactions=[], format="svg"):
     """A Python function to plot the heatmap of a model's pearson correlation matrix.