StellarGraph API¶
Core¶
This contains the core objects used by the StellarGraph library.

class
stellargraph.core.
StellarGraphBase
(incoming_graph_data=None, **attr)[source]¶ StellarGraph class for undirected graph ML models. It stores both graph information from a NetworkX Graph object as well as features for machine learning.
To create a StellarGraph object ready for machine learning, at a minimum pass the graph structure to the StellarGraph as a NetworkX graph:
For undirected models:
Gs = StellarGraph(nx_graph)
For directed models:
Gs = StellarDiGraph(nx_graph)
To create a StellarGraph object with node features, supply the features as a numeric feature vector for each node.
To take the feature vectors from a node attribute in the original NetworkX graph, supply the attribute name to the
node_features
argument:Gs = StellarGraph(nx_graph, node_features="feature")
where the nx_graph contains nodes that have a “feature” attribute containing the feature vector for the node. All nodes of the same type must have the same size feature vectors.
Alternatively, supply the node features as Pandas DataFrame objects with the of the DataFrame set to the node IDs. For graphs with a single node type, you can supply the DataFrame object directly to StellarGraph:
node_data = pd.DataFrame( [feature_vector_1, feature_vector_2, ..], index=[node_id_1, node_id_2, ...]) Gs = StellarGraph(nx_graph, node_features=node_data)
For graphs with multiple node types, provide the node features as Pandas DataFrames for each type separately, as a dictionary by node type. This allows node features to have different sizes for each node type:
node_data = { node_type_1: pd.DataFrame(...), node_type_2: pd.DataFrame(...), } Gs = StellarGraph(nx_graph, node_features=node_data)
You can also supply the node feature vectors as an iterator of node_id and feature vector pairs, for graphs with single and multiple node types:
node_data = zip([node_id_1, node_id_2, ...], [feature_vector_1, feature_vector_2, ..]) Gs = StellarGraph(nx_graph, node_features=node_data)
Parameters:  node_type_name – str, optional (default=globals.TYPE_ATTR_NAME) This is the name for the node types that StellarGraph uses when processing heterogeneous graphs. StellarGraph will look for this attribute in the nodes of the graph to determine their type.
 edge_type_name – str, optional (default=globals.TYPE_ATTR_NAME) This is the name for the edge types that StellarGraph uses when processing heterogeneous graphs. StellarGraph will look for this attribute in the edges of the graph to determine their type.
 node_features – str, dict, list or DataFrame optional (default=None) This tells StellarGraph where to find the node feature information required by some graph models. These are expected to be a numeric feature vector for each node in the graph.

check_graph_for_ml
(features=True)[source]¶ Checks if all properties required for machine learning training/inference are set up. An error will be raised if the graph is not correctly setup.

create_graph_schema
(create_type_maps=True, nodes=None)[source]¶ Create graph schema in dict of dict format from current graph.
Note the assumption we make that there is only one edge of a particular edge type per node pair.
This means that specifying an edge by node0, node1 and edge type is unique.
Parameters:  create_type_maps (bool) – If True quick lookup of node/edge types is created in the schema. This can be slow.
 nodes (list) – A list of node IDs to use to build schema. This must represent all node types and all edge types in the graph. If specified, create_type_maps must be False. If not specified, all nodes and edges in the graph are used.
Returns: GraphSchema object.

get_feature_for_nodes
(nodes, node_type=None)[source]¶ Get the numeric feature vectors for the specified node or nodes. If the node type is not specified the node types will be found for all nodes. It is therefore important to supply the
node_type
for this method to be fast.Parameters:  n – (list or hashable) Node ID or list of node IDs
 node_type – (hashable) the type of the nodes.
Returns: Numpy array containing the node features for the requested nodes.

info
(show_attributes=True, sample=None)[source]¶ Return an information string summarizing information on the current graph. This includes node and edge type information and their attributes.
Note: This requires processing all nodes and edges and could take a long time for a large graph.
Parameters: sample (int) – To speed up the graph analysis, use only a random sample of this many nodes and edges. Returns: An information string.

node_feature_sizes
(node_types=None)[source]¶ Get the feature sizes for the specified node types.
Parameters: node_types – (list) A list of node types. If None all current node types will be used. Returns: A dictionary of node type and integer feature size.

node_types
¶ Get a list of all node types in the graph.
Returns: set of types

class
stellargraph.core.
GraphSchema
[source]¶ Class to encapsulate the schema information for a heterogeneous graph.
Typically this should be created from a StellarGraph object, using the
create_graph_schema()
method.
edge_index
(edge_type)[source]¶ Return edge type index from the type tuple
Parameters: index – Tuple of (node1_type, edge_type, node2_type) Returns: Numerical edge type index

get_edge_type
(edge, index=False)[source]¶  Return the type of the edge as a triple of
 (source_node_type, relation_type, dest_node_type).
The edge is specified as a standard NetworkX multigraph edge triple of (node_id_1, node_id_2, edge_key).
If the graph schema is undirected and there is an edge type for the edge (node_id_2, node_id_1, edge_key) then the edge type for this node will be returned permuted to match the node order.
Parameters:  edge – The edge ID from the original graph as a triple.
 index – Return a numeric type index if True, otherwise return the type triple.
Returns: A node type triple or index.

get_node_type
(node, index=False)[source]¶ Returns the type of the node specified either by node ID.
Parameters:  node – The node ID from the original graph
 index – Return a numeric type index if True, otherwise return the type name.
Returns: A node type name or index

is_of_edge_type
(edge, edge_type, index=False)[source]¶ Tests if an edge is of the given edge type.
The edge is specified as a standard NetworkX multigraph edge triple of (node_id_1, node_id_2, edge_key).
If the graph schema is undirected then the ordering of the nodes of the edge type doesn’t matter.
Parameters:  edge – The edge ID from the original graph as a triple.
 edge_type – The type of the edge as a tuple or EdgeType triple.
Returns: True if the edge is of the given type

node_index
(name)[source]¶ Return node type index from the type name
Parameters: index – name of the node type. Returns: Numerical node type index

sampling_layout
(head_node_types, num_samples)[source]¶ For a sampling scheme with a list of head node types and the number of samples per hop, return the map from the actual sample index to the adjacency list index.
Parameters:  head_node_types – A list of node types of the head nodes.
 num_samples – A list of integers that are the number of neighbours to sample at each hop.
Returns: A list containing, for each head node type, a list consisting of tuples of (node_type, sampling_index). The list matches the list given by the method type_adjacency_list(…) and can be used to reformat the samples given by SampledBreadthFirstWalk to that expected by the HinSAGE model.

sampling_tree
(head_node_types, n_hops)[source]¶ Returns a sampling tree for the specified head node types for neighbours up to n_hops away. A unique ID is created for each sampling node.
Parameters:  head_node_types – An iterable of the types of the head nodes
 n_hops – The number of hops away
Returns: A list of the form [(type_adjacency_index, node_type, [children]), …] where children are (type_adjacency_index, node_type, [children])

type_adjacency_list
(head_node_types, n_hops)[source]¶ Creates a BFS sampling tree as an adjacency list from head node types.
Each list element is a tuple of:
(node_type, [child_1, child_2, ...])
where
child_k
is an index pointing to the child of the current node.Note that the children are ordered by edge type.
Parameters:  head_node_types – Node types of head nodes.
 n_hops – How many hops to sample.
Returns: List of form
[ (node_type, [children]), ...]

Data¶
The data package contains classes and functions to read, process, and query graph data

class
stellargraph.data.
UniformRandomWalk
(graph, graph_schema=None, seed=None)[source]¶ Performs uniform random walks on the given graph

run
(nodes=None, n=None, length=None, seed=None)[source]¶ Perform a random walk starting from the root nodes.
Parameters:  nodes – <list> The root nodes as a list of node IDs
 n – <int> Total number of random walks per root node
 length – <int> Maximum length of each random walk
 seed – <int> Random number generator seed; default is None
Returns: <list> List of lists of nodes ids for each of the random walks


class
stellargraph.data.
BiasedRandomWalk
(graph, graph_schema=None, seed=None)[source]¶ Performs biased second order random walks (like those used in Node2Vec algorithm https://snap.stanford.edu/node2vec/) controlled by the values of two parameters p and q.

run
(nodes=None, n=None, p=1.0, q=1.0, length=None, seed=None, weighted=False, edge_weight_label='weight')[source]¶ Perform a random walk starting from the root nodes.
Parameters:  nodes – <list> The root nodes as a list of node IDs
 n – <int> Total number of random walks per root node
 p – <float> Defines probability, 1/p, of returning to source node
 q – <float> Defines probability, 1/q, for moving to a node away from the source node
 length – <int> Maximum length of each random walk
 seed – <int> Random number generator seed; default is None
 weighted – <False or True> Indicates whether the walk is unweighted or weighted
 edge_weight_label – <string> Label of the edge weight property.
Returns: <list> List of lists of nodes ids for each of the random walks


class
stellargraph.data.
UniformRandomMetaPathWalk
(graph, graph_schema=None, seed=None)[source]¶ For heterogeneous graphs, it performs uniform random walks based on given metapaths.

run
(nodes=None, n=None, length=None, metapaths=None, node_type_attribute='label', seed=None)[source]¶ Performs metapathdriven uniform random walks on heterogeneous graphs.
Parameters:  nodes – <list> The root nodes as a list of node IDs
 n – <int> Total number of random walks per root node
 length – <int> Maximum length of each random walk
 metapaths – <list> List of lists of node labels that specify a metapath schema, e.g.,
 'Paper', 'Author'], ['Author, 'Paper', 'Venue', 'Paper', 'Author']] specifies two metapath ([['Author',) –
 of length 3 and 5 respectively. (schemas) –
 node_type_attribute – <str> The node attribute name that stores the node’s type
 seed – <int> Random number generator seed; default is None
Returns: <list> List of lists of nodes ids for each of the random walks generated


class
stellargraph.data.
SampledBreadthFirstWalk
(graph, graph_schema=None, seed=None)[source]¶ Breadth First Walk that generates a sampled number of paths from a starting node. It can be used to extract a random subgraph starting from a set of initial nodes.

run
(nodes=None, n=1, n_size=None, seed=None)[source]¶ Performs a sampled breadthfirst walk starting from the root nodes.
Parameters:  nodes – <list> A list of root node ids such that from each node n BFWs will be generated up to the
 depth d. (given) –
 n – <int> Number of walks per node id.
 n_size – <list> The number of neighbouring nodes to expand at each depth of the walk. Sampling of
 with replacement is always used regardless of the node degree and number of neighbours (neighbours) –
 requested. –
 seed – <int> Random number generator seed; default is None
Returns: A list of lists such that each list element is a sequence of ids corresponding to a BFW.


class
stellargraph.data.
SampledHeterogeneousBreadthFirstWalk
(graph, graph_schema=None, seed=None)[source]¶ Breadth First Walk for heterogeneous graphs that generates a sampled number of paths from a starting node. It can be used to extract a random subgraph starting from a set of initial nodes.

run
(nodes=None, n=1, n_size=None, seed=None)[source]¶ Performs a sampled breadthfirst walk starting from the root nodes.
Parameters:  nodes – <list> A list of root node ids such that from each node n BFWs will be generated with the number of samples per hop specified in n_size.
 n – <int> Number of walks per node id.
 n_size – <list> The number of neighbouring nodes to expand at each depth of the walk. Sampling of
 with replacement is always used regardless of the node degree and number of neighbours (neighbours) –
 requested. –
 graph_schema – <GraphSchema> If None then the graph schema is extracted from self.graph
 seed – <int> Random number generator seed; default is None
Returns: A list of lists such that each list element is a sequence of ids corresponding to a sampled Heterogeneous BFW.


class
stellargraph.data.
UnsupervisedSampler
(G, nodes=None, length=2, number_of_walks=1, seed=None)[source]¶ The UnsupervisedSampler is responsible for sampling walks in the given graph and returning positive and negative samples w.r.t. those walks, on demand.
The positive samples are all the (target, context) pairs from the walks and the negative samples are contexts generated for each target based on a sampling distribtution.
Currently only uniform random walks are performed, other walk strategies (such as second order walks) will be enabled in the future.
Parameters: 
generator
(batch_size)[source]¶ This method yields a batch_size number of positive and negative samples from the graph. This method generates one walk at a time of a given length from each root node and returns the positive pairs from the walks and the same number of negative pairs from a global node sampling distribution.
Currently the global node sampling distribution for the negative pairs is the degree distribution to the 3/4 power. This is the same used in node2vec (https://snap.stanford.edu/node2vec/).
Parameters: batch_size (int) – The number of samples to generate for each batch. This must be an even number. Returns:  Tuple of lists of target/context pairs and labels – 0 for a negative and 1 for a
 positive pair: ([[target, context] ,… ], [label, …])


class
stellargraph.data.
EdgeSplitter
(g, g_master=None)[source]¶ Class for generating training and test data for link prediction in graphs.
The class requires as input a graph (in networkx format) and a percentage as a function of the total number of edges in the given graph of the number of positive and negative edges to sample. For heterogeneous graphs, the caller can also specify the type of edge and an edge property to split on. In the latter case, only a date property can be used and it must be in the format dd/mm/yyyy. A date to be used as a threshold value such that only edges that have date after the threshold must be given. This effects only the sampling of positive edges.
Negative edges are sampled at random by uniformly (for ‘global’ method) selecting two nodes in the graph and then checking if these edges are connected or not. If not, the pair of nodes is considered a negative sample. Otherwise, it is discarded and the process repeats. Alternatively, negative edges are sampled (for ‘local’ method) using DFS search at a distance from the source node (selected uniformly at random from all nodes in the graph) sampled according to a given set of probabilities.
Positive edges can be sampled so that when they are subsequently removed from the graph, the reduced graph is either guaranteed, or not guaranteed, to remain connected. In the former case, graph connectivity is maintained by first calculating the minimum spanning tree. The edges that belong to the minimum spanning tree are protected from removal, and therefore cannot be sampled for the training set. The edges that do not belong to the minimum spanning tree are then sampled uniformly at random, until the required number of positive edges have been sampled for the training set. In the latter case, when connectedness of the reduced graph is not guaranteed, positive edges are sampled uniformly at random from all the edges in the graph, regardless of whether they belong to the spanning tree (which is not calculated in this case).
Parameters:  g – <StellarGraph or networkx object> The graph to sample edges from.
 g_master – <StellarGraph or networkx object> The graph representing the original dataset and a superset of the graph g. If it is not None, then when positive and negative edges are sampled, care is taken to make sure that a true positive edge is not sampled as a negative edge.

train_test_split
(p=0.5, method='global', probs=None, keep_connected=False, edge_label=None, edge_attribute_label=None, edge_attribute_threshold=None, attribute_is_datetime=None, seed=None)[source]¶ Generates positive and negative edges and a graph that has the same nodes as the original but the positive edges removed. It can be used to generate data from homogeneous and heterogeneous graphs.
For heterogeneous graphs, positive and negative examples can be generated based on specified edge type or edge type and edge property given a threshold value for the latter.
Parameters:  p – <float> Percent of edges to be returned. It is calculated as a function of the total number of edges in the original graph. If the graph is heterogeneous, the percentage is calculated as a function of the total number of edges that satisfy the edge_label, edge_attribute_label and edge_attribute_threshold values given.
 method – <str> How negative edges are sampled. If ‘global’, then nodes are selected uniformly at random. If ‘local’ then the first nodes is sampled uniformly from all nodes in the graph, but the second node is chosen to be from the former’s local neighbourhood.
 probs – <list> list The probabilities for sampling a node that is khops from the source node, e.g., [0.25, 0.75] means that there is a 0.25 probability that the target node will be 1hope away from the source node and 0.75 that it will be 2 hops away from the source node. This only affects sampling of negative edges if method is set to ‘local’.
 keep_connected – <True or False> If True then when positive edges are removed care is taken that the reduced graph remains connected. If False, positive edges are removed without guaranteeing the connectivity of the reduced graph.
 edge_label – <str> If splitting based on edge type, then this parameter specifies the key for the type of edges to split on.
 edge_attribute_label – <str> The label for the edge attribute to split on.
 edge_attribute_threshold – <str> The threshold value applied to the edge attribute when sampling positive examples.
 attribute_is_datetime – <boolean> Specifies if edge attribute is datetime or not.
 seed – <int> seed for random number generator, positive int or 0
Returns: The reduced graph (positive edges removed) and the edge data as 2 numpy arrays, the first array of dimensionality Nx2 (where N is the number of edges) holding the node ids for the edges and the second of dimensionality Nx1 holding the edge labels, 0 for negative and 1 for positive examples.

stellargraph.data.
from_epgm
(epgm_location, dataset_name=None, directed=False)[source]¶ Imports a graph stored in EPGM format to a NetworkX object
Parameters: Returns: A NetworkX graph containing the data for the EPGMstored graph.

stellargraph.data.
load_dataset_BlogCatalog3
(location)[source]¶ This method loads the BlogCatalog3 network dataset (http://socialcomputing.asu.edu/datasets/BlogCatalog3) into a networkx undirected heterogeneous graph.
The graph has two types of nodes, ‘user’ and ‘group’, and two types of edges, ‘friend’ and ‘belongs’. The ‘friend’ edges connect two ‘user’ nodes and the ‘belongs’ edges connects ‘user’ and ‘group’ nodes.
The node and edge types are not included in the dataset that is a collection of node and group ids along with the list of edges in the graph.
Important note about the node IDs: The dataset uses integers for node ids. However, the integers from 1 to 39 are used as IDs for both users and groups. This would cause a confusion when constructing the networkx graph object. As a result, we convert all IDs to string and append the character ‘u’ to the integer ID for user nodes and the character ‘g’ to the integer ID for group nodes.
Parameters: location – <str> The directory where the dataset is located Returns: A networkx Graph object.
Generators¶
The mapper package contains classes and functions to map graph data to neural network inputs

class
stellargraph.mapper.
FullBatchNodeGenerator
(G, name=None, method='gcn', k=1, sparse=True, transform=None)[source]¶ A data generator for use with fullbatch models on homogeneous graphs, e.g., GCN, GAT, SGC. The supplied graph G should be a StellarGraph object that is ready for machine learning. Currently the model requires node features to be available for all nodes in the graph. Use the
flow()
method supplying the nodes and (optionally) targets to get an object that can be used as a Keras data generator.This generator will supply the features array and the adjacency matrix to a fullbatch Keras graph ML model. There is a choice to supply either a sparse adjacency matrix (the default) or a dense adjacency matrix, with the sparse argument.
For these algorithms the adjacency matrix requires preprocessing and the ‘method’ option should be specified with the correct preprocessing for each algorhtm. The options are as follows:
method='gcn'
Normalizes the adjacency matrix for the GCN algorithm. This implements the linearized convolution of Eq. 8 in [1].method='chebyshev'
: Implements the approximate spectral convolution operator by implementing the kth order Chebyshev expansion of Eq. 5 in [1].method='sgc'
: This replicates the kth order smoothed adjacency matrix to implement the Simplified Graph Convolusions of Eq. 8 in [2].method='self_loops'
ormethod='gat'
: Simply sets the diagonal elements of the adjacency matrix to one, effectively adding self loops. This is used by the GAT algorithm of [3].
[1] Kipf and Welling, 2017. [2] Wu et al. 2019. [3] Veličković et al., 2018
Example:
G_generator = FullBatchNodeGenerator(G) train_data_gen = G_generator.flow(node_ids, node_targets) # Fetch the data from train_data_gen, and feed into a Keras model: x_inputs, y_train = train_data_gen[0] model.fit(x=x_inputs, y=y_train) # Alternatively, use the generator itself with model.fit_generator: model.fit_generator(train_gen, epochs=num_epochs, ...)
 For more information, please see the GCN/GAT and SGC demos:
 https://github.com/stellargraph/stellargraph/blob/master/demos/
Parameters:  G (StellarGraphBase) – a machinelearning StellarGraphtype graph
 name (str) – an optional name of the generator
 method (str) – Method to preprocess adjacency matrix. One of ‘gcn’ (default), ‘chebyshev’,’sgc’, ‘self_loops’, or ‘none’.
 k (None or int) – This is the smoothing order for the ‘sgc’ method or the Chebyshev series order for the ‘chebyshev’ method. In both cases this should be positive integer.
 transform (callable) – an optional function to apply on features and adjacency matrix the function takes (features, Aadj) as arguments.
 sparse (bool) – If True (default) a sparse adjacency matrix is used, if False a dense adjacency matrix is used.

flow
(node_ids, targets=None)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied node ids and numeric targets.
Parameters:  node_ids – and iterable of node ids for the nodes of interest (e.g., training, validation, or test set nodes)
 targets – a 2D array of numeric node targets with shape (len(node_ids), target_size)
Returns: A NodeSequence object to use with GCN or GAT models in Keras methods
fit_generator()
,evaluate_generator()
, andpredict_generator()

class
stellargraph.mapper.
GraphSAGENodeGenerator
(G, batch_size, num_samples, schema=None, seed=None, name=None)[source]¶ A data generator for node prediction with Homogeneous GraphSAGE models
At minimum, supply the StellarGraph, the batch size, and the number of node samples for each layer of the GraphSAGE model.
The supplied graph should be a StellarGraph object that is ready for machine learning. Currently the model requires node features for all nodes in the graph.
Use the
flow()
method supplying the nodes and (optionally) targets to get an object that can be used as a Keras data generator.Example:
G_generator = GraphSAGENodeGenerator(G, 50, [10,10]) train_data_gen = G_generator.flow(train_node_ids, train_node_labels) test_data_gen = G_generator.flow(test_node_ids)
Parameters:  G (StellarGraph) – The machinelearning ready graph.
 batch_size (int) – Size of batch to return.
 num_samples (list) – The number of samples per layer (hop) to take.
 schema (GraphSchema) – [Optional] Graph schema for G.
 seed (int) – [Optional] Random seed for the node sampler.
 name (str or None) – Name of the generator (optional)

flow
(node_ids, targets=None, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied node ids and numeric targets.
The node IDs are the nodes to train or inference on: the embeddings calculated for these nodes are passed to the downstream task. These are a subset of the nodes in the graph.
The targets are an array of numeric targets corresponding to the supplied node_ids to be used by the downstream task. They should be given in the same order as the list of node IDs. If they are not specified (for example, for use in prediction), the targets will not be available to the downsteam task.
Note that the shuffle argument should be True for training and False for prediction.
Parameters:  node_ids – an iterable of node IDs
 targets – a 2D array of numeric targets with shape (len(node_ids), target_size)
 shuffle (bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A NodeSequence object to use with the GraphSAGE model in Keras methods
fit_generator
,evaluate_generator
, andpredict_generator

flow_from_dataframe
(node_targets, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied node ids and numeric targets.
Parameters:  node_targets – a Pandas DataFrame of numeric targets indexed by the node ID for that target.
 shuffle (bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A NodeSequence object to use with the GraphSAGE model in Keras methods
fit_generator
,evaluate_generator
, andpredict_generator

sample_features
(head_nodes, sampling_schema)[source]¶ Sample neighbours recursively from the head nodes, collect the features of the sampled nodes, and return these as a list of feature arrays for the GraphSAGE algorithm.
Parameters:  head_nodes – An iterable of head nodes to perform sampling on.
 sampling_schema – The sampling schema for the model
Returns: A list of the same length as
num_samples
of collected features from the sampled nodes of shape:(len(head_nodes), num_sampled_at_layer, feature_size)
where num_sampled_at_layer is the cumulative product of num_samples for that layer.

class
stellargraph.mapper.
GraphSAGELinkGenerator
(G, batch_size, num_samples, seed=None, name=None)[source]¶ A data generator for link prediction with Homogeneous GraphSAGE models
At minimum, supply the StellarGraph, the batch size, and the number of node samples for each layer of the GraphSAGE model.
The supplied graph should be a StellarGraph object that is ready for machine learning. Currently the model requires node features for all nodes in the graph.
Use the
flow()
method supplying the nodes and (optionally) targets, or an UnsupervisedSampler instance that generates node samples on demand, to get an object that can be used as a Keras data generator.Example:
G_generator = GraphSageLinkGenerator(G, 50, [10,10]) train_data_gen = G_generator.flow(edge_ids)
Parameters: 
flow
(link_ids, targets=None, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied edge IDs and numeric targets.
The edge IDs are the edges to train or inference on. They are expected to by tuples of (source_id, destination_id).
The targets are an array of numeric targets corresponding to the supplied link_ids to be used by the downstream task. They should be given in the same order as the list of link IDs. If they are not specified (for example, for use in prediction), the targets will not be available to the downsteam task.
Note that the shuffle argument should be True for training and False for prediction.
Parameters:  link_ids (list or UnsupervisedSampler) – an iterable of (src_id, dst_id) tuples specifying the edges or an UnsupervisedSampler object that has a generator method to generate samples on the fly.
 targets (optional, array) – a 2D array of numeric targets with shape (len(link_ids), target_size)
 shuffle (optional, bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A LinkSequence or OnDemandLinkSequence object to use with the GraphSAGE model methods
fit_generator()
,evaluate_generator()
, andpredict_generator()

sample_features
(head_links, sampling_schema)[source]¶ Sample neighbours recursively from the head nodes, collect the features of the sampled nodes, and return these as a list of feature arrays for the GraphSAGE algorithm.
Parameters:  head_links – An iterable of edges to perform sampling for.
 sampling_schema – The sampling schema for the model
Returns: A list of the same length as
num_samples
of collected features from the sampled nodes of shape:(len(head_nodes), num_sampled_at_layer, feature_size)
where num_sampled_at_layer is the cumulative product of num_samples for that layer.


class
stellargraph.mapper.
HinSAGENodeGenerator
(G, batch_size, num_samples, schema=None, seed=None, name=None)[source]¶ Kerascompatible data mapper for Heterogeneous GraphSAGE (HinSAGE)
At minimum, supply the StellarGraph, the batch size, and the number of node samples for each layer of the HinSAGE model.
The supplied graph should be a StellarGraph object that is ready for machine learning. Currently the model requires node features for all nodes in the graph.
Use the
flow()
method supplying the nodes and (optionally) targets to get an object that can be used as a Keras data generator.Note that the shuffle argument should be True for training and False for prediction.
Example:
G_generator = HinSAGENodeGenerator(G, 50, [10,10]) train_data_gen = G_generator.flow(train_node_ids, train_node_labels) test_data_gen = G_generator.flow(test_node_ids)

flow
(node_ids, targets=None, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied node ids and numeric targets.
The node IDs are the nodes to train or inference on: the embeddings calculated for these nodes are passed to the downstream task. These are a subset of the nodes in the graph.
The targets are an array of numeric targets corresponding to the supplied node_ids to be used by the downstream task. They should be given in the same order as the list of node IDs. If they are not specified (for example, for use in prediction), the targets will not be available to the downsteam task.
Note that the shuffle argument should be True for training and False for prediction.
Parameters:  node_ids (iterable) – The head node IDs
 targets (Numpy array) – a 2D array of numeric targets with shape
(len(node_ids), target_size)
 shuffle (bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A NodeSequence object to use with the GraphSAGE model in Keras methods fit_generator, evaluate_generator, and predict_generator.

flow_from_dataframe
(node_targets, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied node ids and numeric targets.
Note that the shuffle argument should be True for training and False for prediction.
Parameters:  node_targets (DataFrame) – Numeric targets indexed by the node ID for that target.
 shuffle (bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A NodeSequence object to use with the GraphSAGE model in Keras methods fit_generator, evaluate_generator, and predict_generator.

sample_features
(head_nodes, sampling_schema)[source]¶ Sample neighbours recursively from the head nodes, collect the features of the sampled nodes, and return these as a list of feature arrays for the GraphSAGE algorithm.
Parameters:  head_nodes – An iterable of head nodes to perform sampling on.
 sampling_schema – The node sampling schema for the HinSAGE model,
this is can be generated by the
GraphSchema
object.
Returns: A list of the same length as
num_samples
of collected features from the sampled nodes of shape:(len(head_nodes), num_sampled_at_layer, feature_size)
where num_sampled_at_layer is the cumulative product of num_samples for that layer.


class
stellargraph.mapper.
HinSAGELinkGenerator
(G, batch_size, num_samples, seed=None, name=None)[source]¶ A data generator for link prediction with Heterogeneous HinSAGE models
At minimum, supply the StellarGraph, the batch size, and the number of node samples for each layer of the GraphSAGE model.
The supplied graph should be a StellarGraph object that is ready for machine learning. Currently the model requires node features for all nodes in the graph.
Use the
flow()
method supplying the nodes and (optionally) targets to get an object that can be used as a Keras data generator.Note that you don’t need to pass link_type (target link type) to the link mapper, considering that:
 The mapper actually only cares about (src,dst) node types, and these can be inferred from the passed link ids (although this might be expensive, as it requires parsing the links ids passed  yet only once)
 It’s possible to do link prediction on a graph where that link type is completely removed from the graph (e.g., “same_as” links in ER)
Example:
G_generator = HinSAGELinkGenerator(G, 50, [10,10]) data_gen = G_generator.flow(edge_ids)
Parameters: 
flow
(link_ids, targets=None, shuffle=False)[source]¶ Creates a generator/sequence object for training or evaluation with the supplied edge IDs and numeric targets.
The edge IDs are the edges to train or inference on. They are expected to by tuples of (source_id, destination_id).
The targets are an array of numeric targets corresponding to the supplied link_ids to be used by the downstream task. They should be given in the same order as the list of link IDs. If they are not specified (for example, for use in prediction), the targets will not be available to the downsteam task.
Note that the shuffle argument should be True for training and False for prediction.
Parameters:  link_ids – an iterable of (src_id, dst_id) tuples specifying the edges.
 targets – a 2D array of numeric targets with shape
(len(link_ids), target_size)
 shuffle (bool) – If True the node_ids will be shuffled at each epoch, if False the node_ids will be processed in order.
Returns: A LinkSequence object to use with the GraphSAGE model methods
fit_generator()
,evaluate_generator()
, andpredict_generator()

sample_features
(head_links, sampling_schema)[source]¶ Sample neighbours recursively from the head nodes, collect the features of the sampled nodes, and return these as a list of feature arrays for the GraphSAGE algorithm.
Parameters:  head_links – An iterable of edges to perform sampling for.
 sampling_schema – The sampling schema for the model
Returns: A list of the same length as num_samples of collected features from the sampled nodes of shape:
(len(head_nodes), num_sampled_at_layer, feature_size)
where num_sampled_at_layer is the cumulative product of num_samples for that layer.
GraphSAGE model¶
GraphSAGE and compatible aggregator layers

class
stellargraph.layer.graphsage.
GraphSAGE
(layer_sizes, generator=None, n_samples=None, input_dim=None, aggregator=None, bias=True, dropout=0.0, normalize='l2')[source]¶ Implementation of the GraphSAGE algorithm of Hamilton et al. with Keras layers. see: http://snap.stanford.edu/graphsage/
The model minimally requires specification of the layer sizes as a list of ints corresponding to the feature dimensions for each hidden layer and a generator object.
Different neighbour node aggregators can also be specified with the
aggregator
argument, which should be the aggregator class, eitherMeanAggregator
,MeanPoolingAggregator
,MaxPoolingAggregator
, orAttentionalAggregator
.Parameters:  layer_sizes (list) – Hidden feature dimensions for each layer
 generator (Sequence) – A NodeSequence or LinkSequence. If specified the n_samples and input_dim will be taken from this object.
 n_samples (list) – (Optional: needs to be specified if no mapper is provided.) The number of samples per layer in the model.
 input_dim (int) – The dimensions of the node features used as input to the model.
 aggregator (class) – The GraphSAGE aggregator to use. Defaults to the MeanAggregator.
 bias (bool) – If True a bias vector is learnt for each layer in the GraphSAGE model
 dropout (float) – The dropout supplied to each layer in the GraphSAGE model.
 normalize (str or None) – The normalization used after each layer, defaults to L2 normalization.

build
(flatten_output=False)[source]¶ Builds a GraphSAGE model for node or link/node pair prediction, depending on the generator used to construct the model (whether it is a node or link/node pair generator).
Parameters: flatten_output – The GraphSAGE model will return a list of output tensors of form (batch_size, 1, feature_size). If this flag is true, the output will be of size (batch_size, 1*feature_size) Returns: (x_inp, x_out), where x_inp
is a list of Keras input tensors for the specified GraphSAGE model (either node or link/node pair model) andx_out
is the Keras tensor for the model output.Return type: tuple

link_model
(flatten_output=False)[source]¶ Builds a GraphSAGE model for link or node pair prediction
Returns: (x_inp, x_out) where x_inp
is a list of Keras input tensors for (src, dst) node pairs (where (src, dst) node inputs alternate), andx_out
is a list of output tensors for (src, dst) nodes in the node pairsReturn type: tuple

node_model
(flatten_output=False)[source]¶ Builds a GraphSAGE model for node prediction
Parameters: flatten_output – The GraphSAGE model will return an output tensor of form (batch_size, 1, feature_size). If this flag is true, the output will be of size (batch_size, 1*feature_size) Returns: (x_inp, x_out) where x_inp
is a list of Keras input tensors for the specified GraphSAGE model andx_out
is the Keras tensor for the GraphSAGE model output.Return type: tuple

class
stellargraph.layer.graphsage.
MeanAggregator
(output_dim: int = 0, bias: bool = False, act: Callable = 'relu', **kwargs)[source]¶ Mean Aggregator for GraphSAGE implemented with Keras base layer
Parameters:

class
stellargraph.layer.graphsage.
MeanPoolingAggregator
(*args, **kwargs)[source]¶ Mean Pooling Aggregator for GraphSAGE implemented with Keras base layer
Implements the aggregator of Eq. (3) in Hamilton et al. (2017), with max pooling replaced with mean pooling
Parameters:

class
stellargraph.layer.graphsage.
MaxPoolingAggregator
(*args, **kwargs)[source]¶ Max Pooling Aggregator for GraphSAGE implemented with Keras base layer
Implements the aggregator of Eq. (3) in Hamilton et al. (2017)
Parameters:

class
stellargraph.layer.graphsage.
AttentionalAggregator
(*args, **kwargs)[source]¶ Attentional Aggregator for GraphSAGE implemented with Keras base layer
Implements the aggregator of Veličković et al. “Graph Attention Networks” ICLR 2018
Parameters: 
build
(input_shape)[source]¶ Builds layer
Parameters: input_shape (list of list of int) – Shape of input tensors for self and neighbour features

call
(x, **kwargs)[source]¶ Apply aggregator on input tensors, x
Parameters: x (List[Tensor]) – Tensors giving self and neighbour features x[0]: self Tensor (batch_size, head size, feature_size) x[1]: neighbour Tensor (batch_size, head size, neighbours, feature_size) Returns: Keras Tensor representing the aggregated embeddings in the input.

HinSAGE model¶
Heterogeneous GraphSAGE and compatible aggregator layers

class
stellargraph.layer.hinsage.
HinSAGE
(layer_sizes, generator=None, n_samples=None, input_neighbor_tree=None, input_dim=None, aggregator=None, bias=True, dropout=0.0, normalize='l2')[source]¶ Implementation of the GraphSAGE algorithm extended for heterogeneous graphs with Keras layers.

build
(flatten_output=False)[source]¶ Builds a HinSAGE model for node or link/node pair prediction, depending on the generator used to construct the model (whether it is a node or link/node pair generator).
Parameters: flatten_output – The HinSAGE model will return a list of output tensors of form (batch_size, 1, feature_size). If this flag is true, the output will be of size (batch_size, 1*feature_size) Returns: (x_inp, x_out), where x_inp
is a list of Keras input tensors for the specified HinSAGE model (either node or link/node pair model) andx_out
is the Keras tensor for the model output.Return type: tuple


class
stellargraph.layer.hinsage.
MeanHinAggregator
(output_dim: int = 0, bias: bool = False, act: Union[Callable, AnyStr] = 'relu', **kwargs)[source]¶ Mean Aggregator for HinSAGE implemented with Keras base layer
Parameters: 
build
(input_shape)[source]¶ Builds layer
Parameters: input_shape (list of list of int) – Shape of input per neighbour type.

call
(x, **kwargs)[source]¶ Apply MeanAggregation on input tensors, x
Parameters: x – List of Keras Tensors with the following elements
 x[0]: tensor of self features shape (n_batch, n_head, n_feat)
 x[1+r]: tensors of neighbour features each of shape (n_batch, n_head, n_neighbour[r], n_feat[r])
Returns: Keras Tensor representing the aggregated embeddings in the input.

compute_output_shape
(input_shape)[source]¶ Computes the output shape of the layer. Assumes that the layer will be built to match that input shape provided.
Parameters: input_shape (tuple of ints) – Shape tuples can include None for free dimensions, instead of an integer. Returns: An input shape tuple.

GCN model¶

class
stellargraph.layer.gcn.
GCN
(layer_sizes, activations, generator, bias=True, dropout=0.0, kernel_regularizer=None)[source]¶ A stack of Graph Convolutional layers that implement a graph convolution network model as in https://arxiv.org/abs/1609.02907
The model minimally requires specification of the layer sizes as a list of ints corresponding to the feature dimensions for each hidden layer, activation functions for each hidden layers, and a generator object.
To use this class as a Keras model, the features and preprocessed adjacency matrix should be supplied using the
FullBatchNodeGenerator
class. To have the appropriate preprocessing the generator object should be instantiated as follows:generator = FullBatchNodeGenerator(G, method="gcn")
Note that currently the GCN class is compatible with both sparse and dense adjacency matrices and the
FullBatchNodeGenerator
will default to sparse.For more details, please see the GCN demo notebook: demos/nodeclassification/gat/gcncoranodeclassificationexample.ipynb
Notes
 The inputs are tensors with a batch dimension of 1. These are provided by the
FullBatchNodeGenerator
object.  This assumes that the normalized Lapalacian matrix is provided as input to
Keras methods. When using the
FullBatchNodeGenerator
specify themethod='gcn'
argument to do this preprocessing.  The nodes provided to the
FullBatchNodeGenerator.flow
method are used by the final layer to select the predictions for those nodes in order. However, the intermediate layers before the final layer order the nodes in the same way as the adjacency matrix.
Examples
Creating a GCN node classification model from an existing
StellarGraph
objectG
:generator = FullBatchNodeGenerator(G, method="gcn") gcn = GCN( layer_sizes=[32, 4], activations=["elu","softmax"], generator=generator, dropout=0.5 ) x_inp, predictions = gcn.node_model()
Parameters:  layer_sizes (list of int) – list of output sizes of GCN layers in the stack
 activations (list of str) – list of activations applied to each layer’s output
 generator (FullBatchNodeGenerator) – an instance of FullBatchNodeGenerator class constructed on the graph of interest
 bias (bool) – toggles an optional bias in GCN layers
 dropout (float) – dropout rate applied to input features of each GCN layer
 kernel_regularizer (str) – normalization applied to the kernels of GCN layers
 The inputs are tensors with a batch dimension of 1. These are provided by the

class
stellargraph.layer.gcn.
GraphConvolution
(units, activation=None, use_bias=True, final_layer=False, kernel_initializer='glorot_uniform', bias_initializer='zeros', kernel_regularizer=None, bias_regularizer=None, activity_regularizer=None, kernel_constraint=None, bias_constraint=None, **kwargs)[source]¶ Graph Convolution (GCN) Keras layer. The implementation is based on the kerasgcn github repo https://github.com/tkipf/kerasgcn.
Original paper: SemiSupervised Classification with Graph Convolutional Networks. Thomas N. Kipf, Max Welling, International Conference on Learning Representations (ICLR), 2017 https://github.com/tkipf/gcn
Notes
 The inputs are tensors with a batch dimension of 1: Keras requires this batch dimension, and for fullbatch methods we only have a single “batch”.
 There are three inputs required, the node features, the output indices (the nodes that are to be selected in the final layer) and the normalized graph Laplacian matrix
 This class assumes that the normalized Laplacian matrix is passed as input to the Keras methods.
 The output indices are used when
final_layer=True
and the returned outputs are the finallayer features for the nodes indexed by output indices.  If
final_layer=False
all the node features are output in the same ordering as given by the adjacency matrix.
Parameters:  units (int) – dimensionality of output feature vectors
 activation (str) – nonlinear activation applied to layer’s output to obtain output features
 use_bias (bool) – toggles an optional bias
 final_layer (bool) – If False the layer returns output for all nodes, if True it returns the subset specified by the indices passed to it.
 kernel_initializer (str) – name of layer bias f the initializer for kernel parameters (weights)
 bias_initializer (str) – name of the initializer for bias
 attn_kernel_initializer (str) – name of the initializer for attention kernel
 kernel_regularizer (str) – name of regularizer to be applied to layer kernel. Must be a Keras regularizer.
 bias_regularizer (str) – name of regularizer to be applied to layer bias. Must be a Keras regularizer.
 activity_regularizer (str) – not used in the current implementation
 kernel_constraint (str) – constraint applied to layer’s kernel
 bias_constraint (str) – constraint applied to layer’s bias

build
(input_shapes)[source]¶ Builds the layer
Parameters: input_shape (list of int) – shapes of the layer’s inputs (node features and adjacency matrix)

call
(inputs)[source]¶ Applies the layer.
Parameters: inputs (list) – a list of 3 input tensors that includes node features (size 1 x N x F), output indices (size 1 x M) graph adjacency matrix (size N x N), where N is the number of nodes in the graph, and F is the dimensionality of node features. Returns: Keras Tensor that represents the output of the layer.
GAT model¶
Definition of Graph Attention Network (GAT) layer, and GAT class that is a stack of GAT layers

class
stellargraph.layer.graph_attention.
GAT
(layer_sizes, activations, attn_heads=1, attn_heads_reduction=None, bias=True, in_dropout=0.0, attn_dropout=0.0, normalize=None, generator=None)[source]¶ A stack of Graph Attention (GAT) layers with aggregation of multiple attention heads, Eqs 56 of the GAT paper https://arxiv.org/abs/1710.10903
To use this class as a Keras model, the features and preprocessed adjacency matrix should be supplied using the
FullBatchNodeGenerator
class. To have the appropriate preprocessing the generator object should be instantiated as follows:generator = FullBatchNodeGenerator(G, sparse=False, method="gat")
For more details, please see the GAT demo notebook: demos/nodeclassification/gat/gatcoranodeclassificationexample.ipynb
Examples
Creating a GAT node classification model from an existing
StellarGraph
object G:generator = FullBatchNodeGenerator(G, method="gat") gat = GAT( layer_sizes=[8, 4], activations=["elu","softmax"], attn_heads=8, generator=generator, in_dropout=0.5, attn_dropout=0.5, ) x_inp, predictions = gat.node_model()
Notes
 The inputs are tensors with a batch dimension of 1. These are provided by the
FullBatchNodeGenerator
object.  This does not add self loops to the adjacency matrix, you should preprocess
the adjacency matrix to add selfloops, using the
method='gat'
argument of theFullBatchNodeGenerator
.  The nodes provided to the
FullBatchNodeGenerator.flow
method are used by the final layer to select the predictions for those nodes in order. However, the intermediate layers before the final layer order the nodes in the same way as the adjacency matrix.
Parameters:  layer_sizes (list of int) – list of output sizes of GAT layers in the stack. The length of this list defines the number of GraphAttention layers in the stack.
 attn_heads (int or list of int) –
number of attention heads in GraphAttention layers. The options are:
 a single integer: the passed value of
attn_heads
will be applied to all GraphAttention layers in the stack, except the last layer (for which the number of attn_heads will be set to 1).  a list of integers: elements of the list define the number of attention heads in the corresponding layers in the stack.
 a single integer: the passed value of
 attn_heads_reduction (list of str or None) – reductions applied to output features of each attention head, for all layers in the stack. Valid entries in the list are {‘concat’, ‘average’}. If None is passed, the default reductions are applied: ‘concat’ reduction to all layers in the stack except the final layer, ‘average’ reduction to the last layer (Eqs. 56 of the GAT paper).
 activations (list of str) – list of activations applied to each layer’s output
 bias (bool) – toggles an optional bias in GAT layers
 in_dropout (float) – dropout rate applied to input features of each GAT layer
 attn_dropout (float) – dropout rate applied to attention maps
 normalize (str or None) – normalization applied to the final output features of the GAT layers stack. Default is None.
 generator (FullBatchNodeGenerator) – an instance of FullBatchNodeGenerator class constructed on the graph of interest

node_model
(num_nodes=None, feature_size=None)[source]¶ Builds a GCN model for node prediction
Returns: (x_inp, x_out), where x_inp is a list of two Keras input tensors for the GCN model (containing node features and graph laplacian), and x_out is a Keras tensor for the GCN model output. Return type: tuple
 The inputs are tensors with a batch dimension of 1. These are provided by the

class
stellargraph.layer.graph_attention.
GraphAttention
(units, attn_heads=1, attn_heads_reduction='concat', in_dropout_rate=0.0, attn_dropout_rate=0.0, activation='relu', use_bias=True, final_layer=False, kernel_initializer='glorot_uniform', bias_initializer='zeros', attn_kernel_initializer='glorot_uniform', kernel_regularizer=None, bias_regularizer=None, attn_kernel_regularizer=None, activity_regularizer=None, kernel_constraint=None, bias_constraint=None, attn_kernel_constraint=None, **kwargs)[source]¶ Graph Attention (GAT) layer. The base implementation is taken from https://github.com/danielegrattarola/kerasgat, with some modifications added for ease of use.
Based on the original paper: Graph Attention Networks. P. Velickovic et al. ICLR 2018 https://arxiv.org/abs/1710.10903
Notes
 The inputs are tensors with a batch dimension of 1: Keras requires this batch dimension, and for fullbatch methods we only have a single “batch”.
 There are three inputs required, the node features, the output indices (the nodes that are to be selected in the final layer) and the graph adjacency matrix
 This does not add self loops to the adjacency matrix, you should preprocess the adjacency matrix to add selfloops
 The output indices are used when
final_layer=True
and the returned outputs are the finallayer features for the nodes indexed by output indices.  If
final_layer=False
all the node features are output in the same ordering as given by the adjacency matrix.
Parameters:  F_out (int) – dimensionality of output feature vectors
 attn_heads (int or list of int) – number of attention heads
 attn_heads_reduction (str) – reduction applied to output features of each attention head, ‘concat’ or ‘average’. ‘Average’ should be applied in the final prediction layer of the model (Eq. 6 of the paper).
 in_dropout_rate (float) – dropout rate applied to features
 attn_dropout_rate (float) – dropout rate applied to attention coefficients
 activation (str) – nonlinear activation applied to layer’s output to obtain output features (eq. 4 of the GAT paper)
 final_layer (bool) – If False the layer returns output for all nodes, if True it returns the subset specified by the indices passed to it.
 use_bias (bool) – toggles an optional bias
 kernel_initializer (str) – name of layer bias f the initializer for kernel parameters (weights)
 bias_initializer (str) – name of the initializer for bias
 attn_kernel_initializer (str) – name of the initializer for attention kernel
 kernel_regularizer (str) – name of regularizer to be applied to layer kernel. Must be a Keras regularizer.
 bias_regularizer (str) – name of regularizer to be applied to layer bias. Must be a Keras regularizer.
 attn_kernel_regularizer (str) – name of regularizer to be applied to attention kernel. Must be a Keras regularizer.
 activity_regularizer (str) – not used in the current implementation
 kernel_constraint (str) – constraint applied to layer’s kernel. Must be a Keras constraint https://keras.io/constraints/
 bias_constraint (str) – constraint applied to layer’s bias. Must be a Keras constraint https://keras.io/constraints/
 attn_kernel_constraint (str) – constraint applied to attention kernel. Must be a Keras constraint https://keras.io/constraints/
 **kwargs – optional keyword arguments supplied to the Keras
Layer

build
(input_shapes)[source]¶ Builds the layer
Parameters: input_shape (list of int) – shapes of the layer’s inputs (node features and adjacency matrix)

call
(inputs)[source]¶ Creates the layer as a Keras graph.
Note that the inputs are tensors with a batch dimension of 1: Keras requires this batch dimension, and for fullbatch methods we only have a single “batch”.
There are three inputs required, the node features, the output indices (the nodes that are to be selected in the final layer) and the graph adjacency matrix
Notes
This does not add self loops to the adjacency matrix. The output indices are only used when
final_layer=True
Parameters:  inputs (list) – list of inputs with 3 items:
 features (node) –
 indices (output) –
 adjacency matrix (graph) –
 N is the number of nodes in the graph, (where) – F is the dimensionality of node features M is the number of output nodes

class
stellargraph.layer.graph_attention.
GraphAttentionSparse
(*args, **kwargs)[source]¶ Graph Attention (GAT) layer, base implementation taken from https://github.com/danielegrattarola/kerasgat, some modifications added for ease of use.
Based on the original paper: Graph Attention Networks. P. Velickovic et al. ICLR 2018 https://arxiv.org/abs/1710.10903
Notes
 The inputs are tensors with a batch dimension of 1: Keras requires this batch dimension, and for fullbatch methods we only have a single “batch”.
 There are three inputs required, the node features, the output indices (the nodes that are to be selected in the final layer), and the graph adjacency matrix
 This does not add self loops to the adjacency matrix, you should preprocess the adjacency matrix to add selfloops
 The output indices are used when final_layer=True and the returned outputs are the finallayer features for the nodes indexed by output indices.
 If final_layer=False all the node features are output in the same ordering as given by the adjacency matrix.
Parameters:  F_out (int) – dimensionality of output feature vectors
 attn_heads (int or list of int) – number of attention heads
 attn_heads_reduction (str) – reduction applied to output features of each attention head, ‘concat’ or ‘average’. ‘Average’ should be applied in the final prediction layer of the model (Eq. 6 of the paper).
 in_dropout_rate (float) – dropout rate applied to features
 attn_dropout_rate (float) – dropout rate applied to attention coefficients
 activation (str) – nonlinear activation applied to layer’s output to obtain output features (eq. 4 of the GAT paper)
 final_layer (bool) – If False the layer returns output for all nodes, if True it returns the subset specified by the indices passed to it.
 use_bias (bool) – toggles an optional bias
 kernel_initializer (str) – name of layer bias f the initializer for kernel parameters (weights)
 bias_initializer (str) – name of the initializer for bias
 attn_kernel_initializer (str) – name of the initializer for attention kernel
 kernel_regularizer (str) – name of regularizer to be applied to layer kernel. Must be a Keras regularizer.
 bias_regularizer (str) – name of regularizer to be applied to layer bias. Must be a Keras regularizer.
 attn_kernel_regularizer (str) – name of regularizer to be applied to attention kernel. Must be a Keras regularizer.
 activity_regularizer (str) – not used in the current implementation
 kernel_constraint (str) – constraint applied to layer’s kernel. Must be a Keras constraint https://keras.io/constraints/
 bias_constraint (str) – constraint applied to layer’s bias. Must be a Keras constraint https://keras.io/constraints/
 attn_kernel_constraint (str) – constraint applied to attention kernel. Must be a Keras constraint https://keras.io/constraints/
 **kwargs – optional keyword arguments supplied to the Keras
Layer

call
(inputs, **kwargs)[source]¶ Creates the layer as a Keras graph
Notes
This does not add self loops to the adjacency matrix. The output indices are only used when final_layer=True
Parameters:  inputs (list) – list of inputs with 4 items:
 features (node) –
 indices (output) –
 graph adjacency matrix (sparse) –
 N is the number of nodes in the graph, (where) – F is the dimensionality of node features M is the number of output nodes
Link prediction layers¶
Link inference functions for link classification (including link prediction) and link attribute inference (regression)

stellargraph.layer.link_inference.
link_classification
(output_dim: int = 1, output_act: AnyStr = 'sigmoid', edge_embedding_method: AnyStr = 'ip')[source]¶ Defines a function that predicts a binary or multiclass edge classification output from (source, destination) node embeddings (node features).
Parameters:  output_dim (int) – Number of classifier’s output units – desired dimensionality of the output,
 output_act (str) – activation function applied to the output, one of “softmax”, “sigmoid”, etc., or any activation function supported by Keras, see https://keras.io/activations/ for more information.
 edge_embedding_method (str) –
Name of the method of combining (src,dst) node features/embeddings into edge embeddings. One of:
 ’concat’ – concatenation,
 ’ip’ or ‘dot’ – inner product, \(ip(u,v) = sum_{i=1..d}{u_i*v_i}\),
 ’mul’ or ‘hadamard’ – elementwise multiplication, \(h(u,v)_i = u_i*v_i\),
 ’l1’ – l1 operator, \(l_1(u,v)_i = u_iv_i\),
 ’l2’ – l2 operator, \(l_2(u,v)_i = (u_iv_i)^2\),
 ’avg’ – average, \(avg(u,v) = (u+v)/2\).
Returns: Function taking edge tensors with src, dst node embeddings (i.e., pairs of (node_src, node_dst) tensors) and returning logits of output_dim length (e.g., edge class probabilities).

stellargraph.layer.link_inference.
link_regression
(output_dim: int = 1, clip_limits: Optional[Tuple[float]] = None, edge_embedding_method: AnyStr = 'ip')[source]¶ Defines a function that predicts a numeric edge regression output vector/scalar from (source, destination) node embeddings (node features).
Parameters:  output_dim (int) – Number of classifier’s output units – desired dimensionality of the output,
 clip_limits (tuple) – lower and upper thresholds for LeakyClippedLinear unit on top. If None (not provided), the LeakyClippedLinear unit is not applied.
 edge_embedding_method (str) –
Name of the method of combining (src,dst) node features/embeddings into edge embeddings. One of:
 ’concat’ – concatenation,
 ’ip’ or ‘dot’ – inner product, \(ip(u,v) = sum_{i=1..d}{u_i*v_i}\),
 ’mul’ or ‘hadamard’ – elementwise multiplication, \(h(u,v)_i = u_i*v_i\),
 ’l1’ – l1 operator, \(l_1(u,v)_i = u_iv_i\),
 ’l2’ – l2 operator, \(l_2(u,v)_i = (u_iv_i)^2\),
 ’avg’ – average, \(avg(u,v) = (u+v)/2\).
Returns: Function taking edge tensors with src, dst node embeddings (i.e., pairs of (node_src, node_dst) tensors) and returning a numeric value (e.g., edge attribute being predicted) constructed according to edge_embedding_method.

stellargraph.layer.link_inference.
link_inference
(output_dim: int = 1, output_act: AnyStr = 'linear', edge_embedding_method: AnyStr = 'ip', clip_limits: Optional[Tuple[float]] = None, name: AnyStr = 'link_inference')[source]¶ Defines an edge inference function that takes source, destination node embeddings (node features) as input, and returns a numeric vector of output_dim size.
Parameters:  output_dim (int) – Number of predictor’s output units – desired dimensionality of the output.
 output_act (str) – activation function applied to the output, one of “softmax”, “sigmoid”, etc., or any activation function supported by Keras, see https://keras.io/activations/ for more information.
 edge_embedding_method (str) –
Name of the method of combining (src,dst) node features or embeddings into edge embeddings. One of:
 ’concat’ – concatenation,
 ’ip’ or ‘dot’ – inner product, \(ip(u,v) = sum_{i=1..d}{u_i*v_i}\),
 ’mul’ or ‘hadamard’ – elementwise multiplication, \(h(u,v)_i = u_i*v_i\),
 ’l1’ – l1 operator, \(l_1(u,v)_i = u_iv_i\),
 ’l2’ – l2 operator, \(l_2(u,v)_i = (u_iv_i)^2\),
 ’avg’ – average, \(avg(u,v) = (u+v)/2\).
 clip_limits (Tuple[float]) – lower and upper thresholds for LeakyClippedLinear unit on top. If None (not provided), the LeakyClippedLinear unit is not applied.
 name (str) – optional name of the defined function, used for error logging
Returns: Function taking edge tensors with src, dst node embeddings (i.e., pairs of (node_src, node_dst) tensors) and returning a vector of output_dim length (e.g., edge class probabilities, edge attribute prediction, etc.).
Ensembles¶
Ensembles of graph neural network models, GraphSAGE, GCN, GAT, with optional bootstrap sampling of the training data.

class
stellargraph.utils.ensemble.
Ensemble
(model, n_estimators=3, n_predictions=3)[source]¶ The Ensemble class can be used to create ensembles of stellargraph’s graph neural network algorithms including GCN, GraphSAGE, GAT, and HinSAGE. Ensembles can be used for training classification and regression problems for node attribute inference and link prediction.
The Ensemble class can be used to create two different types of ensembles, Naive and Bagging.
Naive ensembles add model diversity by random initialisation of the models’ weights (before training) to different values. Each model in the ensemble is trained on the same training set of examples.
Bagging ensembles add additional model diversity via bootstrap sampling of the training data. That is, each model in the ensemble is trained on a random subset of the training examples, sampled with replacement from the original training data.
The choice of ensemble type, Naive or Bagging, is done implicitly based on how data is passed to the
fit_generator()
method.
compile
(optimizer, loss=None, metrics=None, loss_weights=None, sample_weight_mode=None, weighted_metrics=None)[source]¶ Method for configuring the model for training. It is a wrapper of the keras.models.Model.compile method for all models in the ensemble.
For detailed descriptions of Kerasspecific parameters consult the Keras documentation at https://keras.io/models/sequential/
Parameters:  optimizer (Keras optimizer or str) – (Kerasspecific parameter) The optimizer to use given either as an instance of a keras optimizer or a string naming the optimiser of choice.
 loss (Keras function or str) – (Kerasspecific parameter) The loss function or string indicating the type of loss to use.
 metrics (list or dict) – (Kerasspecific parameter) List of metrics to be evaluated by each model in the ensemble during training and testing. It should be a list for a model with a single output. To specify different metrics for different outputs of a multioutput model, you could also pass a dictionary.
 loss_weights (None or list) – (Kerasspecific parameter) Optional list or dictionary specifying scalar coefficients (Python floats) to weight the loss contributions of different model outputs. The loss value that will be minimized by the model will then be the weighted sum of all individual losses, weighted by the loss_weights coefficients. If a list, it is expected to have a 1:1 mapping to the model’s outputs. If a tensor, it is expected to map output names (strings) to scalar coefficients.
 sample_weight_mode (None, str, list, or dict) – (Kerasspecific parameter) If you need to do timestepwise sample weighting (2D weights), set this to “temporal”. None defaults to samplewise weights (1D). If the model has multiple outputs, you can use a different sample_weight_mode on each output by passing a dictionary or a list of modes.
 weighted_metrics (list) – (Kerasspecific parameter) List of metrics to be evaluated and weighted by sample_weight or class_weight during training and testing.

evaluate_generator
(generator, test_data=None, test_targets=None, max_queue_size=10, workers=1, use_multiprocessing=False, verbose=0)[source]¶ Evaluates the ensemble on a data (node or link) generator. It makes n_predictions for each data point for each of the n_estimators and returns the mean and standard deviation of the predictions.
For detailed descriptions of Kerasspecific parameters consult the Keras documentation at https://keras.io/models/sequential/
Parameters:  generator – The generator object that, if test_data is not None, should be one of type GraphSAGENodeGenerator, HinSAGENodeGenerator, FullBatchNodeGenerator, GraphSAGELinkGenerator, or HinSAGELinkGenerator. However, if test_data is None, then generator should be one of type NodeSequence, LinkSequence, or FullBatchNodeSequence.
 test_data (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the node IDs to evaluate the model on.
 test_targets (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the target values for the test_data.
 max_queue_size (int) – (Kerasspecific parameter) The maximum size for the generator queue.
 workers (int) – (Kerasspecific parameter) The maximum number of workers to use.
 use_multiprocessing (bool) – (Kerasspecific parameter) If True then use process based threading.
 verbose (int) – (Kerasspecific parameter) The verbocity mode that should be 0 or 1 with the former turning verbocity off and the latter on.
Returns: The mean and standard deviation of the model metrics for the given data.
Return type:

fit_generator
(generator, steps_per_epoch=None, epochs=1, verbose=1, validation_generator=None, validation_steps=None, class_weight=None, max_queue_size=10, workers=1, use_multiprocessing=False, shuffle=True, initial_epoch=0, train_data=None, train_targets=None, val_data=None, val_targets=None, bag_size=None, use_early_stopping=False, early_stopping_monitor='val_loss')[source]¶ This method trains the ensemble on the data specified by the generator or the data given in train_data and train_targets. If validation data are given, then the training metrics are evaluated on these data and results printed on screen if verbose level is greater than 0.
The method trains each model in the ensemble in series for the number of epochs specified. Training can also stop early with the best model as evaluated on the validation data, if use_early_stopping is enabled.
if train_data and train_targets are given, then each model in the ensemble is trained using a bootstrapped sample of the data (the train data are resampled with replacement.) The number of bootstrap samples is can be specified via the bag_size parameter; by default, the number of bootstrap samples equals the number of training points.
For detail descriptions of Kerasspecific parameters consult the Keras documentation at https://keras.io/models/sequential/
Parameters:  generator – The generator object for training data. if test_data is not None, it should be one of type GraphSAGENodeGenerator, HinSAGENodeGenerator, FullBatchNodeGenerator, GraphSAGELinkGenerator, or HinSAGELinkGenerator. However, if test_data is None, then generator should be one of type NodeSequence, LinkSequence, SparseFullBatchNodeSequence, or FullBatchNodeSequence.
 steps_per_epoch (None or int) – (Kerasspecific parameter) If not None, it specifies the number of steps to yield from the generator before declaring one epoch finished and starting a new epoch.
 epochs (int) – (Kerasspecific parameter) The number of training epochs.
 verbose (int) – (Kerasspecific parameter) The verbocity mode that should be 0 , 1, or 2 meaning silent, progress bar, and one line per epoch respectively.
 validation_generator – A generator for validation data that is optional (None). If not None then, if val_data is not None, it should be one of type GraphSAGENodeGenerator, HinSAGENodeGenerator, FullBatchNodeGenerator, GraphSAGELinkGenerator, or HinSAGELinkGenerator. However, if val_data is None, then it should be one of type NodeSequence, LinkSequence, SparseFullBatchNodeSequence, or FullBatchNodeSequence.
 validation_steps (None or int) – (Kerasspecific parameter) If validation_generator is not None, then it specifies the number of steps to yield from the generator before stopping at the end of every epoch.
 class_weight (None or dict) – (Kerasspecific parameter) If not None, it should be a dictionary mapping class indices (integers) to a weight (float) value, used for weighting the loss function (during training only). This can be useful to tell the model to “pay more attention” to samples from an underrepresented class.
 max_queue_size (int) – (Kerasspecific parameter) The maximum size for the generator queue.
 workers (int) – (Kerasspecific parameter) The maximum number of workers to use.
 use_multiprocessing (bool) – (Kerasspecific parameter) If True then use process based threading.
 shuffle (bool) – (Kerasspecific parameter) If True, then it shuffles the order of batches at the beginning of each training epoch.
 initial_epoch (int) – (Kerasspecific parameter) Epoch at which to start training (useful for resuming a previous training run).
 train_data (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the data to train the model with.
 train_targets (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the target values for the train data.
 val_data (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the validation data.
 val_targets (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the target values for the validation data.
 bag_size (None or int) – The number of samples in a bootstrap sample. If None and bagging is used, then the number of samples is equal to the number of training points.
 use_early_stopping (bool) – If set to True, then early stopping is used when training each model in the ensemble. The default is False.
 early_stopping_monitor (str) – The quantity to monitor for early stopping, e.g., ‘val_loss’, ‘val_weighted_acc’. It should be a valid Keras metric.
Returns: It returns a list of Keras History objects each corresponding to one trained model in the ensemble.
Return type:

layers
(indx=None)[source]¶ This method returns the layer objects for the model specified by the value of indx.
Parameters: indx (None or int) – The index of the model to return the layers for. If it is None, then the layers for the 0th (or first) model are returned. Returns: The layers for the specified model. Return type: list

predict_generator
(generator, predict_data=None, summarise=False, output_layer=None, max_queue_size=10, workers=1, use_multiprocessing=False, verbose=0)[source]¶ This method generates predictions for the data produced by the given generator or alternatively the data given in parameter predict_data.
For detailed descriptions of Kerasspecific parameters consult the Keras documentation at https://keras.io/models/sequential/
Parameters:  generator – The generator object that, if predict_data is None, should be one of type GraphSAGENodeGenerator, HinSAGENodeGenerator, FullBatchNodeGenerator, GraphSAGELinkGenerator, or HinSAGELinkGenerator. However, if predict_data is not None, then generator should be one of type NodeSequence, LinkSequence, SparseFullBatchNodeSequence, or FullBatchNodeSequence.
 predict_data (None or iterable) – If not None, then it is an iterable, e.g. list, that specifies the node IDs to make predictions for. If generator is of type FullBatchNodeGenerator then predict_data should be all the nodes in the graph since full batch approaches such as GCN and GAT can only be used to make predictions for all graph nodes.
 summarise (bool) – If True, then the mean of the predictions over self.n_estimators and self.n_predictions are returned for each query point. If False, then all predictions are returned.
 output_layer (None or int) – If not None, then the predictions are the outputs of the layer specified. The default is the model’s output layer.
 max_queue_size (int) – (Kerasspecific parameter) The maximum size for the generator queue.
 workers (int) – (Kerasspecific parameter) The maximum number of workers to use.
 use_multiprocessing (bool) – (Kerasspecific parameter) If True then use process based threading.
 verbose (int) – (Kerasspecific parameter) The verbocity mode that should be 0 or 1 with the former turning verbocity off and the latter on.
Returns: The predictions. It will have shape MxKxNxF if summarise is set to False, or NxF otherwise. M is the number of estimators in the ensemble; K is the number of predictions per query point; N is the number of query points; and F is the output dimensionality of the specified layer determined by the shape of the output layer.
Return type: numpy array

Calibration¶
Calibration for classification, binary and multiclass, models.

stellargraph.utils.calibration.
expected_calibration_error
(prediction_probabilities, accuracy, confidence)[source]¶ Helper function for calculating the expected calibration error as defined in the paper On Calibration of Modern Neural Networks, C. Guo, et. al., ICML, 2017
It is assumed that for a validation dataset, the prediction probabilities have been calculated for each point in the dataset and given in the array prediction_probabilities.
Parameters:  prediction_probabilities (numpy array) – The predicted probabilities.
 accuracy (numpy array) – The accuracy such that the ith entry in the array holds the proportion of correctly classified samples that fall in the ith bin.
 confidence (numpy array) – The confidence such that the ith entry in the array is the average prediction probability over all the samples assigned to this bin.
Returns: The expected calibration error.
Return type:

stellargraph.utils.calibration.
plot_reliability_diagram
(calibration_data, predictions, ece=None, filename=None)[source]¶ Helper function for plotting a reliability diagram.
Parameters:  calibration_data (list) – The calibration data as a list where each entry in the list is a 2tuple of type numpy.ndarray. Each entry in the tuple holds the fraction of positives and the mean predicted values for the true and predicted class labels.
 predictions (np.ndarray) – The probabilistic predictions of the classifier for each sample in the dataset used for diagnosing miscalibration.
 ece (None or list of float) – If not None, this list stores the expected calibration error for each class.
 filename (str or None) – If not None, the figure is saved on disk in the given filename.

class
stellargraph.utils.calibration.
TemperatureCalibration
(epochs=1000)[source]¶ A class for temperature calibration for binary and multiclass classification problems.
For binary classification, Platt Scaling is used for calibration. Platt Scaling was proposed in the paper Probabilistic outputs for support vector machines and comparisons to regularized likelihood methods, J. C. Platt, Advances in large margin classifiers, 10(3): 6174, 1999.
For multiclass classification, Temperature Calibration is used. It is an extension of Platt Scaling and it was proposed in the paper On Calibration of Modern Neural Networks, C. Guo et. al., ICML, 2017.
In Temperature Calibration, a classifier’s nonprobabilistic outputs, i.e., logits, are scaled by a trainable parameter called Temperature. The softmax is applied to the rescaled logits to calculate the probabilistic output. As noted in the cited paper, Temperature Scaling does not change the maximum of the softmax function so the classifier’s prediction remain the same.

fit
(x_train, y_train, x_val=None, y_val=None)[source]¶ Train the calibration model.
For temperature scaling of a multiclass classifier, If validation data is given, then training stops when the validation accuracy starts increasing. Validation data are ignored for Platt scaling
Parameters:  x_train (numpy array) – The training data that should be a classifier’s nonprobabilistic outputs. For calibrating a binary classifier it should have shape (N,) where N is the number of training samples. For calibrating a multiclass classifier, it should have shape (N, C) where N is the number of samples and C is the number of classes.
 y_train (numpy array) – The training data class labels. For calibrating a binary classifier it should have shape (N,) where N is the number of training samples. For calibrating a multiclass classifier, it should have shape (N, C) where N is the number of samples and C is the number of classes and the class labels are onehot encoded.
 x_val (numpy array or None) – The validation data used only for calibrating multiclass classification models. It should have shape (M, C) where M is the number of validation samples and C is the number of classes and the class labels are onehot encoded. that should be the classifier’s nonprobabilistic outputs.
 y_val (numpy array or None) – The validation data class labels used only for calibrating multiclass classification models. It should have shape (M, C) where M is the number of validation samples and C is the number of classes and the class labels are onehot encoded.

predict
(x)[source]¶ This method calibrates the given data using the learned temperature. It scales each logit by the temperature, exponentiates the results, and finally normalizes the scaled values such that their sum is 1.
Parameters: x (numpy.ndarray) – The logits. For binary classification problems, it should have dimensionality (N,) where N is the number of samples to calibrate. For multiclass problems, it should have dimensionality (N, C) where C is the number of classes. Returns: The calibrated probabilities. Return type: numpy array


class
stellargraph.utils.calibration.
IsotonicCalibration
[source]¶ A class for applying Isotonic Calibration to the outputs of a binary or multiclass classifier.

fit
(x_train, y_train)[source]¶ Train a calibration model using the provided data.
Parameters:  x_train (numpy array) – The training data that should be the classifier’s probabilistic outputs. It should have shape NxC where N is the number of training samples and C is the number of classes.
 y_train (numpy array) – The training class labels. For binary problems y_train has shape (N,) when N is the number of samples. For multiclass classification, y_train has shape (N,C) where C is the number of classes and y_train is using onehot encoding.

predict
(x)[source]¶ This method calibrates the given data assumed the output of a classification model.
For multiclass classification, the probabilities for each class are first scaled using the corresponding isotonic regression model and then normalized to sum to 1.
Parameters: x (numpy array) – The values to calibrate. For binary classification problems it should have shape (N,) where N is the number of samples to calibrate. For multiclass classification problems, it should have shape (N, C) where C is the number of classes. Returns: The calibrated probabilities. It has shape (N, C) where N is the number of samples and C is the number of classes. Return type: numpy array
