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
- reduce (callable) – A reduction function with signature
-
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
- reduction (callable) – A reduction function with signature
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
-
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)