gigl.transforms.add_positional_encodings

Classes

AddHeteroHopDistanceEncoding	Adds hop distance positional encoding as relative encoding (sparse CSR).
AddHeteroRandomWalkEncodings	Adds both random walk positional and structural encodings to the given

Module Contents

class gigl.transforms.add_positional_encodings.AddHeteroHopDistanceEncoding(h_max, attr_name='hop_distance', is_undirected=False)

Bases: torch_geometric.transforms.BaseTransform

Adds hop distance positional encoding as relative encoding (sparse CSR).

For each pair of nodes (vi, vj), computes the shortest path distance p(vi, vj). This captures structural proximity and can be used with a learnable embedding matrix:

h_hop(vi, vj) = W_hop · onehot(p(vi, vj))

Based on the approach from “Do Transformers Really Perform Bad for Graph Representation?” (Graphormer).

The output is a sparse CSR matrix where:

• Reachable pairs (i, j) within h_max hops have value = hop distance (1 to h_max)

• Unreachable pairs have value = 0 (not stored in sparse tensor)

• Self-loops (diagonal) are not stored (distance to self is implicitly 0)

CSR format is used for efficient row-based lookups during sequence building.

Parameters:

• h_max (int) – Maximum hop distance to consider. Distances > h_max are treated as unreachable (value 0 in sparse matrix). Set to 2-3 for 2-hop sampled subgraphs. Set to min(walk_length // 2, 10) for random walk sampled subgraphs.

• attr_name (str, optional) – The attribute name of the positional encoding. (default: "hop_distance")

• is_undirected (bool, optional) – If set to True, the graph is assumed to be undirected for distance computation. (default: False)

forward(data)

Parameters:

data (torch_geometric.data.HeteroData)

Return type:

torch_geometric.data.HeteroData

attr_name = 'hop_distance'

h_max

is_undirected = False

class gigl.transforms.add_positional_encodings.AddHeteroRandomWalkEncodings(walk_length, pe_attr_name='random_walk_pe', se_attr_name='random_walk_se', is_undirected=False, attach_to_x=False)

Bases: torch_geometric.transforms.BaseTransform

Adds both random walk positional and structural encodings to the given heterogeneous graph (functional name: add_hetero_random_walk_encodings).

This transform computes both encodings in a single pass over the random walk matrix, which is more efficient than applying separate transforms.

Positional Encoding (PE): For each node j, computes the sum of transition probabilities from all other nodes to j after k steps of a random walk, for k = 1, 2, …, walk_length. This captures how “reachable” or “central” a node is from the rest of the graph.

The encoding is the column sum of non-diagonal elements of the k-step random walk matrix:

PE[j, k] = Σ_{i≠j} (P^k)[i, j]

where P is the transition matrix. This measures the probability mass flowing into node j from all other nodes at step k.

Structural Encoding (SE): For each node, computes the probability of returning to itself after k steps of a random walk, for k = 1, 2, …, walk_length. This captures the local structural role of each node (e.g., cycles, clustering coefficient).

The encoding is the diagonal of the k-step random walk matrix:

SE[i, k] = (P^k)[i, i]

Based on the approach from “Graph Neural Networks with Learnable Structural and Positional Representations”.

Parameters:

• walk_length (int) – The number of random walk steps.

• pe_attr_name (str, optional) – The attribute name of the positional encoding. (default: "random_walk_pe")

• se_attr_name (str, optional) – The attribute name of the structural encoding. (default: "random_walk_se")

• is_undirected (bool, optional) – If set to True, the graph is assumed to be undirected, and the adjacency matrix will be made symmetric. (default: False)

• attach_to_x (bool, optional) – If set to True, the encodings are concatenated directly to data[node_type].x for each node type instead of being stored as separate attributes. PE is concatenated first, then SE. (default: False)

forward(data)

Parameters:

data (torch_geometric.data.HeteroData)

Return type:

torch_geometric.data.HeteroData

attach_to_x = False

is_undirected = False

pe_attr_name = 'random_walk_pe'

se_attr_name = 'random_walk_se'

walk_length