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.