Some utilities that are used throughout the software are explained here:

General Utilities


Uses requests to download an URL, maybe from a file


Parses a BEL config (BELNS, BELANNO, or BELEQ) file from the given line iterator over the file

Parameters:lines (iter[str]) – An iterable over the lines in a BEL config file
Returns:A config-style dictionary representing the BEL config file
Return type:dict

Checks if a string is a valid URL

Parameters:s (str) – An input string
Returns:Is the string a valid URL?
Return type:bool

Loads/downloads and parses a config file from the given url or file path

Parameters:location (str) – The URL or file path to a BELNS, BELANNO, or BELEQ file to download and parse
Returns:A config-style dictionary representing the BEL config file
Return type:dict
pybel.utils.expand_dict(flat_dict, sep='_')[source]

Expands a flattened dictionary

  • flat_dict (dict) – a nested dictionary that has been flattened so the keys are composite
  • sep (str) – the separator between concatenated keys
pybel.utils.flatten_dict(d, parent_key='', sep='_')[source]

Flattens a nested dictionary.

  • d (dict or MutableMapping) – A nested dictionary
  • parent_key (str) – The parent’s key. This is a value for tail recursion, so don’t set it yourself.
  • sep (str) – The separator used between dictionary levels

Returns a new graph with flattened edge data dictionaries.

Parameters:graph (nx.MultiDiGraph) – A graph with nested edge data dictionaries
Returns:A graph with flattened edge data dictionaries
Return type:nx.MultiDiGraph

Recursively converts a nested list to a nested tuple


Gets the current PyBEL version

Returns:The current PyBEL version
Return type:str

Tokenizes a version string to a tuple. Truncates qualifiers like -dev.

Parameters:version_string (str) – A version string
Returns:A tuple representing the version string
Return type:tuple
>>> tokenize_version('0.1.2-dev')
(0, 1, 2)

Convert the d[CITATION] entry in an edge data dictionary to a tuple


Flattens a citation dict, from the d[CITATION] entry in an edge data dictionary


Quote a string that isn’t solely alphanumeric

Parameters:s (str) – a string
Return type:str

Checks that a string represents a valid date in ISO 8601 format YYYY-MM-DD

Return type:bool

Checks that the string is a valid date versions string


Tries to parse a datetime object from a standard datetime format or date format

Parameters:s (str) – A string representing a date or datetime
Returns:A parsed date object
Return type:datetime.date

Converts a PyBEL node tuple to a hash

Parameters:node (tuple) – A BEL node
Returns:A hashed version of the node tuple using md5 hash of the binary pickle dump
Return type:str

Extracts only the PyBEL-specific data from the given edge data dictionary

Parameters:data (dict) – An edge data dictionary
Return type:dict
pybel.utils.edge_to_tuple(u, v, k, data)[source]

Converts an edge to tuple

  • u (tuple) – The source BEL node
  • v (tuple) – The target BEL node
  • data (dict) – The edge’s data dictionary

A tuple that can be hashed representing this edge. Makes no promises to its structure.

pybel.utils.hash_edge(u, v, k, d)[source]

Converts an edge tuple to a hash

Returns:A hashed version of the edge tuple using md5 hash of the binary pickle dump of u, v, and the json dump of d
Return type:str
pybel.utils.subdict_matches(target, query, partial_match=True)[source]

Checks if all the keys in the query dict are in the target dict, and that their values match

  1. Checks that all keys in the query dict are in the target dict
  2. Matches the values of the keys in the query dict
    1. If the value is a string, then must match exactly
    2. If the value is a set/list/tuple, then will match any of them
    3. If the value is a dict, then recursively check if that subdict matches
  • target (dict) – The dictionary to search
  • query (dict) – A query dict with keys to match
  • partial_match (bool) – Should the query values be used as partial or exact matches? Defaults to True.

if all keys in b are in target_dict and their values match

Return type:


Parser Utilities

pybel.parser.utils.any_subdict_matches(dict_of_dicts, query_dict)[source]

Checks if dictionary target_dict matches one of the subdictionaries of a

  • dict_of_dicts – dictionary of dictionaries
  • query_dict – dictionary

if dictionary target_dict matches one of the subdictionaries of a

Return type:



takes a dictionary of sets and provides subdicts

Parameters:d (dict) – a dictionary of sets
Return type:list

Determines if an object can be cast to an int

Parameters:s – any object
Returns:true if argument can be cast to an int:
Return type:bool

Defines a delimited list by enumerating each element of the list

pybel.parser.utils.one_of_tags(tags, canonical_tag, identifier)[source]

This is a convenience method for defining the tags usable in the BelParser. For example, statements like g(HGNC:SNCA) can be expressed also as geneAbundance(HGNC:SNCA). The language must define multiple different tags that get normalized to the same thing.

  • tags (list of str) – a list of strings that are the tags for a function. For example, [‘g’, ‘geneAbundance’] for the abundance of a gene
  • canonical_tag (str) – the preferred tag name. Does not have to be one of the tags. For example, ‘GeneAbundance’ (note capitalization) is used for the abundance of a gene
  • identifier – this is the key under which the value for this tag is put in the PyParsing framework.

a PyParsing ParseElement

Return type:


pybel.parser.utils.triple(subject, relation, obj)[source]

Builds a simple triple in PyParsing that has a subject relation object format