deepsnap.graph

Contents

DeepSNAP Graph

class Graph(G=None, netlib=None, **kwargs)[source]

Bases: object

A plain python object modeling a single graph with various (optional) attributes.

Parameters

  • G (Graph object, optional) – The NetworkX or SnapX graph object which contains features and labels. If it is not specified, Graph will use the tensor backend.

  • netlib (types.ModuleType, optional) – The graph backend module. Currently DeepSNAP supports the NetworkX and SnapX (for SnapX only the undirected homogeneous graph) as the graph backend. Default graph backend is the NetworkX.

  • **kwargs (optional) – Keyworded argument list with keys such as node_feature, node_label and values that are corresponding attributes. The features are required for the tensor backend.

static add_edge_attr(G, attr_name: str, edge_attr)[source]

Add edge attribute into a NetworkX graph.

Parameters

  • G (NetworkX Graph) – A NetworkX graph.

  • attr_name (str) – Name of the edge attribute to set.

  • edge_attr (array_like) – Corresponding edge attributes.

static add_graph_attr(G, attr_name: str, graph_attr)[source]

Add graph attribute into a NetworkX graph.

Parameters

  • G (NetworkX Graph) – A NetworkX graph.

  • attr_name (str) – Name of the graph attribute to set.

  • graph_attr (scalar or array_like) – Corresponding graph attributes.

static add_node_attr(G, attr_name: str, node_attr)[source]

Add node attribute into a NetworkX graph. Assume that the node_attr ordering is the same as the node ordering in G.

Parameters

  • G (NetworkX Graph) – A NetworkX graph.

  • attr_name (str) – Name of the node attribute to set.

  • node_attr (array_like) – Corresponding node attributes.

apply_tensor(func, *keys)[source]

Applies the function func to all tensor attributes specified by *keys. If the *keys is not given, func is applied to all present attributes.

Parameters

  • func (callable) – The function that will be applied to a PyTorch tensor(s).

  • *keys (str, optional) – Names of the tensor attributes that will be applied.

Returns

Return the self deepsnap.graph.Graph.

Return type

deepsnap.graph.Graph

apply_transform(transform, update_tensor: bool = True, update_graph: bool = False, deep_copy: bool = False, **kwargs)[source]

Applies the transformation function to current graph object.

Note

When the backend graph object (e.g. networkx object) is changed in the transform function, the argument update_tensor is recommended, which will update the tensor representation to be in sync with the transformed graph. Similarly, update_graph is recommended when the transform function makes change to the tensor objects.

However, the transformation function should not make changes to both of the backend graph object and the tensors simultaneously. Otherwise there might exist inconsistency between the transformed graph and tensors. Also note that update_tensor and update_graph cannot be True at the same time.

It is also possible to set both update_tensor and update_graph to be False. This usually happens when one needs to transform the tensor representation, but do not require that the internal graph object to be in sync, for better efficiency. In this case, the user should note that the internal G object is stale, and that applying a transform in the future with update_tensor=True will overwrite the current transformmation (which with parameters update_tensor=False; update_graph=False).

Parameters

  • transform (callable) – In the format of transform(deepsnap.graph.Graph, **kwargs). The function might need to return deepsnap.graph.Graph (the transformed graph object).

  • update_tensor (bool) – If the graph has changed, use the graph to update the stored tensor attributes.

  • update_graph – (bool): If the tensor attributes have changed, use the attributes to update the graph.

  • deep_copy (bool) –

    If True, the graph will be deepcopied and then fed into the transform() function. In this case, the transform() function might also need to return a Graph object.

    Note

    When returning Graph object in the transform function, user should decide whether the tensor values of the graph is to be copied (deepcopy).

  • **kwargs (optional) – Parameters used in the transform() function.

Returns

The transformed Graph object.

Return type

Graph

Note

This function is different from the function apply_tensor().

apply_transform_multi(transform, update_tensors: bool = True, update_graphs: bool = False, deep_copy: bool = False, **kwargs)[source]

Applies transform function to the current graph object. But Unlike the apply_transform(), the transform argument in this method can return a tuple of graphs (Graph).

Parameters

  • transform (callable) – In the format of transform(deepsnap.graph.Graph, **kwargs). The function might need to return a tuple of graphs that each has the type deepsnap.graph.Graph (the transformed graph objects).

  • update_tensors (bool) – If the graphs have changed, use the graph to update the stored tensor attributes.

  • update_graphs – (bool): If the tensor attributes have changed, use the attributes to update the graphs.

  • deep_copy (bool) – If True, the graph will be deepcopied and then fed into the transform() function. In this case, the transform() function might also need to return a Graph object.

  • **kwargs (optional) – Parameters used in the transform() function.

Returns

A tuple of transformed Graph objects.

Return type

tuple

clone()[source]

Deepcopy the graph object.

Returns

A cloned Graph object with deepcopying all features.

Return type

Graph

contiguous(*keys)[source]

Ensures a contiguous memory layout for the attributes specified by *keys. If *keys is not given, all present attributes are ensured to have a contiguous memory layout.

Parameters

*keys (str, optional) – Tensor attributes which will be in contiguous memory layout.

Returns

Graph object with specified tensor attributes in contiguous memory layout.

Return type

Graph

get_num_dims(key: str, as_label: bool = False) → int[source]

Returns the number of dimensions for one graph/node/edge property.

Parameters

  • key (str) – The chosen property.

  • as_label (bool) – If as_label, treat the tensor as labels.

Returns

The number of dimensions for chosen property.

Return type

int

get_num_labels(key: str)[source]

Gets the lables for a specified key.

Parameters

key (str) – The chosen property.

Returns

Unique lables (in tensor format).

Return type

torch.Tensor

is_directed() → bool[source]

Whether the graph is directed.

Returns

True if the graph is directed.

Return type

bool

is_undirected() → bool[source]

Whether the graph is undirected.

Returns

True if the graph is undirected.

Return type

bool

property keys

Returns all names of the graph attributes.

Returns

List of attributes in the Graph object.

Return type

list

static negative_sampling(edge_index, num_nodes: int, num_neg_samples: int)[source]

Samples random negative edges for a heterogeneous graph given by edge_index.

Parameters

  • edge_index (LongTensor) – The indices for edges.

  • num_nodes (int) – Number of nodes.

  • num_neg_samples (int) – The number of negative samples to return.

Returns

The edge_index tensor for negative edges.

Return type

torch.LongTensor

property num_edge_features

Returns edge feature dimension in the graph.

Returns

Edge feature dimension. 0 if there is no edge_feature.

Return type

int

property num_edge_labels

Returns the number of the edge labels in the graph.

Returns

Number of edge labels. 0 if there is no edge_label.

Return type

int

property num_edges

Returns the number of edges in the graph.

Returns

Number of edges in the graph.

Return type

int

property num_graph_features

Returns graph feature dimension in the graph.

Returns

Graph feature dimension. 0 if there is no graph_feature.

Return type

int

property num_graph_labels

Returns the number of the graph labels in the graph.

Returns

Number of graph labels. 0 if there is no graph_label.

Return type

int

property num_node_features

Returns node feature dimension in the graph.

Returns

Node feature dimension. 0 if there is no node_feature.

Return type

int

property num_node_labels

Returns the number of the node labels in the graph.

Returns

Number of node labels. 0 if there is no node_label.

Return type

int

property num_nodes

Return number of nodes in the graph.

Returns

Number of nodes in the graph.

Return type

int

static pyg_to_graph(data, verbose: bool = False, fixed_split: bool = False, tensor_backend: bool = False, netlib=None)[source]

Transform a torch_geometric.data.Data object to a Graph object.

Parameters

  • data (torch_geometric.data.Data) – A torch_geometric.data.Data object that will be transformed to a deepsnap.grpah.Graph object.

  • verbose (bool) – Whether to print information such as warnings.

  • fixed_split (bool) – Whether to load the fixed data split from the original PyTorch Geometric data.

  • tensor_backend (bool) – True will use pure tensors for graphs.

  • netlib (types.ModuleType, optional) – The graph backend module. Currently DeepSNAP supports the NetworkX and SnapX (for SnapX only the undirected homogeneous graph) as the graph backend. Default graph backend is the NetworkX.

Returns

A new DeepSNAP Graph object.

Return type

Graph

static raw_to_graph(data)[source]

Write other methods for user to import their own data format and make sure all attributes of G are scalar or torch.Tensor.

Not implemented

resample_disjoint(message_ratio: float)[source]

Resample splits of the message passing and supervision edges in the disjoint mode.

Note

If apply_transform() (on the message passing graph) was used before this resampling, it needs to be re-applied after resampling, to update some of the (supervision) edges that were in the objectives.

Parameters

message_ratio (float) – Split ratio.

split(task: str = 'node', split_ratio: Optional[List[float]] = None, shuffle: bool = True)[source]

Split current graph object to a list of graph objects.

Parameters

  • task (str) – One of node, edge or link_pred.

  • split_ratio (list) – A list of ratios such as [train_ratio, validation_ratio, test_ratio]. Default is [0.8, 0.1, 0.1].

  • shuffle (bool) – Whether to shuffle data for the splitting.

Returns

A list of Graph objects.

Return type

list

Split the graph into len(split_ratio) graphs for the link prediction task. Internally this function splits the edge indices, and the model will only compute loss for the node embeddings in each splitted graph. This is only used for the transductive link prediction task. In this task, different parts of the graph are observed in train / val / test. If during training, we might further split the training graph for the message edges and supervision edges.

Note

This functon will be called twice.

Parameters

  • split_ratio (float or list) – The ratio or list of ratios.

  • shuffle (bool) – Whether to shuffle for the splitting.

Returns

A list of Graph objects.

Return type

list

to(device, *keys)[source]

Transfers tensor to specified device for to all attributes that are specified in the *keys. If *keys is not given, the conversion is applied to all present attributes.

Parameters

  • device (str) – Specified device name, such as cpu or cuda.

  • *keys (str, optional) – Tensor attributes that will be transferred to specified device.