topobench.transforms.data_manipulations.hopse_ps_information module#

A transform that adds positional information to the graph.

class CombinedEncodings(encodings, parameters=None, **kwargs)#

Bases: BaseTransform

Combined Encodings transform.

Applies both Feature Encodings (FEs) and Positional/Structural Encodings (PSEs) to a graph. FEs are applied first since they use data.x as input, while PSEs only use graph structure.

Supported Feature Encodings (FEs):

“HKFE”: Heat Kernel Feature Encoding
“KHopFE”: K-hop Feature Encoding
“SheafConnLapPE”: Sheaf Connection Laplacian Positional Encoding

Supported Positional/Structural Encodings (PSEs):

“LapPE”: Laplacian Positional Encoding
“RWSE”: Random Walk Structural Encoding
“ElectrostaticPE”: Electrostatic Positional Encoding
“HKdiagSE”: Heat Kernel Diagonal Structural Encoding

Parameters:

encodingslist of str: List of encodings to apply. Can include any mix of FEs and PSEs. FEs will always be applied before PSEs regardless of order in list.
parametersdict, optional: Parameters for each encoding, keyed by encoding name.
**kwargsdict, optional: Additional keyword arguments.

__init__(encodings, parameters=None, **kwargs)#

forward(data)#

Apply the transform to the input data.

FEs are applied first (they use data.x as input), then PSEs (they only use graph structure).

Parameters:

datatorch_geometric.data.Data: The input data.

Returns:

torch_geometric.data.Data: The transformed data with added encodings.

class Data(x=None, edge_index=None, edge_attr=None, y=None, pos=None, time=None, **kwargs)#

Bases: BaseData, FeatureStore, GraphStore

A data object describing a homogeneous graph. The data object can hold node-level, link-level and graph-level attributes. In general, Data tries to mimic the behavior of a regular :python:`Python` dictionary. In addition, it provides useful functionality for analyzing graph structures, and provides basic PyTorch tensor functionalities. See here for the accompanying tutorial.

from torch_geometric.data import Data

data = Data(x=x, edge_index=edge_index, ...)

# Add additional arguments to `data`:
data.train_idx = torch.tensor([...], dtype=torch.long)
data.test_mask = torch.tensor([...], dtype=torch.bool)

# Analyzing the graph structure:
data.num_nodes
>>> 23

data.is_directed()
>>> False

# PyTorch tensor functionality:
data = data.pin_memory()
data = data.to('cuda:0', non_blocking=True)

Parameters:

x (torch.Tensor, optional) – Node feature matrix with shape [num_nodes, num_node_features]. (default: None)
edge_index (LongTensor, optional) – Graph connectivity in COO format with shape [2, num_edges]. (default: None)
edge_attr (torch.Tensor, optional) – Edge feature matrix with shape [num_edges, num_edge_features]. (default: None)
y (torch.Tensor, optional) – Graph-level or node-level ground-truth labels with arbitrary shape. (default: None)
pos (torch.Tensor, optional) – Node position matrix with shape [num_nodes, num_dimensions]. (default: None)
time (torch.Tensor, optional) – The timestamps for each event with shape [num_edges] or [num_nodes]. (default: None)
**kwargs (optional) – Additional attributes.

classmethod from_dict(mapping)#

Creates a Data object from a dictionary.

__init__(x=None, edge_index=None, edge_attr=None, y=None, pos=None, time=None, **kwargs)#

connected_components()#

Extracts connected components of the graph using a union-find algorithm. The components are returned as a list of Data objects, where each object represents a connected component of the graph.

data = Data()
data.x = torch.tensor([[1.0], [2.0], [3.0], [4.0]])
data.y = torch.tensor([[1.1], [2.1], [3.1], [4.1]])
data.edge_index = torch.tensor(
    [[0, 1, 2, 3], [1, 0, 3, 2]], dtype=torch.long
)

components = data.connected_components()
print(len(components))
>>> 2

print(components[0].x)
>>> Data(x=[2, 1], y=[2, 1], edge_index=[2, 2])

Returns:: A list of disconnected components.
Return type:: List[Data]

debug()#

edge_subgraph(subset)#

Returns the induced subgraph given by the edge indices subset. Will currently preserve all the nodes in the graph, even if they are isolated after subgraph computation.

Parameters:: subset (LongTensor or BoolTensor) – The edges to keep.

get_all_edge_attrs()#

Returns all registered edge attributes.

get_all_tensor_attrs()#

Obtains all feature attributes stored in Data.

is_edge_attr(key)#

Returns True if the object at key key denotes an edge-level tensor attribute.

is_node_attr(key)#

Returns True if the object at key key denotes a node-level tensor attribute.

stores_as(data)#

subgraph(subset)#

Returns the induced subgraph given by the node indices subset.

Parameters:: subset (LongTensor or BoolTensor) – The nodes to keep.

to_dict()#

Returns a dictionary of stored key/value pairs.

to_heterogeneous(node_type=None, edge_type=None, node_type_names=None, edge_type_names=None)#

Converts a Data object to a heterogeneous HeteroData object. For this, node and edge attributes are splitted according to the node-level and edge-level vectors node_type and edge_type, respectively. node_type_names and edge_type_names can be used to give meaningful node and edge type names, respectively. That is, the node_type 0 is given by node_type_names[0]. If the Data object was constructed via to_homogeneous(), the object can be reconstructed without any need to pass in additional arguments.

Parameters:

node_type (torch.Tensor, optional) – A node-level vector denoting the type of each node. (default: None)
edge_type (torch.Tensor, optional) – An edge-level vector denoting the type of each edge. (default: None)
node_type_names (List[str], optional) – The names of node types. (default: None)
edge_type_names (List[Tuple[str, str, str]], optional) – The names of edge types. (default: None)

to_namedtuple()#

Returns a NamedTuple of stored key/value pairs.

update(data)#

Updates the data object with the elements from another data object. Added elements will override existing ones (in case of duplicates).

validate(raise_on_error=True)#

Validates the correctness of the data.

property batch: Tensor | None#: !! processed by numpydoc !!

property edge_attr: Tensor | None#: !! processed by numpydoc !!

property edge_index: Tensor | None#: !! processed by numpydoc !!

property edge_stores: List[EdgeStorage]#: !! processed by numpydoc !!

property edge_weight: Tensor | None#: !! processed by numpydoc !!

property face: Tensor | None#: !! processed by numpydoc !!

property node_stores: List[NodeStorage]#: !! processed by numpydoc !!

property num_edge_features: int#: Returns the number of features per edge in the graph.

property num_edge_types: int#: Returns the number of edge types in the graph.

property num_faces: int | None#: Returns the number of faces in the mesh.

property num_features: int#: Returns the number of features per node in the graph. Alias for num_node_features.

property num_node_features: int#: Returns the number of features per node in the graph.

property num_node_types: int#: Returns the number of node types in the graph.

property num_nodes: int | None#: Returns the number of nodes in the graph.

Note

The number of nodes in the data object is automatically inferred in case node-level attributes are present, e.g., data.x. In some cases, however, a graph may only be given without any node-level attributes. :pyg:`PyG` then guesses the number of nodes according to edge_index.max().item() + 1. However, in case there exists isolated nodes, this number does not have to be correct which can result in unexpected behavior. Thus, we recommend to set the number of nodes in your data object explicitly via data.num_nodes = .... You will be given a warning that requests you to do so.

property pos: Tensor | None#: !! processed by numpydoc !!

property stores: List[BaseStorage]#: !! processed by numpydoc !!

property time: Tensor | None#: !! processed by numpydoc !!

property x: Tensor | None#: !! processed by numpydoc !!

property y: Tensor | int | float | None#: !! processed by numpydoc !!

class HOPSE_PE_Information(**kwargs)#

Bases: BaseTransform

A transform that uses a positional and structural information added to the graph.

Parameters:

**kwargsoptional: Parameters for the transform.

__init__(**kwargs)#

aggregate_inter_nbhd(x_out_per_route)#

Aggregate the outputs of the GNN for each rank.

While the GNN takes care of intra-nbhd aggregation, this will take care of inter-nbhd aggregation. Default: sum.

Parameters:

x_out_per_routedict: The outputs of the GNN for each route.

Returns:

dict: The aggregated outputs of the GNN for each rank.

forward(data)#

Apply the transform to the input data.

Parameters:

datatorch_geometric.data.Data: The input data.

Returns:

torch_geometric.data.Data: The transformed data.

forward_interank(src_rank, dst_rank, nbhd_cache, data)#

Forward for cells where src_rank!=dst_rank.

Parameters:

src_rankint: Source rank of the transmitting cell.
dst_rankint: Destination rank of the transmitting cell.
nbhd_cachedict: Cache of the neighbourhood information.
datatorch_geometric.data.Data: The input data.

Returns:

data: The data object with messages passed.

forward_intrarank(src_rank, route_index, data)#

Forward for cells where src_rank==dst_rank.

Parameters:

src_rankint: Source rank of the transmitting cell.
route_indexint: The index of this particular message passing route.
datatorch_geometric.data.Data: The input data.

Returns:

data: The data object with messages passed.

get_nbhd_cache(params)#

Cache the nbhd information into a dict for the complex at hand.

Parameters:

paramsdict: The parameters of the batch, containing the complex.

Returns:

dict: The neighborhood cache.

interrank_boundary_index(boundary_index, n_dst_nodes)#

Recover lifted graph.

Edge-to-node boundary relationships of a graph with n_nodes and n_edges can be represented as up-adjacency node relations. There are n_nodes+n_edges nodes in this lifted graph. Desgiend to work for regular (edge-to-node and face-to-edge) boundary relationships.

Parameters:

x_srctorch.tensor: Source node features. Shape [n_src_nodes, n_features]. Should represent edge or face features.
boundary_indexlist of lists or list of tensors: List boundary_index[0] stores node ids in the boundary of edge stored in boundary_index[1]. List boundary_index[1] stores list of edges.
n_dst_nodesint: Number of destination nodes.

Returns:

edge_indexlist of lists: The edge_index[0][i] and edge_index[1][i] are the two nodes of edge i.
edge_attrtensor: Edge features are given by feature of bounding node represnting an edge. Shape [n_edges, n_features].

interrank_expand(params, src_rank, dst_rank, nbhd_cache)#

Expand the complex into an interrank Hasse graph.

Parameters:

paramsdict: The parameters of the batch, containting the complex.
src_rankint: The source rank.
dst_rankint: The destination rank.
nbhd_cachedict: The neighborhood cache containing the expanded boundary index and edge attributes.

Returns:

torch_geometric.data.Data: The expanded batch of interrank Hasse graphs for this route.

intrarank_expand(params, src_rank, nbhd)#

Expand the complex into an intrarank Hasse graph.

Parameters:

paramsdict: The parameters of the batch, containting the complex.
src_rankint: The source rank.
nbhdstr: The neighborhood to use.

Returns:

torch_geometric.data.Data: The expanded batch of intrarank Hasse graphs for this route.

class SelectDestinationEncodings(encodings, **kwargs)#

Bases: BaseTransform

Select destination node encodings from expanded graph data.

Used in interrank message passing where we expand the graph to include both source and destination nodes, compute encodings, then select only the encodings for destination nodes.

Parameters:

encodingslist of str: List of encoding names to select (e.g., [‘HKFE’, ‘LapPE’]).
**kwargsdict, optional: Additional keyword arguments.

__init__(encodings, **kwargs)#

forward(data, n_dst_nodes)#

Select encodings for destination nodes only.

Parameters:

datatorch_geometric.data.Data: The input data with encodings computed on expanded graph.
n_dst_nodesint: Number of destination nodes (first n_dst_nodes rows to keep).

Returns:

torch_geometric.data.Data: Data with encodings selected for destination nodes only.

class dotdict#

Bases: dict

Dot.notation access to dictionary attributes.

get_routes_from_neighborhoods(neighborhoods)#

Get the routes from the neighborhoods.

Combination of src_rank, dst_rank. ex: [[0, 0], [1, 0], [1, 1], [1, 1], [2, 1]].

Parameters:

neighborhoodslist: List of neighborhoods of interest.

Returns:

list: List of routes.

interrank_boundary_index(x_src, boundary_index, n_dst_nodes)#

Recover lifted graph.

Parameters:

x_srctorch.tensor: Source node features. Shape [n_src_nodes, n_features]. Should represent edge or face features.
boundary_indexlist of lists or list of tensors: List boundary_index[0] stores node ids in the boundary of edge stored in boundary_index[1]. List boundary_index[1] stores list of edges.
n_dst_nodesint: Number of destination nodes.

Returns:

edge_indexlist of lists: The edge_index[0][i] and edge_index[1][i] are the two nodes of edge i.
edge_attrtensor: Edge features are given by feature of bounding node represnting an edge. Shape [n_edges, n_features].