Synopsis

Metabograph is a Python library for generating metabolic networks from BioPAX data with built-in support for retrieving biological pathway data from Reactome. The generated NetworkX graphs can be used in various application such as training graph neural networks (GNNs) or saved to files for use with viewers such as Gephi.

Examples

Examples can be found in the examples directory. The following are two examples of generated graphs visualized with Gephi.

Links

GitLab

• Homepage
• Source
• Documentation
• Issues
• GitLab package registry

Other Repositories

• Python Package Index

Installation

Metabograph is available on PyPI and can be installed with any standard Python package manage such as pip:

pip install metabograph

Installation From Source

Metabograph can also be installed from source via Git and pip:

git clone --recursive 'https://gitlab.inria.fr/jrye/metabograph.git'
pip install metabograph

Several utility scripts are also provided to manage local installation and virtual environment activation. Please see the Utilities below for further details.

Usage

Configuration File

Metabograph uses a YAML configuration file to set the target species, configure eventual BioPAX SPARQL endpoints and filter graphs by cellular pathways and locations. A default configuration file with comments can be generated with the command metabograph --create-config config.yaml:

# ConfigData

# BioPAX configuration.
biopax:
  # A list of paths to custom OWL files in the BioPAX level-3 format to use, either with or without the default files
  # depending on the value of include_default_owl_files.
  # Type: list[Path] [OPTIONAL]
  custom_owl_files: []

  # An optional URL to a SPARQL endpoint through which to query BioPAX data, such as a local Fuseki server.
  # Type: str [OPTIONAL]
  endpoint: null

  # If True, include complexes and their components.
  # Type: bool [OPTIONAL]
  include_complexes: true

  # If True, include the default BioPAX files for the configured species. These files will be downloaded if necessary.
  # Type: bool [OPTIONAL]
  include_default_owl_files: true

  # If True, include member entities (as defined by BioPAX).
  # Type: bool [OPTIONAL]
  include_member_entities: false

  # If True, items for which a pathway or location is unknown will be kept when filtering by pathway and/or location.
  # Type: bool [OPTIONAL]
  keep_unknown: false

  # Either a list of BioPax entity locations, or a path to a plaintext file with one location per line. See `metabograph
  # --list-locations` for the complete list.
  # Type: Union[list[str], str] [OPTIONAL]
  locations: null

  # Either a list of BioPAX pathways, or a path to a plaintext file with one pathways per line. See `metabograph --list-
  # pathways` for the complete list.
  # Type: Union[list[str], str] [OPTIONAL]
  pathways: null

  # The target species. It must be one supported by BioPAX. See `metabograph --list-species` for the complete list.
  # Type: str [OPTIONAL]
  species: homo sapiens

# Cache configuration.
cache:
  # The path to a cache directory. If unset, the standard XDG user cache directory will be used.
  # Type: Path [OPTIONAL]
  path: null

  # The timeout for the cached data. Data will be cleared from the cache after this timeout. If unset, cached data will
  # not automatically time out.
  # Type: int [OPTIONAL]
  timeout: null

Metabograph Command-Line Tool

The metabograph command-line tool can be used to query the available species, pathways and cellular localizations and generate graph files in GML format from Reactome data.

usage: metabograph [-h] [-c CONFIG] [--clear-cache] [--create-config PATH]
                   [--list-species] [--list-locations] [--list-pathways] [-v]
                   [graph]

Generate graphs from Reactome BioPAX data.

positional arguments:
  graph                 Output path for the generated graph in GML format.
                        This should normally use the .gml extension.

options:
  -h, --help            show this help message and exit
  -c, --config CONFIG   Path to the YAML configuration file.
  --clear-cache         Clear the cache to force a refresh of query data.
  --create-config PATH  Create a YAML configuration file at the given path. If
                        the path is "-", the generated YAML will be printed to
                        STDOUT.
  --list-species        List available species.
  --list-locations      List recognized cellular locations.
  --list-pathways       List recognized pathways.
  -v, --verbose         Increasing logging level to DEBUG. Pass twice to also
                        show SPARQL queries.

Example

The following steps will generate a graph of the pre-mRNA splicing pathway in homo sapiens:

1. Generate a new configuration file with metabograph --create-config config.yaml.

2. Open the file in an editor and verify that the species is set to "homo sapiens":

   species: homo sapiens
   

3. List the available pathways with metabograph --list-pathways and locate the name of the desired pathway. Note that the

   ...
   PPARA activates gene expression
   PRC2 methylates histones and DNA
   pre-mRNA splicing
   Pre-NOTCH Expression and Processing
   Pre-NOTCH Processing in Golgi
   ...
   

4. Set the "pre-mRNA splicing" pathway in the configuration file:

   pathways:
     - pre-mRNA splicing
   

5. Generate the graph for this pathway and save it to a file named pre-mRNA_splicing.gml in GML format: metabograph -c config.yaml pre-mRNA_splicing.gml:

graph [
  directed 1
  node [
    id 0
    label "http://www.reactome.org/biopax/97/48887##Complex10144"
    type "Complex"
    display_names "Spliceosomal A complex (capped, methylated, polyadenylated pre-mRNA)"
    names ""
    location "nucleoplasm"
  ]
  node [
    id 1
    label "http://www.reactome.org/biopax/97/48887##Protein10269"
    type "Protein"
    display_names "SNW1"
    names "SKIP;SNW domain-containing protein;SNW1_HUMAN"
    location "nucleoplasm"
  ]
...

The generated file can then be imported by any software that supports the standard GML file format.

Python API

For the full API, see the API documentation linked above. The following is an example of common basic usage.

# Import the required modules.
from metabograph.config import Config
from metabograph.biopax.query_manager import BiopaxQueryManager
from metabograph.biopax.graph_generator import BiopaxGraphGenerator

# Instantiate a configuration file from a file (or manually).
config = Config(path="config.yaml")

# Instantiate a query manager.
bqm = BiopaxQueryManager(config)

# Get the lists of species, pathways and cellular locations.
species = bqm.list_species()
pathways = bqm.list_pathways()
locations = bqm.list_locations()

# Instantiate a graph generator and get the networkx graph object for the
# current configuration.
bgg = BiopaxGraphGenerator(bqm=bqm)
graph = bgg.get_graph()

# Do stuff with the graph...
print(graph)
# ...

Fuseki Server

Apache Jena Fuseki is a third-party server that provides faster parsing of OWL files than the Python packages owlready2 and rdflib. The script download_fuseki.sh is provided to quickly download the source code and create a configuration file for running the server locally.

By default, the script will download files to the directory tmp/fuseki and write required environment variables to tmp/fuseki/env.sh. These environment variables can be can be loaded manually in a Bash shell via the command source tmp/fuseki/env.sh.

The env.sh file mentioned above will run download_fuseki.sh if necessary and set the Fuseki environment variables.

Once the environment variables have been set, the Fuseki server can be run in a terminal via the command metabograph-fuseki.

The easiest way to run the local Fuseki server regardless of the user's current shell is to run the following command:

./scripts/run_in_venv.sh metabograph-fuseki <path_to_config>

Replace <path_to_config> with the path to the Metabograph configuration file that will be used with Metabograph. See the metabograph-fuseki help message for further options:

usage: metabograph-fuseki [-h] [-v] config

Run the Fuseki server.

positional arguments:
  config         The Metabograph configuration file.

options:
  -h, --help     show this help message and exit
  -v, --verbose  Show debug messages.

NVIDIA cuGraph

NVIDIA cuGraph is a drop-in alternative backend for NetworkX that claims significant speedups without any code changes. To use it, install the appropriate nx-cugraph package in the same environment as Metabograph (e.g. via pip) and then export the environment variableNX_CUGRAPH_AUTOCONFIG=Truebefore running your code:

export NX_CUGRAPH_AUTOCONFIG=True
./your_code.py

# OR
NX_CUGRAPH_AUTOCONFIG=True ./your_code.py

Utilities

The project provides the following files and scripts for convenience. See the dependencies below.

• env.sh - A Bash file that can be sourced to do the following:

  • Create and configure a Python virtual environment.
  • Download and unpack the Fuseki server.
  • Activate the Python virtual environment and configure the Fuseki environment variables.

• build_doc.sh - Build the Python documentation with Sphinx.

• download_fuseki.sh - Download the Fuseki server and unpack it to a temporary directory. This will also generate a file with the required environment variables for using the server.

The remaining scripts are documented in Python Venv Utils

Dependencies

• Bash version 5.0 or newer.
• bsdtar from libarchive (available in the libarchive-tools package on Ubuntu).

References

• BioPAX