dgf.convert

dgf.convert.graph_dict_to_graph

Converts a TF GNN Graph Sample Dict to an InMemoryGraph.

dgf.convert.graph_to_jax_graph

Converts a (NumPy) in-memory graph into a JAX in-memory graph.

Parameters:

Name	Type	Description	Default
`src`	`Union[InMemoryGraph, TFInMemoryGraph]`	The source graph to convert.	required
`cast_arrays`	`bool`	Whether to cast the arrays to jax array. If False, the original arrays are returned. This can be used to interact with jax2tf.	`True`

dgf.convert.graph_to_networkx

Converts an InMemoryGraph into a NetworkX MultiDiGraph.

Usage

# Normal conversion
nx_graph = dgf.convert.graph_to_networkx(graph, schema)

# Convert and write to GraphML
nx_graph = dgf.convert.graph_to_networkx(graph, schema, for_graphml=True)
nx.write_graphml(nx_graph, "/tmp/graph.graphml")

Parameters:

Name	Type	Description	Default
`in_memory_graph`	`InMemoryGraph`	The input graph in `InMemoryGraph` format.	required
`schema`	`GraphSchema`	A `GraphSchema` instance describing the graph structure. Required to determine the source and target node sets for edges.	required
`for_graphml`	`bool`	If True, convert complex node and edge features (such as NumPy arrays and NumPy bytes) into basic strings and scalars that are strictly supported by the GraphML export format. Setting this to True means the result is not invertible with `networkx_to_graph`.	`False`

Returns:

Type	Description
`MultiDiGraph`	A NetworkX `MultiDiGraph` containing the graph data.

dgf.convert.graph_to_serialized_tfgnn_graph

Converts an InMemoryGraph into a serialized TF-GNN graph sample proto.

This function is equivalent to, but significantly faster than, calling: graph_to_tfgnn_graph(graph, schema).SerializeToString(). The performance improvement comes from reduced data copies and the implementation being entirely in C++.

When serializing multiple graphs (e.g., a collection of graph samples), use the graphs_to_serialized_tfgnn_graphs method for even faster computation.

Usage example:

graph, schema = gdf.io.read_graph("/tmp/my_graph")
serialized_graph = dgf.convert.graph_to_serialized_tfgnn_graph(graph,schema)

Parameters:

Name	Type	Description	Default
`graph`	`InMemoryGraph`	The input InMemoryGraph.	required
`schema`	`GraphSchema \| None`	An optional and currently unused graph schema. This argument is included to ensure API consistency with other graph serialization functions, and it may be used in future implementations.	`None`

Returns:

Type	Description
`bytes`	Bytes of a serialized `tf.train.Example` proto containing the graph data
`bytes`	in the TF-GNN format.

dgf.convert.graph_to_sparse_deferred_struct

Converts an in-memory graph into a Sparse Deferred struct.

Parameters:

Name	Type	Description	Default
`in_memory_graph`	`InMemoryGraph`	The input graph in `InMemoryGraph` format.	required
`schema`	`Optional[GraphSchema]`	An optional `GraphSchema` instance describing the graph structure. If provided, it will be converted to a Sparse Deferred schema.	`None`

Returns:

Type	Description
`GraphStruct`	A `sd_struct_lib.GraphStruct` instance containing the same graph data.

dgf.convert.graph_to_tf_graph

Converts a graph to a TF in-memory graph.

Parameters:

Name	Type	Description	Default
`src`	`InMemoryGraph`	The source graph to convert.	required
`schema`	`Optional[GraphSchema]`	Optional graph schema to enforce typing (especially useful for empty arrays).	`None`

Returns:

Type	Description
`TFInMemoryGraph`	A `TFInMemoryGraph` representation of the input graph.

dgf.convert.graph_to_tfgnn_graph

Converts an InMemoryGraph to a TF GNN Graph Sample.

dgf.convert.graph_to_tfgnn_graph_dict

Converts an InMemoryGraph to a TF GNN Graph Sample Dict.

dgf.convert.graphs_to_serialized_tfgnn_graphs

Converts a sequence of InMemoryGraphs into serialized TF-GNN graph sample protos.

This function is significantly faster than calling graph_to_tfgnn_graph(graph, schema).SerializeToString() or graph_to_tfgnn_graph in a loop.

def graph_generator():
  for graph in <sampler>:
    yield graph
serialized_graphs =
dgf.convert.graphs_to_serialized_tfgnn_graphs(graph_generator,schema)

Parameters:

Name	Type	Description	Default
`graphs`	`Sequence[InMemoryGraph]`	The input sequence of InMemoryGraphs.	required
`schema`	`GraphSchema \| None`	An optional and currently unused graph schema. This argument is included to ensure API consistency with other graph serialization functions, and it may be used in future implementations.	`None`
`num_threads`	`int`	The number of threads to use for serialization. If negative, the GIL will be released, but a single thread will be used.	`cpu_count() * 2`

Returns:

Type	Description
`List[bytes]`	A list of bytes, where each element is a serialized `tf.train.Example` proto
`List[bytes]`	containing the data for one graph in the TF-GNN format.

dgf.convert.networkx_to_graph

Converts a NetworkX graph into an InMemoryGraph and its schema.

Usage

in_memory_graph, schema = dgf.convert.networkx_to_graph(nx_graph)

Parameters:

Name	Type	Description	Default
`nx_graph`	`MultiDiGraph`	The input graph in NetworkX format.	required

Returns:

Type	Description
`Tuple[InMemoryGraph, GraphSchema]`	A tuple of (`InMemoryGraph`, `GraphSchema`).

dgf.convert.schema_to_spanner_ddl

Converts a GraphSchema to a string of CREATE statements for Spanner.

Useful for creating a Spanner database that matches the schema of a hgraph.

Can use something like \n.join(schema_to_spanner_ddl(schema).values()) to get a single string with all the CREATE statements.

Assumptions

An #id BYTES(MAX) column is added to each node set table an acts as the primary key for node features.
Edges are stored in a flat (source, target, features) format rather than adjacency list.
Edges will have a nullable id BYTES(MAX) column that is also used as the primary key. Hypergraphs can only be supported if all edge tuples have an associated #id.
Each edge must have a (source, target) specification - NOT NULL constraints are added to the table schema (DDL).

Parameters:

Name	Type	Description	Default
`schema`	`GraphSchema`	A GraphSchema.	required
`max_bytes_length`	`Optional[int]`	Optional max byte length for BYTES columns. Defaults to "MAX".	`None`
`enforce_foreign_keys`	`bool`	Whether to enforce foreign keys in the edge tables. If True, the edge tables will have foreign key constraints. If False, the edge tables will not have foreign key constraints.	`False`

Returns:

Type	Description
	A dictionary mapping node and edge set names to the corresponding Spanner
	CREATE TABLE statements.

Raises:

Type	Description
`ValueError`	If the max_str_length is not a valid value.

dgf.convert.schema_to_sparse_deferred_schema

Converts a DGF GraphSchema into a Sparse Deferred schema.

Parameters:

Name	Type	Description	Default
`schema`	`GraphSchema`	The input schema in `schema_lib.GraphSchema` format.	required

Returns:

Type	Description
`Schema`	A `sd_struct_lib.Schema` instance representing the graph schema.

dgf.convert.schema_to_tfgnn_schema

Converts a GraphSchema object into a TF-GNN schema proto.

Parameters:

Name	Type	Description	Default
`schema`	`GraphSchema`	A GraphSchema object.	required
`add_reverse_edges`	`bool`	If true, for each edge set in the schema, a corresponding reverse edge set is added. For example, an edge set named "my_edge" will result in two edge sets in the output TF-GNN schema: "my_edge" (the original) and "reverse_my_edge" (with source and target swapped).	`False`

Returns:

Type	Description
`GraphSchema`	A TF-GNN schema proto.

dgf.convert.sparse_deferred_struct_to_graph

Converts a Sparse Deferred struct into an in-memory graph.

Parameters:

Name	Type	Description	Default
`sd_graph_struct`	`GraphStruct`	The input graph in `sd_struct_lib.GraphStruct` format.	required

Returns:

Type	Description
`InMemoryGraph`	An `InMemoryGraph` instance containing the same graph data.

dgf.convert.tf_graph_dict_to_tf_graph

Converts a flattened TFInMemoryGraphDict back into a TFInMemoryGraph.

Usage example:

graph_dict = {
    "nodes_n1_reserved_size": tf.constant([2], dtype=tf.int32),
    "nodes_n1_feat": tf.constant([[1.0], [2.0]]),
    "edges_e1_reserved_adjacency": tf.constant([[0, 0], [0, 1]],
    dtype=tf.int64),
}
tf_graph = dgf.api.convert.tf_graph_dict_to_tf_graph(graph_dict)

See the "Graph formats" documentation page for details about the tf graph dict format.

Parameters:

Name	Type	Description	Default
`src`	`TFInMemoryGraphDict`	The source TFInMemoryGraphDict to convert.	required

Returns:

Type	Description
`TFInMemoryGraph`	A reconstructed TFInMemoryGraph.

dgf.convert.tf_graph_to_tf_graph_dict

Converts a TFInMemoryGraph into a flattened TFInMemoryGraphDict.

Usage example:

tf_graph = ...  # A TFInMemoryGraph instance
graph_dict = dgf.api.convert.tf_graph_to_tf_graph_dict(tf_graph)

See the "Graph formats" documentation page for details about the tf graph dict format.

Parameters:

Name	Type	Description	Default
`src`	`TFInMemoryGraph`	The source TFInMemoryGraph to convert.	required

Returns:

Type	Description
`TFInMemoryGraphDict`	A TFInMemoryGraphDict with flattened keys and tensor values.

dgf.convert.tfgnn_graph_to_graph

Converts a TF GNN Graph Sample to an InMemoryGraph.

dgf.convert.tfgnn_schema_to_schema

Converts a TF-GNN schema proto into a GraphSchema object.

Parameters:

Name	Type	Description	Default
`tfgnn_schema`	`GraphSchema`	A TF-GNN schema proto.	required
`fix_shapes`		If true, fixes the extra None dimension added to all the shapes.	required

Returns:

Type	Description
`GraphSchema`	A GraphSchema object.