Refresh api_docs at commit

PiperOrigin-RevId: 549650225
tensorflow · Jul 20, 2023 · 66f2e1b · 66f2e1b
1 parent 035b569
commit 66f2e1b
Show file tree

Hide file tree

Showing 114 changed files with 3,012 additions and 575 deletions.
diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2.md
@@ -37,3 +37,9 @@ GraphUpdate layer with a Graph Attention Network V2 (GATv2).
 
 [`GATv2MPNNGraphUpdate(...)`](./gat_v2/GATv2MPNNGraphUpdate.md): Returns a
 GraphUpdate layer for message passing with GATv2 pooling.
+
+[`graph_update_from_config_dict(...)`](./gat_v2/graph_update_from_config_dict.md):
+Returns a GATv2MPNNGraphUpdate initialized from `cfg`.
+
+[`graph_update_get_config_dict(...)`](./gat_v2/graph_update_get_config_dict.md):
+Returns ConfigDict for graph_update_from_config_dict() with defaults.
diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2Conv.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2Conv.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L22-L323">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L22-L331">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>
@@ -29,8 +29,8 @@ The multi-head attention from Graph Attention Networks v2 (GATv2).
     attention_activation: Union[str, Callable[..., Any]] = &#x27;leaky_relu&#x27;,
     heads_merge_type: str = &#x27;concat&#x27;,
     activation: Union[str, Callable[..., Any]] = &#x27;relu&#x27;,
-    kernel_initializer: Union[None, str, tf.keras.initializers.Initializer] = None,
-    kernel_regularizer: Union[None, str, tf.keras.regularizers.Regularizer] = None,
+    kernel_initializer: Any = None,
+    kernel_regularizer: Any = None,
     **kwargs
 )
 </code></pre>
@@ -140,7 +140,7 @@ from this input.)
 <td>
 Can be set to override `tfgnn.HIDDEN_STATE` for use as
 the input feature from sender nodes to attention.
-IMPORANT: Must be set to `None` for use with `receiver_tag=tfgnn.CONTEXT`
+IMPORTANT: Must be set to `None` for use with `receiver_tag=tfgnn.CONTEXT`
 on an edge set, or for pooling from edges without sender node states.
 </td>
 </tr><tr>
@@ -179,7 +179,7 @@ is dropped out.)
 The nonlinearity used on the transformed inputs
 before multiplying with the trained weights of the attention layer.
 This can be specified as a Keras layer, a tf.keras.activations.*
-function, or a string understood by tf.keras.layers.Activation().
+function, or a string understood by `tf.keras.layers.Activation()`.
 Defaults to "leaky_relu", which in turn defaults to a negative slope
 of `alpha=0.2`.
 </td>
@@ -206,8 +206,10 @@ specified in the same ways as attention_activation.
 `kernel_initializer`<a id="kernel_initializer"></a>
 </td>
 <td>
-Can be set to a `kerner_initializer` as understood
+Can be set to a `kernel_initializer` as understood
 by `tf.keras.layers.Dense` etc.
+An `Initializer` object gets cloned before use to ensure a fresh seed,
+if not set explicitly. For more, see `tfgnn.keras.clone_initializer()`.
 </td>
 </tr><tr>
 <td>
@@ -310,7 +312,7 @@ If `False`, all calls to convolve() will get `sender_node_input=None`.
 
 <h3 id="convolve"><code>convolve</code></h3>
 
-<a target="_blank" class="external" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L242-L301">View
+<a target="_blank" class="external" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L250-L309">View
 source</a>
 
 <pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">

diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2EdgePool.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2EdgePool.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L361-L412">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L369-L420">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2HomGraphUpdate.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2HomGraphUpdate.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L416-L470">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L424-L476">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2MPNNGraphUpdate.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/GATv2MPNNGraphUpdate.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L487-L581">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/layers.py#L493-L589">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>
@@ -31,7 +31,7 @@ Returns a GraphUpdate layer for message passing with GATv2 pooling.
     attention_activation: Union[str, Callable[..., Any]] = &#x27;leaky_relu&#x27;,
     conv_activation: Union[str, Callable[..., Any]] = &#x27;relu&#x27;,
     activation: Union[str, Callable[..., Any]] = &#x27;relu&#x27;,
-    kernel_initializer: Union[None, str, tf.keras.initializers.Initializer] = &#x27;glorot_uniform&#x27;
+    kernel_initializer: Any = &#x27;glorot_uniform&#x27;
 ) -> tf.keras.layers.Layer
 </code></pre>
 
@@ -136,7 +136,7 @@ The dropout rate applied to the resulting node states.
 The nonlinearity used on the transformed inputs
 before multiplying with the trained weights of the attention layer.
 This can be specified as a Keras layer, a tf.keras.activations.*
-function, or a string understood by tf.keras.layers.Activation().
+function, or a string understood by `tf.keras.layers.Activation()`.
 Defaults to "leaky_relu", which in turn defaults to a negative slope
 of `alpha=0.2`.
 </td>
@@ -161,7 +161,7 @@ this graph update.
 `kernel_initializer`<a id="kernel_initializer"></a>
 </td>
 <td>
-Can be set to a `kerner_initializer` as understood
+Can be set to a `kernel_initializer` as understood
 by `tf.keras.layers.Dense` etc.
 </td>
 </tr>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/all_symbols.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/all_symbols.md
@@ -9,3 +9,5 @@
 *   <a href="../gat_v2/GATv2EdgePool.md"><code>gat_v2.GATv2EdgePool</code></a>
 *   <a href="../gat_v2/GATv2HomGraphUpdate.md"><code>gat_v2.GATv2HomGraphUpdate</code></a>
 *   <a href="../gat_v2/GATv2MPNNGraphUpdate.md"><code>gat_v2.GATv2MPNNGraphUpdate</code></a>
+*   <a href="../gat_v2/graph_update_from_config_dict.md"><code>gat_v2.graph_update_from_config_dict</code></a>
+*   <a href="../gat_v2/graph_update_get_config_dict.md"><code>gat_v2.graph_update_get_config_dict</code></a>
diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/graph_update_from_config_dict.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/graph_update_from_config_dict.md
@@ -0,0 +1,74 @@
+# gat_v2.graph_update_from_config_dict
+
+[TOC]
+
+<!-- Insert buttons and diff -->
+
+<table class="tfo-notebook-buttons tfo-api nocontent" align="left">
+<td>
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/config_dict.py#L42-L62">
+    <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
+    View source on GitHub
+  </a>
+</td>
+</table>
+
+Returns a GATv2MPNNGraphUpdate initialized from `cfg`.
+
+<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
+<code>gat_v2.graph_update_from_config_dict(
+    cfg: config_dict.ConfigDict
+) -> tf.keras.layers.Layer
+</code></pre>
+
+<!-- Placeholder for "Used in" -->
+<!-- Tabular view -->
+
+ <table class="responsive fixed orange">
+<colgroup><col width="214px"><col></colgroup>
+<tr><th colspan="2"><h2 class="add-link">Args</h2></th></tr>
+
+<tr>
+<td>
+`cfg`<a id="cfg"></a>
+</td>
+<td>
+A `ConfigDict` with the fields defined by
+`graph_update_get_config_dict()`. All fields with non-`None` values are
+used as keyword arguments for initializing and returning a
+`GATv2MPNNGraphUpdate` object. For the required arguments of
+`GATv2MPNNGraphUpdate.__init__`, users must set a value in
+`cfg` before passing it here.
+</td>
+</tr>
+</table>
+
+<!-- Tabular view -->
+
+ <table class="responsive fixed orange">
+<colgroup><col width="214px"><col></colgroup>
+<tr><th colspan="2"><h2 class="add-link">Returns</h2></th></tr>
+<tr class="alt">
+<td colspan="2">
+A new `GATv2MPNNGraphUpdate` object.
+</td>
+</tr>
+
+</table>
+
+<!-- Tabular view -->
+
+ <table class="responsive fixed orange">
+<colgroup><col width="214px"><col></colgroup>
+<tr><th colspan="2"><h2 class="add-link">Raises</h2></th></tr>
+
+<tr>
+<td>
+`TypeError`<a id="TypeError"></a>
+</td>
+<td>
+if `cfg` fails to supply a required argument for
+`GATv2MPNNGraphUpdate.__init__`.
+</td>
+</tr>
+</table>
diff --git a/tensorflow_gnn/docs/api_docs/python/models/gat_v2/graph_update_get_config_dict.md b/tensorflow_gnn/docs/api_docs/python/models/gat_v2/graph_update_get_config_dict.md
@@ -0,0 +1,22 @@
+# gat_v2.graph_update_get_config_dict
+
+[TOC]
+
+<!-- Insert buttons and diff -->
+
+<table class="tfo-notebook-buttons tfo-api nocontent" align="left">
+<td>
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gat_v2/config_dict.py#L22-L39">
+    <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
+    View source on GitHub
+  </a>
+</td>
+</table>
+
+Returns ConfigDict for graph_update_from_config_dict() with defaults.
+
+<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
+<code>gat_v2.graph_update_get_config_dict() -> config_dict.ConfigDict
+</code></pre>
+
+<!-- Placeholder for "Used in" -->
diff --git a/tensorflow_gnn/docs/api_docs/python/models/gcn/GCNConv.md b/tensorflow_gnn/docs/api_docs/python/models/gcn/GCNConv.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gcn/gcn_conv.py#L28-L218">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gcn/gcn_conv.py#L26-L279">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>
@@ -23,11 +23,11 @@ Implements the Graph Convolutional Network by Kipf&Welling (2016).
     activation=&#x27;relu&#x27;,
     use_bias: bool = True,
     add_self_loops: bool = False,
-    normalize: bool = True,
-    kernel_initializer: bool = None,
+    kernel_initializer: Any = None,
     node_feature: Optional[str] = tfgnn.HIDDEN_STATE,
-    kernel_regularizer: Optional[_RegularizerType] = None,
+    kernel_regularizer: Any = None,
     edge_weight_feature_name: Optional[tfgnn.FieldName] = None,
+    degree_normalization: str = &#x27;in_out&#x27;,
     **kwargs
 )
 </code></pre>
@@ -36,7 +36,40 @@ Implements the Graph Convolutional Network by Kipf&Welling (2016).
 
 This class implements a Graph Convolutional Network from
 https://arxiv.org/abs/1609.02907 as a Keras layer that can be used as a
-convolution on an edge set in a tfgnn.keras.layers.NodeSetUpdate.
+convolution on an edge set in a tfgnn.keras.layers.NodeSetUpdate. The original
+algorithm proposed in the Graph Convolutional Network paper expects a symmetric
+graph as input. That is, if there is an edge from node i to node j, there is
+also an edge from node j to node i. This implementation, however, is able to
+take asymmetric graphs as input.
+
+Let $w_{ij}$ be the weight of the edge from sender i to receiver j. Let
+$\deg^{in}_i$ be the number of incoming edges to i (in the direction of message
+flow, see `receiver_tag`), and $\deg^{out}_i$ the number of outgoing edges from
+i. In a symmetric graphs, both are equal.
+
+In this implementation, we provide multiple approaches for normalizing an edge
+weight $w_{ij}$ in $v_{ij}$, namely `"none"`, `"in"`, `"out"`, `"in_out"`, and
+`"in_in"`. Setting normalization to `"none"` will end up in set $v_{ij} =
+w_{ij}$. The `"in"` normalization normalizes edge weights using the in-degree of
+the receiver node, that is:
+
+$$v_{ij} = w_{ij} / \deg^{in}_j.$$
+
+The `"out"` normalization normalizes edges using the out-degree of sender nodes
+that is:
+
+$$v_{ij} = w_{ij} / \deg^{out}_i.$$
+
+The `"in_out"` normalization normalizes edges as follows:
+
+$$v_{ij} = w_{ij} / (\sqrt{\deg^{out}_i} \sqrt{\deg^{in}_j}).$$
+
+The `"in_in"` normalization normalizes the edge weights as:
+
+$$v_{ij} = w_{ij} / (\sqrt{\deg^{in}_i} \sqrt{\deg^{in}_j}).$$
+
+For symmetric graphs (as in the original GCN paper), `"in_out"` and `"in_in"`
+are equal, but the latter needs to compute degrees just once.
 
 <!-- Tabular view -->
  <table class="responsive fixed orange">
@@ -90,17 +123,13 @@ with an edge weight of one.
 </td>
 </tr><tr>
 <td>
-`normalize`<a id="normalize"></a>
-</td>
-<td>
-Whether to normalize the node features by in-degree.
-</td>
-</tr><tr>
-<td>
 `kernel_initializer`<a id="kernel_initializer"></a>
 </td>
 <td>
-initializer of type tf.keras.initializers .
+Can be set to a `kernel_initializer` as understood
+by `tf.keras.layers.Dense` etc.
+An `Initializer` object gets cloned before use to ensure a fresh seed,
+if not set explicitly. For more, see `tfgnn.keras.clone_initializer()`.
 </td>
 </tr><tr>
 <td>
@@ -120,6 +149,14 @@ it as the edge's entry in the adjacency matrix, instead of the default 1.
 </td>
 </tr><tr>
 <td>
+`degree_normalization`<a id="degree_normalization"></a>
+</td>
+<td>
+Can be set to `"none"`, `"in"`, `"out"`, `"in_out"`,
+or `"in_in"`, as explained above.
+</td>
+</tr><tr>
+<td>
 `**kwargs`<a id="**kwargs"></a>
 </td>
 <td>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/gcn/GCNHomGraphUpdate.md b/tensorflow_gnn/docs/api_docs/python/models/gcn/GCNHomGraphUpdate.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gcn/gcn_conv.py#L221-L278">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/gcn/gcn_conv.py#L282-L338">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/graph_sage/GCNGraphSAGENodeSetUpdate.md b/tensorflow_gnn/docs/api_docs/python/models/graph_sage/GCNGraphSAGENodeSetUpdate.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L257-L473">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L256-L472">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>

diff --git a/tensorflow_gnn/docs/api_docs/python/models/graph_sage/GraphSAGEAggregatorConv.md b/tensorflow_gnn/docs/api_docs/python/models/graph_sage/GraphSAGEAggregatorConv.md
@@ -6,7 +6,7 @@
 
 <table class="tfo-notebook-buttons tfo-api nocontent" align="left">
 <td>
-  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L25-L124">
+  <a target="_blank" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L24-L123">
     <img src="https://www.tensorflow.org/images/GitHub-Mark-32px.png" />
     View source on GitHub
   </a>
@@ -137,7 +137,7 @@ If `False`, all calls to convolve() will get `sender_node_input=None`.
 
 <h3 id="convolve"><code>convolve</code></h3>
 
-<a target="_blank" class="external" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L109-L124">View
+<a target="_blank" class="external" href="https://github.com/tensorflow/gnn/tree/master/tensorflow_gnn/models/graph_sage/layers.py#L108-L123">View
 source</a>
 
 <pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">