MetaboNet

This project supports curation of the model of human cellular metabolism, definition of custom metabolic networks to represent this model, and analyses of these networks.

License and citation

This file is part of project MetaboNet.

MetaboNet supports definition and analysis of custom metabolic networks. Copyright (C) 2019 Thomas Cameron Waller

MetaboNet is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

MetaboNet 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with MetaboNet. If not, see http://www.gnu.org/licenses/.

If you use MetaboNet, please cite its publication.

T. Cameron Waller, Jordan A. Berg, Brian E. Chapman, Jared P. Rutter. "Compartment and Hub Definitions Tune Metabolic Networks for Metabolomic Interpretations". Journal. Year. Issue. link

Archives

Many users might find it more convenient to access archival versions of major exports from MetaboNet.

Access these files from record 3382296 on Zenodo.

Quick Start

1. Open Terminal window
2. Retrieve MetaboNet

$ curl -LO https://github.com/tcameronwaller/metabonet/archive/master.zip
$ unzip master.zip
$ cd metabonet-master

3. Run the interactive MetaboNet player

$ bash interactive_metabonet.sh

Install MetaboNet

As an alternative to the interactive script, here's a step-by-step guide.

DO: Download MetaboNet from GitHub and extract the archive.

$ cd ~/Downloads/
$ wget https://github.com/tcameronwaller/metabonet/archive/master.zip
$ unzip master.zip
$ cd metabonet-master/
$ ls ./
dock LICENSE metabonet README.md setup.py

DO: Inspect the repository's contents.

$ ls ~/Downloads/metabonet-master/
dock_template LICENSE metabonet README.md setup.py

DO: Install MetaboNet to default directory for third-party Python packages.

$ cd metabonet-master/
$ sudo python setup.py install
or
$ pip install -e setup.py

DO: Confirm installation.

$ metabonet --help
$ metabonet model --help
$ metabonet network --help
$ metabonet clean --help

Set Up Dock Directory

Procedures in MetaboNet organize both source (input) and product (output) files within a central directory. These instructions refer to this directory by the name "dock". The user can place this directory wherever on their machine but must tell MetaboNet where to find it.

A template "dock" directory with default files is accessible within the MetaboNet repository.

DO: Copy default "dock" directory to accessible location.

$ cp ~/Downloads/metabonet-master/dock_template/ ~/dock/
$ ls ~/dock/

Customizable Parameters

MetaboNet supports customization at the level of curation of the metabolic model and at the level of definition of metabolic networks.

The MetaboNet repository on GitHub contains default parameters within the "customization" directory.

DO: Inspect these files of customizable parameters.

$ ls ~/dock/source/customization/

Metabolic Information

MetaboNet derives information from the Recon 2M.2 model of human metabolism and from the Human Metabolome Database (HMDB) of metabolites. As the necessary files are large, these instructions specify how to access them from the original repositories.

Access Recon 2M.2 in file "Recon2M.2_MNX_Entrez_Gene.xml" (14.2 MB) from record 583326 on the Zenodo repository.

DO: Download Recon 2M.2 model of human metabolism.

$ cd ~/Downloads/
$ wget https://zenodo.org/record/583326/files/Recon2M.2_MNX_Entrez_Gene.xml

DO: Change the name of this file to "recon2m2.xml" and move it to the "dock" directory.

$ mv ~/Downloads/Recon2M.2_MNX_Entrez_Gene.xml ~/dock/source/recon2m2.xml
$ ls ~/dock/source/

Access the HMDB in version "4.0" of file "hmdb_metabolites.xml" (4.2 GB).

DO: Download the HMDB database about human metabolites. Extract this file and move it to the "dock" directory.

$ cd ~/Downloads/
$ wget http://www.hmdb.ca/system/downloads/current/hmdb_metabolites.zip
$ unzip hmdb_metabolites.zip
$ mv ~/Downloads/hmdb_metabolites.xml ~/dock/source/hmdb_metabolites.xml
$ ls ~/dock/source/

Metabolomic Measurements

MetaboNet integrates metabolomic measurements with metabolic networks. In its current state, MetaboNet is specific to metabolomic measurements from five previously-published studies that the authors chose as examples. The original data sets for these metabolomic measurements came from the Metabolomics Workbench repository. These instructions explain how to collect and curate these five data sets for use in MetaboNet.

Some users might want to integrate their own metabolomic measurements for analysis in metabolic networks. In its current state, MetaboNet requires specific data file formats and expects to curate and integrate five studies at a time. Moreover, MetaboNet makes some assumptions about experimental groups and sample pairs that are specific to the five demonstration studies. It would be possible to adapt MetaboNet to integrate new metabolomic measurements with metabolic networks; however, this adaptation would require changes to the Python code. A future version might make this functionality more versatile from MetaboNet's terminal interface.

Option 1: Access previous measurement files in "dock" directory

DO: Inspect files from metabolomic measurements in "dock" directory.

$ ls ~/dock/source/measurement/

Option 2: Access and prepare metabolomic measurements from scratch

DO: Access and organize data for metabolomic measurements.

1. Locate specific projects and studies on Metabolomics Workbench.

• Project: PR000305, Study: ST000390
• Project: PR000058, Study: ST000061
• Project: PR000322, Study: ST000412
• Project: PR000322, Study: ST000412
• Project: PR000599, Study: ST000842

2. Copy information about samples.

• Click on study's tab "Show all samples".
• Copy information from sample table.
• Some organization is necessary to match experimental groups and pairs of samples.
• Save file as "samples.tsv".

3. Copy information about analytes.

• Click on study's tab "Show named metabolites".
• Save file as "analytes.tsv".

4. Copy information about measurements.

• Some organization is necessary.
• Click on study's tab "Download named metabolite data".
• Save file as "measurements.tsv".

5. Copy information about signals.

• Click on study's tab "Download all metabolite data".
• Some organization is necessary.
• Save file as "signals.tsv".
• These data are more extensive than "measurements.tsv" and are useful to control by total signal for each sample.

6. Correct errors.

• Project PR000305, Study ST000390 -- "analytes.tsv" --- "ascorbic acid", "Vitamin C", change PubChem identifier from "5785" to "54670067".
• Project PR000322, Study ST000412 -- "analytes.tsv" --- "putrescine", "Putrescine", change PubChem identifier from "1049" to "1045". Remove record for "maltose", "Maltose", PubChem "439186". That record is redundant with the record for "cellobiose", PubChem "6255".

Curate Metabolic Model and Metabolomic Measurements

MetaboNet's "model" routine includes multiple procedures to curate the metabolic model and to organize metabolomic measurements. This curation prepares the model to define custom metabolic networks and integrate measurements with these networks.

Reconcile Metabolic Model with MetaNetX

MetaNetX is a repository of metabolic models with useful information about metabolites and reactions.

Option 1: Access previous reconciliation files in "dock" directory

DO: Inspect reconciliation files in "dock" directory.

$ mv ~/dock/source/reconciliation_2019-08-13/ ~/dock/
$ mv ~/dock/reconciliation_2019-08-13/ ~/dock/reconciliation/
$ ls ~/dock/reconciliation/

Option 2: Access and prepare reconciliation files from scratch

DO: Execute the "reconciliation" procedure of the "model" routine.

$ metabonet model -d ~/dock/ -r

DO: Integrate metabolic model with MetaNetX.

1. Import the following file to MetaNetX.

~/dock/reconciliation/recon2m2_reconciliation.xml

2. Save "Mapping summary" from MetaNetX as the following file. This summary is useful for review and also includes information to curate names of metabolites. Import category "chemical compounds mapped to the MNXref namespace with different ID and different description" is of particular interest for curation of information about metabolites.

/dock/reconciliation/metanetx_import_report.tsv

3. Save files from MetaNetX to the following directories and files.

$ cp ~/Downloads/compartments.tsv ~/dock/reconciliation/recon2m2_metanetx_compartments.tsv
$ cp ~/Downloads/enzymes.tsv ~/dock/reconciliation/recon2m2_metanetx_genes.tsv
$ cp ~/Downloads/chemicals.tsv ~/dock/reconciliation/recon2m2_metanetx_metabolites.tsv
$ cp ~/Downloads/reactions.tsv ~/dock/reconciliation/recon2m2_metanetx_reactions.tsv

Curate Metabolic Model

DO: Customize curation by editing the following files of parameters.

ls ~/dock/source/customization/
~/dock/source/customization/curation_compartments.tsv
~/dock/source/customization/curation_processes.tsv
~/dock/source/customization/curation_reactions_custom.tsv
~/dock/source/customization/curation_reactions.tsv
~/dock/source/customization/curation_metabolites.tsv

A file of special use to review automatic curation of reactions follows.

~/dock/enhancement/reactions_filter.tsv

DO: Execute the "collection", "extraction", "enhancement", "curation", and "conversion" procedures of the "model" routine.

The "enhancement" procedure alone requires about 1 hour to complete.

$ metabonet model -d ~/dock/ -ceauv

Export Metabolic Model

MetaboNet's "model" routine exports information from the metabolic model to multiple formats. These files are also part of the project's archive on the Zenodo repository.

DO: Inspect files from model curation procedures.

ls ~/dock/model/
~/dock/model/dymetabonet.json <- this file is compatible for import to DyMetaboNet
~/dock/model/compartments.pickle
~/dock/model/compartments.tsv
~/dock/model/processes.pickle
~/dock/model/processes.tsv
~/dock/model/reactions.pickle
~/dock/model/reactions.tsv
~/dock/model/metabolites.pickle
~/dock/model/metabolites.tsv

Curate Metabolomic Measurements

DO: Execute the "measurement" procedure of the "model" routine.

$ metabonet model -d ~/dock/ -m

DO: Review the following files to check the matches between analytes and metabolites. Discrepancies might justify modifications to curation of metabolites.

~/dock/measurement/study_one_report.tsv
~/dock/measurement/study_two_report.tsv
~/dock/measurement/study_three_report.tsv
~/dock/measurement/study_four_report.tsv
~/dock/measurement/study_five_report.tsv

DO: Inspect files of summaries for metabolomic measurements in "dock" directory.

~/dock/measurement/study_one.tsv
~/dock/measurement/study_two.tsv
~/dock/measurement/study_three.tsv
~/dock/measurement/study_four.tsv
~/dock/measurement/study_five.tsv

Define Custom Metabolic Networks

MetaboNet's "network" routine includes multiple procedures to define and analyze customizable metabolic networks.

DO: Customize definition of metabolic networks by editing the following files of parameters.

~/dock/source/customization/filtration_compartments.tsv
~/dock/source/customization/filtration_processes.tsv
~/dock/source/customization/simplification_reactions.tsv
~/dock/source/customization/simplification_metabolites.tsv

DO: Execute the "candidacy", "network", and "conversion" procedures of the "network" routine.

compartments true, hubs true

$ metabonet network -d ~/dock/ -yc -np -v

compartments true, hubs false

$ metabonet network -d ~/dock/ -ycs -np -v

compartments false, hubs true

$ metabonet network -d ~/dock/ -y -np -v

compartments false, hubs false

$ metabonet network -d ~/dock/ -ys -np -v

Export Metabolic Networks

MetaboNet's "network" routine exports information about the metabolic network.

ls ~/dock/network/
~/dock/network/links.pickle
~/dock/network/nodes_metabolites.pickle
~/dock/network/nodes_reactions.pickle

ls ~/dock/conversion/
~/dock/conversion/network_elements_cytoscape.json <- this file is compatible for import to Cytoscape
~/dock/conversion/network_elements_networkx.json <- this file is compatible for import to NetworkX

Analyze Metabolic Networks

MetaboNet's "network" routine applies functionality from the NetworkX application to describe metabolic networks. This procedure determines and reports multiple metrics on the basis of nodes (bipartite groups for both reactions and metabolites) and the entire network.

DO: Execute the "analysis" procedure of the "network" routine.

$ metabonet network -d ~/dock/ -a
$ ls ~/dock/network/analysis/

Run time of "analysis" procedure can be 0.5-2.0 hours depending on the network.

Visualize Metabolic Networks

The Cytoscape application is useful to visualize metabolic networks from MetaboNet.

DO: Import the following file to Cytoscape.

~/dock/conversion/network_elements_cytoscape.json

Integrate Metabolomic Measurements in Metabolic Network

DO: Execute the "measurement" procedure of the "network" routine.

$ metabonet network -d ~/dock/ -m
$ ls ~/dock/network/measurement/

DO: Import the following file of measurements from all studies for integration with the metabolic network in Cytoscape.

~/dock/network/measurement/metabolites.tsv