Graphs

Graph base class

class tflon.graph.graph.DiGraph(digraph, node_properties=[], edge_properties=[])

Wrapper for directed graph support. Casts digraph to undirected graph and provides edge_direction query.

Parameters:digraph (networkx.DiGraph) – A directed graph
edge_direction(u, v)

Return the direction of an edge relative to a query

Parameters:
  • u – Origin node index
  • v – Destination node index
Returns:

If u->v and v->u are both edges, returns 0

If only u->v is an edge, returns 1 If only v->u is an edge, returns -1

Return type:

char

Raise:
KeyError: If neither u->v nor v->u are edges
classmethod from_json(serialized)

Generate a networkx representation of a serialized json format graph

Parameters:serialized (str) – The serialized json representation
get_edges(u, v)

Get all edges between nodes u and v

Parameters:
  • u – Node index
  • v – Node index
Returns:

a generator yielding edges

Return type:

generator

multiplicity(u, v)

Count the number of edges (1 or 2) between adjacent vertices u and v

Parameters:
  • u – Origin node index
  • v – Destination node index
Returns:

The number of edges between u and v

Return type:

int

node_edges(u)

Get all the edges into or out of a given node

Parameters:u – Node index
Returns:A list of edges
Return type:list
port_number(u, e)

Assigns Digraph graph edge to one of four ports

class tflon.graph.graph.ViGraph(graph, parent_graph, node_properties=[], edge_properties=[], preserve_bonds=False, single_virtual_port=False)

Wrapper for virtual graph support.

Parameters:
  • graph (networkx.Graph) – An undirected graph
  • bonds (IndexMap, list-type) – Bonding edge indices
  • edge_properties (list-type) (optional) –
  • node_properties (list-type) (optional) –
bfs(roots)

Return a block-partitioned BFS of all subgraphs

Parameters:roots (list) – A list of starting nodes, one for each connected component
centroids()

Choose a random node from the center of each connected component (nodes with eccentricity equal to radius)

port_number(u, e)

Assigns Virtual graph edge to one of four ports: virtual/bonding +- tree/cross edge

Graph data pre-processors

tflon.graph.data.DenseEdgesToTableTransform

alias of tflon.graph.data.EdgesToNested

tflon.graph.data.DenseNodesToTableTransform

alias of tflon.graph.data.NodesToNested

class tflon.graph.data.DiGraphTable(data)

Convert a DataFrame containing serialized json format digraph structures to tflon.graph.DiGraph objects.

See documentation of tflon.graph.GraphTable for instantiation

class tflon.graph.data.EdgesToNested(graph_table, columns=None)
class tflon.graph.data.GatherTable(data)

Table type which manages indices for gather operations

class tflon.graph.data.GraphElementsToNested(graph_table, etype, columns=None)

Convert a 2-D tensor to a nested tensor, the number of entries in each nested list is decided by the corresponding number of graph elements

Parameters:graph_table (str) – The name of the table containing tflon.graph.Graph objects.
class tflon.graph.data.GraphTable(data, gtype=<class 'tflon.graph.graph.Graph'>)

Convert a DataFrame containing serialized json format graph structures to tflon.graph.Graph objects.

Parameters:data (pandas.DataFrame) – The input dataframe, with one column containing serialized json molecules
Keyword Arguments:
 convert (bool) – Whether to convert from json representation, if False expects dataframe of tflon.graph.Graph objects (default=True)
class tflon.graph.data.NodesToNested(graph_table, columns=None)
class tflon.graph.data.PoolTable(data)

Table type which manages pooling indices for graph convolution. A pool is a collection of indices which are used to gather from a tensor and then reduce to a tensor of the same size as the original.

class tflon.graph.data.RaggedIndexTable(data, dtype=<type 'numpy.float32'>)

Similar to GatherTable, but stores ragged arrays of indices, used for pulling tensor elements for updates on dynamic data structures

class tflon.graph.data.RaggedReduceTable(data, dtype=<type 'numpy.float32'>)

Similar to BlockReduceTable, but stores ragged arrays of indices, used for reducing tensor elements for updates on dynamic data structures

class tflon.graph.data.SparseRowSelector(data)

Table to convert row indices to a sparse binary matrix for dynamic partition operations.

class tflon.graph.data.SparseToDenseRowSelector(data)

Extends SparseRowSelector to convert a sparse row selection to a dense matrix prior to feed

Graph operations toolkit

class tflon.graph.toolkit.EdgeProperties(*args, **kwargs)
build(*args, **kwargs)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

class tflon.graph.toolkit.ElementProperties(*args, **kwargs)
build(graph_table, properties, etype, dtype=tf.float32)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call()

Instantiate ops executing the module. This is the implementation of __call__, invoked by the base class.

Returns:A tensor or sequence of tensors
class tflon.graph.toolkit.Encoder(*args, **kwargs)

Implementation of the set2set recurrent encoder network: https://arxiv.org/abs/1511.06391

This encoder is used to produce a graph-level encoding for predicting graph-level properties.

Parameters:
  • lstm_cell (tf.nn.rnn_cell.RNNCell) – An instance of a recursive unit used for encoding
  • weight_network (callable) – A function used to calculate attention values from node states
Other Parameters:
 

iterations (int) – The number of encoder steps to apply (default=10)

build(graph_table, lstm_cell, weight_network)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes)

Perform graph encoding

Parameters:nodes (tensor-like) – Node properties
Returns:Graph-level encodings
Return type:Tensor
class tflon.graph.toolkit.Neighborhood(*args, **kwargs)
build(graph_table)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes)

Instantiate ops executing the module. This is the implementation of __call__, invoked by the base class.

Returns:A tensor or sequence of tensors
class tflon.graph.toolkit.NodeProperties(*args, **kwargs)
build(*args, **kwargs)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

class tflon.graph.toolkit.NodeToEdge(*args, **kwargs)

Calculate edge representations from pairs of node states using an order invariant weave op.

Other Parameters:
 
  • activation (callable) – An activation function (default=tf.nn.relu)
  • width (int) – The number of output features, if -1, then output size = input size (default=-1)
build(graph_table)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes)
Parameters:nodes (tensor-like) – Node properties
Returns:edge properties
Return type:Tensor
class tflon.graph.toolkit.Pool(*args, **kwargs)

Graph pooling. Pools all nodes with a given depth (in number of edges traversed). Only nodes at the specified depth are pooled.

Parameters:

depth (int) – The depth to find nodes for pooling.

Keyword Arguments:
 
  • reduce (callable) – A reduction function with signature func(tensor, segments) (Default: tf.segment_sum) * tensor: N-D tensor for reduction * segments: 1-D tensor of segment indices
  • weighting (callable) – A weighting function with signature: func(tensor, segments) (Default: None) * tensor: N-D tensor for weight calculation * segments: 1-D tensor of segment indices
build(graph_table, depth, reduction=<function segment_sum>, weighting=None)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes)
Parameters:nodes (Tensor) – node properties of dimension N x …
Returns:same shape as nodes
Return type:Tensor
class tflon.graph.toolkit.Reduce(*args, **kwargs)

Graph reduce. Pools all nodes or edges within a given graph into a single output.

Keyword Arguments:
 
  • reduction (callable) – A reduction function with signature func(tensor, segments) (Default: tf.segment_sum) * tensor: N-D tensor for reduction * segments: 1-D tensor of segment indices
  • weighting (callable) – A weighting function with signature: func(tensor, segments) (Default: None) * tensor: N-D tensor for weight calculation * segments: 1-D tensor of segment indices
  • element_type – reduce over nodes or edges, defaults = node
batch_size

Get the expected output tensor size

build(graph_table, reduction=<function segment_sum>, weighting=None, element_type='node')

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes)
Parameters:nodes (Tensor) – node properties of dimension N x …
Returns:of shape G x … where G is the number of distinct graphs in the batch
Return type:Tensor
inverse(reduced)

Broadcast graph-level output of this op back to the node level

Parameters:reduced (Tensor) – The output of the reduction op
Returns:of shape N x … where N is the number of nodes in the original batch
Return type:Tensor

Graph recurrent networks (Wave)

class tflon.graph.grnn.DynamicPasses(*args, **kwargs)
build(graph_table)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(node_states, edge_states=None)

Instantiate ops executing the module. This is the implementation of __call__, invoked by the base class.

Returns:A tensor or sequence of tensors
class tflon.graph.grnn.GRNN(*args, **kwargs)

Graph recursive neural network (wave network).

Keyword Arguments:
 
  • num_ports (int) – Number of ports for mixgate (number of edge types * 2) (default=2)
  • edge_properties (bool) – Whether edges have properties (default=False)
Other Arguments:
dagger (callable): A function which returns node blocks, ancestors, and edge types for scheduling graph recursion state updates (default=Graph.bfs) rooter (callable): A function which returns the starting node for the dagger (default=Graph.centroids)
build(graph_table, num_ports=2, edge_properties=False)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(inputs=None, forward_cell=None, backward_cell=None, edge_properties=None)

Perform a single forward-backward pass of graph recursion

Parameters:
  • inputs (tensor-like) – The node properties/states
  • forward_cell (callable) – RNNCell to use for the forward pass, usually an instance of tf.nn.rnn_cell.RNNCell, or a callable accepting two arguments (inputs, states)
  • backward_cell (callable) – RNNCell to use for the backward pass, usually an instance of tf.nn.rnn_cell.RNNCell, or a callable accepting two arguments (inputs, states)
Keyword Arguments:
 

edge_properties (tensor-like) – Edge properties for the graph, if available (default=None)

Returns:

The updated node states

Return type:

Tensor

wrap_cell(*args, **kwargs)

Add a mix gate to an RNNCell

Parameters:
  • cell (RNNCell) – An RNNCell to wrap
  • **kwargs – Additional arguments passed to the GRNNCell constructor
Returns:

A graph recurrent cell

Return type:

GRNNCell

class tflon.graph.grnn.GRNNCell(*args, **kwargs)

An RNNCell wrapper which applies the mix gate to combine multiple states prior to a state update

Parameters:
  • rnn_cell (callable) – A cell matching the tf.nn.rnn_cell.RNNCell API, which is used to compute the state update
  • ports (int) – The number of mix gate ports
  • edge_properties (bool) – Whether edge properties are included in the mix gate calculation
Other Parameters:
 
  • activation (callable) – An activation function for the mix gate weighting functions (default=tf.nn.elu)
  • gate_types (list) – Types of mix gate weightings to include (default=[‘softmax’,’softsign’])
  • rnn_order (str) – Where to input mix gate to recurrent unit ‘mix_to_state’ or ‘mix_to_input’ (default=’mix_to_state’)
  • normalization (str) – Perform a normalization on mix gate ‘none’, ‘layer’, or ‘degree’ (default=’none’)
  • normalize_output (bool) – If True, perform layer normalization on the output of this recurrence (default=False)
build(rnn_cell, ports, edge_properties)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(states, degrees, block, nodes, ancestors, ports, redux, edges, edge_properties)

Compute a partial state update of a subset of nodes

Parameters:
  • states (tensor-like) – Current node states
  • degrees (tensor-like) – Node in and out degrees
  • block (tensor-like) – The subset of nodes to update
  • nodes (tensor-like) – A list of nodes at the arrow side of each update edge
  • ancestors (tensor-like) – A list of ancestor nodes of each update edge
  • ports (tensor-like) – A list of port types for each update edge
  • redux (tensor-like) – Reduction indices (update edges -> nodes)
  • edges (tensor-like) – Edge indices for each update edge
  • edge_properties (tensor-like) – Edge properties for each update edge
Returns:

updated node states

Return type:

Tensor

class tflon.graph.grnn.MiniGRUCell(*args, **kwargs)

A special GRUCell which does not have a read gate. This is commonly used in GRNNs because the read gate is redundant when a mix gate is used.

Parameters:state_size (int) – The width the node states
Keyword Arguments:
 activation (callable) – An activation function used for computing the output gate network
build(state_size, activation=<function elu>)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(inputs, state)

Perform a state update

Parameters:
  • inputs (tensor-like) – The current input values
  • states (tensor-like) – The current state values
Returns:

The output and state tensors, which are identical for a GRU

Return type:

tuple (Tensor, Tensor)

state_size

Get this RNNCell’s state size

zero_state(*args, **kwargs)

Create initial zero state with given batch size and type

Parameters:
  • batch_size (int) – The first dimension size of the state vector
  • dtype (tf.type) – The state vector dtype
class tflon.graph.grnn.MixGate(*args, **kwargs)

Module defining the special mix gate used to combine input states from multiple edges for form a message state

Parameters:
  • state_size (int) – The width of the node state
  • activation (callable) – An activation function for computing weightings
  • ports (int) – The number of ports
  • types (list) – The types of weightings to include, valid values include ‘softmax’, ‘softsign’, and ‘sum’
  • edge_properties (bool) – Whether edge properties will be provided
  • normalization (str) – The type of normalization to apply: ‘none’, ‘layer’, ‘degree’ (default=’none’)
build(state_size, activation, ports, types, edge_properties, normalization)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(states, degrees, nodes, ancestors, ports, redux, edges, edge_properties)

Combine input states to produce a state message for graph recursive node updates

Parameters:
  • states (tensor-like) – Node properties
  • degrees (tensor-like) – In and out degrees for each node
  • nodes (tensor-like) – Indices for the nodes being updated
  • ancestors (tensor-like) – Indices of ancestor nodes
  • ports (tensor-like) – Port types for each edge
  • redux (tensor-like) – Reduction indices
  • edges (tensor-like) – Edge indices
  • edge_properties (tensor-like) – Edge properties
Returns:

Message states for each node in the update

Return type:

Tensor

tflon.graph.grnn.eccentricity_exponential_distribution(graph, base=2.718281828459045)

Create a decaying distribution over nodes by eccentricity

This can be used to randomize the choice of root node for regularizing graph recursive neural networks.

Weave convolutional networks

class tflon.graph.weave.Weave(*args, **kwargs)

Implementation of the weave module from the paper Molecular Graph Convolutions: Moving Beyond Fingerprints (https://link.springer.com/article/10.1007/s10822-016-9938-8)

Other Parameters
edge_properties (bool): Whether to expect edge properties (default=False) digraphs (bool): Whether to expect digraphs (default=False; not supported) activation (callable): Activation function to use for weave ops (default=tf.nn.elu) batch_normalize (bool): Perform batch normalization (default=False) distance (int): The distance, in number of bonds, over which to perform pair weave ops (default=2) pair_width (int): Number of output pair features at each layer, required node_width (int): Number of output node features at each layer, required pair_hidden (int): Number of hidden features for pair weave, if None, same as pair_width (default=None) node_hidden (int): Number of hidden features for node weave, if None, same as node_width (default=None)
build(graph_table)

Instantiate variables required for this module. This is called by __init__, with *args and **kwargs passed from __init__ arguments list.

call(nodes, pairs=None)

Add a single weave module to the compute graph. Pair properties for the first weave should be generated with Weave.initial_pair_state

Parameters:
  • nodes (tensor-like) – Node properties
  • pairs (tensor-like) – Pair properties
Returns:

Updated node and pair properties

Return type:

tuple (Tensor, Tensor)

initial_pair_state(*args, **kwargs)

Create initial zero-state values for pairs. If edge properties are available, gather edge properties for adjacent pairs.

Keyword Arguments:
 edges (tensor-like) – Optional edge properties (default=None)
Returns:initial pair states
Return type:Tensor
outputs(nodes, pairs, include_edges=None)

Add a weave module to the compute graph without updating pair states.

Parameters:
  • nodes (tensor-like) – Node properties
  • pairs (tensor-like) – Pair properties
Keyword Arguments:
 

include_edges (bool) – Include an edge update and return the resulting edge properties (ignore non-adjacent pairs)

Returns:

output node states and (optional) edge states

Return type:

Tensor or tuple(Tensor, Tensor)