Basics - Help and information.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:2e2651fe5b08bcc89cb101e9422023a1b1e5bb5246c1e2960508d589e2807cb5"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "General information about Python"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can get information about python in the <a href=\"https://www.python.org/doc/\" lang=\"EN\">Python documentation webpage</a>. These pages are superbly well written, and have adapted information to pretty much any level, from beginners to more advanced users. \n",
      "\n",
      "We will use Python 2.7, whose documentation can be found <a href=\"https://docs.python.org/2/\">here</a>. Usually, results from a search engine for functions within python will guide you these pages, so it would be a good idea if you familiarise yourself with them.\n",
      "\n",
      "<a href=\"https://secure.flickr.com/photos/marcobellucci/\"><img src=\"./images/questionMark.jpg\" alt=\"Big Question Mark\" title=\"Question Mark, by Marco Bellucci (CC by 2.0)\"></a>\n",
      "\n",
      "\n",
      "The Python documentation has a section called <a href=\"http://legacy.python.org/dev/peps/\">\"Python Enhancement Proposals\"</a> (PEPs), which contain very general information about various topics. Some of them might have information most scientific users do not care about. But there are several notable ones, amongst which:\n",
      "* Python Style Guide (<a href=\"http://legacy.python.org/dev/peps/pep-0008/\">PEP 8</a>)\n",
      "* The Zen of Python (<a href=\"http://legacy.python.org/dev/peps/pep-0020/\">PEP 20</a>)\n",
      "* Convention about docstrings (<a href=\"http://legacy.python.org/dev/peps/pep-0257/\">PEP 257</a>) \n",
      "* CSV file API (<a href=\"http://legacy.python.org/dev/peps/pep-0305/\">PEP 305</a>)\n",
      "* Conditional expressions (<a href=\"http://legacy.python.org/dev/peps/pep-0308/\">PEP 308</a>)\n",
      "\n"
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Tutorials"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Apart from the tutorial of the Level 1 and Level 2 labs, we also recommend taking a look at the <a href=\"https://docs.python.org/2.7/tutorial/index.html\" lang=\"EN\" >tutorial</a> offered by the python guys.\n"
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Information about functions and modules: the <code>help</code> function and the internet"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The easiest way of getting information is using the internet. \n",
      "Any search engine will spit out several hundred millions pages worth of information if you search for <code>python help</code>. Obviously, looking in the documentation pages of the particular module you are using would help. Some of these pages are:\n",
      "\n",
      "* <a href=\"http://matplotlib.org/\">Matplotlib</a>\n",
      "* Scipy/Numpy documentation in <a href=\"http://scipy.org/docs.html\">scipy.org</a>\n",
      "* <a href=\"http://qutip.org/documentation.html\">Qutip</a>\n",
      "* <a href=\"http://documen.tician.de/pyopencl/\">PyOpenCL</a>\n",
      "\n",
      "These often offer tutorials on different topics, but most of these should be taken as reference pages, in case you want specific information about the contents of different modules, submodules, data types or functions (all of which, in reality, are treated as objects in Python).\n",
      "\n",
      "\n",
      "<b>If you do not have access to the internet, Don't panic!</b> Most packages (like matplotlib, scipy,...) have been created by people with good documentation skills, or have had to pass some sort of \"quality\" standard which prompts them to document their code [link here]. Therefore, these packages will come with a complete documentation, usually in the form of docstrings in the scripts.\n",
      "\n",
      "To access these, you only need to type <code> help(Stuff) </code> in the console and python will look for the docstrings pertaining to this topic or function. The following code will show the information available for the function <code>max</code> in numpy:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from numpy import max as maxi  #The name is changed to keep the builtin MAX function\n",
      "help(maxi)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Help on function amax in module numpy.core.fromnumeric:\n",
        "\n",
        "amax(a, axis=None, out=None)\n",
        "    Return the maximum of an array or maximum along an axis.\n",
        "    \n",
        "    Parameters\n",
        "    ----------\n",
        "    a : array_like\n",
        "        Input data.\n",
        "    axis : int, optional\n",
        "        Axis along which to operate.  By default flattened input is used.\n",
        "    out : ndarray, optional\n",
        "        Alternate output array in which to place the result.  Must be of\n",
        "        the same shape and buffer length as the expected output.  See\n",
        "        `doc.ufuncs` (Section \"Output arguments\") for more details.\n",
        "    \n",
        "    Returns\n",
        "    -------\n",
        "    amax : ndarray or scalar\n",
        "        Maximum of `a`. If `axis` is None, the result is a scalar value.\n",
        "        If `axis` is given, the result is an array of dimension\n",
        "        ``a.ndim - 1``.\n",
        "    \n",
        "    See Also\n",
        "    --------\n",
        "    nanmax : NaN values are ignored instead of being propagated.\n",
        "    fmax : same behavior as the C99 fmax function.\n",
        "    argmax : indices of the maximum values.\n",
        "    \n",
        "    Notes\n",
        "    -----\n",
        "    NaN values are propagated, that is if at least one item is NaN, the\n",
        "    corresponding max value will be NaN as well.  To ignore NaN values\n",
        "    (MATLAB behavior), please use nanmax.\n",
        "    \n",
        "    Examples\n",
        "    --------\n",
        "    >>> a = np.arange(4).reshape((2,2))\n",
        "    >>> a\n",
        "    array([[0, 1],\n",
        "           [2, 3]])\n",
        "    >>> np.amax(a)\n",
        "    3\n",
        "    >>> np.amax(a, axis=0)\n",
        "    array([2, 3])\n",
        "    >>> np.amax(a, axis=1)\n",
        "    array([1, 3])\n",
        "    \n",
        "    >>> b = np.arange(5, dtype=np.float)\n",
        "    >>> b[2] = np.NaN\n",
        "    >>> np.amax(b)\n",
        "    nan\n",
        "    >>> np.nanmax(b)\n",
        "    4.0\n",
        "\n"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note that this function is different from the builtin <code>max</code> function."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "help(max)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Help on built-in function max in module __builtin__:\n",
        "\n",
        "max(...)\n",
        "    max(iterable[, key=func]) -> value\n",
        "    max(a, b, c, ...[, key=func]) -> value\n",
        "    \n",
        "    With a single iterable argument, return its largest item.\n",
        "    With two or more arguments, return the largest argument.\n",
        "\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If <code>help</code> is used on modules, it shows the different submodules, data types and functions it contains, often giving more detailed information about their contents."
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Other sources of information"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "One of the best things about Python is the <b>tremendous user base</b>, which provides with questions and answers about the problems they encounter with the language. These are a invaluable resource, as they push the knowledge of python from the \"general information\" given by manuals and tutorials to the specific case uses.\n",
      "\n",
      "They usually do this in forums, mailing lists or places like <a href=\"https://stackoverflow.com/\">StackOverflow</a>.\n",
      "\n",
      "<b>Looking for information in these places is a very valid resource</b>, as you should not waste time in problems that have already been solved elsewhere; furthermore, reading someone else's code will help you in your own coding practice. You should be wary, though, as many solutions to problems are quick-and-dirty approaches to problems.\n",
      "\n",
      "However, <b>posting new questions in these places should be used as the last resort for information</b>, when the manual and search engines have not been your friends (see <a href=\"https://en.wikipedia.org/wiki/RTFM\" title=\"Read the bloody manual\">RTBM</a>).\n",
      "\n",
      "Finally, if you find a solution to one of the problems that you have stumbled upon with no solution on the web, please consider documenting it by posting the answer in the internet. The world will become a better place.\n",
      "\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Exercises\n",
      "* Use the ```help``` function in your python interpreter to get information about the following functions:\n",
      "    * float()\n",
      "    * range()\n",
      "    * sum()\n",
      "    \n",
      "    \n",
      "* Find, at least, one <em>matplotlib</em> function that allows you to plot a contour graph."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}