Merge pull request #210 from sot/update-docs-shiny

Update docs shiny

docs/conf.py

@@ -142,7 +142,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/fetch_tutorial.rst

@@ -1232,8 +1232,9 @@ This brings up a text-based process monitor.  Focus on that window and hit "M"
 to tell it to order by memory usage.  Now go back to your main window and get
 all the ``TEIO`` data for the mission::
 
-  ipython --pylab
+  ipython --matplotlib
   import Ska.engarchive.fetch as fetch
+  import matplotlib.pyplot as plt
   from Ska.Matplotlib import plot_cxctime
   time teio = fetch.MSID('teio', '2000:001', '2010:001', filter_bad=True)
   Out[]: CPU times: user 2.08 s, sys: 0.49 s, total: 2.57 s
@@ -1242,18 +1243,18 @@ all the ``TEIO`` data for the mission::
 Now look at the memory usage and see that around a 1 Gb is being used::
 
   len(teio.vals) / 1e6
-  clf()
+  plt.clf()
   plot_cxctime(teio.times, teio.vals, '.', markersize=0.5)
 
 Making a plot with 13 million points takes 5 to 10 seconds and some memory.
 See what happens to memory when you clear the plot::
 
-  clf()
+  plt.clf()
 
 Now let's get serious and fetch all the AORATE3 values (1 per second) for the mission after deleting the TEIO data::
 
     del teio
-    time aorate3 = fetch.MSID('aorate3', '2000:001', '2010:001', filter_bad=True)
+    %time aorate3 = fetch.MSID('aorate3', '2000:001', '2010:001', filter_bad=True)
     Out[]: CPU times: user 38.83 s, sys: 7.43 s, total: 46.26 s
            Wall time: 60.10 s
 
@@ -1268,8 +1269,8 @@ If you try to make a simple scatter plot with 300 million points you will
 make the machine very unhappy.  But we can do computations or make a histogram of
 the distribution::
 
-  clf()
-  hist(log10(abs(aorate3.vals)+1e-15), log=True, bins=100)
+  plt.clf()
+  plt.hist(np.log10(abs(aorate3.vals)+1e-15), log=True, bins=100)
 
 .. image:: fetchplots/aorate3_hist.png
 

docs/ipython_tutorial.rst

@@ -1,16 +1,15 @@
-**Pylab**
+For interactive data analysis IPython has a special ``--matplotlib`` command line
+option which enables interactive plotting from the command line::
 
-For interactive data analysis IPython has a special ``--pylab`` command line
-option which automatically imports elements of the Numpy and the Matplotlib
-environments.  This provides a Matlab-like environment allowing very simple
-and direct commands like::
+  % ipython --matplotlib
 
-  % ipython --pylab
+  import matplotlib.pyplot as plt
+  import numpy as np
 
-  x = arange(0, 10, 0.2)
-  y = sin(x)
-  print x
-  plot(x, y)
+  x = np.arange(0, 10, 0.2)
+  y = np.sin(x)
+  print(x)
+  plt.plot(x, y)
 
 **Keyboard navigation and history**
 
@@ -19,8 +18,8 @@ you command line history.  This lets you quickly re-do commands, perhaps with a
 slight variation based on seeing the last result.  Try cut-n-pasting the above
 lines in an IPython session.  This should bring up a plot of a sine wave.
 
-Now hit up-arrow once and get back the ``plot(x, y)`` line.  Hit the left-arrow
-key (not backspace) once and type ``**2`` so that the line reads ``plot(x,
+Now hit up-arrow once and get back the ``plt.plot(x, y)`` line.  Hit the left-arrow
+key (not backspace) once and type ``**2`` so that the line reads ``plt.plot(x,
 y**2)``.  Now you can hit Return to see the new curve overlayed within the same
 plot window.  It is not necessary to forward-space to the end of the line, you
 can hit Return with the cursor anywhere in the line.
@@ -29,7 +28,7 @@ Now say you want to change the ``x`` values slightly.  One option is to just hit
 up-arrow 5 times, but a much faster way is to remember that the line started
 with ``x``, so type ``x`` and then start hitting up-arrow.  Only lines that
 start with ``x`` will be displayed and you are immediately at the
-``x = arange(0, 10, 0.2)`` line.  Now use the right-arrow and backspace to change ``10`` to
+``x = np.arange(0, 10, 0.2)`` line.  Now use the right-arrow and backspace to change ``10`` to
 ``15`` and hit Return.  Of course ``y`` needs to be recalculated, so hit ``y``
 then up-arrow, then Return.  Finally ``pl`` up-arrow and Return.  Nice and fast!
 
@@ -56,7 +55,7 @@ can be executed by preceding it with an exclamation point "!".
 **Tab completion**
 
 IPython has a very useful tab completion feature that can be used both to
-complete file names and to inspect python objects.  As a first example do::
+complete file names and to inspect Python objects.  As a first example do::
 
   ls /proj/sot/ska/<TAB>
 
@@ -68,7 +67,7 @@ constant in python is actually a object with a type and associated attributes
 and methods.  For instance try to create a list of 3 numbers::
 
   a = [3, 1, 2, 4]
-  print a
+  print(a)
   a.<TAB>
 
 This will show the available methods for ``a``::
@@ -82,7 +81,7 @@ get help for and use::
 
   help a.sort
   a.sort()
-  print a
+  print(a)
 
 For a more concrete example, say you want to fetch some daily telemetry values
 but forgot exactly how to do the query and what are the available columns.  Use
@@ -109,9 +108,9 @@ help and TAB completion to remind yourself::
 OK, now you remember you wanted ``times`` and ``maxes``.  But look, there are
 other tidbits there for free that look interesting.  So go ahead and print a few::
 
-  print tephin.colnames
-  print tephin.dt
-  print tephin.MSID
+  print(tephin.colnames)
+  print(tephin.dt)
+  print(tephin.MSID)
 
 To make it even easier you don't usually have to use ``print``.  Try the
 following::

docs/matplotlib_tutorial.rst

@@ -1,40 +1,42 @@
 .. include:: references.rst
 
-.. _`plot()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.plot
-.. _`axis()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.axis
-.. _`cla()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.cla
-.. _`clf()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.clf
-.. _`title()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.title
-.. _`gca()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.gca
-.. _`gcf()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.gcf
-.. _`subplot()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.subplot
-.. _`axes()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.axes
-.. _`xlabel()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.xlabel
-.. _`ylabel()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.ylabel
-.. _`text()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.text
-.. _`setp()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.setp
-.. _`figure()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.figure
-.. _`annotate()`: http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.annotate
-
-The ``pylab`` mode of `matplotlib`_ is a collection of command style functions
-that make `matplotlib`_  work like matlab.  Each ``pylab`` function makes
+.. _`plot()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.plot
+.. _`axis()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.axis
+.. _`cla()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.cla
+.. _`clf()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.clf
+.. _`title()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.title
+.. _`gca()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.gca
+.. _`gcf()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.gcf
+.. _`subplot()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.subplot
+.. _`axes()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.axes
+.. _`xlabel()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.xlabel
+.. _`ylabel()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.ylabel
+.. _`text()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.text
+.. _`setp()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.setp
+.. _`figure()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.figure
+.. _`annotate()`: http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.annotate
+
+The ``pyplot`` mode of `matplotlib`_ is a collection of command style functions
+that make `matplotlib`_  work like matlab.  Each ``pyplot`` function makes
 some change to a figure: eg, create a figure, create a plotting area
 in a figure, plot some lines in a plotting area, decorate the plot
-with labels, etc....  ``Pylab`` is stateful, in that it
+with labels, etc....  ``Pyplot`` is stateful, in that it
 keeps track of the current figure and plotting area, and the plotting
 functions are directed to the current axes.  On the
-`matplotlib FAQ <http://matplotlib.sourceforge.net/faq/index.html>`_ page there is a
+`matplotlib FAQ <http://matplotlib.org/faq/index.html>`_ page there is a
 very good discussion on
-`Matplotlib, pylab, and pyplot: how are they related? <http://matplotlib.sourceforge.net/faq/usage_faq.html#matplotlib-pylab-and-pyplot-how-are-they-related>`_.
+`Matplotlib, pylab, and pyplot: how are they related?
+<http://matplotlib.org/faq/usage_faq.html#matplotlib-pylab-and-pyplot-how-are-they-related>`_.
 
 This tutorial has been copied and adapted from the matplotlib
-`pyplot tutorial <http://matplotlib.sourceforge.net/users/pyplot_tutorial.html>`_.
+`pyplot tutorial <http://matplotlib.org/users/pyplot_tutorial.html>`_.
 
 To see `matplotlib`_ in action and make a simple plot do::
 
-  clf()
-  plot([1,2,3])
-  ylabel('some numbers')
+  import matplotlib.pyplot as plt
+  plt.clf()
+  plt.plot([1,2,3])
+  plt.ylabel('some numbers')
 
 .. image:: pyplots/pyplot_simple.png
 
@@ -50,8 +52,8 @@ same length as y but starts with 0.  Hence the x data are
 an arbitrary number of arguments.  For example, to plot x versus y,
 you can issue the command::
 
-  clf()
-  plot([1,2,3,4], [1,4,9,16])
+  plt.clf()
+  plt.plot([1,2,3,4], [1,4,9,16])
 
 For every x, y pair of arguments, there is a optional third argument
 which is the format string that indicates the color and line type of
@@ -60,9 +62,9 @@ matlab, and you concatenate a color string with a line style string.
 The default format string is 'b-', which is a solid blue line.  For
 example, to plot the above with red circles, you would issue::
 
-  clf()
-  plot([1,2,3,4], [1,4,9,16], 'ro')
-  axis([0, 6, 0, 20])
+  plt.clf()
+  plt.plot([1,2,3,4], [1,4,9,16], 'ro')
+  plt.axis([0, 6, 0, 20])
 
 .. image:: pyplots/pyplot_formatstr.png
 
@@ -81,11 +83,11 @@ using arrays.
 ::
 
   # evenly sampled time at 200ms intervals
-  t = arange(0., 5., 0.2)
+  t = np.arange(0., 5., 0.2)
 
   # red dashes, blue squares and green triangles
-  clf()
-  plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
+  plt.clf()
+  plt.plot(t, t, 'r--', t, t**2, 'bs', t, t**3, 'g^')
 
 .. image:: pyplots/pyplot_three.png
 
@@ -101,18 +103,18 @@ scenes.  Below is a script to create two subplots.
 ::
 
   def f(t):
-      return exp(-t) * cos(2*pi*t)
+      return np.exp(-t) * np.cos(2*np.pi*t)
 
-  t1 = arange(0.0, 5.0, 0.1)
-  t2 = arange(0.0, 5.0, 0.02)
+  t1 = np.arange(0.0, 5.0, 0.1)
+  t2 = np.arange(0.0, 5.0, 0.02)
 
-  figure(1)
-  clf()
-  subplot(2, 1, 1)  # (nrows, ncols, fignum)
-  plot(t1, f(t1), 'bo', t2, f(t2), 'k')
+  plt.figure(1)
+  plt.clf()
+  plt.subplot(2, 1, 1)  # (nrows, ncols, fignum)
+  plt.plot(t1, f(t1), 'bo', t2, f(t2), 'k')
 
-  subplot(2, 1, 2)
-  plot(t2, cos(2*pi*t2), 'r--')
+  plt.subplot(2, 1, 2)
+  plt.plot(t2, cos(2*pi*t2), 'r--')
 
 .. image:: pyplots/pyplot_two_subplots.png
 
@@ -134,49 +136,49 @@ You can create multiple figures by using multiple
 number.  Of course, each figure can contain as many axes and subplots
 as your heart desires::
 
-    figure(1)                # the first figure
-    clf()
-    subplot(2, 1, 1)         # the first subplot in the first figure
-    plot([1,2,3])
-    subplot(2, 1, 2)         # the second subplot in the first figure
-    plot([4,5,6])
+    plt.figure(1)                # the first figure
+    plt.clf()
+    plt.subplot(2, 1, 1)         # the first subplot in the first figure
+    plt.plot([1,2,3])
+    plt.subplot(2, 1, 2)         # the second subplot in the first figure
+    plt.plot([4,5,6])
 
 
-    figure(2)                # a second figure
-    clf()
-    plot([4,5,6])            # creates a subplot(111) by default
+    plt.figure(2)                # a second figure
+    plt.clf()
+    plt.plot([4,5,6])            # creates a subplot(111) by default
 
-    figure(1)                # figure 1 current; subplot(2, 1, 2) still current
-    subplot(2, 1, 1)         # make subplot(2, 1, 1) in figure1 current
-    title('Easy as 1,2,3')   # subplot 2, 1, 1 title
+    plt.figure(1)                # figure 1 current; subplot(2, 1, 2) still current
+    plt.subplot(2, 1, 1)         # make subplot(2, 1, 1) in figure1 current
+    plt.title('Easy as 1,2,3')   # subplot 2, 1, 1 title
 
 You can clear the current figure with `clf()`_
 and the current axes with `cla()`_.  If you find
 this statefulness, annoying, don't despair, this is just a thin
 stateful wrapper around an object oriented API, which you can use
-instead  (see `artist-tutorial <http://matplotlib.sourceforge.net/users/artists.html#artist-tutorial>`_)
+instead  (see `artist-tutorial <http://matplotlib.org/users/artists.html#artist-tutorial>`_)
 
 **Working with text**
 
 The `text()`_ command can be used to add text in
 an arbitrary location, and the `xlabel()`_,
 `ylabel()`_ and `title()`_
-are used to add text in the indicated locations (see `text-intro <http://matplotlib.sourceforge.net/users/text_intro.html#text-intro>`_
+are used to add text in the indicated locations (see `text-intro <http://matplotlib.org/users/text_intro.html#text-intro>`_
 for a more detailed example)::
 
   mu, sigma = 100, 15
-  x = mu + sigma * normal(size=10000)
+  x = mu + sigma * np.random.normal(size=10000)
 
   # the histogram of the data
-  clf()
-  n, bins, patches = hist(x, 50, normed=1, facecolor='g', alpha=0.75)
+  plt.clf()
+  n, bins, patches = plt.hist(x, 50, normed=1, facecolor='g', alpha=0.75)
 
-  xlabel('Smarts')
-  ylabel('Probability')
-  title('Histogram of IQ')
-  text(60, .025, r'$\mu=100,\ \sigma=15$')
-  axis([40, 160, 0, 0.03])
-  grid(True)
+  plt.xlabel('Smarts')
+  plt.ylabel('Probability')
+  plt.title('Histogram of IQ')
+  plt.text(60, .025, r'$\mu=100,\ \sigma=15$')
+  plt.axis([40, 160, 0, 0.03])
+  plt.grid(True)
 
 .. image:: pyplots/pyplot_text.png
 
@@ -185,9 +187,10 @@ All of the `text()`_ commands return an
 above, you can customize the properties by passing keyword arguments
 into the text functions or using `setp()`_::
 
-  t = xlabel('my data', fontsize=14, color='red')
+  t = plt.xlabel('my data', fontsize=14, color='red')
 
-These properties are covered in more detail in `text-properties <http://matplotlib.sourceforge.net/users/text_props.html#text-properties>`.
+These properties are covered in more detail in `text-properties
+<http://matplotlib.org/users/text_props.html#text-properties>`.
 
 
 **Using mathematical expressions in text**
@@ -196,18 +199,18 @@ matplotlib accepts TeX equation expressions in any text expression.
 For example to write the expression ``\sigma_i=15`` in the title,
 you can write a TeX expression surrounded by dollar signs::
 
-    title(r'$\sigma_i=15$')
+    plt.title(r'$\sigma_i=15$')
 
 The ``r`` preceeding the title string is important -- it signifies
 that the string is a *raw* string and not to treate backslashes and
 python escapes.  matplotlib has a built-in TeX expression parser and
 layout engine, and ships its own math fonts -- for details see
-`mathtext-tutorial <http://matplotlib.sourceforge.net/users/mathtext.html#mathtext-tutorial>`_.
+`mathtext-tutorial <http://matplotlib.org/users/mathtext.html#mathtext-tutorial>`_.
 Thus you can use mathematical text across platforms
 without requiring a TeX installation.  For those who have LaTeX and
 dvipng installed, you can also use LaTeX to format your text and
 incorporate the output directly into your display figures or saved
-postscript -- see `usetex-tutorial <http://matplotlib.sourceforge.net/users/usetex.html#usetex-tutorial>`_.
+postscript -- see `usetex-tutorial <http://matplotlib.org/users/usetex.html#usetex-tutorial>`_.
 
 
 **Annotating text**