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.

pybel.struct.filters.invert_edge_predicate(edge_predicate)[source]

Build an edge predicate that is the inverse of the given edge predicate.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.and_edge_predicates(edge_predicates)[source]

Concatenate multiple edge predicates to a new predicate that requires all predicates to be met.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.filter_edges(graph, edge_predicates)[source]

Apply a set of filters to the edges iterator of a BEL graph.

Return type

Iterable[Tuple[BaseEntity, BaseEntity, str]]

Returns

An iterable of edges that pass all predicates

pybel.struct.filters.count_passed_edge_filter(graph, edge_predicates)[source]

Return the number of edges passing a given set of predicates.

Return type

int

pybel.struct.filters.build_pmid_exclusion_filter(pmids)[source]

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

Parameters

pmids (Union[str, Iterable[str]]) – A PubMed identifier or list of PubMed identifiers to filter against

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_annotation_dict_all_filter(annotations)[source]

Build an edge predicate for edges whose annotations are super-dictionaries of the given dictionary.

If no annotations are given, will always evaluate to true.

Parameters

annotations (Mapping[str, Iterable[str]]) – The annotation query dict to match

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_annotation_dict_any_filter(annotations)[source]

Build an edge predicate that passes for edges whose data dictionaries match the given dictionary.

If the given dictionary is empty, will always evaluate to true.

Parameters

annotations (Mapping[str, Iterable[str]]) – The annotation query dict to match

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_upstream_edge_predicate(nodes)[source]

Build an edge predicate that pass for relations for which one of the given nodes is the object.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_downstream_edge_predicate(nodes)[source]

Build an edge predicate that passes for edges for which one of the given nodes is the subject.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_relation_predicate(relations)[source]

Build an edge predicate that passes for edges with the given relation.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_pmid_inclusion_filter(pmids)[source]

Build an edge predicate that passes for edges with citations from the given PubMed identifier(s).

Parameters

pmids (Union[str, Iterable[str]]) – A PubMed identifier or list of PubMed identifiers to filter for

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.build_author_inclusion_filter(authors)[source]

Build an edge predicate that passes for edges with citations written by the given author(s).

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.edge_predicate(func)[source]

Decorate an edge predicate function that only takes a dictionary as its singular argument.

Apply this as a decorator to a function that takes a single argument, a PyBEL node data dictionary, to make sure that it can also accept a pair of arguments, a BELGraph and a PyBEL node tuple as well.

Return type

Callable[[BELGraph, BaseEntity, BaseEntity, str], bool]

pybel.struct.filters.true_edge_predicate(graph, u, v, k)[source]

Return true for all edges.

Return type

bool

pybel.struct.filters.false_edge_predicate(graph, u, v, k)[source]

Return false for all edges.

Return type

bool

pybel.struct.filters.has_provenance(edge_data)[source]

Check if the edge has provenance information (i.e. citation and evidence).

Return type

bool

pybel.struct.filters.has_pubmed(edge_data)[source]

Check if the edge has a PubMed citation.

Return type

bool

pybel.struct.filters.has_authors(edge_data)[source]

Check if the edge contains author information for its citation.

Return type

bool

pybel.struct.filters.is_causal_relation(edge_data)[source]

Check if the given relation is causal.

Return type

bool

pybel.struct.filters.not_causal_relation(edge_data)[source]

Check if the given relation is not causal.

Return type

bool

pybel.struct.filters.is_direct_causal_relation(edge_data)[source]

Check if the edge is a direct causal relation.

Return type

bool

pybel.struct.filters.is_associative_relation(edge_data)[source]

Check if the edge has an association relation.

Return type

bool

pybel.struct.filters.has_polarity(edge_data)[source]

Check if the edge has polarity.

Return type

bool

pybel.struct.filters.edge_has_activity(edge_data)[source]

Check if the edge contains an activity in either the subject or object.

Return type

bool

pybel.struct.filters.edge_has_degradation(edge_data)[source]

Check if the edge contains a degradation in either the subject or object.

Return type

bool

pybel.struct.filters.edge_has_translocation(edge_data)[source]

Check if the edge has a translocation in either the subject or object.

Return type

bool

pybel.struct.filters.edge_has_annotation(edge_data, key)[source]

Check if an edge has the given annotation.

Parameters
  • edge_data (Mapping) – The data dictionary from a BELGraph’s edge

  • key (str) – An annotation key

Return type

Optional[Any]

Returns

If the annotation key is present in the current data dictionary

For example, it might be useful to print all edges that are annotated with ‘Subgraph’:

>>> from pybel.examples import sialic_acid_graph
>>> from pybel.examples.sialic_acid_example import sialic_acid_cd33_complex, cd33
>>> edges = {
...     (u, v)
...     for u, v, data in sialic_acid_graph.edges(data=True)
...     if edge_has_annotation(data, 'Species')
... }
>>> assert (sialic_acid_cd33_complex, cd33) in edges
pybel.struct.filters.has_pathology_causal(graph, u, v, k)[source]

Check if the subject is a pathology and has a causal relationship with a non bioprocess/pathology.

Return type

bool

Returns

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

pybel.struct.filters.filter_nodes(graph, node_predicates)[source]

Apply a set of predicates to the nodes iterator of a BEL graph.

Return type

Iterable[BaseEntity]

pybel.struct.filters.get_nodes(graph, node_predicates)[source]

Get the set of all nodes that pass the predicates.

Return type

Set[BaseEntity]

pybel.struct.filters.count_passed_node_filter(graph, node_predicates)[source]

Count how many nodes pass a given set of node predicates.

Return type

int

pybel.struct.filters.summarize_node_filter(graph, node_filters)[source]

Print a summary of the number of nodes passing a given set of filters.

Parameters
  • graph (BELGraph) – A BEL graph

  • node_filters (Union[Callable[[BELGraph, BaseEntity], bool], Iterable[Callable[[BELGraph, BaseEntity], bool]]]) – A node filter or list/tuple of node filters

Return type

None

pybel.struct.filters.get_nodes_by_function(graph, func)[source]

Get all nodes with the given function(s).

Return type

Set[BaseEntity]

pybel.struct.filters.get_nodes_by_namespace(graph, namespaces)[source]

Get all nodes identified by the given namespace(s).

Return type

Set[BaseEntity]

pybel.struct.filters.function_inclusion_filter_builder(func)[source]

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

Parameters

func (Union[str, Iterable[str]]) – A BEL Function or list/set/tuple of BEL functions

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.function_exclusion_filter_builder(func)[source]

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

Parameters

func (Union[str, Iterable[str]]) – A BEL Function or list/set/tuple of BEL functions

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.data_missing_key_builder(key)[source]

Build 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

Return type

Callable[[BELGraph, BaseEntity], bool]

Build a filter for nodes whose associated data with the given key passes the given predicate.

Parameters
  • key (Union[str, List[str]]) – The node data dictionary key to check

  • data_predicate (Callable[[Any], bool]) – The filter to apply to the node data dictionary

Return type

Callable[[BELGraph, BaseEntity], bool]

Build a function for testing data associated with the node in the graph.

Parameters
  • key (Union[str, List[str]]) – The node data dictionary key to check

  • data_predicate (Callable[[Any], bool]) – The filter to apply to the node data dictionary

Return type

Callable[[BELGraph, BaseEntity], bool]

Build a node filter for nodes whose values for the given key are superstrings of the query string(s).

Parameters
  • query (Union[str, Iterable[str]]) – The query string or strings to check if they’re in the node name

  • key (Union[str, List[str]]) – The key for the node data dictionary. Should refer only to entries that have str values

Return type

Callable[[BELGraph, BaseEntity], bool]

Search nodes’ names.

Is a thin wrapper around build_node_key_search() with pybel.constants.NAME

Parameters

query (Union[str, Iterable[str]]) – The query string or strings to check if they’re in the node name

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.namespace_inclusion_builder(namespace)[source]

Build a predicate for namespace inclusion.

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.has_activity(graph, node)[source]

Return true if over any of the node’s edges, it has a molecular activity.

Return type

bool

pybel.struct.filters.has_edge_modifier(graph, node, modifier)[source]

Return true if over any of a nodes edges, it has a given modifier.

Modifier can be one of:

  • pybel.constants.ACTIVITY,

  • pybel.constants.DEGRADATION

  • pybel.constants.TRANSLOCATION.

Parameters

modifier (str) – One of pybel.constants.ACTIVITY, pybel.constants.DEGRADATION, or pybel.constants.TRANSLOCATION

Return type

bool

pybel.struct.filters.is_degraded(graph, node)[source]

Return true if over any of the node’s edges, it is degraded.

Return type

bool

pybel.struct.filters.is_translocated(graph, node)[source]

Return true if over any of the node’s edges, it is translocated.

Return type

bool

pybel.struct.filters.is_isolated_list_abundance(graph, node, cls=<class 'pybel.dsl.node_classes.ListAbundance'>)[source]

Return if the node is a list abundance but has no qualified edges.

Return type

bool

pybel.struct.filters.none_of(nodes)[source]

Build a node predicate that returns false for the given nodes.

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.one_of(nodes)[source]

Build a function that returns true for the given nodes.

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.has_fragment(node, variant_cls)

Return true if the node has at least one of the given variant.

Return type

bool

pybel.struct.filters.has_gene_modification(node, variant_cls)

Return true if the node has at least one of the given variant.

Return type

bool

pybel.struct.filters.has_hgvs(node, variant_cls)

Return true if the node has at least one of the given variant.

Return type

bool

pybel.struct.filters.has_protein_modification(node, variant_cls)

Return true if the node has at least one of the given variant.

Return type

bool

pybel.struct.filters.has_variant(node)[source]

Return true if the node has any variants.

Return type

bool

pybel.struct.filters.has_causal_edges(graph, node)[source]

Check if the node has any causal out-edges or in-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.has_causal_in_edges(graph, node)[source]

Check if the node has any causal in-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.has_causal_out_edges(graph, node)[source]

Check if the node has any causal out-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.has_in_edges(graph, node, edge_types)[source]

Check if the node has any in-edges in the given set.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

  • edge_types (Set[str]) – A collection of edge types to check against

Return type

bool

pybel.struct.filters.has_out_edges(graph, node, edge_types)[source]

Check if the node has any out-edges in the given set.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

  • edge_types (Set[str]) – A collection of edge types to check against

Return type

bool

pybel.struct.filters.is_causal_central(graph, node)[source]

Check if the node has both causal in-edges and also causal out-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.is_causal_sink(graph, node)[source]

Check if the node has causal in-edges but no causal out-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.is_causal_source(graph, node)[source]

Check if the node has causal out-edges but no causal in-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.no_causal_edges(graph, node)[source]

Check if the node does not have any causal out-edges or in-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.no_causal_in_edges(graph, node)[source]

Check if the node does not have any causal in-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.no_causal_out_edges(graph, node)[source]

Check if the node does not have any causal out-edges.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

Return type

bool

pybel.struct.filters.no_in_edges(graph, node, edge_types)[source]

Check if the node does not have any in-edges in the given set.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

  • edge_types (Set[str]) – A collection of edge types to check against

Return type

bool

pybel.struct.filters.no_out_edges(graph, node, edge_types)[source]

Check if the node does not have any out-edges in the given set.

Parameters
  • graph (BELGraph) – A BEL graph

  • node (BaseEntity) – A BEL term

  • edge_types (Set[str]) – A collection of edge types to check against

Return type

bool

pybel.struct.filters.concatenate_node_predicates(node_predicates)[source]

Concatenate multiple node predicates to a new predicate that requires all predicates to be met.

Example usage:

>>> from pybel import BELGraph
>>> from pybel.dsl import Protein
>>> from pybel.struct.filters import not_gene, not_rna
>>> app_protein = Protein(name='APP', namespace='hgnc', identifier='620')
>>> app_rna = app_protein.get_rna()
>>> app_gene = app_rna.get_gene()
>>> graph = BELGraph()
>>> _ = graph.add_transcription(app_gene, app_rna)
>>> _ = graph.add_translation(app_rna, app_protein)
>>> node_predicate = concatenate_node_predicates([not_rna, not_gene])
>>> assert node_predicate(graph, app_protein)
>>> assert not node_predicate(graph, app_rna)
>>> assert not node_predicate(graph, app_gene)
Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.false_node_predicate(_)[source]

Return false for all nodes.

Return type

bool

pybel.struct.filters.invert_node_predicate(f)[source]

Build a node predicate that is the inverse of the given node predicate.

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.node_predicate(f)[source]

Tag a node predicate that takes a dictionary to also accept a pair of (BELGraph, node).

Apply this as a decorator to a function that takes a single argument, a PyBEL node, to make sure that it can also accept a pair of arguments, a BELGraph and a PyBEL node as well.

Return type

Callable[[BELGraph, BaseEntity], bool]

pybel.struct.filters.true_node_predicate(_)[source]

Return true for all nodes.

Given BEL graph graph, applying true_predicate() with a predicate on the nodes iterable as in filter(keep_node_permissive, graph) will result in the same iterable as iterating directly over a BELGraph

Return type

bool

pybel.struct.filters.part_has_modifier(edge_data, part, modifier)[source]

Return true if the modifier is in the given subject/object part.

Parameters
  • edge_data (Mapping) – PyBEL edge data dictionary

  • part (str) – either pybel.constants.SUBJECT or pybel.constants.OBJECT

  • modifier (str) – The modifier to look for

Return type

bool