Colab_TrainNetwork_VideoAnalysis_TF2.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "Colab_TrainNetwork_VideoAnalysis_TF2.ipynb",
      "provenance": [],
      "collapsed_sections": [],
      "include_colab_link": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "accelerator": "GPU"
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/MMathisLab/DeepLabCut-core/blob/master/Colab_TrainNetwork_VideoAnalysis_TF2.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "RK255E7YoEIt"
      },
      "source": [
        "# DeepLabCut 2+ Toolbox | Colab for TensorFlow 2+\n",
        "https://github.com/DeepLabCut/DeepLabCut\n",
        "\n",
        "![alt text](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1607087333173-TG4DRQR5WZ6ETXAJHXEO/ke17ZwdGBToddI8pDm48kKdgWGJOTWy1pqJZDMO95txZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZUJFbgE-7XRK3dMEBRBhUpwsA4PS9IFCXiEkiYtvZKsVufHa_vZp4Er3aXh9hA8Hg33vCVX1-CYF3ghyfBsW8js/dlcTF.png?format=1500w)\n",
        "\n",
        "This notebook illustrates how to use colab:\n",
        "- create a training set\n",
        "- train a network\n",
        "- evaluate a network\n",
        "- create simple quality check plots\n",
        "- analyze novel videos, filter data, create videos\n",
        "\n",
        "###This notebook assumes you already have a project folder with labeled data.\n",
        "\n",
        "NOTE: This notebook demonstrates the necessary steps to use DeepLabCut for your own project.\n",
        "\n",
        "This shows the most simple code to do so, but many of the functions have additional features, so please check out the overview & the protocol paper.\n",
        "\n",
        "Nath\\*, Mathis\\* et al.: Using DeepLabCut for markerless pose estimation during behavior across species. Nature Protocols, 2019.\n",
        "\n",
        "Paper: https://www.nature.com/articles/s41596-019-0176-0\n",
        "\n",
        "Pre-print: https://www.biorxiv.org/content/biorxiv/early/2018/11/24/476531.full.pdf\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "txoddlM8hLKm"
      },
      "source": [
        "## First, go to \"Runtime\" ->\"change runtime type\"->select \"Python3\", and then select \"GPU\"\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "q23BzhA6CXxu"
      },
      "source": [
        "#Install the branch with tf2.x support:\n",
        "!pip install git+https://github.com/DeepLabCut/DeepLabCut-core.git\n",
        "!pip install tf_slim"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "25wSj6TlVclR"
      },
      "source": [
        "**(Be sure to click \"RESTART RUNTIME\" is it is displayed above above before moving on !)**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "cQ-nlTkri4HZ"
      },
      "source": [
        "## Link your Google Drive:\n",
        "\n",
        "### First, place your whole porject folder into you google drive! \"i.e. move the folder named \"Project-YourName-TheDate\" into google drive. This should be done after labeling, but before creating a training set. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "KS4Q4UkR9rgG"
      },
      "source": [
        "#Now, let's link to your GoogleDrive. Run this cell and follow the authorization instructions:\n",
        "#(We recommend putting a copy of the github repo in your google drive if you are using the demo \"examples\")\n",
        "\n",
        "from google.colab import drive\n",
        "drive.mount('/content/drive')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Frnj1RVDyEqs"
      },
      "source": [
        "YOU WILL NEED TO EDIT THE PROJECT PATH **in the config.yaml file** TO BE SET TO YOUR GOOGLE DRIVE LINK!\n",
        "\n",
        "You can simply double click on the file on the left, and edit within colab to have the correct path name set.\n",
        "\n",
        "Typically, this will be: /content/drive/My Drive/yourProjectFolderName\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "vhENAlQnFENJ"
      },
      "source": [
        "#Setup your project variables:\n",
        "# PLEASE EDIT THESE:\n",
        "ProjectFolderName = 'yourproject-DLC-2020-12-04' \n",
        "VideoType = 'mp4' \n",
        "\n",
        "#don't edit these:\n",
        "videofile_path = ['/content/drive/My Drive/'+ProjectFolderName+'/videos/'] #Enter the list of videos or folder to analyze.\n",
        "videofile_path\n",
        "\n",
        "#This creates a path variable that links to your google drive copy\n",
        "#No need to edit this, as you set it up before: \n",
        "path_config_file = '/content/drive/My Drive/'+ProjectFolderName+'/config.yaml'\n",
        "path_config_file"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "3K9Ndy1beyfG"
      },
      "source": [
        "import deeplabcutcore as deeplabcut\n",
        "import tensorflow\n",
        "tensorflow.__version__"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "xNi9s1dboEJN"
      },
      "source": [
        "## Create a training dataset:\n",
        "### You must do this step inside of Colab:\n",
        "After running this script the training dataset is created and saved in the project directory under the subdirectory **'training-datasets'**\n",
        "\n",
        "This function also creates new subdirectories under **dlc-models** and appends the project config.yaml file with the correct path to the training and testing pose configuration file. These files hold the parameters for training the network. Such an example file is provided with the toolbox and named as **pose_cfg.yaml**.\n",
        "\n",
        "Now it is the time to start training the network!"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "lFuQndbvBFUR"
      },
      "source": [
        "#Set the shuffle you want to create, train, evaluate, use for analysis, etc (1 is default):\n",
        "SHUF = 1"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "scrolled": true,
        "id": "eMeUwgxPoEJP"
      },
      "source": [
        "# Note: if you are using the demo data (i.e. examples/Reaching-Mackenzie-2018-08-30/), first delete the folder called dlc-models! \n",
        "#Then, run this cell. There are many more functions you can set here, including which network to use.\n",
        "#check the docstring for full options you can do!\n",
        "deeplabcut.create_training_dataset(path_config_file, net_type='resnet_50', Shuffles=[SHUF], augmenter_type='imgaug')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "c4FczXGDoEJU"
      },
      "source": [
        "## Start training:\n",
        "This function trains the network for a specific shuffle of the training dataset. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "_pOvDq_2oEJW"
      },
      "source": [
        "#let's also change the display and save_iters just in case Colab takes away the GPU... \n",
        "#if that happens, you can reload from a saved point. Typically, you want to train to 200,000 + iterations.\n",
        "#more info and there are more things you can set: https://github.com/DeepLabCut/DeepLabCut/blob/master/docs/functionDetails.md#g-train-the-network\n",
        "\n",
        "deeplabcut.train_network(path_config_file, shuffle=SHUF, displayiters=10,saveiters=500)\n",
        "\n",
        "#this will run until you stop it (CTRL+C), or hit \"STOP\" icon, or when it hits the end (default, 1.03M iterations). \n",
        "#Whichever you chose, you will see what looks like an error message, but it's not an error - don't worry...."
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "RiDwIVf5-3H_"
      },
      "source": [
        "**When you hit \"STOP\" you will get a KeyInterrupt \"error\"! No worries! :)**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "xZygsb2DoEJc"
      },
      "source": [
        "## Start evaluating:\n",
        "This funtion evaluates a trained model for a specific shuffle/shuffles at a particular state or all the states on the data set (images)\n",
        "and stores the results as .csv file in a subdirectory under **evaluation-results**"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "nv4zlbrnoEJg"
      },
      "source": [
        "deeplabcut.evaluate_network(path_config_file,Shuffles=[SHUF], plotting=False)\n",
        "\n",
        "# Here you want to see a low pixel error! Of course, it can only be as good as the labeler, \n",
        "#so be sure your labels are good! (And you have trained enough ;). \n",
        "# Also note that the test is typically on only a few images, so also good to look\n",
        "# at video performance (below)."
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "BaLBl3TQtrfB"
      },
      "source": [
        "## There is an optional refinement step you can do outside of Colab:\n",
        "- if your pixel errors are not low enough, please check out the protocol guide on how to refine your network!\n",
        "- You will need to adjust the labels **outside of Colab!** We recommend coming back to train and analyze videos... \n",
        "- pplease see the repo and protocol instructions on how to refine your data!"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "OVFLSKKfoEJk"
      },
      "source": [
        "## Start Analyzing videos: \n",
        "This function analyzes the new video. The user can choose the best model from the evaluation results and specify the correct snapshot index for the variable **snapshotindex** in the **config.yaml** file. Otherwise, by default the most recent snapshot is used to analyse the video.\n",
        "\n",
        "The results are stored in hd5 file in the same directory where the video resides. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "Y_LZiS_0oEJl"
      },
      "source": [
        "deeplabcut.analyze_videos(path_config_file, videofile_path, videotype=VideoType, shuffle=SHUF)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LrkIDiciSWH1"
      },
      "source": [
        "You can also now filter your data to smooth any small jitters:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "X8SmVAIkSbLp"
      },
      "source": [
        "deeplabcut.filterpredictions(path_config_file, videofile_path, videotype=VideoType, shuffle=SHUF)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "8GTiuJESoEKH"
      },
      "source": [
        "## Plot the trajectories of the analyzed videos:\n",
        "This function plots the trajectories of all the body parts across the entire video. Each body part is identified by a unique color."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "gX21zZbXoEKJ"
      },
      "source": [
        "import matplotlib\n",
        "deeplabcut.plot_trajectories(path_config_file, videofile_path, videotype=VideoType, shuffle=SHUF, filtered=True)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pqaCw15v8EmB"
      },
      "source": [
        "Now you can look at the plot-poses file and check the \"plot-likelihood.png\" might want to change the \"p-cutoff\" in the config.yaml file so that you have only high confidnece points plotted in the video. i.e. ~0.8 or 0.9. The current default is 0.4. "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "pCrUvQIvoEKD"
      },
      "source": [
        "## Create labeled video:\n",
        "This funtion is for visualiztion purpose and can be used to create a video in .mp4 format with labels predicted by the network. This video is saved in the same directory where the original video resides. "
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "6aDF7Q7KoEKE"
      },
      "source": [
        "deeplabcut.create_labeled_video(path_config_file,videofile_path, videotype=VideoType, shuffle=SHUF, filtered=True)"
      ],
      "execution_count": null,
      "outputs": []
    }
  ]
}