Constructor – Reconstruction Curation Tool

A web application to build, curate, and validate biochemical reactions for genome‑scale reconstructions.
Launch Constructor »

View Source  ·  Report Bug  ·  Request Feature

Table of Contents

1. About The Project
   • Key Features
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact
7. Acknowledgments
8. Citation

About The Project

Constructor (sometimes referred to simply as the Reconstruction Curation Tool) helps domain experts and the wider metabolic‑modeling community create balanced, well‑annotated biochemical reactions that can be seamlessly incorporated into genome‑scale metabolic reconstructions such as those hosted by the Virtual Metabolic Human (VMH).

The traditional workflow of curating reactions across multiple spreadsheets and scripts is time‑consuming and error‑prone. Constructor brings everything into a single, collaborative interface:

• Manage substrates/products, compartments, charge and atom balance in real‑time.
• Fetch existing reactions from VMH and Rhea, or start from scratch.
• Draw metabolites with ChemDoodle, or paste identifiers (ChEBI, VMH, etc.).
• Automatically assess mass & charge balance and highlight discrepancies.
• Annotate reactions with references, external links, gene‑protein‑reaction (GPR) rules and organ localisation.
• Save reactions privately, share with collaborators, or push directly to VMH with one click.
• Keep track of community activity with a built‑in leaderboard and statistics dashboard.

(back to top)

Key Features

• 🧪 Interactive Reaction Builder – drag‑and‑drop UI with on‑the‑fly validation.
• 🔗 Database Integration – import from VMH/Rhea and export back to VMH.
• 🧬 GPR & Gene‑Info Parsing – associate genes, organs and sub‑cellular localisation.
• 📊 Leaderboard & Stats – Chart.js powered dashboard of community curation.
• 🖼️ ChemDoodle & 3Dmol.js – visualise 2‑D sketches and 3‑D structures inline.

(back to top)

Built With

This stack aims to be familiar to both Python/Django developers and front‑end contributors.

• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

Follow these instructions to get a local development instance running.

Prerequisites

• Python >= 3.10
• Django >= 5.0
• PostgreSQL (or another Django‑compatible RDBMS)
• Reaction Decoder Tool (RDT) >= 2.4.1 – Download, and put the jar file under folder curationTool
• Matlab 2024a

# Ubuntu example – install system packages
sudo apt update && sudo apt install python3.10 python3.10-venv build-essential postgresql postgresql-contrib

Installation

# 1. Clone the repo
$ git clone https://github.com/opencobra/reconstructor.git && cd reconstructor

# 2. Create and activate a virtual environment
$ python3.10 -m venv .venv
$ source .venv/bin/activate

# 3. Install Python dependencies
$ pip install -r requirements.txt

# 4. Configure database and create config.json in root directory
# Follow the format in example.config.json, and fill in requested values

# 5. Apply migrations and run
$ cd curationTool
$ python manage.py makemigrations
$ python manage.py migrate
$ python manage.py runserver

Visit http://127.0.0.1:8000/ to start curating reactions 🌱.

(back to top)

Usage

Below is the most common workflow – see the tutorials directory for step‑by‑step guides.

1. Create or fetch a reaction in the Reactants tab.
2. Inspect atom mapping and chemical balance alerts.
3. Add references, external links, comments or gene rules in their respective tabs.
4. Save the reaction (or Save As to duplicate).
5. Navigate to Saved Reactions → select entries → Add to VMH.

For code structure explanation, please check docs/CODE_STRUCTURE.md.

For more examples, please refer to the Documentation

(back to top)

Contributing

Contributions keep Constructor improving – whether it's code, documentation, or testing. All PRs are welcome!

1. Fork the project
2. Create a feature branch git checkout -b feature/awesome‑feature
3. Commit your changes git commit -m 'feat: add awesome feature'
4. Push to your branch git push origin feature/awesome‑feature
5. Open a pull request

Community leaderboard

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE for details.

(back to top)

Contact

openCOBRA Team – [email protected]

DMTC Team - digitalmetabolictwin.org

Project Link: https://github.com/opencobra/reconstructor

(back to top)

Acknowledgments

• Virtual Metabolic Human
• Reaction Decoder Tool
• ChemDoodle Web Components and 3Dmol.js
• Chart.js
• Semantic UI

(back to top)

Citation

Cite this work in your paper:

Alwer, S., Sathe, V., Brennan, A., and McGoldrick J. "Constructor: An open-source interface for quality-controlled metabolic reconstruction." Available at: https://github.com/opencobra/reconstructor.