ecco is a Jupyter library dedicated to the formal modelling and analysis of ecosystems.
It implements methods described and used in several papers:
- Using discrete systems to exhaustively characterize the dynamics of an integrated ecosystem. C. Gaucherel, F. Pommereau. DOI:10.1111/2041-210X.13242
- Maintaining biodiversity promotes the multifunctionality of social-ecological systems: holistic modelling of a mountain system. Z. Mao, J. Centanni, F. Pommereau, A. Stokes, C. Gaucherel. DOI:10.1016/j.ecoser.2020.101220
- Discrete-event models for conservation assessment of integrated ecosystems. C. Gaucherel, C. Carpentier, I. R. Geijzendorffer, C. Noûs, F. Pommereau. DOI:10.1016/j.ecoinf.2020.101205
- Understanding Ecosystem Complexity via Application of a Process-Based State Space rather than a Potential Surface. C. Gaucherel, F. Pommereau, C. Hély. DOI:10.1155/2020/7163920
At the heart of ecco is the reaction rules modelling language described in DOI:10.1111/2041-210X.13242 that allows to describe an ecosystem as:
- a set of Boolean entities that define the state of the ecosystem
- a set of rules that define the transitions (aka, states changes)
All together, this yields a state space that ecco can compute, analyse, and render graphically in a way that is suitable for interactive exploration and analysis.
ecco also features static analysis tools that do not rely on the state space computation.
ecco uses symbolic state spaces representation based on decision diagrams, older tools have used explicit state spaces instead.
They have not been publicly released but their features will be progressively ported into ecco.
One may find such an early version of ecco here: DOI:10.5281/zenodo.3241370
ecco is documented through Jupyter notebooks that can be found into directory doc.
ecco is available as a Docker image so you don't need to install it.
But of course you need to have Docker installed.
The simplest way to run ecco from this Docker image is to download this script and run it.
It will take care if everything.
Use ecco.py --help and see below for further information about the available options.
If you wish to do it manually, run docker run -p 8000:8000 franckpommereau/ecco jupyterhub then point your browser to localhost:8000 and login as user ecco with password ecco.
The notebooks and example models are available in directory doc.
The Docker command above runs ecco on the top of a multi-user JupyterHub installation, you may reconfigure it according to you needs (in particular, to add users and data persistence) for a production usage.
You may also want to run docker run -p 8000:8000 -u ecco -w /home/ecco franckpommereau/ecco jupyter-notebook --no-browser --port=8000 --ip=0.0.0.0 to start only Jupyter Notebook without JupyterHub.
To run a specific version of ecco, use docker run ... franckpommereau/ecco:VERSION ... where version is one of the tags listed on ecco Github page.
Just use the docker image from the quickstart above, change user ecco's password or remove it's account, and create other accounts according to your needs.
First, you should install all the dependencies:
- Python 3 (version tested: 3.7)
- GraphViz (version tested: 2.40.1)
- Jupyter (version tested: 1.0.0)
- NetworkX (version tested: 2.4)
- pandas (version tested: 0.25.3)
- NumPy (version tested: 1.18.1)
- BQPlot (version tested: 0.11.9)
- ipywidgets (version tested: 7.5.1)
- colour (version tested: 0.1.5)
- bitarray (version tested: 1.2.0)
- prince (version tested: 0.7.1)
- SymPy (version tested: 1.5)
- 竜 TatSu (version tested: 4.4.0)
- Cython (version tested: 0.29.14)
- psutil (version tested: 5.6.7)
- pydot (version tested: 1.4.1)
- pyddd (latest version)
- pyits (latest version)
- pytl (latest version)
- pyits model-checker (latest version)
- ptnet (latest version)
Then, run python setup.py install as usual, or pip install git+https://github.com/fpom/ecco.git to install directly from the GitHub repository.
Looking at docker/Dockerfile in the distribution will give you the commands to run on a Linux box.
You may want to configure Jupyter notebooks so that files with extensions .rr are opened and edited as Python files, which is more convenient than editing them as plain text (editing as YAML could be another good choice).
To do so, add the following to /etc/jupyter/nbconfig/edit.json:
{
"Editor": {
"file_extension_modes": {
".rr": "Python",
}
}
}You may copy ecco.py somewhere in your PATH, renaming it to ecco.
Then, running just ecco will start the Docker container and point your browser onto the freshly started Jupyter Notebook.
Stop the container with Ctrl-C.
Since ecco runs inside a Docker container, you will not find your files, and everything done inside the container will be lost when it shuts down.
To work around this, use option --mount that allows to access a local directory from within the container.
For instance ecco --mount workdir creates a directory workdir inside the container that gives access to your local directory workdir so that everything that is saved to it is also saved outside of the container.
You may use --mount has many times as necessary.
Option --tag allows to run a specific version of ecco and defaults to the lastest.
Option --port allows to change the TCP port on which jupyter-notebook is available, and it defaults to 8000.
An experimental option --gui provides desktop integration.
It's experimental since it has been tested only under Linux/Gnome so far, but in principle it should work everywhere else.
To use it, you'll have to install package PySide2 that provides the portable graphical library.
That done, you may run ecco --gui --no-browse on you session startup to run a background instance of the container and install an icon in the system tray.
The other options are available too of course, in particular --mount.
Right-clicking on the tray icon yields a menu that allows to point your browser onto the running jupyter-notebook (which --no-browse avoided), or shutting down the container and the GUI.
Lastly, after its own options, ecco accepts any command with options to be run inside the container instead of juputer-notebook.
Other, more specific, options are available, run ecco --help to list them.
Please use GitHub issues to report problems or ask questions about ecco itself.
For more general questions, feel free to send an email to [email protected].
Copyright 2020-2021 Franck Pommereau [email protected]
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses.