Skip to main content

Parsing, validation, compilation, and data exchange of Biological Expression Language (BEL)

Project description

PyBEL is a pure Python package for parsing and handling biological networks encoded in the Biological Expression Language (BEL).

It facilitates data interchange between data formats like NetworkX, Node-Link JSON, JGIF, CSV, SIF, Cytoscape, CX, INDRA, and GraphDati; database systems like SQL and Neo4J; and web services like NDEx, BioDati Studio, and BEL Commons. It also provides exports for analytical tools like HiPathia, Drug2ways and SPIA; machine learning tools like PyKEEN and OpenBioLink; and others.

Its companion package, PyBEL Tools, contains a suite of functions and pipelines for analyzing the resulting biological networks.

We realize that we have a name conflict with the python wrapper for the cheminformatics package, OpenBabel. If you’re looking for their python wrapper, see here.


If you find PyBEL useful for your work, please consider citing:

Installation Current version on PyPI Stable Supported Python Versions MIT License

PyBEL can be installed easily from PyPI with the following code in your favorite shell:

$ pip install pybel

or from the latest code on GitHub with:

$ pip install git+

See the installation documentation for more advanced instructions. Also, check the change log at CHANGELOG.rst.

Getting Started

More examples can be found in the documentation and in the PyBEL Notebooks repository.

Compiling and Saving a BEL Graph

This example illustrates how the a BEL document from the Human Brain Pharmacome project can be loaded and compiled directly from GitHub.

>>> import pybel
>>> url = ''
>>> graph = pybel.from_bel_script_url(url)

Other functions for loading BEL content from many formats can be found in the I/O documentation. Note that PyBEL can handle BEL 1.0 and BEL 2.0+ simultaneously.

After you have a BEL graph, there are numerous ways to save it. The pybel.dump function knows how to output it in many formats based on the file extension you give. For all of the possibilities, check the I/O documentation.

>>> import pybel
>>> graph = ...
>>> # write as BEL
>>> pybel.dump(graph, 'my_graph.bel')
>>> # write as Node-Link JSON for network viewers like D3
>>> pybel.dump(graph, 'my_graph.bel.nodelink.json')
>>> # write as GraphDati JSON for BioDati
>>> pybel.dump(graph, 'my_graph.bel.graphdati.json')
>>> # write as CX JSON for NDEx
>>> pybel.dump(graph, '')
>>> # write as INDRA JSON for INDRA
>>> pybel.dump(graph, 'my_graph.indra.json')

Summarizing the Contents of the Graph

The BELGraph object has several “dispatches” which are properties that organize its various functionalities. One is the BELGraph.summarize dispatch, which allows for printing summaries to the console.

These examples will use the RAS Model from EMMAA, so you’ll have to be sure to pip install indra first. The graph can be acquired and summarized with BELGraph.summarize.statistics() as in:

>>> import pybel
>>> graph = pybel.from_emmaa('rasmodel', date='2020-05-29-17-31-58')  # Needs
>>> graph.summarize.statistics()
---------------------  -------------------
Name                   rasmodel
Version                2020-05-29-17-31-58
Number of Nodes        126
Number of Namespaces   5
Number of Edges        206
Number of Annotations  4
Number of Citations    1
Number of Authors      0
Network Density        1.31E-02
Number of Components   1
Number of Warnings     0
---------------------  -------------------

The number of nodes of each type can be summarized with BELGraph.summarize.nodes() as in:

>>> graph.summarize.nodes(examples=False)
Type (3)        Count
------------  -------
Protein            97
Complex            27
Abundance           2

The number of nodes with each namespace can be summarized with BELGraph.summarize.namespaces() as in:

>>> graph.summarize.namespaces(examples=False)
Namespace (4)      Count
---------------  -------
HGNC                  94
FPLX                   3
CHEBI                  1
TEXT                   1

The edges can be summarized with BELGraph.summarize.edges() as in:

>>> graph.summarize.edges(examples=False)
Edge Type (12)                       Count
---------------------------------  -------
Protein increases Protein               64
Protein hasVariant Protein              48
Protein partOf Complex                  47
Complex increases Protein               20
Protein decreases Protein                9
Complex directlyIncreases Protein        8
Protein increases Complex                3
Abundance partOf Complex                 3
Protein increases Abundance              1
Complex partOf Complex                   1
Protein decreases Abundance              1
Abundance decreases Protein              1

Grounding the Graph

Not all BEL graphs contain both the name and identifier for each entity. Some even use non-standard prefixes (also called namespaces in BEL). Usually, BEL graphs are validated against controlled vocabularies, so the following demo shows how to add the corresponding identifiers to all nodes.

from urllib.request import urlretrieve

url = ''
urlretrieve(url, 'large_corpus.bel.nodelink.json.gz')

import pybel
graph = pybel.load('large_corpus.bel.nodelink.json.gz')

import pybel.grounding
grounded_graph = pybel.grounding.ground(graph)

Note: you have to install pyobo for this to work and be running Python 3.7+.

Displaying a BEL Graph in Jupyter

After installing jinja2 and ipython, BEL graphs can be displayed in Jupyter notebooks.

>>> from pybel.examples import sialic_acid_graph
>>> from import to_jupyter
>>> to_jupyter(sialic_acid_graph)

Using the Parser

If you don’t want to use the pybel.BELGraph data structure and just want to turn BEL statements into JSON for your own purposes, you can directly use the pybel.parse() function.

>>> import pybel
>>> pybel.parse('p(hgnc:4617 ! GSK3B) regulates p(hgnc:6893 ! MAPT)')
{'source': {'function': 'Protein', 'concept': {'namespace': 'hgnc', 'identifier': '4617', 'name': 'GSK3B'}}, 'relation': 'regulates', 'target': {'function': 'Protein', 'concept': {'namespace': 'hgnc', 'identifier': '6893', 'name': 'MAPT'}}}

This functionality can also be exposed through a Flask-based web application with python -m pybel.apps.parser after installing flask with pip install flask. Note that the first run requires about a ~2 second delay to generate the parser, after which each parse is very fast.

Using the CLI

PyBEL also installs a command line interface with the command pybel for simple utilities such as data conversion. In this example, a BEL document is compiled then exported to GraphML for viewing in Cytoscape.

$ pybel compile ~/Desktop/example.bel
$ pybel serialize ~/Desktop/example.bel --graphml ~/Desktop/example.graphml

In Cytoscape, open with Import > Network > From File.


Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See CONTRIBUTING.rst for more information on getting involved.



The development of PyBEL has been supported by several projects/organizations (in alphabetical order):


Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pybel-0.15.5.tar.gz (431.0 kB view hashes)

Uploaded Source

Built Distribution

pybel-0.15.5-py3-none-any.whl (387.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page