OpenScience.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Open Science: Theory and Practice"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Overview and Objectives"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "\"Open Science\" is something of an umbrella term encompassing everything related to reproducible, transparent science.\n",
    "\n",
    "There have been some complaints that Open Science is amorphous and ambiguous, that its prescription for reproducibility is not, in itself, reproducible.\n",
    "\n",
    "However, Open Science is broadly defined and meant to appeal to every area of science, from life sciences to computational sciences to theoretical sciences. What Open Science looks like is field-specific, but there are general principles that cut across all fields of science.\n",
    "\n",
    "By the end of this lecture, you should be able to"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Define \"open science\" and its importance to scientific inquiry\n",
    " - Recall the core strategies for reproducing and replicating results\n",
    " - Package and release your Python code via distribution channels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Part 1: What is \"Open Science\"?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![openscience](OpenScience/openscience1.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Simply put, Open Science is the **movement to make all scientific data, methods, and materials accessible to all levels of society**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Why is this a good thing?\n",
    "\n",
    " - The vast majority of research is publicly funded; it would seem logical that the public have access to it!\n",
    " - Open and transparent research makes peer review and replication much easier.\n",
    " - There is some convincing evidence that Open Science gives projects more downstream impact in the scientific community"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Nonetheless, there are some downsides to making everything openly available.\n",
    "\n",
    " - The deluge of science will overwhelm already heavily-burdened researchers.\n",
    " - The tools could be used for more nefarious purposes (a good example is a particularly virulent strain of influenza that researchers were experimenting with a few years back that could potentially be used as a bioweapon)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "My opinion--as you've probably guessed by the title of the lecture--is that the benefits of good Open Science practices outweigh the drawbacks, for the following reason:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**I learn best when I can dig in and get my hands dirty.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Reading a paper or even a blog post that vaguely describes a method is one thing. Actually seeing the code, changing it, and re-running it to observe the results is something else entirely and, so I believe, is vastly superior in educational terms."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The scientific deluge is legitimate, though this was already happening even without the addition of open data, open access, and open source. And it would seem that, while we do absolutely need to exercise caution in our research and not pursue the ends by any means necessary, science is the pursuit of knowledge for its own sake and that should also be respected to the highest degree."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To that end, there are **six** main themes that comprise the Open Science guidelines."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " 1. Open data: all data used in the project should be made available.\n",
    " 2. Open source: all code written in the project should be publicly available.\n",
    " 3. Open methods: the exact procedure of the project is publicly documented.\n",
    " 4. Open review: correspondence between reviewers and authors is public.\n",
    " 5. Open access: resulting publications are publicly available.\n",
    " 6. Open education: all education materials are publicly available."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 1: Open Data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![opendata](OpenScience/opendata.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "If you had to pick the \"core\" of Open Science, this would probably be it. All of the data used in your study and experiments are published online."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This is definitely a shift from prior precedent; most raw data from scientific experiments remain cloistered."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The situation is further complicated by Terms of Service agreements that prohibit the sharing of data collected.\n",
    " - For example: if you hooked up a Python client to listen to and capture public Twitter posts, you are forbidden from sharing the Twitter data publicly.\n",
    " - Which seems odd, given that the data are public anyway, but there you go."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "**Repositories** and online data banks have sprung up around this idea. Many research institutions host their own open data repositories, as do some large tech companies."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - CERN, the organization behind the Large Hadron Collider, has posted its data online: http://opendata.cern.ch/about/CMS\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![cerndata](OpenScience/cerndata.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - Amazon has released its own set of large public datasets: https://aws.amazon.com/public-data-sets/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![awsdata](OpenScience/awsdata.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - Kaggle also has some pretty fantastic open datasets from its competitions: https://www.kaggle.com/datasets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![kaggledata](OpenScience/kaggledata.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - DataHub is a general-purpose repository for anyone to submit their own datasets. https://datahub.io/en/dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![datahub](OpenScience/datahub.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 2: Open Source"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This is probably the part you're most familiar with. Any (and *all*) code that's used in your project is published somewhere publicly for download."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "There are certainly conditions where code can't be fully open sourced--proprietary corporate secrets, pending patents, etc--but to fully adhere to Open Science, the code has to be made completely available for anyone."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Like with open data, there are numerous **repositories** across the web that specialize in providing publicly-available versioning systems for both maintaining and publishing your code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - GitHub is easily the most popular, and is where the materials for this lecture are published! https://github.com/\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![github](OpenScience/github.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - BitBucket is another option that also uses git to manage team codebases https://bitbucket.org/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![bitbucket](OpenScience/bitbucket.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - SourceForge is one of the oldest and most well-known online repositories https://sourceforge.net/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sourceforge](OpenScience/sourceforge-logo.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 3: Open Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This is probably the trickiest item. How does one make *methods* reproducible?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Open source code is part of it, but even more important is the effort put into making the methods in the code understandable. This takes several forms:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - Documentation, both as accompanying doc files (e.g. JavaDoc) as well as in-code comments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Proofs of the methods devised if they're novel, or references to their original sources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Pre-packaged examples that will run with little or no prior configuration on the user's part"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " - Pre-registered methods _before_ any work is conducted"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Self-contained virtual container scripts that satisfy all the prerequisites"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 4: Open Review"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The cornerstone of the scientific process is that of *peer review*: your peers, your colleagues, your fellow researchers should vet your work before it's officially included as part of the scientific literature."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "However, this process is fraught with ambiguity and opacity. Conflicts of interest can potentially lead to biased reviews (if you're reviewing the paper of a competitor, it isn't exactly in your best interest to go easy on them), and it can be difficult to assess a published paper in the public sphere without a trail of edits from which to begin."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Online open review journals such as [**The Journal of Open Source Software (JOSS)**](http://joss.theoj.org/) have begun proliferating to address this shortcoming."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Reviews essentially take the form of GitHub tickets, and researchers in the field can discuss and debate the merits of the work in an open forum."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![tickets](OpenScience/ghubtickets.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "There's also a site, called \"Open Review\", where conferences can elect to have their papers openly and publicly reviewed, threaded-comment style."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![openreview](OpenScience/openreview.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 5: Open Access"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Once a project is published, the paper should be made publicly available for anyone, anywhere to download and read for themselves."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Easily the most popular open access paper repository is [**arXiv**](http://arxiv.org/) (pronounced \"archive\"...geddit?). Other repositories modeled directly after its success, such as bioRxiv, have already started springing up."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "arXiv is already *hugely* popular."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "![arxiv](OpenScience/arxiv.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In fact, so many papers are archived here on a regular basis, that someone created their own open source \"aggregator\" service: http://www.arxiv-sanity.com , which collates the papers you want to read and helps filter out all the others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Preprints have become _so_ popular, that versions of arXiv have popped up for almost every area!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![preprints](OpenScience/preprint-servers.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### 6: Open Education"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This and Open Methods are closely related. In this sense, any course materials that come from research that is done are made available for others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "[**MIT OpenCourseWare**](http://ocw.mit.edu/index.htm) is probably the best example of open education at work, but these types of sites are proliferating."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Many courses ([including this one!](https://github.com/eds-uga/csci1360e-su18)) are making their materials freely available on GitHub."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - Tech companies such as GitHub (aptly named: [GitHub Classroom](https://classroom.github.com/)) are developing educational tools specifically aimed at student classrooms. Amazon Web Services [provides a similar platform](https://aws.amazon.com/education/) for course materials, often bundled with its cloud compute services."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "**Note**: This does not by default include MOOCs. If MOOCs make their materials freely available online, then and only then would it fall under this section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "So that's all great! But..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**What can _I_ do? Where do I start?**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Part 2: Open Science Best Practices"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "In the previous section we went over the absolute essentials for an Open Science project or research endeavor. It included some examples of real-world services and tools to help expedite the process."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Here, we'll go into a bit more detail as to exactly how you should tweak your projects to be truly Open Science. It's not really something you can just \"tack on\" at the end; rather, you'll need to design your projects from the onset to be part of the Open Science initiative."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "When you invent the next [TensorFlow](https://www.tensorflow.org/), we'll all be thanking you for following these best practices!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Version control"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a good starting point for any project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Version control keeps track of changes within your code base."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's a lot like Google docs, but for code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "You all know Dropbox? Has it ever saved your life? If so, the next time you start a coding project, use some form of _version control_."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![versioncontrol](OpenScience/version_control.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "There are several different version control systems out there for code, depending on what you like."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I personally prefer `git`, but I've used all of these before."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![vcsystems](OpenScience/vc_systems.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Anatomy of an open source project"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "There are some common files and folder hierarchies to implement at the very start of a new project. The [shablona](https://github.com/uwescience/shablona) GitHub repository has all this documented very well, but here are the highlights:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - Your `src` folder, containing all your source code. Surprise!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - A directory of `tests` for your code. Always always always *always* ***always*** write tests!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - A `README` file of some kind. This is your introduction that summarizes your project, gives a basic overview of how to use it, what the prerequisites are, links to further (more detailed) documentation, and any problems that are known."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - A `doc` folder containing *detailed* documentation about every aspect of your project, including any examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - A build script of some sort: a script you can run which automates the majority of the install process."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - Continuous integration (CI). This is bit more advanced, but the idea of continuous integration is to have your code exported out to an auto-compiler every time you update the code, so that you know *immediately* whether or not it builds successfully."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - A `LICENSE` file. This is often overlooked (like clicking through a EULA), but in the age of open source and Open Science it is *absolutely essential* to have a license of some sort."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![shablona](OpenScience/shablona.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Document, document, document"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This is drilled into computer science students from day 1, and yet one constant across every software project is that the *documentation sucks*. To meet basic adequacy standards, documentation should include"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - **The code itself**. This is the [radical notion](https://en.wikipedia.org/wiki/Self-documenting_code) that code should be easy to understand, especially if read by someone who did NOT write it. Save [code golf](https://en.wikipedia.org/wiki/Code_golf) for the competitions!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - **Comments in the code**. Invariably there will be some logic in the code that doesn't make sense at first glance. This should be explained with clear comments. Not comments like `# loop through the array`, but useful comments like `# Because the array is already sorted, we only loop through parts of it to search for the value we want`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "What does this code do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def do(a, b):\n",
    "    c = a + \" \" + b\n",
    "    return c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "What if I'd written it this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "def full_name(first_name, last_name):\n",
    "    name = first_name + \" \" + last_name\n",
    "    return name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Or even this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def full_name(first_name, last_name):\n",
    "    \"\"\"\n",
    "    Helper function, to concatenate the first name and the last name\n",
    "    into a single full name.\n",
    "    \"\"\"\n",
    "    \n",
    "    # Concatenates the two names with a space in between.\n",
    "    name = first_name + \" \" + last_name\n",
    "    \n",
    "    # Return the full name.\n",
    "    return name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python (and _any other_ programming language) will have a \"style\" of documenting the code whereby other utilities can take those comments and turn them into documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Java pioneered this approach in the 1990s with \"Javadocs\" and every language since has emulated that in some way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Python's version is \"Sphinx\" http://www.sphinx-doc.org/en/master/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![sphinx](OpenScience/sphinx.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - **README**. This is usually the user's first introduction to a new software package (GitHub makes this file the default landing page of a repository!). It should clearly state the purpose of the software, how to install and run it, and some basic usage examples before pointing the user to where they can go to learn more."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Examples and tests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Right after the `README`, this is the next place the user will go: examples for how to run the code. Is it command line? What options are there? What kind of data can I run through it? What should I expect for output? These sorts of questions can be addressed with"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - **Quickstart**. This is file that is dedicated to getting the user up and running with the software as quickly as possible with an example. The goal is to put the user in the driver's seat as quickly as possible, and let them ask questions later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - **Examples**. This usually takes the form of a bash script, written to invoke the code and have it run on a sample dataset that's provided. Alternatively, you can give a step-by-step guide of what commands to run, what inputs to give, and what the expected output should be."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    " - **Unit tests**. You'll learn more about this as you take higher-level software engineering courses, but the main idea is you want to write code that *tests* your main code. The user can also go here to get a feel for how the code should be used."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    " - **Containers**. This is a very advanced topic that we won't cover in this course, but the \"wave of the future\" is to build your software inside *containers* (e.g. [Docker](https://www.docker.com/)). Think of containers as super-lightweight virtual machines that anyone can build from a simple script. Using containers, you can package your software in such a way that you don't have to worry about operating systems or clashing software dependencies."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Scientific Notebooks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you're an R or Python user, you've probably heard of \"scientific notebooks\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They're interactive, usually web-based applications that blur the lines between\n",
    " - written documents\n",
    " - code modules\n",
    " - figures and tables\n",
    "\n",
    "by interleaving all three within the same medium."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**These very slides were built entirely in Jupyter, a multi-language scientific notebook platform!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![jupyterpreview](OpenScience/jupyterpreview.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "While these slides were built in Jupyter, they were exported into HTML and PDF, so the code isn't technically live anymore."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, through platforms like mybinder, you can turn any GitHub repository into a collection of active notebooks! You can do this yourself with these slides--all you need is a web browser!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![mybinder](OpenScience/mybinder.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Containers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**WARNING: This is super-advanced.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Has anyone ever\n",
    " - tried to run code that is 6+ months old?\n",
    " - tried to install an old(er) video game on a new computer?\n",
    " - tried to install a new app on an old smartphone OS?\n",
    " \n",
    "Did it run?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Here's a great example: Python 2 versus Python 3."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python 2 was the _de facto_ Python version for over a decade (it's kind of the Windows XP of Python). When Python 3 was introduced in the late 2000s, nobody upgraded."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "What should this code output?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "division = 5 / 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.5\n"
     ]
    }
   ],
   "source": [
    "print(division)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This notebook is running Python 3. Let's run it in Python 2, shall we?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "![python2](OpenScience/python2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Containers, such as **Docker**, allow you to create bash-script-like _recipes_ that build the precise environment you want."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![docker](OpenScience/docker.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This has _huge_ implications in reproducibility: you can provide others with an exact set of instructions--even a pre-built image!--of the environment in which you conducted your work."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Python Package Index (pypi) is your friend"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "![pypi](OpenScience/pypi-large.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "**PyPI** is the [Python Package Index](https://pypi.python.org/pypi), and is where the *vast* majority of external Python packages are hosted (over 85,000 as of this lecture!). In addition to publishing your code on GitHub, you can also package your code to be automatically installed via a package manager like `pip` or `easy_install`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Provided you're already adhering to the anatomy of an open source project, there are only a few other steps needed to get your code ready for publishing on PyPI: in particular, writing the `setup.py` script that will tell the package managers of people who want to install your package exactly *how* to install your package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Then you just upload the code to PyPI! http://peterdowns.com/posts/first-time-with-pypi.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Pre-registration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pre-registration means _publishing your methods publicly BEFORE any work has been done_."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why is this important?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Sites like Protocols.io https://www.protocols.io/ and OSF https://osf.io/prereg/ have pre-registration modules, sometimes linked with certain journals who agree to publish the results of the methods, regardless of whether they're positive or negative."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![protocols](OpenScience/protocols.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![osf](OpenScience/osf.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This makes sense for wet lab / life sciences or even theory-driven statistics, but what about empirical or computational studies like applied machine learning?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Turns out, there are a number of pre-registration sites for those too, including OpenML."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![openml](OpenScience/openml.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Licensing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "Yes, this is super boring, I agree. Fortunately, the wonderful folks at GitHub have created an awesome resource for you to use."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "[**Choose a License**](http://choosealicense.com/): It provides a handy choose-your-adventure flowchart for picking the perfect open software license for your project. I highly recommend it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "However, if you're just looking for a [**tl;dr** version](https://en.wikipedia.org/wiki/Wikipedia:Too_long;_didn%27t_read) and want the basic lay of the land, GitHub's default licenses for new projects include"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    " - MIT License (pretty much the \"no warranty whatsoever, use at your own risk\" license)\n",
    " - Apache 2.0 License (almost exactly like the MIT, but allows for patents and trademarks)\n",
    " - GPLv3 License (requires anyone who modifies your code to publish those modifications under GPLv3 too)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Final Thoughts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "In my view, Open Science and its practices will only become more important.\n",
    " - Replicating previous results\n",
    " - Providing hands-on tools to the upcoming generation of scientists"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Six major areas of Open Science\n",
    " - These have to be addressed from the beginning, not tacked on after the fact"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Already lots of great open source tools and repositories to encourage Open Science practices\n",
    " - data repositories\n",
    " - tools for method replication and testing\n",
    " - standards for code structure, results presentation, and method preregistration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Additional Resources\n",
    "\n",
    "**These slides!** https://github.com/quinngroup/open-science-2018\n",
    "\n",
    " 1. GitHub template for open source Python projects https://github.com/uwescience/shablona\n",
    " 2. Mozilla Open Science Lab https://science.mozilla.org/\n",
    " 3. Open Science Framework (OSF) for all phases of the scientific pipeline https://osf.io/ \n",
    " 4. The Center for Open Science (COS), which supports OSF https://cos.io/\n",
    " 5. Docker https://www.docker.com/"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}