topobench.transforms.liftings.graph2hypergraph.mapper_lifting module#

This module implements the MapperCover class.

class AddLaplacianEigenvectorPE(k, attr_name='laplacian_eigenvector_pe', is_undirected=False, **kwargs)#

Bases: BaseTransform

Adds the Laplacian eigenvector positional encoding from the “Benchmarking Graph Neural Networks” paper to the given graph (functional name: add_laplacian_eigenvector_pe).

Parameters:

  • k (int) – The number of non-trivial eigenvectors to consider.

  • attr_name (str, optional) – The attribute name of the data object to add positional encodings to. If set to None, will be concatenated to data.x. (default: "laplacian_eigenvector_pe")

  • is_undirected (bool, optional) – If set to True, this transform expects undirected graphs as input, and can hence speed up the computation of eigenvectors. (default: False)

  • **kwargs (optional) – Additional arguments of scipy.sparse.linalg.eigs() (when is_undirected is False) or scipy.sparse.linalg.eigsh() (when is_undirected is True).

__init__(k, attr_name='laplacian_eigenvector_pe', is_undirected=False, **kwargs)#
forward(data)#
SPARSE_THRESHOLD: int = 100#
class Compose(transforms)#

Bases: BaseTransform

Composes several transforms together.

Parameters:

transforms (List[Callable]) – List of transforms to compose.

__init__(transforms)#
forward(data)#
class Graph2HypergraphLifting(**kwargs)#

Bases: GraphLifting

Abstract class for lifting graphs to hypergraphs.

Parameters:
**kwargsoptional

Additional arguments for the class.

__init__(**kwargs)#
class MapperCover(resolution=10, gain=0.3)#

Bases: object

The MapperCover class computes the cover used in constructing the Mapper for the MapperLifting class.

Parameters:
resolutionint, optional

The number of intervals in the MapperCover. Default is 10.

gainfloat, optional

The proportion of overlap between consectutive intervals in the MapperCover and should be value between 0 and 0.5. Default is 0.3.

Attributes:
cover_intervals(resolution, 2) Tensor

A tensor containing each interval in the MapperCover.

__init__(resolution=10, gain=0.3)#
fit_transform(filtered_data)#

Construct an interval cover over filtered data.

Parameters:
filtered_data(n_sample, 1) Tensor

Filtered data to construct the Mapper cover.

Returns:
< (n_sample, resolution) boolean Tensor.

Mask which identifies which data points are in each cover set. Covers which are empty are removed so output tensor has at most size (n_sample, resolution).

class MapperLifting(filter_attr='laplacian', resolution=10, gain=0.3, filter_func=None, **kwargs)#

Bases: Graph2HypergraphLifting

Lift graphs to hypergraph domain using a Mapper construction for CC-pooling.

Parameters:
filter_attrstr, optional

Name of the filter functional to filter data to 1-dimensional subspace. The filter attribute can be “laplacican”, “svd”, “pca”, “feature_sum”, “position_sum”. You may also define your own filter_attr string if the filter_func parameter is defined. Default is “laplacian”.

resolutionint, optional

The number of intervals to construct the MapperCover. Default is 10.

gainfloat, optional

The percentage of overlap between consectutive intervals in MapperCover and should be a value between 0 and 0.5. Default is 0.3.

filter_funcobject, optional

Filter function used for Mapper construction. Self defined lambda function or transform to filter data. Function must output an (n_sample, 1) Tensor. If filter_func is not None, user must define filter_attr as a string not already listed above. Default is None.

**kwargsoptional

Additional arguments for the class.

Attributes:
filtered_datadict

Filtered data used to compute the Mapper lifting. Dictionary is of the form {filter_attr: filter_func(data)}.

cover(k, resolution) boolean Tensor

Mask computed from the MapperCover class to compute the Mapper lifting with k < n_sample.

clustersdict

Distinct connected components in each cover set computed after fitting the Mapper cover. Dictionary has integer keys and tuple values of the form (cover_set_i, nodes_in_cluster). Each cluster is a rank 2 hyperedge in the hypergraph.

Notes

The following are common filter functions which can be called with filter_attr.

1. “laplacian” : Converts data to an undirected graph and then applies the torch_geometric.transforms.AddLaplacianEigenvectorPE(k=1) transform and projects onto the smallest nonzero eigenvector.

2. “svd” : Applies the torch_geometric.transforms.SVDFeatureReduction(out_channels=1) transform to the node feature matrix (ie. torch_geometric.Data.data.x) to project data to a 1-dimensional subspace.

3. “feature_pca” : Applies torch.pca_lowrank(q=1) transform to node feature matrix (ie. torch_geometric.Data.data.x) and then projects to the 1st principal component.

4. “position_pca” : Applies torch.pca_lowrank(q=1) transform to node position matrix (ie. torch_geometric.Data.data.pos) and then projects to the 1st principal component.

5. “feature_sum” : Applies torch.sum(dim=1) to the node feature matrix in the graph (ie. torch_geometric.Data.data.x).

6. “position_sum” : Applies torch.sum(dim=1) to the node position matrix in the graph (ie. torch_geometric.Data.data.pos).

You may also construct your own filter_attr and filter_func:

7. “my_filter_attr” : Name of a self defined function my_filter_func = lambda data : my_filter_func(data) where my_filter_func(data) outputs a (n_sample, 1) Tensor.

References

[1]

Hajij, M., Zamzmi, G., Papamarkou, T., Miolane, N., Guzmán-Sáenz, A., Ramamurthy, K. N., et al. (2022). Topological deep learning: Going beyond graph data. arXiv preprint arXiv:2206.00606.

__init__(filter_attr='laplacian', resolution=10, gain=0.3, filter_func=None, **kwargs)#
lift_topology(data)#

Lift the topology of a graph to hypergraph domain by Mapper on Graphs.

Parameters:
datatorch_geometric.data.Data

The input data to be lifted.

Returns:
dict

The lifted topology.

class SVDFeatureReduction(out_channels)#

Bases: BaseTransform

Dimensionality reduction of node features via Singular Value Decomposition (SVD) (functional name: svd_feature_reduction).

Parameters:

out_channels (int) – The dimensionality of node features after reduction.

__init__(out_channels)#
forward(data)#
class ToUndirected(reduce='add', merge=True)#

Bases: BaseTransform

Converts a homogeneous or heterogeneous graph to an undirected graph such that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\) (functional name: to_undirected). In heterogeneous graphs, will add “reverse” connections for all existing edge types.

Parameters:

  • reduce (str, optional) – The reduce operation to use for merging edge features ("add", "mean", "min", "max", "mul"). (default: "add")

  • merge (bool, optional) – If set to False, will create reverse edge types for connections pointing to the same source and target node type. If set to True, reverse edges will be merged into the original relation. This option only has effects in HeteroData graph data. (default: True)

__init__(reduce='add', merge=True)#
forward(data)#