examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "view-in-github"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "RK255E7YoEIt"
      },
      "source": [
        "# DeepLabCut Toolbox - Colab for standard (single animal) projects!\n",
        "https://github.com/DeepLabCut/DeepLabCut\n",
        "\n",
        "This notebook illustrates how to use the cloud to:\n",
        "- create a training set\n",
        "- train a network\n",
        "- evaluate a network\n",
        "- create simple quality check plots\n",
        "- analyze novel videos!\n",
        "\n",
        "###This notebook assumes you already have a project folder with labeled data! \n",
        "\n",
        "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",
        "\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": {
        "colab_type": "text",
        "id": "txoddlM8hLKm"
      },
      "source": [
        "## First, go to \"Runtime\" ->\"change runtime type\"->select \"Python3\", and then select \"GPU\"\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "q23BzhA6CXxu"
      },
      "outputs": [],
      "source": [
        "#(this will take a few minutes to install all the dependences!)\n",
        "!pip install deeplabcut"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "25wSj6TlVclR"
      },
      "source": [
        "**(Be sure to click \"RESTART RUNTIME\" if it is displayed above before moving on !)**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "cQ-nlTkri4HZ"
      },
      "source": [
        "## Link your Google Drive (with your labeled data, or the demo data):\n",
        "\n",
        "### First, place your project folder into you google drive! \"i.e. move the folder named \"Project-YourName-TheDate\" into google drive."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "KS4Q4UkR9rgG"
      },
      "outputs": [],
      "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')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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",
        "Typically, this will be: /content/drive/My Drive/yourProjectFolderName\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "vhENAlQnFENJ"
      },
      "outputs": [],
      "source": [
        "#Setup your project variables:\n",
        "# PLEASE EDIT THESE:\n",
        "  \n",
        "ProjectFolderName = 'myproject-teamDLC-2020-03-29'\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"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "3K9Ndy1beyfG"
      },
      "outputs": [],
      "source": [
        "import deeplabcut"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "o4orkg9QTHKK"
      },
      "outputs": [],
      "source": [
        "deeplabcut.__version__"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "Z7ZlDr3wV4D1"
      },
      "outputs": [],
      "source": [
        "#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"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "eMeUwgxPoEJP",
        "scrolled": true
      },
      "outputs": [],
      "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 netowkr to use!\n",
        "#check the docstring for full options you can do!\n",
        "deeplabcut.create_training_dataset(path_config_file, net_type='resnet_50', augmenter_type='imgaug')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "c4FczXGDoEJU"
      },
      "source": [
        "## Start training:\n",
        "This function trains the network for a specific shuffle of the training dataset. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "_pOvDq_2oEJW"
      },
      "outputs": [],
      "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/wiki/DOCSTRINGS#train_network\n",
        "\n",
        "deeplabcut.train_network(path_config_file, shuffle=1, 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...."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "RiDwIVf5-3H_"
      },
      "source": [
        "**When you hit \"STOP\" you will get a KeyInterrupt \"error\"! No worries! :)**"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "id": "xZygsb2DoEJc"
      },
      "source": [
        "## Start evaluating:\n",
        "This function 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",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "nv4zlbrnoEJg"
      },
      "outputs": [],
      "source": [
        "%matplotlib notebook\n",
        "deeplabcut.evaluate_network(path_config_file,plotting=True)\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 ;)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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",
        "- Please see the repo and protocol instructions on how to refine your data!"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "Y_LZiS_0oEJl"
      },
      "outputs": [],
      "source": [
        "deeplabcut.analyze_videos(path_config_file,videofile_path, videotype=VideoType)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "gX21zZbXoEKJ"
      },
      "outputs": [],
      "source": [
        "deeplabcut.plot_trajectories(path_config_file,videofile_path, videotype=VideoType)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "colab_type": "text",
        "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": {
        "colab_type": "text",
        "id": "pCrUvQIvoEKD"
      },
      "source": [
        "## Create labeled video:\n",
        "This function 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",
      "execution_count": null,
      "metadata": {
        "colab": {},
        "colab_type": "code",
        "id": "6aDF7Q7KoEKE"
      },
      "outputs": [],
      "source": [
        "deeplabcut.create_labeled_video(path_config_file,videofile_path, videotype=VideoType)"
      ]
    }
  ],
  "metadata": {
    "accelerator": "GPU",
    "colab": {
      "collapsed_sections": [],
      "include_colab_link": true,
      "name": "Copy of latest_Colab_TrainNetwork_VideoAnalysis.ipynb",
      "provenance": [],
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3.8.12 ('dlc')",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.8.12"
    },
    "vscode": {
      "interpreter": {
        "hash": "70cad038f2bddb56e8a0ba66c48b76ebce20579892bf83e71733a81977e3ceea"
      }
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}