Neo4j-based hierarchies

Neo4j-based persisent graph hierarchies.

This module implements data structures that allow working with persistent graph hierarchies stored in an instance of the Neo4j database:

• Neo4jHierarchy – class for persistent graph hierarchies.

• TypedNeo4jGraph – class for schema-aware property graph.

class regraph.backends.neo4j.hierarchies.Neo4jHierarchy(uri=None, user=None, password=None, driver=None, graph_label='graph', typing_label='homomorphism', relation_label='binaryRelation', graph_edge_label='edge', graph_typing_label='typing', graph_relation_label='relation')

Class for persistent hierarchies.

Methods

add_empty_graph(self, graph_id[, attrs])	“Add a new empty graph to the hierarchy.
add_graph(self, graph_id, graph[, attrs])	Add a new graph to the hierarchy.
add_graph_from_data(self, graph_id, …[, attrs])	Add a new graph to the hierarchy from the input node/edge lists.
add_relation(self, left, right, relation[, …])	Add relation to the hierarchy.
add_typing(self, source, target, mapping[, …])	Add homomorphism to the hierarchy.
bfs_tree(self, graph[, reverse])	BFS tree from the graph to all other reachable graphs.
close(self)	Close connection to the database.
copy_graph(self, graph_id, new_graph_id[, …])	Create a copy of a graph in a hierarchy.
execute(self, query)	Execute a Cypher query.
from_json([uri, user, password, driver, …])	Create hierarchy object from JSON representation.
get_graph(self, graph_id)	Get a graph object associated to the node ‘graph_id’.
get_graph_attrs(self, graph_id)	Get attributes of a graph in the hierarchy.
get_relation(self, left_id, right_id)	Get a relation dict associated to the rel ‘left_id->target_id’.
get_relation_attrs(self, left_id, right_id)	Get attributes of a reltion in the hierarchy.
get_typing(self, source_id, target_id)	Get a typing dict associated to the edge ‘source_id->target_id’.
get_typing_attrs(self, source_id, target_id)	Get attributes of a typing in the hierarchy.
graphs(self[, data])	Return a list of graphs in the hierarchy.
load([uri, user, password, driver, …])	Load the hierarchy.
predecessors(self, node_id)	Return the set of predecessors.
relabel_graph(self, graph_id, new_graph_id)	Relabel a graph in the hierarchy.
relabel_graph_node(self, graph_id, node, …)	Rename a node in a graph of the hierarchy.
relabel_graphs(self, mapping)	Relabel graphs in the hierarchy.
relations(self[, data])	Return a list of relations.
remove_graph(self, graph_id[, reconnect])	Remove graph from the hierarchy.
remove_relation(self, left, right)	Remove a relation from the hierarchy.
remove_typing(self, s, t)	Remove a typing from the hierarchy.
set_graph_attrs(self, graph_id, attrs[, update])	Set attributes of a graph in the hierarchy.
set_node_relation(self, left_graph, …)	Set relation for a particular node.
set_relation_attrs(self, left, right, attrs)	Set attributes of a relation in the hierarchy.
set_typing_attrs(self, source, target, attrs)	Set attributes of a typing in the hierarchy.
shortest_path(self, source, target)	Shortest path from ‘source’ to ‘target’.
successors(self, node_id)	Return the set of successors.
typings(self[, data])	Return a list of graph typing edges in the hierarchy.

add_empty_graph(self, graph_id, attrs=None)

“Add a new empty graph to the hierarchy.

Parameters

graph_idhashable

Id of a new node in the hierarchy

graph_attrsdict, optional

Dictionary containing attributes of the new node

add_graph(self, graph_id, graph, attrs=None)

Add a new graph to the hierarchy.

Parameters

graph_idhashable

Id of a new node in the hierarchy

graphregraph.Graph

Graph object corresponding to the new node of the hierarchy

graph_attrsdict, optional

Dictionary containing attributes of the new node

add_graph_from_data(self, graph_id, node_list, edge_list, attrs=None)

Add a new graph to the hierarchy from the input node/edge lists.

Parameters

graph_idhashable

Id of a new node in the hierarchy

node_listiterable

List of nodes (with attributes)

edge_listiterable

List of edges (with attributes)

graph_attrsdict, optional

Dictionary containing attributes of the new node

add_relation(self, left, right, relation, attrs=None)

Add relation to the hierarchy.

This method adds a relation between two graphs in the hierarchy corresponding to the nodes with ids left and right, the relation itself is defined by a dictionary relation, where a key is a node in the left graph and its corresponding value is a set of nodes from the right graph to which the node is related. Relations in the hierarchy are symmetric (see example below).

Parameters

left

Id of the hierarchy’s node represening the left graph

right

Id of the hierarchy’s node represening the right graph

relationdict

Dictionary representing a relation of nodes from left to the nodes from right, a key of the dictionary is assumed to be a node from left and its value a set of ids of related nodes from right

attrsdict

Dictionary containing attributes of the new relation

Raises

HierarchyError

This error is raised in the following cases:

• node with id left/right is not defined in the hierarchy;

• node with id left/right is not a graph;

• a relation between left and right already exists;

• some node ids specified in relation are not found in the

left/right graph.

add_typing(self, source, target, mapping, attrs=None, check=True)

Add homomorphism to the hierarchy.

Parameters

sourcehashable

Id of the source graph node of typing

targethashable

Id of the target graph node of typing

mappingdict

Dictionary representing a mapping of nodes from the source graph to target’s nodes

attrsdict

Dictionary containing attributes of the new typing edge

Raises

HierarchyError

This error is raised in the following cases:

• source or target ids are not found in the hierarchy

• a typing edge between source and target already exists

• addition of an edge between source and target creates

a cycle or produces paths that do not commute with some already existing paths

InvalidHomomorphism

If a homomorphisms from a graph at the source to a graph at the target given by mapping is not a valid homomorphism.

bfs_tree(self, graph, reverse=False)

BFS tree from the graph to all other reachable graphs.

close(self)

Close connection to the database.

copy_graph(self, graph_id, new_graph_id, attach_graphs=[])

Create a copy of a graph in a hierarchy.

execute(self, query)

Execute a Cypher query.

classmethod from_json(uri=None, user=None, password=None, driver=None, json_data=None, ignore=None, clear=False)

Create hierarchy object from JSON representation.

Parameters

uristr, optional

Uri for Neo4j database connection

userstr, optional

Username for Neo4j database connection

passwordstr, optional

Password for Neo4j database connection

driverneo4j.v1.direct.DirectDriver, optional

DB driver object

json_datadict, optional

JSON-like dict containing representation of a hierarchy

ignoredict, optional

Dictionary containing components to ignore in the process of converting from JSON, dictionary should respect the following format: {

“graphs”: <collection of ids of graphs to ignore>, “rules”: <collection of ids of rules to ignore>, “typing”: <collection of tuples containing typing

edges to ignore>,

“rule_typing”: <collection of tuples containing rule

typing edges to ignore>>,

“relations”: <collection of tuples containing

relations to ignore>,

}

directedbool, optional

True if graphs from JSON representation should be loaded as directed graphs, False otherwise, default value – True

Returns

hierarchyregraph.hierarchy.Hierarchy

get_graph(self, graph_id)

Get a graph object associated to the node ‘graph_id’.

get_graph_attrs(self, graph_id)

Get attributes of a graph in the hierarchy.

Parameters

graph_idhashable

Id of the graph

get_relation(self, left_id, right_id)

Get a relation dict associated to the rel ‘left_id->target_id’.

get_relation_attrs(self, left_id, right_id)

Get attributes of a reltion in the hierarchy.

Parameters

lefthashable

Id of the left graph

righthashable

Id of the right graph

get_typing(self, source_id, target_id)

Get a typing dict associated to the edge ‘source_id->target_id’.

get_typing_attrs(self, source_id, target_id)

Get attributes of a typing in the hierarchy.

Parameters

sourcehashable

Id of the source graph

targethashable

Id of the target graph

graphs(self, data=False)

Return a list of graphs in the hierarchy.

classmethod load(uri=None, user=None, password=None, driver=None, filename=None, ignore=None, clear=False)

Load the hierarchy.

predecessors(self, node_id)

Return the set of predecessors.

relabel_graph(self, graph_id, new_graph_id)

Relabel a graph in the hierarchy.

Parameters

graph_idhashable

Id of the graph to relabel

new_graph_idhashable

New graph id to assign to this graph

relabel_graph_node(self, graph_id, node, new_name)

Rename a node in a graph of the hierarchy.

relabel_graphs(self, mapping)

Relabel graphs in the hierarchy.

Parameters

mapping: dict

A dictionary with keys being old graph ids and their values being new id’s of the respective graphs.

Raises

ReGraphError

If new id’s do not define a set of distinct graph id’s.

relations(self, data=False)

Return a list of relations.

remove_graph(self, graph_id, reconnect=False)

Remove graph from the hierarchy.

Removes a graph from the hierarchy, if the reconnect parameter is set to True, adds typing from the predecessors of the removed node to all its successors, by composing the homomorphisms (for every predecessor p and for every successor ‘s’ composes two homomorphisms p->`node_id` and node_id->`s`, then removes node_id and all its incident edges, by which makes node’s removal a procedure of ‘forgetting’ one level of ‘abstraction’).

Parameters

node_id

Id of a graph to remove

reconnectbool

Reconnect the descendants of the removed node to its predecessors

Raises

HierarchyError

If graph with node_id is not defined in the hierarchy

remove_relation(self, left, right)

Remove a relation from the hierarchy.

remove_typing(self, s, t)

Remove a typing from the hierarchy.

set_graph_attrs(self, graph_id, attrs, update=False)

Set attributes of a graph in the hierarchy.

Parameters

graph_idhashable

Id of the graph

set_node_relation(self, left_graph, right_graph, left_node, right_node)

Set relation for a particular node.

set_relation_attrs(self, left, right, attrs)

Set attributes of a relation in the hierarchy.

Parameters

lefthashable

Id of the left graph

righthashable

Id of the right graph

set_typing_attrs(self, source, target, attrs)

Set attributes of a typing in the hierarchy.

Parameters

sourcehashable

Id of the source graph

targethashable

Id of the target graph

shortest_path(self, source, target)

Shortest path from ‘source’ to ‘target’.

successors(self, node_id)

Return the set of successors.

typings(self, data=False)

Return a list of graph typing edges in the hierarchy.

class regraph.backends.neo4j.hierarchies.TypedNeo4jGraph(uri=None, user=None, password=None, driver=None, schema_graph=None, data_graph=None, typing=None, clear=False, graph_label='graph', typing_label='homomorphism', graph_edge_label='edge', graph_typing_label='typing', schema_node_label='type', data_node_label='node')

Class implementing two level hiearchy.

This class encapsulates neo4j.v1.GraphDatabase object. It provides an interface for accessing typed graphs accommodated in the Neo4j DB. Our system is assumed to consist of two graphs (the data graph) and (the schema graph) connected with a graph homomorphisms (defining typing of the data graph by the schema graph).

Attributes

_driverneo4j.v1.GraphDatabase

Driver providing connection to a Neo4j database

_graph_labelstr

_typing_labelstr

_graph_edge_labelstr

_graph_typing_labelstr

_schema_node_labelstr

Label of nodes inducing the schema graph.

_data_node_labelstr

Top level represents a data instance, while bottom level represents

a graphical schema.

Methods

add_data_edge(self, source, target[, attrs])	Add a data edge.
add_data_edge_attrs(self, source, target, attrs)	Add a data edge.
add_data_node(self, node_id, typing[, attrs])	Add a data node typed by the specified schema node.
add_data_node_attrs(self, node_id, attrs)	Add the attributes to a data node.
add_schema_edge(self, source, target[, attrs])	Add a schema node.
add_schema_node(self, node_id[, attrs])	Add a schema node.
add_schema_node_attrs(self, node_id, attrs)	Add the attributes of a schema node.
clone_schema_node(self, node, data_typing)	Clone a schema node.
find_data_matching(self, pattern[, …])	Find matching of a pattern in the data graph.
find_schema_matching(self, pattern[, nodes])	Find matching of a pattern in the schema graph.
get_data(self)	Get the data graph object.
get_data_edges(self[, data])	Get the edges of the data.
get_data_node(self, node_id)	Get the attributes of a data node.
get_data_nodes(self[, data])	Get to nodes of the data.
get_data_typing(self)	Get the typing of the data.
get_instances(self, schema_node)	Get all the instances of the schema node.
get_node_type(self, node_id)	Get the type of a node in the data.
get_schema(self)	Get the schema graph object.
get_schema_edges(self[, data])	Get the edges of the schema.
get_schema_node(self, node_id)	Get the attributes of a schema node.
get_schema_nodes(self[, data])	Get the nodes of the schema.
merge_data_nodes(self, node_list)	Merge data nodes.
relabel_data_node(self, node_id, new_node_id)	Relabel a node in the data.
relabel_schema_node(self, node_id, new_node_id)	Relabel a node in the schema.
remove_data_edge(self, source, target)	Remove a data edge.
remove_data_node(self, node_id)	Remove a data node.
remove_data_node_attrs(self, node_id, attrs)	Remove the attributes of a data node.
remove_schema_edge(self, source, target)	Remove a schema node.
remove_schema_edge_attrs(self, source, …)	Remove a schema node.
remove_schema_node(self, node_id)	Remove a schema node.
remove_schema_node_attrs(self, node_id, attrs)	Remove a schema node.
rewrite_data(self, rule, instance[, …])	Rewrite the data graph.
rewrite_schema(self, rule[, instance, …])	Rewrite the schema graph.

add_data_edge(self, source, target, attrs=None)

Add a data edge.

add_data_edge_attrs(self, source, target, attrs)

Add a data edge.

add_data_node(self, node_id, typing, attrs=None)

Add a data node typed by the specified schema node.

add_data_node_attrs(self, node_id, attrs)

Add the attributes to a data node.

add_schema_edge(self, source, target, attrs=None)

Add a schema node.

add_schema_node(self, node_id, attrs=None)

Add a schema node.

add_schema_node_attrs(self, node_id, attrs)

Add the attributes of a schema node.

clone_schema_node(self, node, data_typing)

Clone a schema node.

find_data_matching(self, pattern, pattern_typing=None, nodes=None)

Find matching of a pattern in the data graph.

Parameters

patternGraph object

A pattern to match

pattern_typingdict

A dictionary that specifies a typing of a pattern, keys of the dictionary – graph id that types a pattern, this graph should be among parents of the graph_id graph; values are mappings of nodes from pattern to the typing graph;

nodesiterable

Subset of nodes where matching should be performed

Returns

instanceslist of dict

List of matched instances

find_schema_matching(self, pattern, nodes=None)

Find matching of a pattern in the schema graph.

Parameters

patternGraph object

A pattern to match

pattern_typingdict

A dictionary that specifies a typing of a pattern, keys of the dictionary – graph id that types a pattern, this graph should be among parents of the graph_id graph; values are mappings of nodes from pattern to the typing graph;

nodesiterable

Subset of nodes where matching should be performed

Returns

instanceslist of dict

List of matched instances

get_data(self)

Get the data graph object.

get_data_edges(self, data=False)

Get the edges of the data.

get_data_node(self, node_id)

Get the attributes of a data node.

get_data_nodes(self, data=False)

Get to nodes of the data.

get_data_typing(self)

Get the typing of the data.

get_instances(self, schema_node)

Get all the instances of the schema node.

get_node_type(self, node_id)

Get the type of a node in the data.

get_schema(self)

Get the schema graph object.

get_schema_edges(self, data=False)

Get the edges of the schema.

get_schema_node(self, node_id)

Get the attributes of a schema node.

get_schema_nodes(self, data=False)

Get the nodes of the schema.

merge_data_nodes(self, node_list)

Merge data nodes.

relabel_data_node(self, node_id, new_node_id)

Relabel a node in the data.

relabel_schema_node(self, node_id, new_node_id)

Relabel a node in the schema.

remove_data_edge(self, source, target)

Remove a data edge.

remove_data_node(self, node_id)

Remove a data node.

remove_data_node_attrs(self, node_id, attrs)

Remove the attributes of a data node.

remove_schema_edge(self, source, target)

Remove a schema node.

remove_schema_edge_attrs(self, source, target, attrs)

Remove a schema node.

remove_schema_node(self, node_id)

Remove a schema node.

remove_schema_node_attrs(self, node_id, attrs)

Remove a schema node.

rewrite_data(self, rule, instance, rhs_typing=None, strict=False)

Rewrite the data graph.

Parameters

ruleregraph.rule.Rule

Rule object to apply

instancedict, optional

Dictionary containing an instance of the lhs of the rule in the data graph, by default, tries to construct the identity morphism of the nodes of the pattern

rhs_typingdict, optional

Dictionary containing typing of the rhs by the schema.

strictbool, optional

Rewriting is strict when propagation down is not allowed

Raises

HierarchyError

If the graph is not in the database

RewritingError

If the provided p and rhs typing are inconsistent

rewrite_schema(self, rule, instance=None, data_typing=None, strict=False)

Rewrite the schema graph.

Parameters

ruleregraph.rule.Rule

Rule object to apply

instancedict, optional

Dictionary containing an instance of the lhs of the rule in the schema graph, by default, tries to construct the identity morphism of the nodes of the pattern

data_typingdict, optional

Dictionary containing typing of data by the interface of the rule.

strictbool, optional

Rewriting is strict when propagation down is not allowed

Raises

HierarchyError

If the graph is not in the database

RewritingError

If the provided p and rhs typing are inconsistent