Annotating Systems Biology Models
Authors: Andreas Dräger, Thomas J. Zajac, Matthias König, Kaustubh Trivedi
ModelPolisher accesses the BiGG Models knowledgebase to annotate and autocomplete SBML models. Thereby, the program mainly relies on BiGG identifiers for model components. Moreover, it fixes some apparent errors in the models and uses mappings from AnnotateDB to further add annotations.
ModelPolisher is primarily a command-line based tool. You can run ModelPolisher locally using Docker
or using your installation of BiGG Models database (see https://github.com/SBRG/bigg_models).
Note: If you run into trouble with larger files, especially _java.lang.OutOfMemoryError: GC overhead limit exceeded_
, please use the JVM Xmx
flag (e.g., java -Xmx4G -jar ModelPolisher-VERSION.jar
).
The online version of ModelPolisher is described in this article: http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0149263
The article "BiGG Models: A platform for integrating, standardizing and sharing genome-scale models" describes BiGG Models knowledge-base including ModelPolisher.
NOTE: You may run ModelPolisher, without building, using Docker (preferred). See here.
ModelPolisher uses gradle
to build. Make sure you have gradle (version >= 5.0)
installed in your system before following the procedure below.
First clone this github project and go to directory <path>/ModelPolisher/
. Then, ModelPolisher can be built using Gradle. Gradle runs task fatJar
by default which produces jar
file, with dependencies, for ModelPolisher in <path>/ModelPolisher/target/
directory. So, in order to build ModelPolisher run any of following command under ModelPolisher/
directory:
gradle fatJar
or gradle
Additionally gradle devel
is provided to easily run a non-release version with Docker.
NOTE: fatJar
requires postgresql
database(s) to be set-up to run ModelPolisher.
We recommend users to run ModelPolisher using docker
, though ModelPolisher can be run from ModelPolisher jar
, which is preferred for developers.
NOTE: ModelPolisher provides various command line options which can be seen using:
java -jar <path>/ModelPolisher/target/ModelPolisher-2.1-beta.jar -?
In the example commands below few options are taken by default. See list of mostly used options here.
ModelPolisher can be run in docker containers. This allows user to skip the build process, and database setup required to run ModelPolisher. Please install docker
and docker-compose
, if not installed already.
Clone ModelPolisher and change directory to ModelPolisher/:
git clone https://github.com/draeger-lab/ModelPolisher/
cd <path>/ModelPolisher
Now, bring up docker containers required for ModelPolisher(NOTE: You must be in ModelPolisher/
directory):
docker-compose up
We recommend using docker-compose in non-detached mode when building containers for first time. If you have previously built ModelPolisher containers use docker-compose up --detach
.
NOTE: Once database backend is set-up by docker-compose
, the databases are also available at following ports for localhost
:
1013
1310
On running these commands, databases will be restored in respective containers. After databases are successfully set up, use the following command (in ModelPolisher/
directory) to run ModelPolisher:
docker-compose run -v <path_directory_having_models>:/models/ polisher java -jar /ModelPolisher-2.1-beta.jar --input=/models/<model_name> --output=/models/output/<output_name> --annotate-with-bigg=true --add-adb-annotations=true --output-combine=true
Note: You must pass absolute path for host directory. This command will mount volume <path_directory_having_models>
to /models/
in container. Thus, outputs will be produced in directory <path_directory_having_models>/output
.
User may use -u <username_or_uid>
with docker-compose run
in above command to generate output with correct ownership. Preferably use uid (obtained by id -u <username>
) due to some existing bugs in docker.
To bring down the containers, you can run docker-compose stop
. This will only stop the containers but won't delete them. Otherwise, you can use docker-compose down -v
to stop and remove all containers and related volumes.
Note: docker-compose down -v
will cause all databases to be restored again on running docker-compose up
, as restored databases exist in containers not in images.
Using docker
might cause system space to be filled up, and docker-compose up
may fail due to insufficient space. Use the following commands if there is need to empty space used by ModelPolisher_docker:
docker stop modelpolisher_biggdb modelpolisher_adb modelpolisher_java
docker rm modelpolisher_biggdb modelpolisher_adb modelpolisher_java
docker rmi modelpolisher_java:latest modelpolisher_adb:latest modelpolisher_biggdb:latest postgres:11.4 openjdk:11-slim
docker volume prune
Building using gradle devel
builds a container with the local ModelPolisher jar.
This container can be used analogously to the release version, though either -f docker-compose.devel.yml
needs to be
passed to each invocation of docker-compose
or the COMPOSE_FILE
environment variable needs to be set so it points
to docker-compose.devel.yml
, e.g. using export COMPOSE_FILE=docker-compose.devel.yml
for sh or bash.
For polishing models, you essentially need to run ModelPolisher using jar
produced from build instructions.
User needs to host the BiGG Database & AnnotateDB on PostgreSQL
on your local system.
Now, you can run the following command in general:
java -jar "<path>/ModelPolisher/target/ModelPolisher-2.1-beta.jar" \
--input=<input> \
--output=<output> \
--output-combine=true \
--annotate-with-bigg=true \
--bigg-host=<host> \
--bigg-port=<port> \
--bigg-dbname=<postgres_dbname> \
--bigg-user=<postgres_username> \
--bigg-passwd=<user_password> \
--add-adb-annotations=true \
--adb-host=<host> \
--adb-port=<port> \
--adb-dbname=<postgres_dbname> \
--adb-user=<postgres_username> \
--adb-passwd=<user_password>
We understand problems in setting-up database backend and that a developer would need to build ModelPolisher multiple times and making required changes in java
Dockerfile will be a tedious task.
We recommend the following practice for developers:
docker-compose up
.jar
by gradle fatJar
.java -jar ./target/ModelPolisher-2.1-beta.jar --input=<input> --output=<output> --output-combine=true --annotate-with-bigg=true --bigg-host=0.0.0.0 --bigg-port=1310 --add-adb-annotations=true --adb-host=0.0.0.0 --adb-port=1013
Note: All above commands must be run in <path>/ModelPolisher/
directory and you must have installed Java version >= 8
and Gradle version >= 5.0
.
ModelPolisher is distributed under the MIT License (see LICENSE). An Overview of all dependencies is provided in THIRD-PARTY.txt, their respective licenses can be found in the licenses folder.