PyBEL-CX Documentation

A PyBEL extension for interconversion with CX.


To support this feature, we need 2 command line scripts:

  1. Export script: takes a CX document from STDIN stream and write a BEL network out to STDOUT. Writes error message to STDERR when error occurs.

  2. Import script: takes a BEL network from STDIN and write a CX network to STDOUT

Here are some other specs for these scripts:

  • Relatively easy to deploy.

  • Have minimum memory footprint possible.

  • The scripts will be run as a task from the server so it is OK if runtime is long.

  • They can take extra command line arguments if necessary

  • The scripts return 0 when succeeded and returns a non-zero exit code when it failed.


PyBEL-CX can be installed easily from PyPI with the following code in your favorite terminal:

$ python3 -m pip install pybel-cx

or from the latest code on GitHub with:

$ python3 -m pip install git+

Command Line Usage

PyBEL-CX installs two command line utilities: bel_to_cx and cx_to_bel.


Running this script has the caveat that the CX document should conform to the schema created by PyBEL-CX.

$ cat | cx_to_bel > my_network.bel


$ cat my_network.bel | bel_to_cx >

Command Line Interface Usage


Programmatic Usage

CX Conversion

This module wraps conversion between pybel.BELGraph and CX JSON.

CX is an aspect-oriented network interchange format encoded in JSON with a format inspired by the JSON-LD encoding of Resource Description Framework (RDF). It is primarily used by the Network Data Exchange (NDEx) and more recent versions of Cytoscape.

See also

pybel_cx.to_cx(graph: pybel.struct.graph.BELGraph) → List[Dict][source]

Convert a BEL Graph to a CX JSON object for use with NDEx.

pybel_cx.to_cx_file(graph: pybel.struct.graph.BELGraph, file: TextIO, indent: Optional[int] = 2, **kwargs) → None[source]

Write a BEL graph to a JSON file in CX format.

  • graph – A BEL graph

  • file – A writable file or file-like

  • indent – How many spaces to use to pretty print. Change to None for no pretty printing

Example: >>> from pybel.examples import sialic_acid_graph >>> from pybel_cx import to_cx_file >>> with open(‘’, ‘w’) as f: >>> … to_cx_file(sialic_acid_graph, f)

pybel_cx.to_cx_jsons(graph: pybel.struct.graph.BELGraph, **kwargs) → str[source]

Dump a BEL graph as CX JSON to a string.


CX JSON string

pybel_cx.from_cx(cx: List[Dict]) → pybel.struct.graph.BELGraph[source]

Rebuild a BELGraph from CX JSON output from PyBEL.


cx – The CX JSON for this graph

pybel_cx.from_cx_file(file: TextIO) → pybel.struct.graph.BELGraph[source]

Read a file containing CX JSON and converts to a BEL graph.


file (file) – A readable file or file-like containing the CX JSON for this graph


A BEL Graph representing the CX graph contained in the file

pybel_cx.from_cx_jsons(graph_cx_json_str: str) → pybel.struct.graph.BELGraph[source]

Reconstitute a BEL graph from a CX JSON string.


graph_cx_json_str – CX JSON string


A BEL graph representing the CX graph contained in the string

NDEx Client

Integration with NDEx.

This module provides a wrapper around CX import/export and the NDEx client to allow for easy upload and download of BEL documents to the NDEx database.

The programmatic API also provides options for specifying username and password. By default, it checks the environment variables: NDEX_USERNAME and NDEX_PASSWORD.

pybel_cx.to_ndex(graph, username=None, password=None, debug=False)[source]

Upload a BEL graph to NDEx.

  • graph (pybel.BELGraph) – A BEL graph

  • username (Optional[str]) – NDEx username

  • password (Optional[str]) – NDEx password

  • debug (bool) – If true, turn on NDEx client debugging


The UUID assigned to the network by NDEx

Return type


Example Usage:

>>> from pybel.examples import sialic_acid_graph
>>> from pybel_cx import to_ndex
>>> to_ndex(sialic_acid_graph)
pybel_cx.from_ndex(network_id, username=None, password=None, debug=False)[source]

Download a BEL Graph from NDEx.


This function only will work for CX documents that have been originally exported from PyBEL

  • network_id (str) – The UUID assigned to the network by NDEx

  • username (Optional[str]) – NDEx username

  • password (Optional[str]) – NDEx password

  • debug (bool) – If true, turn on NDEx client debugging

Return type


Example Usage:

>>> from pybel_cx import from_ndex
>>> network_id = '1709e6f3-04a1-11e7-aba2-0ac135e8bacf'
>>> graph = from_ndex(network_id)

Indices and tables