ansible/files/materials/1-Finding Functions and Documentation in Jupyter.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Finding Functions with NumPy and Jupyter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NumPy is a large complex library with hundreds of useful functions. Often the hardest part of solving a problem with NumPy is simply finding the right function to use, or figuring out whether a function you've found can solve your problem.\n",
    "\n",
    "The official documentation for Numpy and SciPy are excellent resources:\n",
    "\n",
    "- The official NumPy documentation: [https://docs.scipy.org/doc/numpy-1.13.0/reference/](https://docs.scipy.org/doc/numpy-1.13.0/reference/)\n",
    "- The offical SciPy documentation: [https://docs.scipy.org/doc/scipy/reference/](https://docs.scipy.org/doc/scipy/reference/)\n",
    "\n",
    "There are also a few tricks you can use to learn about NumPy functions without having to leave the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose, for example, that we want to find the [eigenvalues](https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors) of a matrix. The first thing we might try is to use Jupyter's tab-completion feature to see if there's a top-level function with a name like \"eigenvalues\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Place your cursor immediately after the `e` and hit TAB to see the top-level numpy functions\n",
    "# that start with the letter \"e\"\n",
    "np.e"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unfortunately for us, none of the functions that appear look like they're related to eigenvalues. The next thing we can try is to use [`np.lookfor`](https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.lookfor.html) to search for \"eigenvalue\" by keyword:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.lookfor(\"eigenvalue\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That looks more promising, but now we have to figure out which function to use. For that, we can use Jupyter's `?` operator. Running a cell containing `function_name?` will bring up a window containing documentation about the function.\n",
    "\n",
    "Execute the following cell and read the documentation for `eigvals`. In particular, notice that if you scroll down, there are **\"Examples\"** and **\"See Also\"** sections. These sections are as or more useful than the description of the what a function does."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.linalg.eigvals?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For cases where we just to check a docstring quickly, it can be more ergonomic to bring up documentation in-line using Shift+Tab:\n",
    "\n",
    "Place your cursor after \"eigvals\", hold Shift, and then press Tab. You should see the signature and the first line of the function's documentation. You can see the rest of the documentation by pressing Tab again without letting go of Shift."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.linalg.eigvals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise: Finding Functions\n",
    "\n",
    "Use `np.lookfor` and `?` to find functions that do the following:\n",
    "\n",
    "- Compute the largest value in an array.\n",
    "- Compute the smallest value in an array.\n",
    "- Compute the value at the 90th percentile of an array.\n",
    "- Sort an array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise: Finding Functions (continued)\n",
    "\n",
    "Continue using `np.lookfor` and `?` to find functions that do the following:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Find a value in a sorted array.\n",
    "- Compute the [natural logarithm](https://en.wikipedia.org/wiki/Natural_logarithm) of each element in an array.\n",
    "- Compute the [Correlation Coefficient](https://en.wikipedia.org/wiki/Correlation_coefficient) between two arrays.\n",
    "- Fit coefficients of a polynomial function.\n",
    "- Compute a [Covariance Matrix](https://en.wikipedia.org/wiki/Covariance_matrix)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}