2016-07-20-notes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# UBC Scientific Software Seminar\n",
    "\n",
    "## July 20, 2016\n",
    "\n",
    "Today's Agenda:\n",
    "\n",
    "1. JupyterHub\n",
    "2. Jupyter Notebooks\n",
    "3. Git/GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. JupyterHub\n",
    "\n",
    "[JupyterHub](https://pims.jupyter.ca) is a web service provided by the [Pacific Institute for the Mathematical Sciences (PIMS)](http://www.pims.math.ca/) and hosts [Jupyter](http://jupyter.org/) notebooks (such as this document itself) for UBC students, fellows and faculty (via CWL login). When you login to JupyterHub, you see your home directory and various tabs to create files and folders, create notebooks, check which processes are running, etc. Essentially, your JupyterHub account is a Linux machine which is running remotely on a server provided by PIMS and you interact with your remote machine via a browser on your local device.\n",
    "\n",
    "\n",
    "## 2. Jupyter Notebooks\n",
    "\n",
    "A [Jupyter notebook](https://jupyter.org) is a web application which allows you to write markdown and execute code all in the browser. To get started with a new Jupyter notebook with a Python 3 kernel, click the `New` tab in the top right corner of the JupyterHub main page and then click `Python 3`. This will open a notebook in a new tab in your browser.\n",
    "\n",
    "Cells in a notebook contain markdown code or Python code depending of the setting in the toolbar. [Markdown](https://en.wikipedia.org/wiki/Markdown) is a markup language simply designed to easily convert to HTML. See this [guide](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for a quick intro to markdown. Here are some examples:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**Headings:** Create headings with hashes `#`, `##`, `###`, etc. For example, in a new markdown cell, type the following:\n",
    "\n",
    "```\n",
    "### A Heading for a New Section\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce:\n",
    "\n",
    "### A Heading for a New Section"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**Links:** Create a link with the syntax `[text](url)`. For example, in a new markdown cell, type the following:\n",
    "\n",
    "```\n",
    "[A Link to GitHub](https://github.com/)\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce:\n",
    "\n",
    "[A Link to GitHub](https://github.com/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**LaTeX:** LaTeX code in a markdown cell will be rendered as LaTeX. For example, in a markdown cell, type:\n",
    "\n",
    "```\n",
    "$$\\int_a^b f(x) \\ dx = F(b) - F(a)$$\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce\n",
    "\n",
    "$$\\int_a^b f(x) \\ dx = F(b) - F(a)$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**Lists:** Use asterisks to create unordered lists. For example, in a new markdown cell, type the following:\n",
    "\n",
    "```\n",
    "* Python\n",
    "* C++\n",
    "* JavaScript\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce:\n",
    "\n",
    "* Python\n",
    "* C++\n",
    "* JavaScript"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "**Images:** Include an image with the syntax `![text](url)`. For example, in a new markdown cell, type the following:\n",
    "\n",
    "```\n",
    "![Python Logo](https://www.python.org/static/community_logos/python-logo-master-v3-TM.png)\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce:\n",
    "\n",
    "![Python Logo](https://www.python.org/static/community_logos/python-logo-master-v3-TM.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "**Python Code:** In a new cell, use the toolbar to set the selected cell to `Code` and type the following:\n",
    "\n",
    "```python\n",
    "for n in range(0,4):\n",
    "    print(n,\"squared is equal to\",n**2)\n",
    "```\n",
    "\n",
    "and hit `Shift + Enter` to produce the output:\n",
    "\n",
    "```\n",
    "0 squared is equal to 0\n",
    "1 squared is equal to 1\n",
    "2 squared is equal to 4\n",
    "3 squared is equal to 9\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 2.1: Create a Jupyter notebook about a project you are working on\n",
    "\n",
    "Create a new Jupyter notebook with a Python 3 kernel and write a short description of a project you are working on or interested in. Use markdown cells including text, link, images, headings, lists and LaTeX, and use code cells to execute Python code. Take your time because we're going to be pushing these notebooks to GitHub in a later exercise."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Git/GitHub\n",
    "\n",
    "[GitHub](https://github.com) is a website (which is different from [JupyterHub](https://pims.jupyter.ca/)) which hosts Git repositories. [Git](https://git-scm.com/) is an open source, version control software used to manage and share software projects. We will be using Git and GitHub repeatedly in this seminar and so we won't explore all the details right now. Rather, we'll learn the basics and then repeat and build on these topics and commands over the next few weeks.\n",
    "\n",
    "A Git repository is a directory (aka folder) which Git is tracking and recording changes – it is very powerful! Using Git and GitHub is a steep learning curve and the following are some helpful resources:\n",
    "\n",
    "* [GitHub Help](https://help.github.com/)\n",
    "* [Git documentation](https://git-scm.com/)\n",
    "* [GitHub Training on YouTube](https://www.youtube.com/watch?v=8oRjP8yj2Wo&list=PLg7s6cbtAD165JTRsXh8ofwRw0PqUnkVH)\n",
    "\n",
    "**Before getting started**, we need to configure your Git seetings on JupyterHub (see [GitHub Help](https://help.github.com/articles/set-up-git/)):\n",
    "\n",
    "* Sign in to you JupyterHub account\n",
    "* Open a new terminal (by clicking `New > Terminal` in the top right of the main JupyterHub page)\n",
    "* In the terminal, enter the commands:\n",
    "    * `git config --global user.name \"YOUR NAME\"`\n",
    "    * `git config --global user.email \"YOUR EMAIL ADDRESS\"`\n",
    "* The email address you enter should match the one you used to setup your GitHub account (this is how GitHub identifies your GitHub account)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 3.1: Create a repository on GitHub\n",
    "\n",
    "Create a new repository on GitHub (for the exercises to be completed during the seminar):\n",
    "\n",
    "* Open a new tab in your browser and sign in to your [GitHub](https://github.com/) account\n",
    "* Click `+` in the top right corner of your browser window and click `New repository`\n",
    "* You are navigated to a new page:\n",
    "    * Enter the repository name `ubcs3-exercises`\n",
    "    * Enter a description of the repository (such as `\"A collection of exercises completed during the UBC Scientific Software Seminar\"`)\n",
    "    * Choose to make the repository `Public`\n",
    "    * Choose to initialize the repository with a `README.md` file\n",
    "    * Click `Create repository`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 3.2: Clone a GitHub repository to your JupyterHub account\n",
    "\n",
    "The repository you created in the previous exercise exists only on GitHub. We want to clone that repo to our JupyterHub account so that we can work on the project on JupyterHub, for example, by adding Jupyter notebooks:\n",
    "\n",
    "* Open a new tab in your browser and sign in to your [JupyterHub](https://pims.jupyter.ca) account\n",
    "* Click `New` in the top right of the main page and select `Terminal`\n",
    "* The terminal is where we use [Bash](https://www.gnu.org/software/bash/) commands to communicate directly with the Linux machine underlying our JupyterHub account. For example, to orient ourselves in the terminal, we can do the following:\n",
    "    * Enter the Bash command `pwd` to print the name of the directory you are currently working in (it should be your home directory `/home/<CWL-username>` where `<CWL-username>` is your own CWL username)\n",
    "    * Enter the Bash command `ls` to list the contents of the current directory\n",
    "* In a new browser tab:\n",
    "    * Navigate to the repository on GitHub that we created in the previous exercise\n",
    "    * Click the green button `Clone or download` and then click the clipboard icon to copy the repo URL to your clipboard\n",
    "* Go back to the browser tab with the terminal on JupyterHub:\n",
    "    * Enter the command `git clone <GitHub Repo URL>` where `<GitHub Repo URL>` is the URL of your GitHub repo which you copied to your clipboard in the last step. For example, according to the names I chose above, I would enter:\n",
    "        * `git clone https://github.com/patrickwalls/ubcs3-exercises.git`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 3.3: Make a change to README.md on JupyterHub and push the change to GitHub\n",
    "\n",
    "On your main page on JupyterHub, you should have a folder called `ubcs3-exercises` or whatever name you chose in the previous exercises. This is the clone we made in the previous exercise.\n",
    "\n",
    "* On your main page on JupyterHub (in your home directory), click on the folder `ubcs3-exercises`\n",
    "* Click on the file `README.md`\n",
    "* The text file will open in the JupyterHub text editor in a new tab in your bowser\n",
    "* Make a change to the README.md file:\n",
    "    * Add a line which starts with `Exercise 1.` and then describes the Jupyter notebook you wrote in Exercise 2.1 about a project you are interested in\n",
    "    * Click `File` and then `Save` and then close the broswer tab\n",
    "* Let's look at the change we've made:\n",
    "    * Open a new terminal from the JupyterHub main page\n",
    "    * Navigate to the repo `ubcs3-exercises` by entering the command:\n",
    "        * `cd ubcs3-exercises`\n",
    "    * To see the state of the Git repo, enter the command:\n",
    "        * `git status`\n",
    "    * The output tells us that we have an untracked modification to the file `README.md`\n",
    "* Add the change to the staging area by entering the command:\n",
    "    * `git add README.md`\n",
    "* Commit the change with a descriptive message by entering the command:\n",
    "    * `git commit -m \"Added a description of Exercise 1 to README.md\"`\n",
    "* The change we made only exists on JupyterHub and so to push the change to GitHub we enter the command in the terminal:\n",
    "    * `git push origin master`\n",
    "    * Git will ask you for your GitHub username and password\n",
    "* To recap, after we've edited the file `README.md` using the text editor on JupyterHub, we enter the commands (in the terminal while working in the `ubc3-exercises` directory):\n",
    "    * `git add README.md`\n",
    "    * `git commit -m \"Added a description to Exercise 2.1 to README.md\"`\n",
    "    * `git push origin master`\n",
    "* Go to GitHub, navigate to the `ubcs3-exercises` repo and see that the changes we made while working in JupyterHub have been updated on GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 3.4: Make a change to README.md on GitHub and pull the change to JupyterHub\n",
    "\n",
    "In the last exercise, we made a change to the file `README.md` using the text editor on JupyterHub and then we pushed the changes to GitHub. In this exercise, we'll go the other way and make a change on GitHub and pull the change to JupyterHub.\n",
    "\n",
    "* Open a browser tab and navigate to the GitHub repo `ubc3-exercises` we've been working with in the last few exercises\n",
    "* Click on `README.md`\n",
    "* Click the pencil icon in the toolbar above the text in the `README.md` file\n",
    "* You are navigated to a text editor on GitHub where you can make changes to `README.md`\n",
    "    * Add a line the file which displays the name of the Jupyter notebook we created in the first exercise above\n",
    "    * Write a commit message describing the change\n",
    "    * Click `Commit changes`\n",
    "* In a new browser tab, sign in to your JupyterHub account and open a new terminal\n",
    "* Enter the command `cd ubc3-exercises` to change into the directory called `ubc3-exercises`\n",
    "* Enter `git pull` and the chagnes from GitHub will update the `README.md` file on JupyterHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXERCISE 3.5: Add your Jupyter notebook to the Git repo and push it to GitHub\n",
    "\n",
    "Finally, let's add our Jupyter notebook from Exercise 2.1 above into our Git repository on JupyterHub.\n",
    "\n",
    "* Open a new terminal in JupyerHub\n",
    "* Type the command `mv <path to file> <destination directory>` to move a file to the destination directory. For example, the notebook I wrote in Exercise 2.1 is called `intro-scikit-learn.ipynb` and saved in the folder `~/ubcs3/week-1/` (note that the tilde `~` refers to your home directory) therefore I would enter the command\n",
    "\n",
    "```\n",
    "mv ~/ubcs3/week-1/intro-scikit-learn.ipynb ~/ubcs3-exercises/\n",
    "```\n",
    "\n",
    "* Type the command `git status` to see that we have an untracked file\n",
    "* Add, commit and push the changes to GitHub:\n",
    "    * `git add intro-scikit-learn.ipynb`\n",
    "    * `git commit -m \"Added a the notebook from Exercise 2.1\"`\n",
    "    * `git push origin master`\n",
    "* Git will ask for your GitHub username and password\n",
    "* Go to GitHub and see that your notebook is now on your GitHub repo!"
   ]
  }
 ],
 "metadata": {
  "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.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}