docs/tutorials/_template.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Tce3stUlHN0L"
   },
   "source": [
    "##### Copyright 2019 The TensorFlow Authors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 0,
   "metadata": {
    "cellView": "form",
    "colab": {},
    "colab_type": "code",
    "id": "tuOe1ymfHZPu"
   },
   "outputs": [],
   "source": [
    "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
    "# you may not use this file except in compliance with the License.\n",
    "# You may obtain a copy of the License at\n",
    "#\n",
    "# https://www.apache.org/licenses/LICENSE-2.0\n",
    "#\n",
    "# Unless required by applicable law or agreed to in writing, software\n",
    "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
    "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
    "# See the License for the specific language governing permissions and\n",
    "# limitations under the License."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "qFdPvlXBOdUN"
   },
   "source": [
    "# Title"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "MfBg1C5NB3X0"
   },
   "source": [
    "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://www.tensorflow.org/addons/tutorials/image_ops\"><img src=\"https://www.tensorflow.org/images/tf_logo_32px.png\" />View on TensorFlow.org</a>\n",
    "  </td>\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/tensorflow/addons/blob/master/docs/tutorials/_template.ipynb\"><img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
    "  </td>\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://github.com/tensorflow/addons/blob/master/docs/tutorials/_template.ipynb\"><img src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" />View source on GitHub</a>\n",
    "  </td>\n",
    "      <td>\n",
    "    <a href=\"https://storage.googleapis.com/tensorflow_docs/docs/docs/tutorials/image_ops.ipynb\"><img src=\"https://www.tensorflow.org/images/download_logo_32px.png\" />Download notebook</a>\n",
    "  </td>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "r6P32iYYV27b"
   },
   "source": [
    "[Update button links]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "xHxb-dlhMIzW"
   },
   "source": [
    "## Overview\n",
    "\n",
    "[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.]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "MUXex9ctTuDB"
   },
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "1Eh-iCRVBm0p"
   },
   "source": [
    "[Put all your imports and installs up into a setup section.]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "IqR2PQG4ZaZ0"
   },
   "outputs": [],
   "source": [
    "try:\n",
    "  %tensorflow_version 2.x\n",
    "except:\n",
    "  pass\n",
    "\n",
    "import tensorflow as tf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: tensorflow-addons~=0.6 in /usr/local/google/home/markdaoust/venv3/lib/python3.6/site-packages (0.6.0)\r\n"
     ]
    }
   ],
   "source": [
    "!pip install --no-deps tensorflow-addons~=0.7"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import tensorflow_addons as tfa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "UhNtHfuxCGVy"
   },
   "source": [
    "## Resources\n",
    "\n",
    "* [TensorFlow documentation contributor guide](https://www.tensorflow.org/community/contribute/docs)\n",
    "* [TensorFlow documentation style guide](https://www.tensorflow.org/community/contribute/docs_style)\n",
    "* [Google developer documentation style guide](https://developers.google.com/style/highlights)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "2V22fKegUtF9"
   },
   "source": [
    "## Notebook style\n",
    "\n",
    "* Include the collapsed license at the top (uses the Colab \"Form\" mode to hide the cells).\n",
    "* Save the notebook with the table of contents open.\n",
    "* Use one `H1` header for the title.\n",
    "* Include the button-bar immediately after the `H1`.\n",
    "* Include an overview section before any code.\n",
    "* Put all your installs and imports in a setup section.\n",
    "* Write Python 3 compatible code. You don't have to worry about Python 2 compatibility.\n",
    "* Keep code and text cells as brief as possible.\n",
    "* Avoid leaving an empty cell at the end of the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "QKp40qS-DGEZ"
   },
   "source": [
    "### Code style\n",
    "\n",
    "* Notebooks are for people. Write code optimized for clarity.\n",
    "* 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.\n",
    "* Demonstrate small parts before combining them into something more complex, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 0,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "KtylpxOmceaC"
   },
   "outputs": [],
   "source": [
    "# Build the model\n",
    "model = tf.keras.Sequential([\n",
    "    tf.keras.layers.Dense(10, activation='relu', input_shape=(None, 5)),\n",
    "    tf.keras.layers.Dense(3)\n",
    "])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "pwdM2pl3RSPb"
   },
   "source": [
    "Run the model on a single batch of data, and inspect the output:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 0,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "mMOeXVmbdilM"
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "result = model(tf.constant(np.random.randn(10,5), dtype = tf.float32)).numpy()\n",
    "\n",
    "print(\"min:\", result.min())\n",
    "print(\"max:\", result.max())\n",
    "print(\"mean:\", result.mean())\n",
    "print(\"shape:\", result.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "uabQmjMtRtzs"
   },
   "source": [
    "Compile the model for training:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 0,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "U82B_tH2d294"
   },
   "outputs": [],
   "source": [
    "model.compile(optimizer=tf.keras.optimizers.Adam(),\n",
    "              loss=tf.keras.losses.categorical_crossentropy)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "TJdqBNBbS78n"
   },
   "source": [
    "### Code content\n",
    "\n",
    "* Use the highest level API that gets the job done (unless the goal is to demonstrate the low level API).\n",
    "* Use `keras.Sequential` > keras functional api > keras model subclassing > ...\n",
    "* Use `model.fit` > `model.train_on_batch` > manual `GradientTapes`.\n",
    "* Use eager-style code.\n",
    "* Use `tensorflow_datasets` and `tf.data` where possible.\n",
    "* Avoid `compat.v1`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "78HBT9cQXJko"
   },
   "source": [
    "### Text\n",
    "\n",
    "* Use an imperative style. \"Run a batch of images through the model.\"\n",
    "* Use sentence case in titles/headings. \n",
    "* Use short titles/headings: \"Download the data\", \"Build the Model\", \"Train the model\".\n",
    "* Use the [Google developer documentation style guide](https://developers.google.com/style/highlights).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "YrsKXcPRUvK9"
   },
   "source": [
    "## GitHub workflow\n",
    "\n",
    "* Be consistent about how you save your notebooks, otherwise the JSON diffs are messy.\n",
    "* This notebook has the \"Omit code cell output when saving this notebook\" option set. GitHub refuses to diff notebooks with large diffs (inline images).\n",
    "* [ReviewNB.com](http://reviewnb.com) can help with diffs. This is linked in a comment on a notebook pull request.\n",
    "* Use the [Open in Colab](https://chrome.google.com/webstore/detail/open-in-colab/iogfkhleblhcpcekbiedikdehleodpjo) extension to open a GitHub notebook in Colab.\n",
    "* 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.\n",
    "* For PRs it's helpful to post a direct Colab link to the PR head: https://colab.research.google.com/github/{USER}/{REPO}/blob/{BRANCH}/{PATH}.ipynb"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [
    "Tce3stUlHN0L"
   ],
   "name": "template.ipynb",
   "private_outputs": true,
   "provenance": [],
   "toc_visible": true,
   "version": "0.3.2"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}