Filters

This module contains functions for filtering node and edge iterables. It relies heavily on the concepts of functional programming and the concept of predicates.

Node Filters

A node filter is a function that takes two arguments: a pybel.BELGraph and a node tuple. It returns a boolean representing whether the node passed the given test.

This module contains a set of default functions for filtering lists of nodes and building node filtering functions.

A general use for a node filter function is to use the built-in filter() in code like filter(your_node_filter, graph)

pybel_tools.filters.node_filters.summarize_node_filter(graph, node_filters)[source]

Prints a summary of the number of nodes passing a given set of filters

Parameters:
pybel_tools.filters.node_filters.node_inclusion_filter_builder(nbunch)[source]

Builds a filter that only passes on nodes in the given list

Parameters:nbunch (iter[tuple]) – An iterable of BEL nodes
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.node_exclusion_filter_builder(nodes)[source]

Builds a filter that fails on nodes in the given list

Parameters:nodes (list) – A list of nodes
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.function_inclusion_filter_builder(func)[source]

Builds a filter that only passes on nodes of the given function(s)

Parameters:func (str or iter[str]) – A BEL Function or list/set/tuple of BEL functions
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.function_exclusion_filter_builder(func)[source]

Builds a filter that fails on nodes of the given function(s)

Parameters:func (str or list[str] or tuple[str] or set[str]) – A BEL Function or list/set/tuple of BEL functions
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.function_namespace_inclusion_builder(func, namespace)[source]

Builds a filter function for matching the given BEL function with the given namespace or namespaces

Parameters:
  • func (str) – A BEL function
  • or iter[str] namespace (str) – The namespace to serach by
Returns:

A node filter (graph, node) -> bool

Return type:

types.FunctionType

pybel_tools.filters.node_filters.namespace_inclusion_builder(namespace)[source]

Builds a predicate for namespace inclusion

Parameters:or iter[str] namespace (str) – A namespace or iter of namespaces
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.data_contains_key_builder(key)[source]

Builds a filter that passes only on nodes that have the given key in their data dictionary

Parameters:key (str) – A key for the node’s data dictionary
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.data_missing_key_builder(key)[source]

Builds a filter that passes only on nodes that don’t have the given key in their data dictionary

Parameters:key (str) – A key for the node’s data dictionary
Returns:A node filter (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.node_has_cname(graph, node)

Passes for nodes that have been annotated with a canonical name

pybel_tools.filters.node_filters.node_missing_cname(graph, node)

Fails for nodes that have been annotated with a canonical name

pybel_tools.filters.node_filters.node_has_label(graph, node)

Passes for nodes that have been annotated with a label

pybel_tools.filters.node_filters.node_missing_label(graph, node)

Fails for nodes that have been annotated with a label

pybel_tools.filters.node_filters.include_pathology_filter(graph, node)

A filter that passes for nodes that are pybel.constants.PATHOLOGY

pybel_tools.filters.node_filters.exclude_pathology_filter(graph, node)

A filter that fails for nodes that are pybel.constants.PATHOLOGY

pybel_tools.filters.node_filters.node_is_upstream_leaf(graph, node)[source]

Returns if the node is an upstream leaf. An upstream leaf is defined as a node that has no in-edges, and exactly 1 out-edge.

Parameters:
Returns:

If the node is an upstream leaf

Return type:

bool

Passes for nodes who have the given key in their data dictionaries and whose associated values pass the given filter function

Parameters:
  • key (str) – The node data dictionary key to check
  • data_filter (types.FunctionType) – The filter to apply to the node data dictionary
Returns:

A node predicate (graph, node) -> bool

Return type:

types.FunctionType

Builds a node filter that only passes for nodes whose values for the given key are superstrings of the query string(s)

Parameters:
  • query (str or iter[str]) – The query string or strings to check if they’re in the node name
  • key (str) – The key for the node data dictionary. Should refer only to entries that have str values
Returns:

A node predicate (graph, node) -> bool

Return type:

types.FunctionType

Searches nodes’ names. Is a thin wrapper around build_node_key_search() with pybel.constants.NAME

Parameters:query (str or iter[str]) – The query string or strings to check if they’re in the node name
Returns:A node predicate (graph, node) -> bool
Return type:types.FunctionType

Searches nodes’ canonical names. Is a thin wrapper around build_node_key_search().

Parameters:query (str or iter[str]) – The query string or strings to check if they’re in the node name
Returns:A node predicate (graph, node) -> bool
Return type:types.FunctionType
pybel_tools.filters.node_filters.iter_undefined_families(graph, namespace)[source]

Finds protein families from a given namespace (Such as SFAM) that aren’t qualified by members

Parameters:
Returns:

An iterator over nodes that don’t

Return type:

iter[tuple]

Edge Filters

A edge filter is a function that takes five arguments: a pybel.BELGraph, a source node tuple, a target node tuple, a key, and a data dictionary. It returns a boolean representing whether the edge passed the given test.

This module contains a set of default functions for filtering lists of edges and building edge filtering functions.

A general use for an edge filter function is to use the built-in filter() in code like filter(your_edge_filter, graph.edges_iter(keys=True, data=True))

pybel_tools.filters.edge_filters.summarize_edge_filter(graph, edge_filters)[source]

Prints a summary of the number of edges passing a given set of filters

Parameters:
pybel_tools.filters.edge_filters.build_edge_data_filter(annotations, partial_match=True)[source]

Builds a filter that keeps edges whose data dictionaries are superdictionaries to the given dictionary

Parameters:
  • annotations (dict) – The annotation query dict to match
  • partial_match (bool) – Should the query values be used as partial or exact matches? Defaults to True.
Return type:

(pybel.BELGraph, tuple, tuple, int) -> bool

pybel_tools.filters.edge_filters.build_annotation_dict_all_filter(annotations, partial_match=True)[source]

Builds a filter that keeps edges whose data dictionaries’s annotations entry are superdictionaries to the given dictionary

Parameters:
  • annotations (dict) – The annotation query dict to match
  • partial_match (bool) – Should the query values be used as partial or exact matches? Defaults to True.
Return type:

(pybel.BELGraph, tuple, tuple, int) -> bool

pybel_tools.filters.edge_filters.build_annotation_dict_any_filter(annotations)[source]

Builds a filter that keeps edges whose data dictionaries’s annotations entry contain any match to the target dictionary

Parameters:annotations (dict) – The annotation query dict to match
pybel_tools.filters.edge_filters.build_relation_filter(relations)[source]

Builds a filter that passes only for edges with the given relation

Parameters:relations (str or iter[str]) – A relation or iterable of relations
Returns:An edge filter function (graph, node, node, key, data) -> bool
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool
pybel_tools.filters.edge_filters.build_pmid_inclusion_filter(pmid)[source]

Only passes for edges with citations whose references are one of the given PubMed identifiers

Parameters:pmid (str or iter[str]) – A PubMed identifier or list of PubMed identifiers to filter for
Returns:An edge filter function (graph, node, node, key, data) -> bool
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool
pybel_tools.filters.edge_filters.build_pmid_exclusion_filter(pmid)[source]

Fails for edges with citations whose references are one of the given PubMed identifiers

Parameters:pmid (str or iter[str]) – A PubMed identifier or list of PubMed identifiers to filter against
Returns:An edge filter function (graph, node, node, key, data) -> bool
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool
pybel_tools.filters.edge_filters.build_author_inclusion_filter(author)[source]

Only passes for edges with author information that matches one of the given authors

Parameters:author (str or iter[str]) – The author or list of authors to filter by
Returns:An edge filter
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool
pybel_tools.filters.edge_filters.has_pathology_causal(graph, u, v, k)[source]

Returns if the subject of this edge is a pathology and participates in a causal relation where the object is not a pathology. These relations are generally nonsense.

Parameters:
  • graph (pybel.BELGraph) – A BEL Graph
  • u (tuple) – A BEL node
  • v (tuple) – A BEL node
  • k (int) – The edge key between the given nodes
Returns:

If the subject of this edge is a pathology and it participates in a causal reaction.

Return type:

bool

pybel_tools.filters.edge_filters.build_source_namespace_filter(namespaces)[source]

Only passes for edges whose source nodes have the given namespace or one of the given namespaces

Parameters:namespaces (str or iter[str]) – The namespace or namespaces to filter by
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool
pybel_tools.filters.edge_filters.build_target_namespace_filter(namespaces)[source]

Only passes for edges whose target nodes have the given namespace or one of the given namespaces

Parameters:namespaces (str or iter[str]) – The namespace or namespaces to filter by
Return type:(pybel.BELGraph, tuple, tuple, int) -> bool