1-css/1-2-workflow.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### GESIS Fall Seminar in Computational Social Science 2022\n",
    "### Introduction to Computational Social Science with Python\n",
    "# Day 1-2: Setting up Your Workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Overview\n",
    "\n",
    "* Map of software tools and options\n",
    "* Typical workflow\n",
    "   1. Installing Python and managing libraries with **Anaconda**\n",
    "   2. Writing and running Python code with **Jupyter**\n",
    "   3. Version control with **git**\n",
    "   4. Code sharing and cloud storage with **GitHub**\n",
    "   5. Efficient and reproducible workflows with **Bash**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Map of Software Tools and Options\n",
    "\n",
    "![Software map](figs/software_map.png \"Software map\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## IDEs\n",
    "\n",
    "* Integrated development environment\n",
    "* A software application that facilitates computer programming and software development\n",
    "  * Text editor with syntax highlighting, auto completion and smart indentation\n",
    "  * Shell with syntax highlighting\n",
    "  * Popular libraries\n",
    "  * (Debugger)\n",
    "* For example:\n",
    "  * Spyder\n",
    "  * PyCharm\n",
    "  * Atom + Hydrogen/Terminal\n",
    "  * **Jupyter + Anaconda**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Anaconda\n",
    "\n",
    "![Anaconda](figs/anaconda.png \"Anaconda\")\n",
    "\n",
    "* Freemium open-source cross-platform distribution of the Pyhton and R programming languages\n",
    "  * `conda` – package management system\n",
    "  * `pandas`, `numpy`, `statsmodels`, `networkx`, `scikit-learn`, `matplotlib` – packages for data science \n",
    "  * Anaconda Navigator – graphical user interface\n",
    "  * Jupyter Notebook – web app for creating and sharing code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Installing Anaconda\n",
    "\n",
    "* Go to https://www.anaconda.com/download/\n",
    "* Select your OS\n",
    "* **Download Python 3.8 version**\n",
    "* Follow instructions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Jupyter\n",
    "\n",
    "![Jupyter](figs/jupyter.png \"Jupyter\")\n",
    "\n",
    "* Open-source web application for creating and sharing documents with:\n",
    "  * Live code\n",
    "  * Equations\n",
    "  * Visualizations\n",
    "  * Explanatory text\n",
    "* Supports more than 40 programming languages, including Python and R\n",
    "* Notebook files have *.ipynb* extension and can be easily shared, e.g. on GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Launching Jupyter\n",
    "\n",
    "* Launch Anaconda Navigator and click on Jupyter Notebook icon\n",
    "\n",
    "or \n",
    "\n",
    "* Open Terminal/cmd and type: \n",
    "\n",
    "```\n",
    "> jupyter notebook\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using Jupyter\n",
    "\n",
    "* New &rarr; Notebook: Python 3\n",
    "* Insert &rarr; Insert Cell Below\n",
    "* Cell &rarr; Cell Type &rarr;\n",
    "  * Markdown\n",
    "    * Lightweight markup language\n",
    "    * See cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet\n",
    "    * CTRL+ENTER to run\n",
    "    * Double-click to edit\n",
    "  * Code\n",
    "    * CTRL+ENTER to run\n",
    "* Cell &rarr; Run All\n",
    "  * Code is run top-down so you can use code from cells above in current cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Shutting Down Jupyter\n",
    "\n",
    "* Do not forget to Command+S / CTRL+S !\n",
    "* Jupyter is a server and closing the browser window will not shut it down\n",
    "* To close a notebook:\n",
    "    * File &rarr; Close and Halt\n",
    "    * On Notebook Dashboard &rarr; Slect notebook &rarr; Shutdown\n",
    "* To shut down server:\n",
    "    * On Notebook Dashboard &rarr; Quit\n",
    "    * Terminal &rarr; CTRL+C &rarr; `y`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Alternative Python Workflow\n",
    "\n",
    "* Use another IDE\n",
    "\n",
    "or \n",
    "\n",
    "* Use text editor (e.g. Atom) to create .py files\n",
    "* Run files in Terminal/cmd\n",
    "\n",
    "```\n",
    "> cd Path/to/file\n",
    "> python filename.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Version Control and Cloud Storage with GitHub\n",
    "\n",
    "![GutHub Octocat](figs/Octocat.jpg \"GutHub Octocat\")\n",
    "\n",
    "* Code hosting platform for version control and collaboration\n",
    "* Based on Git\n",
    "  * Version control system for tracking changes in computer files and coordinating work on those files among multiple people\n",
    "  * Created in 2005 by Linus Torvalds\n",
    "* Largest host of source code in the world\n",
    "* Bought by Microsoft in 2018"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## GitHub Lingo\n",
    "\n",
    "* **Repository** – a space for a project/assignment\n",
    "* **Clone** – a copy of the repository that lives on your computer\n",
    "* **Branch** – a paralel version of the repository\n",
    "* **Commit** – save changes with a short description\n",
    "* **Pull request** – ask changes to be merged\n",
    "* **Merge** – incorporate changes (then delete branch)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## GitHub Workflow\n",
    "\n",
    "![GutHub Workflow](figs/github.jpg \"GutHub Workflow\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Getting Started with GitHub\n",
    "\n",
    "* Create personal account on https://github.com/\n",
    "* Go to https://education.github.com/ and get the Student Developer Pack for some cool freebies"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Three ways to interact\n",
    "  1. Browser\n",
    "  2. Command line \n",
    "  3. GitHub Desktop"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Terminal = Console = Shell = Bash = Command Line = Command Prompt\n",
    "\n",
    "(for our purposes here)\n",
    "\n",
    "![Terminal](figs/terminal.png \"Terminal\")\n",
    "\n",
    "* Efficient way to access files, run programs, and execute code\n",
    "* Allows to schedule and batch-process tasks\n",
    "* Provides scripts for reproducible workflows across different operating systems"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Useful Bash Commands\n",
    "* Print current working directory\n",
    "```\n",
    "pwd\n",
    "```\n",
    "* Change current working directory\n",
    "```\n",
    "cd Path/to/directory\n",
    "```\n",
    "* Go back to the parent directory of the current one\n",
    "```\n",
    "cd ..\n",
    "```\n",
    "* Go back to your home directory\n",
    "```\n",
    "cd ~\n",
    "```\n",
    "* Create a new directory\n",
    "```\n",
    "mkdir dirname\n",
    "```\n",
    "* Print a list of files and subdirectories\n",
    "```\n",
    "ls\n",
    "```\n",
    "* Launch a Python interpreter (type `exit()` to stop and go back to bash) \n",
    "```\n",
    "python\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "## Change Your Default Text Editor for Git\n",
    "\n",
    "You can use your favorite editor by customizing the Git default editor.\n",
    "\n",
    "For example, you can use [**Nano**](https://www.nano-editor.org/). It is much easier to use than Vim: `Ctrl+o` to save and `Ctrl+x` to close.\n",
    "\n",
    "To set Nano as the default editor for your commit messages, run the following:\n",
    "\n",
    "```\n",
    "git config --global core.editor \"nano\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Nano comes pre-installed with Linux and OS. For Windows, download and install [**Nano-win**](https://github.com/mcandre/nano-win)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Important Git Commands \n",
    "\n",
    "* Copy online repository\n",
    "```\n",
    "git clone https://github.com/gesis-css-python/materials.git\n",
    "```\n",
    "* Update local repository\n",
    "```\n",
    "git pull\n",
    "```\n",
    "* See the status of local respository\n",
    "```\n",
    "git status\n",
    "```\n",
    "* See the change history of local respository\n",
    "```\n",
    "git log\n",
    "```\n",
    "* Stage all changes\n",
    "```\n",
    "git add --all\n",
    "```\n",
    "* Commit staged changes\n",
    "```\n",
    "git commit -m \"your commit message here\"\n",
    "```\n",
    "* Upload your changes to online repository\n",
    "```\n",
    "git push\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Viewing Course Materials on GitHub (Browser)\n",
    "\n",
    "* Syllabus and course materials at https://github.com/gesis-css-python/materials\n",
    "\n",
    "* Answers to exercises at https://github.com/gesis-css-python/materials/answers\n",
    "\n",
    "    * To view this repository, you need to be added to the Students team of the GitHub organization \"GESIS Introduction to Computational Social Science with Python\"\n",
    "    * Please e-mail your GitHub username to m.tsvetkova@lse.ac.uk\n",
    "    * Do not forget to **accept the invitation** to join the team and organization!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Cloning Course Materials from GitHub (Command Line)\n",
    "\n",
    "### \\*Install and set up `git`\n",
    "\n",
    "Follow instructions here: https://help.github.com/articles/set-up-git/\n",
    "\n",
    "### Cloning\n",
    "\n",
    "  `> cd Path/to/directory`\n",
    "\n",
    "  `> git clone https://github.com/gesis-css-python/materials.git`\n",
    "\n",
    "### Updating\n",
    "\n",
    "  `> cd Path/to/materials`\n",
    "\n",
    "  `> git pull`\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Storing Your Work on the Cloud (Command Line)\n",
    "\n",
    "![Git Commands](figs/git.jpg \"Git Commands\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## When Working Solo or in Small Teams (Command Line)\n",
    "\n",
    "For your solo work or small-team projects where you have push privileges:\n",
    "\n",
    "1. To create a local copy, **clone** the repository (Terminal)\n",
    "\n",
    "  `> cd Path/to/directory`\n",
    "\n",
    "  `> git clone link.git`\n",
    "  \n",
    "  (You can obtain the link when you click the \"Clone or download\" button on the GitHub page for the repository)\n",
    "\n",
    "2. You can now make changes in the downloaded file (Jupyter)\n",
    "\n",
    "3. To create a new version of the file, **commit** changed file \n",
    "\n",
    "  `> cd Path/to/directory`\n",
    "  \n",
    "  `> git add --all` \n",
    "  \n",
    "  `> git commit -m 'Submitting assignment'`\n",
    "  \n",
    "\n",
    "4. To update the online copy with the local changes you made, **push to the master branch**\n",
    "  \n",
    "  `> git push`\n",
    "\n",
    "\n",
    "5. If someone else is also working on the file, **pull** every time before starting work to make sure there are no conflicts (Terminal)\n",
    "\n",
    "  `> cd Path/to/directory`\n",
    "  \n",
    "  `> git pull`\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## When Working in Large Teams\n",
    "\n",
    "If you do not have push privileges or more generally, in cases when the collaborative work is more strictly managed:\n",
    "\n",
    "1. Fork or branch\n",
    "   * **fork** means you create your own copy on the cloud; this is more commonly used by external collaborators\n",
    "   * **branch** is linked to the original repository more directly; this is used by internal team members to encapsulate work on specific features\n",
    "2. Make changes and add commits.\n",
    "3. Open a **pull request**\n",
    "4. Discuss and review commits.\n",
    "5. Wait for repository admin to **merge** your branch/fork.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using GitHub: General Notes\n",
    "\n",
    "* For cloud storage and sharing, do not forget to push (especially on GitHub Desktop!)\n",
    "   * Check if the changes are online. If you cannot see them after refreshing, no one else can.\n",
    "* GitHub does all the version control for you. Do not duplicate and rename files!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Additional resources\n",
    "   * Get started: [GitHub tutorials](https://guides.github.com/)\n",
    "   * Get it done: [Git cheatsheet](https://education.github.com/git-cheat-sheet-education.pdf)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}