Appendix1-InstallingOnYourOwnComputer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "This workshop used a hosted, online version of the Feature Reader. However, moving forward, you will likely want to use these tools on your own machine.\n",
    "\n",
    "To do so, you need to install the HTRC Feature Reader library for Python alongside the data science libraries that it depends on. \n",
    "\n",
    "For ease, this lesson will focus on installing Python through a scientific distribution called Anaconda. Anaconda is an easy-to-install Python distribution that already includes most of the dependencies for the HTRC Feature Reader.\n",
    "\n",
    "To install Anaconda, download the installer for your system from the [Anaconda download page](https://www.continuum.io/downloads) and follow their instructions for installation of either the Windows 64-bit Graphical Installer or the Mac OS X 64-bit Graphical Installer. Install the Python 3 version.\n",
    "\n",
    "<img src=\"images/conda-install.PNG\" width=\"400px\" alt=\"Conda Install\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing the HTRC Feature Reader\n",
    "\n",
    "The HTRC Feature Reader can be installed by command line. First open a terminal application:\n",
    "\n",
    "- *Windows*: Open 'Command Prompt' from the Start Menu and type: `activate`.\n",
    "- *Mac OX/Linux*: Open 'Terminal' from Applications and type `source activate`.\n",
    "\n",
    "If Anaconda was properly installed, you should see something similar to this:\n",
    "\n",
    "<img src=\"images/activating-env.png\" width=\"450px\" alt=\"Activating the default Anaconda environment.\" />\n",
    "\n",
    "Now, you need to type one command:\n",
    "\n",
    "```bash\n",
    "conda install -c htrc htrc-feature-reader\n",
    "```\n",
    "\n",
    "This command installs the HTRC Feature Reader and its necessary dependencies. We specify `-c htrc` so the installation command knows to find the library from the `htrc` organization.\n",
    "\n",
    "That's it! At this point you have everything necessary to start reading HTRC Feature Reader files.\n",
    "\n",
    "> *psst*, advanced users: You can install the HTRC Feature Reader *without* Anaconda with `pip install htrc-feature-reader`, though for this lesson you'll need to install two additional libraries `pip install matplotlib jupyter`. Also, note that not all manual installations are alike because of hard-to-configure system optimizations: this is why we recommend Anaconda. If you think your code is going slow, you should check that Numpy has access to [BLAS and LAPACK libraries](http://stackoverflow.com/a/19350234/233577) and install [Pandas recommended packages](http://pandas.pydata.org/pandas-docs/version/0.15.2/install.html#recommended-dependencies). The rest is up to you, advanced user!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Start a Notebook\n",
    "\n",
    "Using Python the traditional way -- writing a script to a file and running it -- can become clunky for text analysis, where the ability to look at and interact with data is invaluable.\n",
    "This lesson uses an alternative approach: Jupyter notebooks.\n",
    "\n",
    "Jupyter gives you an interactive version of Python (called IPython) that you can access in a \"notebook\" format in your web browser. This format has many benefits. The interactivity means that you don't need to re-run an entire script each time: you can run or re-run blocks of code as you go along, without losing your enviroment (i.e. the variables and code that are already loaded). The notebook format makes it easier to examine bits of information as you go along, and allows for text blocks to intersperse a narrative.\n",
    "\n",
    "Jupyter was installed alongside Anaconda in the previous section, so it should be available to load now.\n",
    "\n",
    "From the Start Menu (Windows) or Applications directory (Mac OS), open \"Jupyter notebook\". This will start Jupyter on your computer and open a browser window. Keep the console window in the background, the browser is where the magic happens.\n",
    "\n",
    "<img src=\"images/open-notebook.PNG\" width=\"250px\" alt=\"Opening Jupyter on Windows\"  />\n",
    "\n",
    "If your web browser does not open automatically, Jupyter can be accessed by going to the address \"localhost:8888\" - or a different port number, which is noted in the console (\"The Jupyter Notebook is running at...\"):\n",
    "\n",
    "<img src=\"images/notebook-start.png\" width=\"500px\" alt=\"A freshly started Jupyter notebook instance.\" />\n",
    "\n",
    "Jupyter is now showing a directory structure from your home folder. Create a directory and for your project and start your first notebook there!\n",
    "\n",
    "Here there are instructions for editing a cell of text or code, and running it. Try editing and running a cell, and notice that it only affects itself. Here are a few tips for using the notebook as the lesson continues:\n",
    "\n",
    "- New cells are created with the <i class=\"fa-plus fa\"> Plus</i> button in the toolbar. When not editing, this can be done by pressing 'b' on your keyboard.\n",
    "- New cells are \"code\" cells by default, but can be changed to \"Markdown\" (a type of text input) in a dropdown menu on the toolbar. In edit mode, you can paste in code from this lesson or type it yourself.\n",
    "- Switching a cell to edit mode is done by pressing Enter.\n",
    "- Running a cell is done by clicking <i class=\"fa-step-forward fa\"> Play</i> in the toolbar, or with `Ctrl+Enter` (`Ctrl+Return` on Mac OS). To run a cell and immediately move forward, use `Shift+Enter` instead.\n",
    "\n",
    "In this notebook, it's time to give the HTRC Feature Reader a try. When it is time to try some code, start a new cell with <i class=\"fa-plus fa\"> Plus</i>, and run the code with <i class=\"fa-step-forward fa\"> Play</i>. Before continuing, click on the title to change it to something more descriptive than \"Start Here\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Collecting your own data\n",
    "\n",
    "After you learn to use the feature data in this workshop, you may want to work with the entirety of the dataset. The details on how to do this are described in [Appendix 2: rsync](Appendix2-CollectingDatasetFiles.ipynb)."
   ]
  }
 ],
 "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}