Topic	Badge(s)
General
GitHub release
Available on
Compliance
References

refineGEMs

refineGEMs is a python package intended to help with the curation of genome-scale metabolic models (GEMS).

• refineGEMs
  • Overview
  • Installation
    • pypi Via pip
    • docker Via Docker
      • (a) Image from Docker Hub
      • (b) Local build
      • How to use
  • Contributing
  • Licence
    • Logo licence and brand usage
    • Documentation graphics licence
  • How to cite
  • Repositories using refineGEMs

Overview

Currently refineGEMs can be used for the investigation of a genome-scale metabolic model (GEM)/multiple GEMs, it can complete the following tasks:

• Loading GEMs with COBRApy and libSBML
• Report and visualise number of metabolites, reactions and genes
• Report orphaned, deadends and disconnected metabolites
• Report mass and charge unbalanced reactions
• Report the Memote score and provide a whole MEMOTE report
• Find and fill gaps automatically via databases like KEGG, BioCyc, SwissProt or a user-defined database
• Compare the charges and masses of the metabolites present in the model to the charges and masses denoted in the ModelSEED Database.

Other applications of refineGEMs to curate a given model include:

• The correction of a model created with CarveMe v1.5.1 or v1.5.2 (for example moving all relevant information from the notes to the annotation field or automatically annotating the GeneProduct section of the model with the respective NCBI gene/protein identifiers from the GeneProduct identifiers)
• The addition of KEGG Pathways as Groups (using the libSBML Groups Plugin)
• Updating the SBO-Term annotations based on SBOannotator

Installation

The toolbox refineGEMscan be installed via pip or via Docker.

Via pip

You can install refineGEMs via pip:

pip install refineGEMs

or to a local conda environment where refineGEMs is distributed via this GitHub repository and all dependencies are denoted in the pyproject.toml file:

# clone or pull the latest source code
git clone https://github.com/draeger-lab/refinegems.git
cd refinegems

conda create -n <EnvName> python=3.10 (at least but < 3.13)

conda activate <EnvName>

# check that pip comes from <EnvName>
which pip

pip install .

Optional features require additional packages that are not needed for the base installation:

# ChEBI lookups
pip install "refineGEMs[chebi]"

# SBO label lookup via OLS
pip install "refineGEMs[ols]"

# SBO annotation
pip install "refineGEMs[sbo]"

# install all optional dependencies
pip install "refineGEMs[optional]"

[!CAUTION] Some connected tools are optional and currently need to be installed directly from GitHub before using the corresponding refineGEMs workflow step. If they are missing, refineGEMs reports the missing dependency and skips the affected optional step where possible.

# For MCC
pip install "masschargecuration@git+https://github.com/Biomathsys/MassChargeCuration"

# For BOFdat, our fork with hot fix(es):
pip install "bofdat@git+https://github.com/draeger-lab/BOFdat"

# ModelPolisher client:
pip install "model-polisher@git+https://github.com/draeger-lab/MPClient"

Via Docker

refineGEMs can also be used via Docker. You can pull the latest image from (a) Docker Hub or (b) build it locally.

(a) Image from Docker Hub

To pull the image from Docker Hub, simply use:

   docker pull biodatalab/refinegems:<tag>

(b) Local build

To build the Docker image locally, firstly clone the repository:

   git clone "https://github.com/draeger-lab/refinegems.git"

Then change into the directory and build the image:

   cd refinegems
   docker build -t refinegems .

The default image installs the runtime optional dependency group from pyproject.toml, but excludes the documentation dependencies. Optional connected tools that are currently installed directly from GitHub are included by default and can be disabled for a smaller image:

   # build without the optional connected GitHub tools
   docker build \
      --build-arg INSTALL_EXTERNAL_TOOLS=false \
      -t refinegems:runtime .

The full default can also be made explicit:

   docker build \
      --build-arg INSTALL_EXTERNAL_TOOLS=true \
      -t refinegems:full .

How to use

[!NOTE] To provide the input files and retrieve the output files mount one folder as workspace folder to the Docker image with -v.

The default command executed by the image is refinegems -h and provides the help information for the CLI of refineGEMs.

   docker run refinegems -h

To use the image interactively and open a bash shell, run the following command:

   docker run -it --entrypoint bash refinegems

To use the image for specific commands, you can simply use every of the CLI commands as entrypoint. For example, to curate a (draft) model, run:

   docker run --name <container_name> -v <user_folder>:/rg_cont refinegems analyse stats ./path/to/model.xml

Contributing

Contributions are welcome from users, developers, model curators, and documentation writers. Please read the contributing guide before opening larger changes. It describes the recommended development workflow, coding and documentation standards, media database notes, review process, and pull request checklist.

GitHub issue forms are available for bug reports and feature requests. Pull requests should target the dev branch and use the repository pull request template. Please also follow the project code of conduct.

Licence

The refineGEMs source code is distributed under the MIT licence. Bundled third-party data, database identifiers, adapted code, and connected external tools remain under their own licences or terms; see THIRD_PARTY_LICENSES.md for details.

Logo licence and brand usage

The refineGEMs logos are licensed separately from the source code under the Creative Commons Attribution 4.0 International Licence (CC BY 4.0). The asset-side notice is stored at docs/source/images/logos/LOGO_LICENSE.md.

For colours, minimum size, clear space, and acceptable modifications, see the brand usage guide.

Documentation graphics licence

Project-created documentation graphics are licensed separately from the source code under the Creative Commons Attribution 4.0 International Licence (CC BY 4.0). The asset-side notice is stored at docs/source/images/GRAPHICS_LICENSE.md. Third-party graphics are excluded unless explicitly listed there or accompanied by a compatible notice.

How to cite

When using refineGEMs, please cite the latest publication:

Famke Bäuerle, Gwendolyn O. Döbel, Laura Camus, Simon Heilbronner, and Andreas Dräger. Genome-scale metabolic models consistently predict in vitro characteristics of Corynebacterium striatum. Front. Bioinform., oct 2023. doi:10.3389/fbinf.2023.1214074.

Repositories using refineGEMs

• C_striatum_GEMs
• draeger-lab/Cacnes - private
• draeger-lab/Cgranulosum - private
• draeger-lab/Koxytoca - private
• draeger-lab/Mfortuitum - private
• draeger-lab/Scohnii - private
• draeger-lab/Shaemolyticus - private
• draeger-lab/Ssanguinis - private