morphoclass.layers package

Module contents

Various layers used in neural networks in this package.

class morphoclass.layers.AttentionGlobalPool(n_features, attention_per_feature=False, save_attention=False)

Bases: torch.nn.modules.module.Module

A graph global pooling layer with attention.

Parameters

  • n_features (int) – The number of input features.

  • attention_per_feature (bool, default False) – If true then separate attention weights are learned for each feature.

  • save_attention (bool, default False.) – If true then the attention values generated upon the forward pass will be cached in the layer instance. Might be useful for debugging and explain-AI applications.

forward(x, batch_segmentation)

Compute the forward pass.

Parameters

  • x (torch.Tensor) – A batch of node features.

  • batch_segmentation (torch.Tensor) – A segmentation map for the node features. It’s a one-dimensional tensor with integer entries. Nodes with the same value in the segmentation map are considered to be from the same graph.

Returns

The pooled node features.

Return type

torch.Tensor

training: bool
class morphoclass.layers.BidirectionalBlock(c_in, c_out, K=5, normalization='sym', lambda_max=3.0, flow='target_to_source')

Bases: torch.nn.modules.module.Module

A parallel pair of ChebConv layers with opposite edge directions.

Parameters

  • c_in (int) – The number of input channels.

  • c_out (int) – The number of output channels.

  • K (int) – The maximal order of the Chebyshev polynomials

  • normalization ({"sym", "rw", None}) – The type of the graph Laplacian normalization. See ChebConv for more details.

  • lambda_max (float) – The value for replacing the highest graph Laplacian eigenvalue with. Eigenvalues of the graph Laplacian can only be reliably used for undirected graphs. This layer, however, makes most sense for directed graphs. In oder to still be able to normalize the graph Laplacian it was decided to use a fix value. Experiments show that this approach is effective.

  • flow ({"target_to_source", "source_to_target"}) – The direction of the message passing flow in the ChebConv layers. This is not exactly the same as transposing the adjacency matrix, probably due to the asymmetric way the normalization of the graph Laplacian works.

forward(x, edge_index, edge_weight=None)

Compute the forward pass.

Parameters

  • x (torch.Tensor) – A batch of node features.

  • edge_index (torch.Tensor) – A batch of adjacency matrices.

  • edge_weight (torch.Tensor) – A batch of edge weights.

Returns

x – The output node features.

Return type

torch.Tensor

training: bool
class morphoclass.layers.BidirectionalResBlock(c_in, c_out)

Bases: torch.nn.modules.module.Module

A BidirectionalBlock layer with a skip connection.

Parameters

  • c_in (int) – The number of input channels.

  • c_out (int) – The number of output channels.

forward(x, edge_index)

Perform the forward pass.

Parameters

  • x (torch.Tensor) – A batch of node features.

  • edge_index (torch.Tensor) – A batch of adjacency matrices.

Returns

x – The output node features.

Return type

torch.Tensor

training: bool
class morphoclass.layers.Cat

Bases: torch.nn.modules.module.Module

Concatenate the outputs of multiple parallel layers.

forward(x_list)

Perform the forward pass.

Parameters

x_list (iterable of torch.Tensor) – An iterable of outputs of a number of torch layers.

Returns

The concatenated input tensors.

Return type

torch.Tensor

training: bool
class morphoclass.layers.ChebConv(in_channels, out_channels, K, bias=True, flow='target_to_source', **kwargs)

Bases: torch_geometric.nn.conv.message_passing.MessagePassing

ChebConv layer based on torch_geometric.nn.conv.ChebConv.

This implementation corrects a few things that were not quite correct in the original implementation:

  1. Initialization set to glorot rather then uniform

  2. The default flow is set to target_to_source. This way the call self.propagate(…) computes M @ x rather than M.T @ x.

  3. The computation of the normalised Laplacian

These points might be implemented in future versions of PyG so that this implementation will become redundant.

Parameters

  • in_channels (int) – Size of each input sample.

  • out_channels (int) – Size of each output sample.

  • K (int) – Chebyshev filter size, i.e. number of hops \(K\).

  • bias (bool, default True) – If set to False, the layer will not learn an additive bias.

  • **kwargs – Additional arguments of torch_geometric.nn.conv.MessagePassing.

forward(x, edge_index, edge_weight=None, batch=None, lambda_max=3.0)

Compute the forward pass.

Parameters

  • x – The batched input node features.

  • edge_index – The batched input adjacency matrices.

  • edge_weight – The edge weights.

  • batch – Not used?

  • lambda_max (float) – The lambda_max value to use for the normalization of the graph Laplacian.

Returns

out – The output feature maps.

Return type

torch.Tensor

message(x_j, norm)

Perform a message passing step.

Parameters

  • x_j – Node features.

  • norm – The edge weights (?). See documentation of pytorch-geometric for more details.

Returns

The result of message passing.

Return type

torch.Tensor

static norm(edge_index, num_nodes, edge_weight, dtype=None, lambda_max=3.0)

Given the adjacency matrix calculate the normalised Laplacian.

Parameters

  • edge_index – The edge indices of the adjacency matrix.

  • num_nodes – The number of nodes in the graph, the adjacency matrix is of dimension (num_nodes, num_nodes).

  • edge_weight – The entries in the adjacency matrix index by edge_index

  • dtype – The dtype of the adjacency matrix.

  • lambda_max – The pre-computed maximal eigenvalue of the normalised Laplacian. Note that in the original PyG implementation this was implicitly assumed to have value 2.0.

Returns

The sparse form of the normalised graph Laplacian.

Return type

edge_index, norm

reset_parameters()

Initialize all weights with Glorot and set all biases to zero.

class morphoclass.layers.ChebConvSeparable(in_channels, out_channels, orders, bias=True, flow='target_to_source', **kwargs)

Bases: torch_geometric.nn.conv.message_passing.MessagePassing

Separable version of the ChebConv layer.

Two changes:

  1. Depth-separable convolutions

  2. Sparse specification of order parameter for polynomials (see the order parameter in __init__).

Parameters

  • in_channels (int) – Size of each input sample.

  • out_channels (int) – Size of each output sample.

  • orders (int or iterable of int) – The Chebyshev filter sizes. If an integer is provided then all sizes from 0 to (K-1) will be included, otherwise only those in the iterable.

  • bias (bool, default True) – If set to False, the layer will not learn an additive bias.

  • **kwargs – Additional arguments of torch_geometric.nn.conv.MessagePassing.

forward(x, edge_index, edge_weight=None, batch=None, lambda_max=3.0)

Compute the forward pass.

Parameters

  • x – The batched input node features.

  • edge_index – The batched input adjacency matrices.

  • edge_weight – The edge weights.

  • batch – Not used?

  • lambda_max (float) – The lambda_max value to use for the normalization of the graph Laplacian.

Returns

out – The output feature maps.

Return type

torch.Tensor

message(x_j, norm)

Perform a message passing step.

Parameters

  • x_j – Node features.

  • norm – The edge weights (?). See documentation of pytorch-geometric for more details.

Returns

The result of message passing.

Return type

torch.Tensor

static norm(edge_index, num_nodes, edge_weight, dtype=None, lambda_max=3.0)

Given the adjacency matrix calculate the normalised Laplacian.

Parameters

  • edge_index – the edge indices of the adjacency matrix

  • num_nodes – the number of nodes in the graph, the adjacency matrix is of dimension (`num_nodes, num_nodes)

  • edge_weight – the entries in the adjacency matrix index by edge_index

  • dtype – the dtype of the adjacency matrix

  • lambda_max – the pre-computed maximal eigenvalue of the normalised Laplacian. Note that in the original PyG implementation this was implicitly assumed to have value 2.0.

Returns

the sparse form of the normalised graph Laplacian

Return type

edge_index, norm

reset_parameters()

Initialize all weights with Glorot and set all biases to zero.

class morphoclass.layers.GaussianPointTransformer(out_features)

Bases: morphoclass.layers.perslay.PointTransformer

Applies Gaussian point transformation for persistence diagram embedding.

This transformation can be applied to persistence diagrams, and is implemented as described in [1]. Note that points are assumed to lie in a normalized diagram, i.e. coordinates should lie in the interval (0, 1).

Shapes:

  • input: [N, 2]. N is the total number of points in the batch (belonging to different persistence diagrams as specified by point_index), and 2 refers to the 2 coordinates of each point of each persistence diagram i.e. (birth_date, death_date).

  • point_index: [N]. N is the total number of points in the batch.

  • output: [N, Q]. N is the total number of points in the batch, and Q is the desired number of learnable sample points used in the transformation.

Parameters

out_features (int) – Size of each output sample, corresponding to the desired number of sample points.

sample_points

Sample points of the transformation, with shape [2, Q].

Type

tensor

sample_inverse_sigmas

Inverse standard deviations of the transformation, with shape [2, Q] since each of the 2 dimensions may have different sigma.

Type

tensor

Examples

>>> inp = torch.tensor([[0.2, 0.3], [0.1, 0.4], [0.6, 0.3], [0.2, 0.1],        [0.5, 0.2], [0.1, 0.3], [0.6, 0.2]])
>>> point_index = torch.tensor([0, 0, 0, 1, 1, 2, 2])
>>> m = GaussianPointTransformer(out_features=32)
>>> output = m(inp)
>>> print(inp.size())
torch.Size([7, 2])
>>> print(output.size())
torch.Size([7, 32])

References

[1] Carriere, Mathieu, et al. “PersLay: A Neural Network Layer for Persistence Diagrams and New Graph Topological Signatures.” stat 1050 (2019): 17.

extra_repr()

Get a string representation of layer parameters.

forward(input, point_index)

Perform the forward pass.

Parameters

  • input (torch.Tensor) – A batch of input data.

  • point_index (torch.Tensor) – A segmentation map for the samples in the batch.

Returns

The output tensor.

Return type

torch.Tensor

reset_parameters()

Randomly initialize the trainable parameters.

training: bool
class morphoclass.layers.PersLay(out_features, transformation='gaussian', operation='sum', weights='uniform')

Bases: torch.nn.modules.module.Module

Applies PersLay embedding layer.

This transformation can be applied to persistence diagrams, and is implemented as described in [1]. Note that points are assumed to lie in a normalized diagram, i.e. coordinates should lie in the interval (0, 1).

Shapes:

  • input : [N, 2]. N is the total number of points in the batch (belonging to different persistence diagrams as specified by point_index), and 2 refers to the 2 coordinates of each point of each persistence diagram i.e. (birth_date, death_date).

  • point_index : [N]. N is the total number of points in the batch.

  • output : [D, Q]. D is the number of different persistence diagrams in the batch, and Q is the desired number of learnable sample points used in the transformation.

Parameters

  • out_features (int) – Output size of the produced embedding.

  • transformation (str or nn.Module) – A point transformation, mapping each point of a persistence diagram to a vector. One of ‘gaussian’, ‘pointwise’, or a nn.Module.

  • operation (str) – A permutation invariant operation. One of ‘sum’, ‘mean’, ‘max’.

  • weights (str) – Approach to be used for the weights. One of ‘attention’ (learnable pointwise weights), ‘uniform’ (all weights set to 1), ‘grid’ (learnable weights on a 10x10 grid).

References

[1] Carriere, Mathieu, et al. “PersLay: A Neural Network Layer for Persistence Diagrams and New Graph Topological Signatures.” stat 1050 (2019): 17.

forward(input, point_index)

Perform the forward pass.

Parameters

  • input (torch.Tensor) – A batch of input data.

  • point_index (torch.Tensor) – A segmentation map for the samples in the batch.

Returns

The output tensor.

Return type

torch.Tensor

reset_parameters()

Randomly initialize trainable parameters.

training: bool
class morphoclass.layers.PointwisePointTransformer(out_features, hidden_features=32)

Bases: morphoclass.layers.perslay.PointTransformer

Applies point-wise point transformation for persistence diagram embedding.

Parameters

  • out_features (int) – Size of each output sample, corresponding to the desired number of sample points.

  • hidden_features (int) – The size of the hidden layer.

extra_repr()

Get a string representation of layer parameters.

forward(input, point_index)

Perform the forward pass.

Parameters

  • input (torch.Tensor) – A batch of input data.

  • point_index (torch.Tensor) – A segmentation map for the samples in the batch.

Returns

The output tensor.

Return type

torch.Tensor

training: bool
class morphoclass.layers.RunningStd(*shape, eps=1e-05)

Bases: torch.nn.modules.module.Module

Layer for normalization by the standard deviation.

This layer keeps track of the (biased) standard deviation of streaming data at training time. The data is normalized using this standard deviation both at training and at inference time.

Parameters

  • shape (int) – The shape of the input tensor.

  • eps (float, optional) – A value added to the standard deviation for numerical stability.

training: bool
class morphoclass.layers.TreeLSTMPool(x_size, h_size)

Bases: torch.nn.modules.module.Module

Child-Sum Tree LSTM Pooling Layer.

This class implements the Tree-LSTM as described in the reference. After traversing the whole tree the hidden state of the root node is returned as the result of the pooling.

Batched graphs can be processed as well. In that case the hidden states of all root nodes of all graphs are returned.

WARNING: this implementation is not at all optimized, and ideally one should be able to apply LSTM cells to multiple nodes in parallel. In principle all cells yielded by topologically_sorted can be processed in parallel, but the current implementation sequentially loops through them.

Parameters

  • x_size (int) – Dimension of the node embedding vector

  • h_size (int) – Dimension of the hidden state and the memory cell vectors

See also

https

//arxiv.org/abs/1503.00075

forward(x, edge_index)

Compute the forward pass.

Parameters

  • x – The batched node feature maps for pooling.

  • edge_index – The batched adjacency matrices.

Returns

h – The pooled features

Return type

torch.Tensor

static topologically_sorted(adj)

Topologically sort nodes in a given tree.

Topological sort mean that we start with all leaf nodes and yield them. Next all nodes for which all children have already been processed are yielded. This is repeated until all nodes have been seen.

At each iteration step a list of nodes is returned (an equivalent node mask to be precise) which are next in the topological order.

Parameters

adj (matrix_like) – The adjacency matrix describing the tree to be sorted

Yields

active_nodes (array_like of type bool) – Node mask for the current set of nodes in a sorted tree.

training: bool