getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<a id='getting-started'></a>\n",
    "<div id=\"qe-notebook-header\" align=\"right\" style=\"text-align:right;\">\n",
    "        <a href=\"https://quantecon.org/\" title=\"quantecon.org\">\n",
    "                <img style=\"width:250px;display:inline;\" width=\"250px\" src=\"https://assets.quantecon.org/img/qe-menubar-logo.svg\" alt=\"QuantEcon\">\n",
    "        </a>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting up Your Python Environment\n",
    "\n",
    "\n",
    "<a id='index-0'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "- [Setting up Your Python Environment](#Setting-up-Your-Python-Environment)  \n",
    "  - [Overview](#Overview)  \n",
    "  - [Anaconda](#Anaconda)  \n",
    "  - [Jupyter Notebooks](#Jupyter-Notebooks)  \n",
    "  - [Installing Libraries](#Installing-Libraries)  \n",
    "  - [Working with Files](#Working-with-Files)  \n",
    "  - [Editors and IDEs](#Editors-and-IDEs)  \n",
    "  - [Exercises](#Exercises)  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "\n",
    "In this lecture, you will learn how to\n",
    "\n",
    "1. get a Python environment up and running with all the necessary tools  \n",
    "1. execute simple Python commands  \n",
    "1. run a sample program  \n",
    "1. install the code libraries that underpin these lectures  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Anaconda\n",
    "\n",
    "The [core Python package](https://www.python.org/downloads/) is easy to install but *not* what you should choose for these lectures.\n",
    "\n",
    "These lectures require the entire scientific programming ecosystem, which\n",
    "\n",
    "- the core installation doesn’t provide  \n",
    "- is painful to install one piece at a time  \n",
    "\n",
    "\n",
    "Hence the best approach for our purposes is to install a free Python distribution that contains\n",
    "\n",
    "1. the core Python language **and**  \n",
    "1. the most popular scientific libraries  \n",
    "\n",
    "\n",
    "The best such distribution is [Anaconda](https://www.anaconda.com/what-is-anaconda/).\n",
    "\n",
    "Anaconda is\n",
    "\n",
    "- very popular  \n",
    "- cross platform  \n",
    "- comprehensive  \n",
    "- completely unrelated to the [Nicki Minaj song](https://www.youtube.com/watch?v=LDZX4ooRsWs) of the same name  \n",
    "\n",
    "\n",
    "Anaconda also comes with a great package management system to organize your code libraries.\n",
    "\n",
    "**All of what follows assumes that you adopt this recommendation!**.\n",
    "\n",
    "\n",
    "<a id='install-anaconda'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing Anaconda\n",
    "\n",
    "\n",
    "<a id='index-1'></a>\n",
    "Installing Anaconda is straightforward: [download](https://www.anaconda.com/download/) the binary and follow the instructions.\n",
    "\n",
    "Important points:\n",
    "\n",
    "- Install the latest version.  \n",
    "- If you are asked during the installation process whether you’d like to make Anaconda your default Python installation, say **yes**.  \n",
    "- Otherwise, you can accept all of the defaults.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Updating Anaconda\n",
    "\n",
    "Anaconda supplies a tool called conda to manage and upgrade your Anaconda packages.\n",
    "\n",
    "One conda command you should execute regularly is the one that updates the whole Anaconda distribution.\n",
    "\n",
    "As a practice run, please execute the following\n",
    "\n",
    "1. Open up a terminal  \n",
    "1. Type `conda update anaconda`  \n",
    "\n",
    "\n",
    "For more information on conda,  type conda help in a terminal.\n",
    "\n",
    "\n",
    "<a id='ipython-notebook'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Jupyter Notebooks\n",
    "\n",
    "\n",
    "<a id='index-5'></a>\n",
    "[Jupyter](http://jupyter.org/) notebooks are one of the many possible ways to interact with Python and the scientific libraries.\n",
    "\n",
    "They use  a *browser-based* interface to Python with\n",
    "\n",
    "- The ability to write and execute Python commands.  \n",
    "- Formatted output in the browser, including tables, figures, animation, etc.  \n",
    "- The option to mix in formatted text and mathematical expressions.  \n",
    "\n",
    "\n",
    "Because of these possibilities, Jupyter is fast turning into a major player in the scientific computing ecosystem.\n",
    "\n",
    "Here’s an image showing execution of some code (borrowed from [here](http://matplotlib.org/examples/pylab_examples/hexbin_demo.html)) in a Jupyter notebook\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/jp_demo.png\" style=\"\">\n",
    "\n",
    "  \n",
    "You can find a nice example of the kinds of things you can do in a Jupyter notebook (such as include maths and text) [here](http://nbviewer.jupyter.org/github/QuantEcon/TaxSmoothing/blob/master/Tax_Smoothing_1.ipynb).\n",
    "\n",
    "While Jupyter isn’t the only way to code in Python, it’s great for when you wish to\n",
    "\n",
    "- start coding in Python  \n",
    "- test new ideas or interact with small pieces of code  \n",
    "- share or collaborate scientific ideas with students or colleagues  \n",
    "\n",
    "\n",
    "These lectures are designed for executing in Jupyter notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Starting the Jupyter Notebook\n",
    "\n",
    "\n",
    "<a id='index-6'></a>\n",
    "Once you have installed Anaconda, you can start the Jupyter notebook.\n",
    "\n",
    "Either\n",
    "\n",
    "- search for Jupyter in your applications menu, or  \n",
    "- open up a terminal and type `jupyter notebook`  \n",
    "  \n",
    "  - Windows users should substitute “Anaconda command prompt” for “terminal” in the previous line.  \n",
    "  \n",
    "\n",
    "\n",
    "If you use the second option, you will see something like this (click to enlarge)\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/starting_nb.png\" style=\"\">\n",
    "\n",
    "  \n",
    "The output tells us the notebook is running at `http://localhost:8888/`\n",
    "\n",
    "- `localhost` is the name of the local machine  \n",
    "- `8888` refers to [port number](https://en.wikipedia.org/wiki/Port_%28computer_networking%29) 8888 on your computer  \n",
    "\n",
    "\n",
    "Thus, the Jupyter kernel is listening for Python commands on port 8888 of our local machine.\n",
    "\n",
    "Hopefully, your default browser has also opened up with a web page that looks something like this (click to enlarge)\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb.png\" style=\"\">\n",
    "\n",
    "  \n",
    "What you see here is called the Jupyter *dashboard*.\n",
    "\n",
    "If you look at the URL at the top, it should be `localhost:8888` or similar, matching the message above.\n",
    "\n",
    "Assuming all this has worked OK, you can now click on `New` at the top right and select `Python 3` or similar.\n",
    "\n",
    "Here’s what shows up on our machine:\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb2.png\" style=\"\">\n",
    "\n",
    "  \n",
    "The notebook displays an *active cell*, into which you can type Python commands."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Notebook Basics\n",
    "\n",
    "\n",
    "<a id='index-7'></a>\n",
    "Let’s start with how to edit code and run simple programs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Running Cells\n",
    "\n",
    "Notice that in the previous figure the cell is surrounded by a green border.\n",
    "\n",
    "This means that the cell is in *edit mode*.\n",
    "\n",
    "As a result, you can type in Python code and it will appear in the cell.\n",
    "\n",
    "When you’re ready to execute the code in a cell, hit `Shift-Enter` instead of the usual `Enter`.\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb3.png\" style=\"\">\n",
    "\n",
    "  \n",
    "(Note: There are also menu and button options for running code in a cell that you can find by exploring)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Modal Editing\n",
    "\n",
    "The next thing to understand about the Jupyter notebook is that it uses a *modal* editing system.\n",
    "\n",
    "This means that the effect of typing at the keyboard **depends on which mode you are in**.\n",
    "\n",
    "The two modes are\n",
    "\n",
    "1. Edit mode  \n",
    "  \n",
    "  - Indicated by a green border around one cell  \n",
    "  - Whatever you type appears as is in that cell  \n",
    "  \n",
    "1. Command mode  \n",
    "  \n",
    "  - The green border is replaced by a grey border  \n",
    "  - Key strokes are interpreted as commands — for example, typing b adds a new cell below  the current one  \n",
    "  \n",
    "\n",
    "\n",
    "To switch to\n",
    "\n",
    "- command mode from edit mode, hit the `Esc` key or `Ctrl-M`  \n",
    "- edit mode from command mode, hit `Enter` or click in a cell  \n",
    "\n",
    "\n",
    "The modal behavior of the Jupyter notebook is a little tricky at first but very efficient when you get used to it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### User Interface Tour\n",
    "\n",
    "At this stage, we recommend you take your time to\n",
    "\n",
    "- look at the various options in the menus and see what they do  \n",
    "- take the “user interface tour”, which can be accessed through the help menu  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Inserting Unicode (e.g., Greek Letters)\n",
    "\n",
    "Python 3 introduced support for [unicode characters](https://docs.python.org/3/howto/unicode.html),\n",
    "allowing the use of characters such as $ \\alpha $ and $ \\beta $ in your code.\n",
    "\n",
    "Unicode characters can be typed quickly in Jupyter using the tab key.\n",
    "\n",
    "Try creating a new code cell and typing \\alpha, then hitting the tab key on your keyboard.\n",
    "\n",
    "\n",
    "<a id='a-test-program'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### A Test Program\n",
    "\n",
    "Let’s run a test program.\n",
    "\n",
    "Here’s an arbitrary program we can use: [http://matplotlib.org/1.4.1/examples/pie_and_polar_charts/polar_bar_demo.html](http://matplotlib.org/1.4.1/examples/pie_and_polar_charts/polar_bar_demo.html).\n",
    "\n",
    "On that page, you’ll see the following code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "N = 20\n",
    "θ = np.linspace(0.0, 2 * np.pi, N, endpoint=False)\n",
    "radii = 10 * np.random.rand(N)\n",
    "width = np.pi / 4 * np.random.rand(N)\n",
    "\n",
    "ax = plt.subplot(111, polar=True)\n",
    "bars = ax.bar(θ, radii, width=width, bottom=0.0)\n",
    "\n",
    "# Use custom colors and opacity\n",
    "for r, bar in zip(radii, bars):\n",
    "    bar.set_facecolor(plt.cm.jet(r / 10.))\n",
    "    bar.set_alpha(0.5)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Don’t worry about the details for now — let’s just run it and see what happens.\n",
    "\n",
    "The easiest way to run this code is to copy and paste into a cell in the notebook.\n",
    "\n",
    "(In older versions of Jupyter you might need to add the command `%matplotlib inline` before you generate the figure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Working with the Notebook\n",
    "\n",
    "Here are a few more tips on working with Jupyter notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Tab Completion\n",
    "\n",
    "In the previous program, we executed the line `import numpy as np`\n",
    "\n",
    "- NumPy is a numerical library we’ll work with in depth.  \n",
    "\n",
    "\n",
    "After this import command, functions in NumPy can be accessed with `np.<function_name>` type syntax.\n",
    "\n",
    "- For example, try `np.random.randn(3)`.  \n",
    "\n",
    "\n",
    "We can explore these attributes of `np` using the `Tab` key.\n",
    "\n",
    "For example, here we type `np.ran` and hit Tab (click to enlarge)\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb6.png\" style=\"\">\n",
    "\n",
    "  \n",
    "Jupyter offers up the two possible completions, `random` and `rank`.\n",
    "\n",
    "In this way, the Tab key helps remind you of what’s available and also saves you typing.\n",
    "\n",
    "\n",
    "<a id='gs-help'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### On-Line Help\n",
    "\n",
    "\n",
    "<a id='index-8'></a>\n",
    "To get help on `np.rank`, say, we can execute `np.rank?`.\n",
    "\n",
    "Documentation appears in a split window of the browser, like so\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb6a.png\" style=\"\">\n",
    "\n",
    "  \n",
    "Clicking on the top right of the lower split closes the on-line help."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Other Content\n",
    "\n",
    "In addition to executing code, the Jupyter notebook allows you to embed text, equations, figures and even videos in the page.\n",
    "\n",
    "For example, here we enter a mixture of plain text and LaTeX instead of code\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb7.png\" style=\"\">\n",
    "\n",
    "  \n",
    "Next we `Esc` to enter command mode and then type `m` to indicate that we\n",
    "are writing [Markdown](http://daringfireball.net/projects/markdown/), a mark-up language similar to (but simpler than) LaTeX.\n",
    "\n",
    "(You can also use your mouse to select `Markdown` from the `Code` drop-down box just below the list of menu items)\n",
    "\n",
    "Now we `Shift+Enter` to produce this\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb8.png\" style=\"\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sharing Notebooks\n",
    "\n",
    "\n",
    "<a id='index-10'></a>\n",
    "Notebook files are just text files structured in [JSON](https://en.wikipedia.org/wiki/JSON) and typically ending with `.ipynb`.\n",
    "\n",
    "You can share them in the usual way that you share files — or by using web services such as [nbviewer](http://nbviewer.jupyter.org/).\n",
    "\n",
    "The notebooks you see on that site are **static** html representations.\n",
    "\n",
    "To run one, download it as an `ipynb` file by clicking on the download icon at the top right.\n",
    "\n",
    "Save it somewhere, navigate to it from the Jupyter dashboard and then run as discussed above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### QuantEcon Notes\n",
    "\n",
    "QuantEcon has its own site for sharing Jupyter notebooks related\n",
    "to economics – [QuantEcon Notes](http://notes.quantecon.org/).\n",
    "\n",
    "Notebooks submitted to QuantEcon Notes can be shared with a link, and are open\n",
    "to comments and votes by the community."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing Libraries\n",
    "\n",
    "\n",
    "<a id='index-11'></a>\n",
    "Most of the libraries we need come in Anaconda.\n",
    "\n",
    "Other libraries can be installed with `pip`.\n",
    "\n",
    "One library we’ll be using is [QuantEcon.py](http://quantecon.org/python_index.html).\n",
    "\n",
    "\n",
    "<a id='gs-install-qe'></a>\n",
    "You can install [QuantEcon.py](http://quantecon.org/python_index.html) by\n",
    "starting Jupyter and typing\n",
    "\n",
    "> `!pip install --upgrade quantecon`\n",
    "\n",
    "\n",
    "into a cell.\n",
    "\n",
    "Alternatively, you can type the following into a terminal\n",
    "\n",
    "> `pip install quantecon`\n",
    "\n",
    "\n",
    "More instructions can be found on the [library page](http://quantecon.org/python_index.html).\n",
    "\n",
    "To upgrade to the latest version, which you should do regularly, use\n",
    "\n",
    "> `pip install --upgrade quantecon`\n",
    "\n",
    "\n",
    "Another library we will be using is [interpolation.py](https://github.com/EconForge/interpolation.py).\n",
    "\n",
    "This can be installed by typing in Jupyter\n",
    "\n",
    "> `!pip install interpolation`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with Files\n",
    "\n",
    "How does one run a locally saved Python file?\n",
    "\n",
    "There are a number of ways to do this but let’s focus on methods using Jupyter notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Option 1: Copy and Paste\n",
    "\n",
    "The steps are:\n",
    "\n",
    "1. Navigate to your file with your mouse/trackpad using a file browser.  \n",
    "1. Click on your file to open it with a text editor.  \n",
    "1. Copy and paste into a cell and `Shift-Enter`.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Method 2: Run\n",
    "\n",
    "Using the `run` command is often easier than copy and paste.\n",
    "\n",
    "- For example, `%run test.py` will run the file `test.py`.  \n",
    "\n",
    "\n",
    "(You might find that the `%` is unnecessary — use `%automagic` to toggle the need for `%`)\n",
    "\n",
    "Note that Jupyter only looks for `test.py` in the present working directory (PWD).\n",
    "\n",
    "If `test.py` isn’t in that directory, you will get an error.\n",
    "\n",
    "Let’s look at a successful example, where we run a file `test.py` with contents:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "for i in range(5):\n",
    "    print('foobar')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here’s the notebook (click to enlarge)\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb_run.png\" style=\"\">\n",
    "\n",
    "  \n",
    "Here\n",
    "\n",
    "- `pwd` asks Jupyter to show the PWD (or `%pwd` — see the comment about automagic above)  \n",
    "  \n",
    "  - This is where Jupyter is going to look for files to run.  \n",
    "  - Your output will look a bit different depending on your OS.  \n",
    "  \n",
    "- `ls` asks Jupyter to list files in the PWD (or `%ls`)  \n",
    "  \n",
    "  - Note that `test.py` is there (on our computer, because we saved it there earlier).  \n",
    "  \n",
    "- `cat test.py` asks Jupyter to print the contents of `test.py` (or `!type test.py` on Windows)  \n",
    "- `run test.py` runs the file and prints any output  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### But File X isn’t in my PWD!\n",
    "\n",
    "If you’re trying to run a file not in the present working directory, you’ll get an error.\n",
    "\n",
    "To fix this error you need to either\n",
    "\n",
    "1. Shift the file into the PWD, or  \n",
    "1. Change the PWD to where the file lives  \n",
    "\n",
    "\n",
    "One way to achieve the first option is to use the `Upload` button\n",
    "\n",
    "- The button is on the top level dashboard, where Jupyter first opened to  \n",
    "- Look where the pointer is in this picture  \n",
    "\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb_upload.png\" style=\"\">\n",
    "\n",
    "  \n",
    "The second option can be achieved using the `cd` command\n",
    "\n",
    "> - On Windows it might look like this `cd C:/Python27/Scripts/dir`  \n",
    "- On Linux / OSX it might look like this `cd /home/user/scripts/dir`  \n",
    "\n",
    "\n",
    "\n",
    "Note: You can type the first letter or two of each directory name and then use the tab key to expand."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Loading Files\n",
    "\n",
    "It’s often convenient to be able to see your code before you run it.\n",
    "\n",
    "In the following example, we execute `load white_noise_plot.py` where `white_noise_plot.py` is in the PWD.\n",
    "\n",
    "(Use `%load` if automagic is off)\n",
    "\n",
    "Now the code from the file appears in a cell ready to execute.\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/nb_wntest2.png\" style=\"\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving Files\n",
    "\n",
    "To save the contents of a cell as file `foo.py`\n",
    "\n",
    "- put `%%file foo.py` as the first line of the cell  \n",
    "- `Shift+Enter`  \n",
    "\n",
    "\n",
    "Here `%%file` is an example of a [cell magic](http://ipython.readthedocs.org/en/stable/interactive/magics.html#cell-magics)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Editors and IDEs\n",
    "\n",
    "The preceding discussion covers most of what you need to know to interact with\n",
    "this website.\n",
    "\n",
    "However, as you start to write longer programs, you might want to experiment\n",
    "with your workflow.\n",
    "\n",
    "There are many different options and we mention them only in passing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### JupyterLab\n",
    "\n",
    "\n",
    "<a id='index-13'></a>\n",
    "[JupyterLab](https://github.com/jupyterlab/jupyterlab) is an integrated development environment centered around Jupyter notebooks.\n",
    "\n",
    "It is available through Anaconda and will soon be made the default environment for Jupyter notebooks.\n",
    "\n",
    "Reading the docs or searching for a recent YouTube video will give you more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Text Editors\n",
    "\n",
    "A text editor is an application that is specifically designed to work with text files — such as Python programs.\n",
    "\n",
    "Nothing beats the power and efficiency of a good text editor for working with program text.\n",
    "\n",
    "A good text editor will provide\n",
    "\n",
    "> - efficient text editing commands (e.g., copy, paste, search and replace)  \n",
    "- syntax highlighting, etc.  \n",
    "\n",
    "\n",
    "\n",
    "Among the most popular are [Sublime Text](http://www.sublimetext.com/) and [Atom](https://atom.io/).\n",
    "\n",
    "For a top quality open source text editor with a steeper learning curve, try [Emacs](http://www.gnu.org/software/emacs/).\n",
    "\n",
    "If you want an outstanding free text editor and don’t mind a seemingly vertical learning curve plus long days of pain and suffering while all your neural pathways are rewired, try [Vim](http://www.vim.org/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Text Editors Plus IPython Shell\n",
    "\n",
    "\n",
    "<a id='index-15'></a>\n",
    "A text editor is for writing programs.\n",
    "\n",
    "To run them you can continue to use Jupyter as described above.\n",
    "\n",
    "Another option is to use the excellent [IPython shell](https://ipython.org).\n",
    "\n",
    "To use an IPython shell, open up a terminal and type `ipython`.\n",
    "\n",
    "You should see something like this\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/ipython_shell.png\" style=\"\">\n",
    "\n",
    "  \n",
    "The IPython shell has many of the features of the notebook: tab completion, color syntax, etc.\n",
    "\n",
    "It also has command history through the arrow key.\n",
    "\n",
    "The up arrow key to brings previously typed commands to the prompt.\n",
    "\n",
    "This saves a lot of typing…\n",
    "\n",
    "Here’s one set up, on a Linux box, with\n",
    "\n",
    "- a file being edited in  [Vim](http://www.vim.org/)  \n",
    "- an IPython shell next to it, to run the file  \n",
    "\n",
    "\n",
    "<img src=\"https://s3-ap-southeast-2.amazonaws.com/lectures.quantecon.org/py/_static/lecture_specific/getting_started/editing_vim.png\" style=\"\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### IDEs\n",
    "\n",
    "IDEs are Integrated Development Environments, which allow you to edit, execute\n",
    "and interact with code from an integrated environment.\n",
    "\n",
    "One of the most popular in recent times is VS Code, which is [now available\n",
    "via Anaconda](https://www.anaconda.com/blog/company-blog/vs-code-in-anaconda-distribution-5-1/).\n",
    "\n",
    "We hear good things about VS Code — please tell us about your experiences on\n",
    "[the forum](http://discourse.quantecon.org/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 1\n",
    "\n",
    "If Jupyter is still running, quit by using `Ctrl-C` at the terminal where you started it.\n",
    "\n",
    "Now launch again, but this time using `jupyter notebook --no-browser`.\n",
    "\n",
    "This should start the kernel without launching the browser.\n",
    "\n",
    "Note also the startup message: It should give you a URL such as `http://localhost:8888` where the notebook is running.\n",
    "\n",
    "Now\n",
    "\n",
    "1. Start your browser — or open a new tab if it’s already running.  \n",
    "1. Enter the URL from above (e.g. `http://localhost:8888`) in the address bar at the top.  \n",
    "\n",
    "\n",
    "You should now be able to run a standard Jupyter notebook session.\n",
    "\n",
    "This is an alternative way to start the notebook that can also be handy.\n",
    "\n",
    "\n",
    "<a id='gs-ex2'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 2\n",
    "\n",
    "\n",
    "<a id='index-16'></a>\n",
    "This exercise will familiarize you with git and GitHub.\n",
    "\n",
    "[Git](http://git-scm.com/) is a *version control system* — a piece of software used to manage digital projects such as code libraries.\n",
    "\n",
    "In many cases, the associated collections of files — called *repositories* — are stored on [GitHub](https://github.com/).\n",
    "\n",
    "GitHub is a wonderland of collaborative coding projects.\n",
    "\n",
    "For example, it hosts many of the scientific libraries we’ll be using later\n",
    "on, such as [this one](https://github.com/pydata/pandas).\n",
    "\n",
    "Git is the underlying software used to manage these projects.\n",
    "\n",
    "Git is an extremely powerful tool for distributed collaboration — for\n",
    "example, we use it to share and synchronize all the source files for these\n",
    "lectures.\n",
    "\n",
    "There are two main flavors of Git\n",
    "\n",
    "1. the plain vanilla [command line Git](http://git-scm.com/downloads) version  \n",
    "1. the various point-and-click GUI versions  \n",
    "  \n",
    "  - See, for example, the [GitHub version](https://desktop.github.com/)  \n",
    "  \n",
    "\n",
    "\n",
    "As an exercise, try\n",
    "\n",
    "1. Installing Git.  \n",
    "1. Getting a copy of [QuantEcon.py](https://github.com/QuantEcon/QuantEcon.py) using Git.  \n",
    "\n",
    "\n",
    "For example, if you’ve installed the command line version, open up a terminal and enter.\n",
    "\n",
    "> `git clone https://github.com/QuantEcon/QuantEcon.py`.\n",
    "\n",
    "\n",
    "(This is just `git clone` in front of the URL for the repository)\n",
    "\n",
    "Even better,\n",
    "\n",
    "1. Sign up to [GitHub](https://github.com/).  \n",
    "1. Look into ‘forking’ GitHub repositories (forking means making your own copy of a GitHub repository, stored on GitHub).  \n",
    "1. Fork [QuantEcon.py](https://github.com/QuantEcon/QuantEcon.py).  \n",
    "1. Clone your fork to some local directory, make edits, commit them, and push them back up to your forked GitHub repo.  \n",
    "1. If you made a valuable improvement, send us a [pull request](https://help.github.com/articles/about-pull-requests/)!  \n",
    "\n",
    "\n",
    "For reading on these and other topics, try\n",
    "\n",
    "- [The official Git documentation](http://git-scm.com/doc).  \n",
    "- Reading through the docs on [GitHub](https://github.com/).  \n",
    "- [Pro Git Book](http://git-scm.com/book) by Scott Chacon and Ben Straub.  \n",
    "- One of the thousands of Git tutorials on the Net.  "
   ]
  }
 ],
 "metadata": {
  "filename": "getting_started.rst",
  "kernelspec": {
   "display_name": "Python",
   "language": "python3",
   "name": "python3"
  },
  "title": "Setting up Your Python Environment"
 },
 "nbformat": 4,
 "nbformat_minor": 2
}