Cache

Manager API

The BaseManager takes care of building and maintaining the connection to the database via SQLAlchemy.

class pybel.manager.BaseManager(connection=None, echo=False, autoflush=None, autocommit=None, expire_on_commit=None, scopefunc=None)[source]

Creates a connection to database and a persistent session using SQLAlchemy

A custom default can be set as an environment variable with the name pybel.constants.PYBEL_CONNECTION, using an RFC-1738 string. For example, a MySQL string can be given with the following form:

mysql+pymysql://<username>:<password>@<host>/<dbname>?charset=utf8[&<options>]

A SQLite connection string can be given in the form:

sqlite:///~/Desktop/cache.db

Further options and examples can be found on the SQLAlchemy documentation on engine configuration.

Parameters:
  • connection (str) – An RFC-1738 database connection string. If None, tries to load from the environment variable PYBEL_CONNECTION then from the config file ~/.config/pybel/config.json whose value for PYBEL_CONNECTION defaults to pybel.constants.DEFAULT_CACHE_LOCATION
  • echo (bool) – Turn on echoing sql
  • autoflush (bool) – Defaults to True if not specified in kwargs or configuration.
  • autocommit (bool) – Defaults to False if not specified in kwargs or configuration.
  • expire_on_commit (bool) – Defaults to False if not specified in kwargs or configuration.
  • scopefunc – Scoped function to pass to sqlalchemy.orm.scoped_session()

From the Flask-SQLAlchemy documentation:

An extra key 'scopefunc' can be set on the options dict to specify a custom scope function. If it’s not provided, Flask’s app context stack identity is used. This will ensure that sessions are created and removed with the request/response cycle, and should be fine in most cases.

session_maker = None

A SQLAlchemy session maker

session = None

A SQLAlchemy session object

create_all(checkfirst=True)[source]

Creates the PyBEL cache’s database and tables

Parameters:checkfirst (bool) – Check if the database is made before trying to re-make it
drop_all(checkfirst=True)[source]

Drops all data, tables, and databases for the PyBEL cache

The Manager collates multiple groups of functions for interacting with the database. For sake of code clarity, they are separated across multiple classes that are documented below.

class pybel.manager.Manager(*args, **kwargs)[source]

Bases: pybel.manager.query_manager.QueryManager, pybel.manager.cache_manager.InsertManager, pybel.manager.cache_manager.NetworkManager, pybel.manager.cache_manager.EquivalenceManager, pybel.manager.cache_manager.OwlNamespaceManager, pybel.manager.cache_manager.OwlAnnotationManager

The definition cache manager takes care of storing BEL namespace and annotation files for later use. It uses SQLite by default for speed and lightness, but any database can be used with its SQLAlchemy interface.

static ensure(connection=None, *args, **kwargs)[source]

A convenience method for turning a string into a connection, or passing a Manager through.

Parameters:
  • connection (None or str or Manager) – An RFC-1738 database connection string, a pre-built Manager, or None for default connection
  • kwargs – Keyword arguments to pass to the constructor of Manager
Return type:

Manager

Manager Components

class pybel.manager.NetworkManager(use_namespace_cache=False, *args, **kwargs)[source]

Groups functions for inserting and querying networks in the database’s network store.

Parameters:use_namespace_cache – Should namespaces be cached in-memory?
count_networks()[source]

Counts the number of networks in the cache

Return type:int
list_networks()[source]

Lists all networks in the cache

Return type:list[Network]
list_recent_networks()[source]

Lists the most recently created version of each network (by name)

Return type:list[Network]
has_name_version(name, version)[source]

Checks if the name/version combination is already in the database

Parameters:
  • name (str) – The network name
  • version (str) – The network version
Return type:

bool

drop_network_by_id(network_id)[source]

Drops a network by its database identifier

Parameters:network_id (int) – The network’s database identifier
drop_networks()[source]

Drops all networks

get_network_versions(name)[source]

Returns all of the versions of a network with the given name

Parameters:name (str) – The name of the network to query
Return type:set[str]
get_network_by_name_version(name, version)[source]

Loads most recently added graph with the given name, or allows for specification of version

Parameters:
  • name (str) – The name of the network.
  • version (str) – The version string of the network.
Returns:

A BEL graph

Return type:

BELGraph

get_networks_by_name(name)[source]

Gets all networks with the given name. Useful for getting all versions of a given network.

Parameters:name (str) – The name of the network
Return type:list[Network]
get_most_recent_network_by_name(name)[source]

Gets the most recently created network with the given name.

Parameters:name (str) – The name of the network
Return type:Network
get_network_by_id(network_id)[source]

Gets a network from the database by its identifier.

Parameters:network_id (int) – The network’s database identifier
Return type:Network
get_graph_by_id(network_id)[source]

Gets a network from the database by its identifier and converts to a BEL graph

Parameters:network_id (int) – The network’s database identifier
Return type:BELGraph
get_networks_by_ids(network_ids)[source]

Gets a list of networks with the given identifiers. Note: order is not necessarily preserved.

Parameters:network_ids (iter[int]) – The identifiers of networks in the database
Return type:list[Network]
get_graphs_by_ids(network_ids)[source]

Gets a list of networks with the given identifiers and converts to BEL graphs. Note: order is not necessarily preserved.

Parameters:network_ids (iter[int]) – The identifiers of networks in the database
Return type:list[BELGraph]
get_graph_by_ids(network_ids)[source]

Gets a combine BEL Graph from a list of network identifiers

Parameters:network_ids (list[int]) – A list of network identifiers
Return type:pybel.BELGraph
class pybel.manager.QueryManager(connection=None, echo=False, autoflush=None, autocommit=None, expire_on_commit=None, scopefunc=None)[source]

Groups queries over the edge store

Parameters:
  • connection (str) – An RFC-1738 database connection string. If None, tries to load from the environment variable PYBEL_CONNECTION then from the config file ~/.config/pybel/config.json whose value for PYBEL_CONNECTION defaults to pybel.constants.DEFAULT_CACHE_LOCATION
  • echo (bool) – Turn on echoing sql
  • autoflush (bool) – Defaults to True if not specified in kwargs or configuration.
  • autocommit (bool) – Defaults to False if not specified in kwargs or configuration.
  • expire_on_commit (bool) – Defaults to False if not specified in kwargs or configuration.
  • scopefunc – Scoped function to pass to sqlalchemy.orm.scoped_session()

From the Flask-SQLAlchemy documentation:

An extra key 'scopefunc' can be set on the options dict to specify a custom scope function. If it’s not provided, Flask’s app context stack identity is used. This will ensure that sessions are created and removed with the request/response cycle, and should be fine in most cases.

count_nodes()[source]

Counts the number of nodes in the cache

Return type:int
get_node_tuple_by_hash(node_hash)[source]

Looks up a node by the hash and returns the corresponding PyBEL node tuple

Parameters:node_hash (str) – The hash of a PyBEL node tuple from pybel.utils.hash_node()
Return type:tuple
get_node_by_tuple(node)[source]

Looks up a node by the PyBEL node tuple

Parameters:node (tuple) – A PyBEL node tuple
Return type:Node
query_nodes(node_id=None, bel=None, type=None, namespace=None, name=None, modification_type=None, modification_name=None, as_dict_list=False)[source]

Builds and runs a query over all nodes in the PyBEL cache.

Parameters:
  • node_id (int) – The node ID to get
  • bel (str) – BEL term that describes the biological entity. e.g. p(HGNC:APP)
  • type (str) – Type of the biological entity. e.g. Protein
  • namespace (str) – Namespace keyword that is used in BEL. e.g. HGNC
  • name (str) – Name of the biological entity. e.g. APP
  • modification_name (str) –
  • modification_type (str) –
  • as_dict_list (bool) – Identifies whether the result should be a list of dictionaries or a list of Node objects.
Returns:

A list of the fitting nodes as Node objects or dicts.

Return type:

list[Node]

count_edges()[source]

Counts the number of edges in the cache

Return type:int
get_edge_by_tuple(u, v, d)[source]

Looks up an edge by PyBEL edge tuple

Parameters:
  • u (tuple) – A PyBEL node tuple
  • v (tuple) – A PyBEL node tuple
  • d (dict) –
Return type:

Edge

query_edges(edge_id=None, bel=None, source=None, target=None, relation=None, citation=None, evidence=None, annotation=None, property=None, as_dict_list=False)[source]

Builds and runs a query over all edges in the PyBEL cache.

Parameters:
  • edge_id (int) – The edge identifier
  • bel (str) – BEL statement that represents the desired edge.
  • or Node source (str) – BEL term of source node e.g. p(HGNC:APP) or Node object.
  • or Node target (str) – BEL term of target node e.g. p(HGNC:APP) or Node object.
  • relation (str) – The relation that should be present between source and target node.
  • or Citation citation (str) – The citation that backs the edge up. It is possible to use the reference_id or a Citation object.
  • or Evidence evidence (str) – The supporting text of the edge
  • or str annotation (dict) – Dictionary of {annotationKey: annotationValue} parameters or just an annotationValue parameter as string.
  • property – An edge property object or a corresponding database identifier.
  • as_dict_list (bool) – Identifies whether the result should be a list of dictionaries or a list of Edge objects.
Return type:

list[Edge]

query_citations(citation_id=None, type=None, reference=None, name=None, author=None, date=None, evidence_text=None, as_dict_list=False)[source]

Builds and runs a query over all citations in the PyBEL cache.

Parameters:
  • citation_id (int) –
  • type (str) – Type of the citation. e.g. PubMed
  • reference (str) – The identifier used for the citation. e.g. PubMed_ID
  • name (str) – Title of the citation.
  • or list[str] author (str) – The name or a list of names of authors participated in the citation.
  • date (str or datetime.date) – Publishing date of the citation.
  • evidence_text (str) –
  • as_dict_list (bool) – Identifies whether the result should be a list of dictionaries or a list of Citation objects.
Returns:

List of Citation objects or corresponding dicts.

Return type:

list[Citation] or dict

query_node_properties(property_id=None, participant=None, modifier=None, as_dict_list=False)[source]

Builds and runs a query over all property entries in the database.

Parameters:
  • property_id (int) – Database primary identifier.
  • participant (str) – The participant that is effected by the property (OBJECT or SUBJECT)
  • modifier (str) – The modifier of the property.
  • as_dict_list (bool) – Identifies weather the result should be a list of dictionaries or a list of Property objects.
Return type:

list[Property]

query_edges_by_pmid(pubmed_identifiers)[source]

Gets all edges annotated to the given documents

Parameters:pubmed_identifiers (list[str]) – A list of PubMed document identifiers
Return type:list[Edge]
query_induction(nodes)[source]

Gets all edges between any of the given nodes

Parameters:nodes (list[Node]) – A list of nodes (length > 2)
Return type:list[Edge]
query_neighbors(nodes)[source]

Gets all edges incident to any of the given nodes

Parameters:nodes (list[Node]) – A list of nodes
Return type:list[Edge]

Database Models

This module contains the SQLAlchemy database models that support the definition cache and graph cache.

class pybel.manager.models.Base(**kwargs)

The most base type

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class pybel.manager.models.Namespace(**kwargs)[source]

Represents a BEL Namespace

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

uploaded

The date of upload

url

Source url of the given namespace definition file (.belns)

keyword

Keyword that is used in a BEL file to identify a specific namespace

name

Name of the given namespace

domain

Domain for which this namespace is valid

species

Taxonomy identifiers for which this namespace is valid

description

Optional short description of the namespace

version

Version of the namespace

created

DateTime of the creation of the namespace definition file

query_url

URL that can be used to query the namespace (eternally from PyBEL)

author

The author of the namespace

license

License information

contact

Contact information

to_values()[source]

Returns this namespace as a dictionary of names to their encodings. Encodings are represented as a string, and lookup operations take constant time O(8).

Return type:dict[str,str]
to_tree_list()[source]

Returns an edge set of the tree represented by this namespace’s hierarchy

Return type:set[tuple[str,str]]
to_json(include_id=True)[source]

Returns the table entry as a dictionary without the SQLAlchemy instance information.

Return type:dict
class pybel.manager.models.NamespaceEntry(**kwargs)[source]

Represents a name within a BEL namespace

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

name

Name that is defined in the corresponding namespace definition file

encoding

The biological entity types for which this name is valid

to_json(include_id=False)[source]

Describes the namespaceEntry as dictionary of Namespace-Keyword and Name.

Return type:dict
class pybel.manager.models.NamespaceEntryEquivalence(**kwargs)[source]

Represents the equivalance classes between entities

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class pybel.manager.models.Annotation(**kwargs)[source]

Represents a BEL Annotation

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

uploaded

The date of upload

url

Source url of the given annotation definition file (.belanno)

keyword

Keyword that is used in a BEL file to identify a specific annotation

type

Annotation type

description

Optional short description of the given annotation

version

Version of the annotation

created

DateTime of the creation of the given annotation definition

name

Name of the annotation definition

author

Author information

license

License information

contact

Contact information

get_entries()[source]

Gets a set of the names of all etries

Return type:set[str]
to_tree_list()[source]

Returns an edge set of the tree represented by this namespace’s hierarchy

Return type:set[tuple[str,str]]
to_json(include_id=False)[source]

Returns this annotation as a JSON dictionary

Return type:dict
class pybel.manager.models.AnnotationEntry(**kwargs)[source]

Represents a value within a BEL Annotation

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

name

Name that is defined in the corresponding annotation definition file

to_json(include_id=False)[source]

Describes the annotationEntry as dictionary of Annotation-Keyword and Annotation-Name.

Return type:dict
class pybel.manager.models.Network(**kwargs)[source]

Represents a collection of edges, specified by a BEL Script

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

name

Name of the given Network (from the BEL file)

version

Release version of the given Network (from the BEL file)

authors

Authors of the underlying BEL file

contact

Contact information extracted from the underlying BEL file

description

Descriptive text extracted from the BEL file

copyright

Copyright information

disclaimer

Disclaimer information

licenses

License information

blob

A pickled version of this network

to_json(include_id=False)[source]

Returns this network as JSON

Return type:dict
as_bel()[source]

Gets this network and loads it into a BELGraph

Return type:BELGraph
store_bel(graph)[source]

Inserts a bel graph

Parameters:graph (BELGraph) – A BEL Graph
class pybel.manager.models.Node(**kwargs)[source]

Represents a BEL Term

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

type

The type of the represented biological entity e.g. Protein or Gene

namespace_pattern

Contains regex pattern for value identification.

is_variant

Identifies weather or not the given node is a variant

fusion

Identifies weather or not the given node is a fusion

bel

Valid BEL term that represents the given node

to_json(include_id=False, include_hash=False)[source]

Serializes this node as a PyBEL node data dictionary

Parameters:
  • include_id (bool) – Include the database identifier?
  • include_hash (bool) – Include the node hash?
Return type:

dict

to_tuple()[source]

Converts this node to a PyBEL tuple

Return type:tuple
class pybel.manager.models.Modification(**kwargs)[source]

The modifications that are present in the network are stored in this table.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

modType

Type of the stored modification e.g. Fusion

modNamespace

Namespace for the modification name

modName

Name of the given modification (used for pmod or gmod)

aminoA

Three letter amino acid code

position

Position

data

Recreates a is_variant dictionary for BELGraph

Returns:Dictionary that describes a variant or a fusion.
Return type:dict
to_json()[source]

Enables json serialization for the class this method is defined in.

Return type:dict
class pybel.manager.models.Author(**kwargs)[source]

Contains all author names.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class pybel.manager.models.Citation(**kwargs)[source]

The information about the citations that are used to prove a specific relation are stored in this table.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

type

Type of the stored publication e.g. PubMed

reference

Reference identifier of the publication e.g. PubMed_ID

name

Journal name

title

Title of the publication

volume

Volume of the journal

issue

Issue within the volume

pages

Pages of the publication

date

Publication date

first_id

First author

last_id

Last author

to_json(include_id=False)[source]

Creates a citation dictionary that is used to recreate the edge data dictionary of a BELGraph.

Returns:Citation dictionary for the recreation of a BELGraph.
Return type:dict
class pybel.manager.models.Evidence(**kwargs)[source]

This table contains the evidence text that proves a specific relationship and refers the source that is cited.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

text

Supporting text from a given publication

to_json(include_id=False)[source]

Creates a dictionary that is used to recreate the edge data dictionary for a BELGraph.

Returns:Dictionary containing citation and evidence for a BELGraph edge.
Return type:dict
class pybel.manager.models.Edge(**kwargs)[source]

Relationships are represented in this table. It shows the nodes that are in a relation to eachother and provides information about the context of the relation by refaring to the annotation, property and evidence tables.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bel

Valid BEL statement that represents the given edge

sha512

The hash of the source, target, and associated metadata

get_data_json()[source]

Gets the PyBEL edge data dictionary this edge represents

Return type:dict
to_json(include_id=False, include_hash=False)[source]

Creates a dictionary of one BEL Edge that can be used to create an edge in a BELGraph.

Parameters:
  • include_id (bool) – Include the database identifier?
  • include_hash (bool) – Include the node hash?
Returns:

Dictionary that contains information about an edge of a BELGraph. Including participants and edge data information.

Return type:

dict

insert_into_graph(graph)[source]

Inserts this edge into a BEL Graph

Parameters:graph (pybel.BELGraph) – A BEL graph
class pybel.manager.models.Property(**kwargs)[source]

The property table contains additional information that is used to describe the context of a relation.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

participant

Identifies which participant of the edge if affected by the given property

modifier

The modifier to the corresponding participant

relativeKey

Relative key of effect e.g. to_tloc or from_tloc

propValue

Value of the effect

effectNamespace

Optional namespace that defines modifier value

effectName

Value for specific modifiers e.g. Activity

data

Creates a property dict that is used to recreate an edge dictionary for a BELGraph.

Returns:Property dictionary of an edge that is participant (sub/obj) related.
Return type:dict
to_json()[source]

Enables json serialization for the class this method is defined in.

Return type:dict