docs/overview.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6XvCUmCEd4Dm"
      },
      "source": [
        "# TensorFlow Datasets\n",
        "\n",
        "TFDS provides a collection of ready-to-use datasets for use with TensorFlow, Jax, and other Machine Learning frameworks.\n",
        "\n",
        "It handles downloading and preparing the data deterministically and constructing a `tf.data.Dataset` (or `np.array`).\n",
        "\n",
        "Note: Do not confuse [TFDS](https://www.tensorflow.org/datasets) (this library) with `tf.data` (TensorFlow API to build efficient data pipelines). TFDS is a high level wrapper around `tf.data`. If you're not familiar with this API, we encourage you to read [the official tf.data guide](https://www.tensorflow.org/guide/data) first.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "J8y9ZkLXmAZc"
      },
      "source": [
        "Copyright 2018 The TensorFlow Datasets Authors, Licensed under the Apache License, Version 2.0"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "OGw9EgE0tC0C"
      },
      "source": [
        "\u003ctable class=\"tfo-notebook-buttons\" align=\"left\"\u003e\n",
        "  \u003ctd\u003e\n",
        "    \u003ca target=\"_blank\" href=\"https://www.tensorflow.org/datasets/overview\"\u003e\u003cimg src=\"https://www.tensorflow.org/images/tf_logo_32px.png\" /\u003eView on TensorFlow.org\u003c/a\u003e\n",
        "  \u003c/td\u003e\n",
        "  \u003ctd\u003e\n",
        "    \u003ca target=\"_blank\" href=\"https://colab.research.google.com/github/tensorflow/datasets/blob/master/docs/overview.ipynb\"\u003e\u003cimg src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" /\u003eRun in Google Colab\u003c/a\u003e\n",
        "  \u003c/td\u003e\n",
        "  \u003ctd\u003e\n",
        "    \u003ca target=\"_blank\" href=\"https://github.com/tensorflow/datasets/blob/master/docs/overview.ipynb\"\u003e\u003cimg src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" /\u003eView source on GitHub\u003c/a\u003e\n",
        "  \u003c/td\u003e\n",
        "  \u003ctd\u003e\n",
        "    \u003ca href=\"https://storage.googleapis.com/tensorflow_docs/datasets/docs/overview.ipynb\"\u003e\u003cimg src=\"https://www.tensorflow.org/images/download_logo_32px.png\" /\u003eDownload notebook\u003c/a\u003e\n",
        "  \u003c/td\u003e\n",
        "\u003c/table\u003e"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "_7hshda5eaGL"
      },
      "source": [
        "## Installation\n",
        "\n",
        "TFDS exists in two packages:\n",
        "\n",
        "* `pip install tensorflow-datasets`: The stable version, released every few months.\n",
        "* `pip install tfds-nightly`: Released every day, contains the last versions of the datasets.\n",
        "\n",
        "This colab uses `tfds-nightly`:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "cellView": "both",
        "id": "boeZp0sYbO41"
      },
      "outputs": [],
      "source": [
        "!pip install -q tfds-nightly tensorflow matplotlib"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "TTBSvHcSLBzc"
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\n",
        "import numpy as np\n",
        "import tensorflow as tf\n",
        "\n",
        "import tensorflow_datasets as tfds"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "VZZyuO13fPvk"
      },
      "source": [
        "## Find available datasets\n",
        "\n",
        "All dataset builders are subclass of `tfds.core.DatasetBuilder`. To get the list of available builders, use `tfds.list_builders()` or look at our [catalog](https://www.tensorflow.org/datasets/catalog/overview)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "FAvbSVzjLCIb"
      },
      "outputs": [],
      "source": [
        "tfds.list_builders()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "VjI6VgOBf0v0"
      },
      "source": [
        "## Load a dataset\n",
        "\n",
        "### tfds.load\n",
        "\n",
        "The easiest way of loading a dataset is `tfds.load`. It will:\n",
        "\n",
        "1. Download the data and save it as [`tfrecord`](https://www.tensorflow.org/tutorials/load_data/tfrecord) files.\n",
        "2. Load the `tfrecord` and create the `tf.data.Dataset`.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "dCou80mnLLPV"
      },
      "outputs": [],
      "source": [
        "ds = tfds.load('mnist', split='train', shuffle_files=True)\n",
        "assert isinstance(ds, tf.data.Dataset)\n",
        "print(ds)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "byOXYCEJS7S6"
      },
      "source": [
        "Some common arguments:\n",
        "\n",
        "*   `split=`: Which split to read (e.g. `'train'`, `['train', 'test']`, `'train[80%:]'`,...). See our [split API guide](https://www.tensorflow.org/datasets/splits).\n",
        "*   `shuffle_files=`: Control whether to shuffle the files between each epoch (TFDS store big datasets in multiple smaller files).\n",
        "*   `data_dir=`: Location where the dataset is saved (\n",
        "defaults to `~/tensorflow_datasets/`)\n",
        "*   `with_info=True`: Returns the `tfds.core.DatasetInfo` containing dataset metadata\n",
        "*   `download=False`: Disable download\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qeNmFx_1RXCb"
      },
      "source": [
        "### tfds.builder\n",
        "\n",
        "`tfds.load` is a thin wrapper around `tfds.core.DatasetBuilder`. You can get the same output using the `tfds.core.DatasetBuilder` API:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "2zN_jQ2ER40W"
      },
      "outputs": [],
      "source": [
        "builder = tfds.builder('mnist')\n",
        "# 1. Create the tfrecord files (no-op if already exists)\n",
        "builder.download_and_prepare()\n",
        "# 2. Load the `tf.data.Dataset`\n",
        "ds = builder.as_dataset(split='train', shuffle_files=True)\n",
        "print(ds)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "IwrjccfjoQCD"
      },
      "source": [
        "### `tfds build` CLI\n",
        "\n",
        "If you want to generate a specific dataset, you can use the [`tfds` command line](https://www.tensorflow.org/datasets/cli). For example:\n",
        "\n",
        "```sh\n",
        "tfds build mnist\n",
        "```\n",
        "\n",
        "See [the doc](https://www.tensorflow.org/datasets/cli) for available flags."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "aW132I-rbJXE"
      },
      "source": [
        "## Iterate over a dataset\n",
        "\n",
        "### As dict\n",
        "\n",
        "By default, the `tf.data.Dataset` object contains a `dict` of `tf.Tensor`s:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "JAGjXdk_bIYQ"
      },
      "outputs": [],
      "source": [
        "ds = tfds.load('mnist', split='train')\n",
        "ds = ds.take(1)  # Only take a single example\n",
        "\n",
        "for example in ds:  # example is `{'image': tf.Tensor, 'label': tf.Tensor}`\n",
        "  print(list(example.keys()))\n",
        "  image = example[\"image\"]\n",
        "  label = example[\"label\"]\n",
        "  print(image.shape, label)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "sIqX2bmhu-8d"
      },
      "source": [
        "To find out the `dict` key names and structure, look at the dataset documentation in [our catalog](https://www.tensorflow.org/datasets/catalog/overview#all_datasets). For example: [mnist documentation](https://www.tensorflow.org/datasets/catalog/mnist)."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "umAtqBBqdkDG"
      },
      "source": [
        "### As tuple (`as_supervised=True`)\n",
        "\n",
        "By using `as_supervised=True`, you can get a tuple `(features, label)` instead for supervised datasets."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "nJ4O0xy3djfV"
      },
      "outputs": [],
      "source": [
        "ds = tfds.load('mnist', split='train', as_supervised=True)\n",
        "ds = ds.take(1)\n",
        "\n",
        "for image, label in ds:  # example is (image, label)\n",
        "  print(image.shape, label)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "u9palgyHfEwQ"
      },
      "source": [
        "### As numpy (`tfds.as_numpy`)\n",
        "\n",
        "Uses `tfds.as_numpy` to convert:\n",
        "\n",
        "*   `tf.Tensor` -\u003e `np.array`\n",
        "*   `tf.data.Dataset` -\u003e `Iterator[Tree[np.array]]` (`Tree` can be arbitrary nested `Dict`, `Tuple`)\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "tzQTCUkAfe9R"
      },
      "outputs": [],
      "source": [
        "ds = tfds.load('mnist', split='train', as_supervised=True)\n",
        "ds = ds.take(1)\n",
        "\n",
        "for image, label in tfds.as_numpy(ds):\n",
        "  print(type(image), type(label), label)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XaRN-LdXUkl_"
      },
      "source": [
        "### As batched tf.Tensor (`batch_size=-1`)\n",
        "\n",
        "By using `batch_size=-1`, you can load the full dataset in a single batch.\n",
        "\n",
        "This can be combined with `as_supervised=True` and `tfds.as_numpy` to get the the data as `(np.array, np.array)`:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "Gg8BNsv-UzFl"
      },
      "outputs": [],
      "source": [
        "image, label = tfds.as_numpy(tfds.load(\n",
        "    'mnist',\n",
        "    split='test',\n",
        "    batch_size=-1,\n",
        "    as_supervised=True,\n",
        "))\n",
        "\n",
        "print(type(image), image.shape)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "kRJrB3L6wgKI"
      },
      "source": [
        "Be careful that your dataset can fit in memory, and that all examples have the same shape."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "heaKNg7-X4jN"
      },
      "source": [
        "## Benchmark your datasets\n",
        "\n",
        "Benchmarking a dataset is a simple `tfds.benchmark` call on any iterable (e.g. `tf.data.Dataset`, `tfds.as_numpy`,...).\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ZyQzZ98bX3dM"
      },
      "outputs": [],
      "source": [
        "ds = tfds.load('mnist', split='train')\n",
        "ds = ds.batch(32).prefetch(1)\n",
        "\n",
        "tfds.benchmark(ds, batch_size=32)\n",
        "tfds.benchmark(ds, batch_size=32)  # Second epoch much faster due to auto-caching"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MT0yEX_4kYnV"
      },
      "source": [
        "* Do not forget to normalize the results per batch size with the `batch_size=` kwarg.\n",
        "* In the summary, the first warmup batch is separated from the other ones to capture `tf.data.Dataset` extra setup time (e.g. buffers initialization,...).\n",
        "* Notice how the second iteration is much faster due to [TFDS auto-caching](https://www.tensorflow.org/datasets/performances#auto-caching).\n",
        "* `tfds.benchmark` returns a `tfds.core.BenchmarkResult` which can be inspected for further analysis."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "o-cuwvVbeb43"
      },
      "source": [
        "### Build end-to-end pipeline\n",
        "\n",
        "To go further, you can look:\n",
        "\n",
        "*   Our [end-to-end Keras example](https://www.tensorflow.org/datasets/keras_example) to see a full training pipeline (with batching, shuffling,...).\n",
        "*   Our [performance guide](https://www.tensorflow.org/datasets/performances) to improve the speed of your pipelines (tip: use `tfds.benchmark(ds)` to benchmark your datasets).\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gTRTEQqscxAE"
      },
      "source": [
        "## Visualization\n",
        "\n",
        "### tfds.as_dataframe\n",
        "\n",
        "`tf.data.Dataset` objects can be converted to [`pandas.DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) with `tfds.as_dataframe` to be visualized on [Colab](https://colab.research.google.com).\n",
        "\n",
        "* Add the `tfds.core.DatasetInfo` as second argument of `tfds.as_dataframe` to visualize images, audio, texts, videos,...\n",
        "* Use `ds.take(x)` to only display the first `x` examples. `pandas.DataFrame` will load the full dataset in-memory, and can be very expensive to display."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "FKouwN_yVSGQ"
      },
      "outputs": [],
      "source": [
        "ds, info = tfds.load('mnist', split='train', with_info=True)\n",
        "\n",
        "tfds.as_dataframe(ds.take(4), info)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "b-eDO_EXVGWC"
      },
      "source": [
        "### tfds.show_examples\n",
        "\n",
        "`tfds.show_examples` returns a `matplotlib.figure.Figure` (only image datasets supported now):"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "DpE2FD56cSQR"
      },
      "outputs": [],
      "source": [
        "ds, info = tfds.load('mnist', split='train', with_info=True)\n",
        "\n",
        "fig = tfds.show_examples(ds, info)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Y0iVVStvk0oI"
      },
      "source": [
        "## Access the dataset metadata\n",
        "\n",
        "All builders include a `tfds.core.DatasetInfo` object containing the dataset metadata.\n",
        "\n",
        "It can be accessed through:\n",
        "\n",
        "*   The `tfds.load` API:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "UgLgtcd1ljzt"
      },
      "outputs": [],
      "source": [
        "ds, info = tfds.load('mnist', with_info=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "XodyqNXrlxTM"
      },
      "source": [
        "*   The `tfds.core.DatasetBuilder` API:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "nmq97QkilxeL"
      },
      "outputs": [],
      "source": [
        "builder = tfds.builder('mnist')\n",
        "info = builder.info"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zMGOk_ZsmPeu"
      },
      "source": [
        "The dataset info contains additional informations about the dataset (version, citation, homepage, description,...)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "O-wLIKD-mZQT"
      },
      "outputs": [],
      "source": [
        "print(info)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "1zvAfRtwnAFk"
      },
      "source": [
        "### Features metadata (label names, image shape,...)\n",
        "\n",
        "Access the `tfds.features.FeatureDict`:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "RcyZXncqoFab"
      },
      "outputs": [],
      "source": [
        "info.features"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KAm9AV7loyw5"
      },
      "source": [
        "Number of classes, label names:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "HhfzBH6qowpz"
      },
      "outputs": [],
      "source": [
        "print(info.features[\"label\"].num_classes)\n",
        "print(info.features[\"label\"].names)\n",
        "print(info.features[\"label\"].int2str(7))  # Human readable version (8 -\u003e 'cat')\n",
        "print(info.features[\"label\"].str2int('7'))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "g5eWtk9ro_AK"
      },
      "source": [
        "Shapes, dtypes:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "SergV_wQowLY"
      },
      "outputs": [],
      "source": [
        "print(info.features.shape)\n",
        "print(info.features.dtype)\n",
        "print(info.features['image'].shape)\n",
        "print(info.features['image'].dtype)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "thMOZ4IKm55N"
      },
      "source": [
        "### Split metadata (e.g. split names, number of examples,...)\n",
        "\n",
        "Access the `tfds.core.SplitDict`:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "FBbfwA8Sp4ax"
      },
      "outputs": [],
      "source": [
        "print(info.splits)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EVw1UVYa2HgN"
      },
      "source": [
        "Available splits:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "fRBieOOquDzX"
      },
      "outputs": [],
      "source": [
        "print(list(info.splits.keys()))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "iHW0VfA0t3dO"
      },
      "source": [
        "Get info on individual split:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "-h_OSpRsqKpP"
      },
      "outputs": [],
      "source": [
        "print(info.splits['train'].num_examples)\n",
        "print(info.splits['train'].filenames)\n",
        "print(info.splits['train'].num_shards)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fWhSkHFNuLwW"
      },
      "source": [
        "It also works with the subsplit API:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "HO5irBZ3uIzQ"
      },
      "outputs": [],
      "source": [
        "print(info.splits['train[15%:75%]'].num_examples)\n",
        "print(info.splits['train[15%:75%]'].file_instructions)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "YZp2XJwQQrI0"
      },
      "source": [
        "## Troubleshooting\n",
        "\n",
        "### Manual download (if download fails)\n",
        "\n",
        "If download fails for some reason (e.g. offline,...). You can always manually download the data yourself and place it in the `manual_dir` (defaults to `~/tensorflow_datasets/downloads/manual/`.\n",
        "\n",
        "To find out which urls to download, look into:\n",
        "\n",
        " * For new datasets (implemented as folder): [`tensorflow_datasets/`](https://github.com/tensorflow/datasets/tree/master/tensorflow_datasets/)`\u003ctype\u003e/\u003cdataset_name\u003e/checksums.tsv`. For example: [`tensorflow_datasets/datasets/bool_q/checksums.tsv`](https://github.com/tensorflow/datasets/blob/master/tensorflow_datasets/datasets/bool_q/checksums.tsv).\n",
        "\n",
        "   You can find the dataset source location in [our catalog](https://www.tensorflow.org/datasets/catalog/overview).\n",
        " * For old datasets: [`tensorflow_datasets/url_checksums/\u003cdataset_name\u003e.txt`](https://github.com/tensorflow/datasets/tree/master/tensorflow_datasets/url_checksums)\n",
        "\n",
        "### Fixing `NonMatchingChecksumError`\n",
        "\n",
        "TFDS ensure determinism by validating the checksums of downloaded urls.\n",
        "If `NonMatchingChecksumError` is raised, might indicate:\n",
        "\n",
        "  * The website may be down (e.g. `503 status code`). Please check the url.\n",
        "  * For Google Drive URLs, try again later as Drive sometimes rejects downloads when too many people access the same URL. See [bug](https://github.com/tensorflow/datasets/issues/1482)\n",
        "  * The original datasets files may have been updated. In this case the TFDS dataset builder should be updated. Please open a new Github issue or PR:\n",
        "     * Register the new checksums with `tfds build --register_checksums`\n",
        "     * Eventually update the dataset generation code.\n",
        "     * Update the dataset `VERSION`\n",
        "     * Update the dataset `RELEASE_NOTES`: What caused the checksums to change ? Did some examples changed ?\n",
        "     * Make sure the dataset can still be built.\n",
        "     * Send us a PR\n",
        "\n",
        "Note: You can also inspect the downloaded file in `~/tensorflow_datasets/download/`.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "GmeeOokMODg2"
      },
      "source": [
        "## Citation\n",
        "\n",
        "If you're using `tensorflow-datasets` for a paper, please include the following citation, in addition to any citation specific to the used datasets (which can be found in the [dataset catalog](https://www.tensorflow.org/datasets/catalog/overview)).\n",
        "\n",
        "```\n",
        "@misc{TFDS,\n",
        "  title = { {TensorFlow Datasets}, A collection of ready-to-use datasets},\n",
        "  howpublished = {\\url{https://www.tensorflow.org/datasets}},\n",
        "}\n",
        "```"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "collapsed_sections": [],
      "name": "tensorflow/datasets",
      "private_outputs": true,
      "provenance": [],
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}