gammagl.data.HeteroGraph

class HeteroGraph(_mapping: Dict[str, Any] | None = None, **kwargs)

Bases: BaseGraph

A data object describing a heterogeneous graph, holding multiple node and/or edge types in disjunct storage objects. Storage objects can hold either node-level, link-level or graph-level attributes. In general, HeteroGraph tries to mimic the behaviour of a regular nested Python dictionary. In addition, it provides useful functionality for analyzing graph structures, and provides basic tensor functionalities.

>>> from gammagl.data import HeteroGraph
>>> import tensorlayerx as tlx
>>> data = HeteroGraph()
# Create two node types "paper" and "author" holding a feature matrix:
>>> num_papers = 6
>>> num_paper_features = 16
>>> num_authors = 3
>>> num_authors_features = 8
>>> data['paper'].x = tlx.random_uniform((num_papers, num_paper_features))
>>> data['author'].x =  tlx.random_uniform((num_authors, num_authors_features))
# Create an edge type "(author, writes, paper)" and building the
# graph connectivity:
>>> edge = tlx.convert_to_tensor([
... [0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2],
... [0, 1, 3, 5, 0, 1, 2, 3, 4, 5, 1, 2, 3, 4, 5]
... ])
>>> data['author', 'writes', 'paper'].edge_index = edge
>>> data['paper'].num_nodes
3
>>> data.num_nodes
9
>>> data['author', 'writes', 'paper'].num_edges
15
>>> data.num_edges
15

Note that there exists multiple ways to create a heterogeneous graph data, e.g.: * To initialize a node of type "paper" holding a node feature matrix x_paper named x:

>>> from gammagl.data import HeteroGraph
>>> data = HeteroGraph()
>>> data['paper'].x = x_paper
>>> data = HeteroGraph(paper={ 'x': x_paper })
>>> data = HeteroGraph({'paper': { 'x': x_paper }})

• To initialize an edge from source node type "author" to destination node type "paper" with relation type "writes" holding a graph connectivity matrix edge_index_author_paper named edge_index:

>>> data = HeteroGraph()
>>> data['author', 'writes', 'paper'].edge_index = edge_index_author_paper
>>> data = HeteroGraph(author__writes__paper={
    'edge_index': edge_index_author_paper
})
>>> data = HeteroGraph({
    ('author', 'writes', 'paper'):
    { 'edge_index': edge_index_author_paper }
})

property stores: List[BaseStorage]

Returns a list of all storages of the graph.

property node_types: List[str]

Returns a list of all node types of the graph.

property node_stores: List[NodeStorage]

Returns a list of all node storages of the graph.

property edge_types: List[Tuple[str, str, str]]

Returns a list of all edge types of the graph.

property edge_stores: List[EdgeStorage]

Returns a list of all edge storages of the graph.

node_items() → List[Tuple[str, NodeStorage]]

Returns a list of node type and node storage pairs.

edge_items() → List[Tuple[Tuple[str, str, str], EdgeStorage]]

Returns a list of edge type and edge storage pairs.

to_dict() → Dict[str, Any]

Returns a dictionary of stored key/value pairs.

to_namedtuple() → NamedTuple

Returns a NamedTuple of stored key/value pairs.

__cat_dim__(key: str, value: Any, store: NodeStorage | EdgeStorage | None = None, *args, **kwargs) → Any

Returns the dimension for which the value value of the attribute key will get concatenated when creating mini-batches using gammagl.loader.DataLoader.

Note

This method is for internal use only, and should only be overridden in case the mini-batch creation process is corrupted for a specific attribute.

__inc__(key: str, value: Any, store: NodeStorage | EdgeStorage | None = None, *args, **kwargs) → Any

Returns the incremental count to cumulatively increase the value value of the attribute key when creating mini-batches using gammagl.loader.DataLoader.

Note

This method is for internal use only, and should only be overridden in case the mini-batch creation process is corrupted for a specific attribute.

property num_nodes: int | None

Returns the number of nodes in the graph.

property num_node_features: Dict[str, int]

Returns the number of features per node type in the graph.

property num_features: Dict[str, int]

Returns the number of features per node type in the graph. Alias for num_node_features.

property num_edge_features: Dict[Tuple[str, str, str], int]

Returns the number of features per edge type in the graph.

is_undirected() → bool

Returns True if graph edges are undirected.

numpy(inplace=True)

Convert the Graph into numpy format. In numpy format, the graph edges and node features are in numpy.ndarray format. But you can’t use send and recv in numpy graph.

Parameters:

inplace (bool) – (Default True) Whether to convert the graph into numpy inplace.

metadata() → Tuple[List[str], List[Tuple[str, str, str]]]

Returns the heterogeneous meta-data, i.e. its node and edge types.

>>> data = HeteroGraph()
>>> data['paper'].x = ...
>>> data['author'].x = ...
>>> data['author', 'writes', 'paper'].edge_index = ...
>>> print(data.metadata())
(['paper', 'author'], [('author', 'writes', 'paper')])

collect(key: str) → Dict[str | Tuple[str, str, str], Any]

Collects the attribute key from all node and edge types.

>>> data = HeteroGraph()
>>> data['paper'].x = ...
>>> data['author'].x = ...
>>> print(data.collect('x'))
{ 'paper': ..., 'author': ...}

Note

This is equivalent to writing data.x_dict.

get_node_store(key: str) → NodeStorage

Gets the NodeStorage object of a particular node type key. If the storage is not present yet, will create a new gammagl.data.storage.NodeStorage object for the given node type.

>>> data = HeteroGraph()
>>> node_storage = data.get_node_store('paper')

get_edge_store(src: str, rel: str, dst: str) → EdgeStorage

Gets the EdgeStorage object of a particular edge type given by the tuple (src, rel, dst). If the storage is not present yet, will create a new gammagl.data.storage.EdgeStorage object for the given edge type.

>>> data = HeteroGraph()
>>> edge_storage = data.get_edge_store('author', 'writes', 'paper')

rename(name: str, new_name: str) → HeteroGraph

Renames the node type name to new_name in-place.

to_homogeneous(node_attrs: List[str] | None = None, edge_attrs: List[str] | None = None, add_node_type: bool = True, add_edge_type: bool = True) → Graph

Converts a HeteroGraph object to a homogeneous Graph object. By default, all features with same feature dimensionality across different types will be merged into a single representation, unless otherwise specified via the node_attrs and edge_attrs arguments.

Furthermore, attributes named node_type and edge_type will be added to the returned Graph object, denoting node-level and edge-level vectors holding the node and edge type as integers, respectively.

Parameters:

• node_attrs (list[str], optional) – The node features to combine across all node types. These node features need to be of the same feature dimensionality. If set to None, will automatically determine which node features to combine. (default: None)

• edge_attrs (list[str], optional) – The edge features to combine across all edge types. These edge features need to be of the same feature dimensionality. If set to None, will automatically determine which edge features to combine. (default: None)

• add_node_type (bool, optional) – If set to False, will not add the node-level vector node_type to the returned Graph object. (default: True)

• add_edge_type (bool, optional) – If set to False, will not add the edge-level vector edge_type to the returned Graph object. (default: True)