Mutation¶
This module contains functions that mutate or make transformations on a network

pybel_tools.mutation.
collapse_nodes
(graph, dict_of_sets_of_nodes)[source]¶ Collapses all nodes in values to the key nodes, in place
Parameters:  graph (pybel.BELGraph) – A BEL graph
 dict_of_sets_of_nodes (dict[tuple,set[tuple]]) – A dictionary of {node: set of nodes}

pybel_tools.mutation.
build_central_dogma_collapse_dict
(graph)[source]¶ Builds a dictionary to direct the collapsing on the central dogma
Parameters: graph (pybel.BELGraph) – A BEL graph Returns: A dictionary of {node: set of nodes} Return type: dict[tuple,set[tuple]]

pybel_tools.mutation.
build_central_dogma_collapse_gene_dict
(graph)[source]¶ Builds a dictionary to direct the collapsing on the central dogma
Parameters: graph (pybel.BELGraph) – A BEL graph Returns: A dictionary of {node: set of PyBEL node tuples} Return type: dict[tuple,set[tuple]]

pybel_tools.mutation.
collapse_by_central_dogma
(graph)[source]¶ Collapses all nodes from the central dogma (GENE, RNA, PROTEIN) to PROTEIN, or most downstream possible entity, in place. This function wraps
collapse_nodes()
andbuild_central_dogma_collapse_dict()
.Parameters: graph (pybel.BELGraph) – A BEL graph Equivalent to:
>>> collapse_nodes(graph, build_central_dogma_collapse_dict(graph))

pybel_tools.mutation.
collapse_by_central_dogma_to_genes
(graph)[source]¶ Collapses all nodes from the central dogma (
pybel.constants.GENE
,pybel.constants.RNA
,pybel.constants.MIRNA
, andpybel.constants.PROTEIN
) topybel.constants.GENE
, inplace. This function wrapscollapse_nodes()
andbuild_central_dogma_collapse_gene_dict()
.Parameters: graph (pybel.BELGraph) – A BEL graph Equivalent to:
>>> infer_central_dogma(graph) >>> collapse_nodes(graph, build_central_dogma_collapse_gene_dict(graph))

pybel_tools.mutation.
collapse_by_central_dogma_to_genes_out_place
(graph)[source]¶ Collapses all nodes from the central dogma (
pybel.constants.GENE
,pybel.constants.RNA
,pybel.constants.MIRNA
, andpybel.constants.PROTEIN
) topybel.constants.GENE
, inplace. This function wrapscollapse_nodes()
andbuild_central_dogma_collapse_gene_dict()
.Parameters: graph (pybel.BELGraph) – A BEL graph Return type: pybel.BELGraph Equivalent to:
>>> infer_central_dogma(graph) >>> collapse_nodes(graph, build_central_dogma_collapse_gene_dict(graph))

pybel_tools.mutation.
rewire_variants_to_genes
(graph)[source]¶ Finds all protein variants that are pointing to a gene and not a protein and fixes them by changing their function to be
pybel.constants.GENE
, in placeParameters: graph (pybel.BELGraph) – A BEL graph A use case is after running
collapse_by_central_dogma_to_genes()

pybel_tools.mutation.
collapse_all_variants
(graph)[source]¶ Collapses all
hasVariant
edges to the parent node, in placeParameters: graph (pybel.BELGraph) – A BEL Graph

pybel_tools.mutation.
collapse_all_variants_out_place
(graph)[source]¶ Collapses all
hasVariant
edges to the parent node, not in placeParameters: graph (pybel.BELGraph) – A BEL Graph Return type: pybel.BELGraph

pybel_tools.mutation.
collapse_gene_variants
(graph)[source]¶ Collapses all gene’s variants’ edges to their parents, inplace
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
collapse_protein_variants
(graph)[source]¶ Collapses all protein’s variants’ edges to their parents, inplace
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
opening_on_central_dogma
(graph)[source]¶ Infers central dogmatic relations with
infer_central_dogma()
then successively prunes gene leaves then RNA leaves withprune_central_dogma()
to connect disparate elements in a knowledge assemblyParameters: graph (pybel.BELGraph) – A BEL graph Equivalent to:
>>> infer_central_dogma(graph) >>> prune_central_dogma(graph)

pybel_tools.mutation.
collapse_consistent_edges
(graph)[source]¶ Collapses consistent edges together
Warning
This operation doesn’t preserve evidences or other annotations
Parameters: graph (pybel.BELGraph) – A BEL Graph

pybel_tools.mutation.
remove_filtered_edges
(graph, edge_filters)[source]¶ Removes edges passing the given edge filters
Parameters:  graph (pybel.BELGraph) – A BEL graph
 edge_filters (types.FunctionType or iter[types.FunctionType]) – An edge filter or list of edge filters (graph, node, node, key, data)> bool
Returns:

pybel_tools.mutation.
remove_leaves_by_type
(graph, function=None, prune_threshold=1)[source]¶ Removes all nodes in graph (inplace) with only a connection to one node. Useful for gene and RNA. Allows for optional filter by function type.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 function (str) – If set, filters by the node’s function from
pybel.constants
likepybel.constants.GENE
,pybel.constants.RNA
,pybel.constants.PROTEIN
, orpybel.constants.BIOPROCESS
 prune_threshold (int) – Removes nodes with less than or equal to this number of connections. Defaults to
1

pybel_tools.mutation.
prune_central_dogma
(graph)[source]¶ Prunes genes, then RNA, in place
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
remove_inconsistent_edges
(graph)[source]¶ Remove all edges between node paris with consistent edges.
This is the allornothing approach. It would be better to do more careful investigation of the evidences during curation.
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
get_upstream_causal_subgraph
(graph, nbunch)[source]¶ Induces a subgraph from all of the upstream causal entities of the nodes in the nbunch
Parameters:  graph (pybel.BELGraph) – A BEL graph
 or list[tuple] nbunch (tuple) – A BEL node or iterable of BEL nodes
Returns: A BEL Graph
Return type:

pybel_tools.mutation.
get_peripheral_successor_edges
(graph, subgraph)[source]¶ Gets the set of possible successor edges peripheral to the subgraph. The source nodes in this iterable are all inside the subgraph, while the targets are outside.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 subgraph – An iterator of BEL nodes
Returns: An iterable of possible successor edges (4tuples of node, node, key, data)
Return type:

pybel_tools.mutation.
get_peripheral_predecessor_edges
(graph, subgraph)[source]¶ Gets the set of possible predecessor edges peripheral to the subgraph. The target nodes in this iterable are all inside the subgraph, while the sources are outside.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 subgraph – An iterator of BEL nodes
Returns: An iterable on possible predecessor edges (4tuples of node, node, key, data)
Return type:

pybel_tools.mutation.
count_sources
(edge_iter)[source]¶ Counts the source nodes in an edge iterator with keys and data
Parameters: edge_iter (iter[tuple]) – An iterable on possible predecessor edges (4tuples of node, node, key, data) Returns: A counter of source nodes in the iterable Return type: collections.Counter

pybel_tools.mutation.
count_targets
(edge_iter)[source]¶ Counts the target nodes in an edge iterator with keys and data
Parameters: edge_iter (iter[tuple]) – An iterable on possible predecessor edges (4tuples of node, node, key, data) Returns: A counter of target nodes in the iterable Return type: collections.Counter

pybel_tools.mutation.
count_possible_successors
(graph, subgraph)[source]¶ Parameters:  graph (pybel.BELGraph) – A BEL graph
 subgraph – An iterator of BEL nodes
Returns: A counter of possible successor nodes
Return type:

pybel_tools.mutation.
count_possible_predecessors
(graph, subgraph)[source]¶ Parameters:  graph (pybel.BELGraph) – A BEL graph
 subgraph – An iterator of BEL nodes
Returns: A counter of possible predecessor nodes
Return type:

pybel_tools.mutation.
get_subgraph_edges
(graph, annotation, value, source_filter=None, target_filter=None)[source]¶ Gets all edges from a given subgraph whose source and target nodes pass all of the given filters
Parameters:  graph (pybel.BELGraph) – A BEL graph
 annotation (str) – The annotation to search
 value (str) – The annotation value to search by
 source_filter – Optional filter for source nodes (graph, node) > bool
 target_filter – Optional filter for target nodes (graph, node) > bool
Returns: An iterable of (source node, target node, key, data) for all edges that match the annotation/value and node filters
Return type:

pybel_tools.mutation.
get_subgraph_peripheral_nodes
(graph, subgraph, node_filters=None, edge_filters=None)[source]¶ Gets a summary dictionary of all peripheral nodes to a given subgraph
Parameters:  graph (pybel.BELGraph) – A BEL graph
 subgraph (iter[tuple]) – A set of nodes
 node_filters (lambda) – Optional. A list of node filter predicates with the interface (graph, node) > bool. See
pybel_tools.filters.node_filters
for more information  edge_filters (lambda) – Optional. A list of edge filter predicates with the interface (graph, node, node, key, data)
> bool. See
pybel_tools.filters.edge_filters
for more information
Returns: A dictionary of {external node: {‘successor’: {internal node: list of (key, dict)}, ‘predecessor’: {internal node: list of (key, dict)}}}
Return type: For example, it might be useful to quantify the number of predecessors and successors
>>> import pybel_tools as pbt >>> sgn = 'Blood vessel dilation subgraph' >>> sg = pbt.selection.get_subgraph_by_annotation_value(graph, annotation='Subgraph', value=sgn) >>> p = pbt.mutation.get_subgraph_peripheral_nodes(graph, sg, node_filters=pbt.filters.exclude_pathology_filter) >>> for node in sorted(p, key=lambda n: len(set(p[n]['successor'])  set(p[n]['predecessor'])), reverse=True): >>> if 1 == len(p[sgn][node]['successor']) or 1 == len(p[sgn][node]['predecessor']): >>> continue >>> print(node, >>> len(p[node]['successor']), >>> len(p[node]['predecessor']), >>> len(set(p[node]['successor'])  set(p[node]['predecessor'])))

pybel_tools.mutation.
expand_periphery
(universe, graph, node_filters=None, edge_filters=None, threshold=2)[source]¶ Iterates over all possible edges, peripheral to a given subgraph, that could be added from the given graph. Edges could be added if they go to nodes that are involved in relationships that occur with more than the threshold (default 2) number of nodes in the subgraph.
Parameters:  universe (pybel.BELGraph) – The universe of BEL knowledge
 graph (pybel.BELGraph) – The (sub)graph to expand
 node_filters (lambda) – Optional. A list of node filter predicates with the interface (graph, node) > bool. See
pybel_tools.filters.node_filters
for more information  edge_filters (lambda) – Optional. A list of edge filter predicates with the interface (graph, node, node, key, data)
> bool. See
pybel_tools.filters.edge_filters
for more information  threshold – Minimum frequency of betweenness occurrence to add a gap node
A reasonable edge filter to use is
pybel_tools.filters.keep_causal_edges()
because this function can allow for huge expansions if there happen to be hub nodes.

pybel_tools.mutation.
expand_node_neighborhood
(universe, graph, node)[source]¶ Expands around the neighborhoods of the given node in the result graph by looking at the universe graph, in place.
Parameters:  universe (pybel.BELGraph) – The graph containing the stuff to add
 graph (pybel.BELGraph) – The graph to add stuff to
 node (tuple) – A node tuples from the query graph

pybel_tools.mutation.
expand_nodes_neighborhoods
(universe, graph, nodes)[source]¶ Expands around the neighborhoods of the given node in the result graph by looking at the universe graph, in place.
Parameters:  universe (pybel.BELGraph) – The graph containing the stuff to add
 graph (pybel.BELGraph) – The graph to add stuff to
 nodes (list[tuple]) – A node tuples from the query graph

pybel_tools.mutation.
expand_all_node_neighborhoods
(universe, graph, filter_pathologies=False)[source]¶ Expands the neighborhoods of all nodes in the given graph based on the universe graph.
Parameters:  universe (pybel.BELGraph) – The graph containing the stuff to add
 graph (pybel.BELGraph) – The graph to add stuff to
 filter_pathologies (bool) – Should expansion take place around pathologies?

pybel_tools.mutation.
expand_upstream_causal_subgraph
(universe, graph)[source]¶ Adds the upstream causal relations to the given subgraph
Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich with upstream causal controllers of contained nodes

pybel_tools.mutation.
enrich_grouping
(universe, graph, function, relation)[source]¶ Adds all of the grouped elements. See
enrich_complexes()
,enrich_composites()
, andenrich_reactions()
Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich
 function (str) – The function by which the subject of each triple is filtered
 relation (str) – The relationship by which the predicate of each triple is filtered

pybel_tools.mutation.
enrich_complexes
(universe, graph)[source]¶ Adds all of the members of the complexes in the subgraph that are in the original graph with appropriate
pybel.constants.HAS_COMPONENT
relationships, in place.Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich

pybel_tools.mutation.
enrich_composites
(universe, graph)[source]¶ Adds all of the members of the composite abundances in the subgraph that are in the original graph with appropriate
pybel.constants.HAS_COMPONENT
relationships, in place.Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich

pybel_tools.mutation.
enrich_reactions
(universe, graph)[source]¶ Adds all of the reactants and products of reactions in the subgraph that are in the original graph with appropriate
pybel.constants.HAS_REACTANT
andpybel.constants.HAS_PRODUCT
relationships, respectively, in place.Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich

pybel_tools.mutation.
enrich_variants
(universe, graph)[source]¶ Adds the reference nodes for all variants of genes, RNAs, miRNAs, and proteins
Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich
Equivalent to:
>>> from pybel.constants import PROTEIN, RNA, MIRNA, GENE >>> enrich_variants_helper(universe, graph, PROTEIN) >>> enrich_variants_helper(universe, graph, RNA) >>> enrich_variants_helper(universe, graph, MIRNA) >>> enrich_variants_helper(universe, graph, GENE)
See also
enrich_variants_helper()

pybel_tools.mutation.
enrich_unqualified
(universe, graph)[source]¶ Enriches the subgraph with the unqualified edges from the graph.
Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich
The reason you might want to do this is you induce a subgraph from the original graph based on an annotation filter, but the unqualified edges that don’t have annotations that most likely connect elements within your graph are not included.
See also
This function thinly wraps the successive application of the following functions:
Equivalent to:
>>> enrich_complexes(universe, graph) >>> enrich_composites(universe, graph) >>> enrich_reactions(universe, graph) >>> enrich_variants(universe, graph)

pybel_tools.mutation.
expand_internal
(universe, graph, edge_filters=None)[source]¶ Edges between entities in the subgraph that pass the given filters
Parameters:  universe (pybel.BELGraph) – The full graph
 graph (pybel.BELGraph) – A subgraph to find the upstream information
 edge_filters (list or lambda) – Optional list of edge filter functions (graph, node, node, key, data) > bool

pybel_tools.mutation.
expand_internal_causal
(universe, graph)[source]¶ Adds causal edges between entities in the subgraph. Is an extremely thin wrapper around
expand_internal()
.Parameters:  universe (pybel.BELGraph) – A BEL graph representing the universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph to enrich with causal relations between contained nodes
Equivalent to:
>>> import pybel_tools as pbt >>> pbt.mutation.expand_internal(universe, graph, edge_filters=pbt.filters.edge_is_causal)

pybel_tools.mutation.
is_node_highlighted
(graph, node)[source]¶ Returns if the given node is highlighted.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 node (tuple) – A BEL node
Returns: Does the node contain highlight information?
Return type:

pybel_tools.mutation.
highlight_nodes
(graph, nodes=None, color=None)[source]¶ Adds a highlight tag to the given nodes.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 nodes (iter[tuple]) – The nodes to add a highlight tag on
 color (str) – The color to highlight (use something that works with CSS)

pybel_tools.mutation.
remove_highlight_nodes
(graph, nodes=None)[source]¶ Removes the highlight from the given nodes, or all nodes if none given.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 nodes (list) – The list of nodes to unhighlight

pybel_tools.mutation.
is_edge_highlighted
(graph, u, v, k, d)[source]¶ Returns if the given edge is highlighted.
Parameters: graph (pybel.BELGraph) – A BEL graph Returns: Does the edge contain highlight information? Return type: bool

pybel_tools.mutation.
highlight_edges
(graph, edges=None, color=None)[source]¶ Adds a highlight tag to the given edges.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 edges (iter[tuple]) – The edges (4tuples of u, v, k, d) to add a highlight tag on
 color (str) – The color to highlight (use something that works with CSS)

pybel_tools.mutation.
remove_highlight_edges
(graph, edges=None)[source]¶ Removes the highlight from the given edges, or all edges if none given.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 edges (iter[tuple]) – The edges (4tuple of u,v,k,d) to remove the highlight from)

pybel_tools.mutation.
highlight_subgraph
(universe, graph)[source]¶ Highlights all nodes/edges in the universe that in the given graph.
Parameters: universe (pybel.BELGraph) – The universe of knowledge

pybel_tools.mutation.
remove_highlight_subgraph
(graph, subgraph)[source]¶ Removes the highlight from all nodes/edges in the graph that are in the subgraph.
Parameters:  graph (pybel.BELGraph) – The BEL graph to mutate
 subgraph (pybel.BELGraph) – The subgraph from which to remove the highlighting

pybel_tools.mutation.
infer_central_dogma
(graph)[source]¶ Adds all RNAProtein translations then all GeneRNA transcriptions by applying
infer_central_dogmatic_translations()
theninfer_central_dogmatic_transcriptions()
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
infer_missing_two_way_edges
(graph)[source]¶ If a two way edge exists, and the opposite direction doesn’t exist, add it to the graph
Use: two way edges from BEL definition and/or axiomatic inverses of membership relations
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
infer_missing_backwards_edge
(graph, u, v, k)[source]¶ Adds the same edge, but in the opposite direction if not already present
Parameters:  graph (pybel.BELGraph) – A BEL graph
 u (tuple) – A BEL node
 v (tuple) – A BEL node
 k (int) – The edge key

pybel_tools.mutation.
infer_missing_inverse_edge
(graph, relations)[source]¶ Adds inferred edges based on predefined axioms
Parameters:  graph (pybel.BELGraph) – A BEL network
 relations (str or iter[str]) – single or iterable of relation names to add their inverse inferred edges

pybel_tools.mutation.
enrich_internal_unqualified_edges
(graph, subgraph)[source]¶ Adds the missing unqualified edges between entities in the subgraph that are contained within the full graph
Parameters:  graph (pybel.BELGraph) – The full BEL graph
 subgraph (pybel.BELGraph) – The query BEL subgraph
Parses all of the citation author strings to lists by splitting on the pipe character “”
Parameters:  graph (pybel.BELGraph) – A BEL graph
 force_parse (bool) – Forces serialization without checking the tag
Returns: A set of all authors in this graph
Return type:
Recombines all authors with the pipe character “”.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 force_serialize (bool) – Forces serialization without checking the tag

pybel_tools.mutation.
add_canonical_names
(graph, replace=False)[source]¶ Adds a canonical name to each node’s data dictionary if they are missing, in place.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 replace (bool) – Should the canonical names be recalculated?

pybel_tools.mutation.
enrich_pubmed_citations
(graph, stringify_authors=False, manager=None)[source]¶ Overwrites all PubMed citations with values from NCBI’s eUtils lookup service.
Sets authors as list, so probably a good idea to run
pybel_tools.mutation.serialize_authors()
before exporting.Parameters:  graph (pybel.BELGraph) – A BEL graph
 stringify_authors (bool) – Converts all author lists to author strings using
pybel_tools.mutation.serialize_authors()
. Defaults toFalse
.  manager (None or str or Manager) – An RFC1738 database connection string, a prebuilt
pybel.manager.Manager
, orNone
for default connection
Returns: A set of PMIDs for which the eUtils service crashed
Return type:

pybel_tools.mutation.
add_identifiers
(graph)[source]¶ Adds stable node and edge identifiers to the graph, inplace using the PyBEL node and edge hashes as a hexadecimal str.
Parameters: graph (pybel.BELGraph) – A BEL Graph

pybel_tools.mutation.
random_by_nodes
(graph, percentage=None)[source]¶ Gets a random graph by inducing over a percentage of the original nodes
Parameters:  graph (pybel.BELGraph) – A BEL graph
 percentage (float) – The percentage of edges to keep
Return type:

pybel_tools.mutation.
random_by_edges
(graph, percentage=None)[source]¶ Gets a random graph by keeping a certain percentage of original edges
Parameters:  graph (pybel.BELGraph) – A BEL graph
 percentage (float) – The percentage of edges to keep
Return type:

pybel_tools.mutation.
shuffle_node_data
(graph, key, percentage=None)[source]¶ Shuffles the node’s data. Useful for permutation testing.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 key (str) – The node data dictionary key
 percentage (float) – What percentage of possible swaps to make
Return type:

pybel_tools.mutation.
shuffle_relations
(graph, percentage=None)[source]¶ Shuffles the relations. Useful for permutation testing.
Parameters:  graph (pybel.BELGraph) – A BEL graph
 percentage (float) – What percentage of possible swaps to make
Return type:

pybel_tools.mutation.
ensure_node_from_universe
(universe, graph, node, raise_for_missing=False)[source]¶ Makes sure that the subgraph has the given node
Parameters:  universe (pybel.BELGraph) – The universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph
 node (tuple) – A BEL node
 raise_for_missing (bool) – Should an error be thrown if the given node is not in the universe?

pybel_tools.mutation.
remove_isolated_nodes
(graph)[source]¶ Removes isolated nodes from the network
Parameters: graph (pybel.BELGraph) – A BEL graph

pybel_tools.mutation.
update_node_helper
(universe, graph)[source]¶ Updates the nodes’ data dictionaries from the universe
Parameters:  universe (pybel.BELGraph) – The universe of all knowledge
 graph (pybel.BELGraph) – The target BEL graph