01-learning-jupyter-environment.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Learning the Environment\n",
    "\n",
    "What is this thing that you're using right now?\n",
    "\n",
    "For this workshop, we've set up a coding environment, with the necessary tools and data already preloaded. The interface that you're using is called _Jupyter_ - which allows you to interact with code in your browser, though a format called a 'notebook'. In addition to being in the browser, Jupyter is pleasant because it's _interactive_, so you can interact with your code. The traditional way of running code involves writing a script and running the whole thing; the interactive approach used by Jupyter is better for data analysis, because you explore, tinker, and converse with your data.\n",
    "\n",
    "The HathiTrust data is too big to just open and manipulate on your own machine, so we will be using various tools within Python to explore it.  This means that we will have to ask questions of it first, rather than just viewing it. Python is a flexible programming language. If you've never programmed before, don't worry - we give you many examples, which you can follow along with and modify for your own needs. You'll learn the main skills in this workshop!\n",
    "\n",
    "You will be using a set of custom access tools via a set of Python tools written specifically for this dataset. Those tools rely on a data-science specific set of tools called *Pandas*. So, while you're learning to work with HathiTrust Extracted Feature files, you're also secretly learning common and widely useful data processing and analysis skills.\n",
    "\n",
    "This means that you will need to consider your questions through the affordances of your data model as well as the data tools you have access to. There will be some questions that are simply not possible to ask of this dataset, while others will need some transformation to acurately represent the data available. This is a totally normal process that many computational projects go through.\n",
    "\n",
    "In this workshop, we're working in the browser, with Jupyter, Python and all the corresponding data installed on somebody else's computer, but it can be run on your own computers. While you're in the browser, keep in mind that your custom code is *ephemeral* - it won't stay saved for the long term."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises\n",
    "\n",
    "### Let's get comfortable with Jupyter\n",
    "\n",
    "Jupyter is one of many execution environtments for Python.  Its specific vision of the world is that work is done iteratively, with an active session.\n",
    "\n",
    "\"Script-like\" execution means that you write down all the code in a file, and that entire file is run in order. \n",
    "\n",
    "\"Interpreter-like\" execution means that you type in commands one at a time. The session pauses after each, waiting for the next command. This is really similar to how the command line is run.\n",
    "\n",
    "Jupyter is a hybrid of both those things.  Notebooks are composed of cells.  Then the cells are executed (almost like mini scripts).  This gives you the advantage of keeping the session alive so you don't have to repeat loading data, etc., and the advantage of being able to execute multiple lines of code at the same time.\n",
    "\n",
    "Jupyter is extremely powerful, but there are a few traps.\n",
    "\n",
    "Let's get comfortable with cells first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Ensure that this cell is active, you can do that by clicking inside here.\")\n",
    "print(\"Press shift+enter to execute this cell.\")\n",
    "print(\"Try using the right shift and return at the same time, with one hand.\")\n",
    "print(\"You can also press the 'play' button at the top.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The cell above contains four print statements that will be executed sequentially once the cell is executed. You should see all the content printed out below that cell.\n",
    "\n",
    "Let's look at a more complex code snippet."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "title = \"Jupyter and You\"\n",
    "author = \"Human, A.\"\n",
    "year_published = 2018\n",
    "\n",
    "print(\"The book, \" + title + \", by \" + author + \", was published in \" + str(year_published) + \".\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code cell defines a few variables that are describing a book, and has a print statement with a summary about them. Each line is executed and does something, but only the final one actually makes something appear to the screen.\n",
    "\n",
    "Important to understand:  Python has eyes on things that exist within the session. You can have a ton of code working behind the scenes without anything printed out.  This is different from your human eyes.  This is where print statements (and some fun jupyter stuff comes in handy).\n",
    "\n",
    "So if you want to see it with your human eyes, you have to explicitly make that happen somehow.\n",
    "\n",
    "If Python doesn't yell at you, the code executed.  Now, it may not have done the thing you wanted it to do, but it did do something!\n",
    "\n",
    "**Take a few minutes to play with changing and executing the code above to get a feel for things.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Jupyter pain points\n",
    "\n",
    "Powerfully flexible systems open up endless opportunities to powerfully tangle your code up.\n",
    "\n",
    "Here are a few key tips as you are getting started:\n",
    "\n",
    "* While Jupyter allows you to evaluate cells out of order, please try to only do them in order.\n",
    "* if you are getting errors that make no sense, sometimes going back to the top and starting over fixes it.\n",
    "\n",
    "There are so many tips and tricks, but just try and pay attention to how we are using it and try to match that.  You need to get a feel for it before we can have a more detailed discussion."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing prerequisites\n",
    "\n",
    "Python users have specific conventions about how and where things are organized in code. We'll be highlighting a few, but there is pretty decent documentation about the rest of it if you continue on in Python.\n",
    "\n",
    "Python has a default set of functions and tools, things like `print()` that are so commonly used that you don't need to do anything special to be able to use them.\n",
    "\n",
    "There are other things that come preloaded with standard Python (this is the Standard Library), but you'll have to specifically ask for them.  We'll be using some of those.\n",
    "\n",
    "There are also tools that have been installed separately. We won't really be covering these because it is nuanced and worth a workshop of it's own, but this is covered in Python books and courses.  We have preloaded these things for you within this binder repository, so we can skip this.\n",
    "\n",
    "Whether part of the standard library or installed separately, you use **import statements** to bring them into your current session. Once imported, you have access to use the functions and content from that toolkit.  \n",
    "\n",
    "There are many ways to import libraries into your python session.  Each style determines how you access it.  Many tools have recommended conventions for importing.\n",
    "\n",
    "Below are the import statements that you'll need to have in your notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from htrc_features import FeatureReader\n",
    "import os"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We don't want to dive too deeply into the syntax here. But here are some brief explainations:\n",
    "\n",
    "* `from htrc_features import FeatureReader` this is a library installed from this package: https://pypi.org/project/htrc-feature-reader/.  The import convention we are using here is to import just one function.  This means we can directly call `FeatureReader()` within our code, but nothing else from that library.  This library is one created by the HTRC team and is used for parsing the data from the extracted features.\n",
    "* `import os` this is part of the standard library, and provides tools for working with your file system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we shift from notebook to notebook, these will be repeated for you.  You may also see some other repeated code. That's because each notebook is a separate universe and session.  You may have several active notebooks, but they aren't sharing memory or information with eachother."
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}