intro-to-binder.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "This notebook was shamelessly copied from the Data Carpentry lesson on sharing your work: https://github.com/Reproducible-Science-Curriculum/sharing-RR-Jupyter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Sharing an interactive repository with Binder\n",
    "\n",
    "<img src=\"https://mybinder.org/static/logo.svg?v=f9f0d927b67cc9dc99d788c822ca21c0\" style=\"float: left; height:150px\" />\n",
    "\n",
    "<div style=\"clear: both\"></div>\n",
    "*(press space to continue, shift+space to go back)*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "* GitHub is a great service for sharing your code, but the materials in a GitHub repository are static."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* How could you *run* a GitHub repository in your browser?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Running code is more complicated than displaying code\n",
    "\n",
    "To run code, you need (at least) the following things:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Hardware on which to run code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* All the software needed to run your code, including:\n",
    "  1. The code itself.\n",
    "  2. Hardware for running your programming language\n",
    "  3. Something to run your code (e.g., `python`, `r`)\n",
    "  4. Packages needed to run the code (e.g., `pandas`, `matplotlib`)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Binder provides these things\n",
    "\n",
    "Binder is a service that provides your code, the hardware, and the software."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "You can create a link to a **live, interactive** version of your code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Here's an example of a Binder link:\n",
    "\n",
    "https://mybinder.org/v2/gh/trekhleb/homemade-machine-learning/master?filepath=notebooks%2Fanomaly_detection%2Fanomaly_detection_gaussian_demo.ipynb\n",
    "\n",
    "Clicking it will create a *live* version of the repository (a collection of notebooks\n",
    "that introduce you to machine learning). Because the link has a \"filepath\" argument,\n",
    "it will open the notebook on anomaly detection.\n",
    "\n",
    "Here's the repository that you've just run:\n",
    "\n",
    "https://github.com/trekhleb/homemade-machine-learning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Note**: The Binder link has a very similar structure to the github repository link!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Build your Binder\n",
    "\n",
    "To build a Binder go to `mybinder.org` and paste in the URL of your repository, like so:\n",
    "\n",
    "<img src=\"./fig/binder_gui.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Share your Binder link with others\n",
    "\n",
    "Now that you've got a Binder, you can share a link that will let others interact with it.\n",
    "\n",
    "This link is listed in the Binder GUI and should update itself as you fill in the forms. Copy the link and share it with your friends!\n",
    "\n",
    "<img src=\"./fig/binder_link.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## A README.md for the computer\n",
    "\n",
    "If you are using other packages, you need tell Binder what to do!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "We need to create a file to specify which software we need.\n",
    "\n",
    "In python, that file is called `requirements.txt`.\n",
    "\n",
    "We also need to include any additional resources (e.g., any data files we need like `gapminder.csv`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Create a new file\n",
    "\n",
    "Using the GitHub GUI, click the \"create new file\" button. This will open a text editor where you can create a new file in your GitHub repository.\n",
    "\n",
    "<img src=\"./fig/click_new_file.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Add software dependencies to this file\n",
    "\n",
    "In the \"new file\" GUI, we'll write down the software needed to run this code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "In our case, this means `matplotlib` and `pandas`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We'll call this file `requirements.txt`, as these are the **requirements** for running the code.\n",
    "\n",
    "<img src=\"./fig/populate_file.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Now build your Binder\n",
    "\n",
    "To build a Binder go to `mybinder.org` & click `launch` to build your Binder\n",
    "\n",
    "Binder will find your `requirements.txt` and provides the software for running your code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "This may take a while!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "When it's ready, Binder will link you to a live Jupyter Notebook session running in the cloud!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Wrapping up\n",
    "\n",
    "In this section we started with a static GitHub repository with Jupyter Notebooks inside. We then..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Created a file called `requirements.txt` that specified which software was needed to run our code.\n",
    "* Used the `mybinder.org` interface to build a Binder from this repository.\n",
    "* Created a Binder link in order to share our interactive repository with others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Next steps\n",
    "\n",
    "There are many more workflows that you can enable with Binder, and we recommend checking out a list of example Binder repositories at:\n",
    "\n",
    "https://github.com/binder-examples/\n",
    "\n",
    "Look for, and click, the Binder Badge:\n",
    "\n",
    "<img src=\"https://mybinder.org/badge.svg\" style=\"float: left;\">\n",
    "\n",
    "<br /><br />to explore the repository's Binder!"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.5"
  },
  "livereveal": {
   "autolaunch": true,
   "scroll": true,
   "start_slideshow_at": "selected"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}