Copyright 2020 The TensorFlow Authors.



In [ ]:

    
#@title Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Title

View on TensorFlow.org

View source on GitHub

Download notebook

[Update button links]

Overview

[Include a paragraph or two explaining what this example demonstrates, who should be interested in it, and what you need to know before you get started.]

Setup

[Put all your imports and installs up into a setup section.]



In [ ]:

    
import tensorflow as tf
import tensorflow_addons as tfa

Resources

Notebook style

Include the collapsed license at the top (uses the Colab "Form" mode to hide the cells).
Save the notebook with the table of contents open.
Use one H1 header for the title.
Include the button-bar immediately after the H1.
Include an overview section before any code.
Put all your installs and imports in a setup section.
Write Python 3 compatible code. You don't have to worry about Python 2 compatibility.
Keep code and text cells as brief as possible.
Avoid leaving an empty cell at the end of the notebook.

Code style

Notebooks are for people. Write code optimized for clarity.
Keep examples quick. Use small datasets, or small slices of datasets. Don't train to convergence, train until it's obvious it's making progress.
Demonstrate small parts before combining them into something more complex, like this:



In [ ]:

    
# Build the model
model = tf.keras.Sequential([
    tf.keras.layers.Dense(10, activation='relu', input_shape=(None, 5)),
    tf.keras.layers.Dense(3)
])

Run the model on a single batch of data, and inspect the output:



In [ ]:

    
import numpy as np

result = model(tf.constant(np.random.randn(10,5), dtype = tf.float32)).numpy()

print("min:", result.min())
print("max:", result.max())
print("mean:", result.mean())
print("shape:", result.shape)

Compile the model for training:



In [ ]:

    
model.compile(optimizer=tf.keras.optimizers.Adam(),
              loss=tf.keras.losses.categorical_crossentropy)

Code content

Use the highest level API that gets the job done (unless the goal is to demonstrate the low level API).
Use keras.Sequential > keras functional api > keras model subclassing > ...
Use model.fit > model.train_on_batch > manual GradientTapes.
Use eager-style code.
Use tensorflow_datasets and tf.data where possible.
Avoid compat.v1.

Text

Use an imperative style. "Run a batch of images through the model."
Use sentence case in titles/headings.
Use short titles/headings: "Download the data", "Build the Model", "Train the model".
Use the Google developer documentation style guide.

GitHub workflow

Be consistent about how you save your notebooks, otherwise the JSON diffs are messy.
This notebook has the "Omit code cell output when saving this notebook" option set. GitHub refuses to diff notebooks with large diffs (inline images).
ReviewNB.com can help with diffs. This is linked in a comment on a notebook pull request.
Use the Open in Colab extension to open a GitHub notebook in Colab.
The easiest way to edit a notebook in GitHub is to open it with Colab from the branch you want to edit. Then use File --> Save a copy in GitHub, which will save it back to the branch you opened it from.
For PRs it's helpful to post a direct Colab link to the PR head: