.. _limits:


***************
Upper Limits
***************

.. _RooStats:

Understanding RooStats
=============================

I will use RooStats `RooStats <http://root.cern.ch/root/html/RooStats.html/>`_
in order to set an upper limit on the :math:`\Upsilon(3S)`::

  python -c 'import sphinx'

If that fails grab the latest version of and install it with::

  > sudo easy_install -U Sphinx

Now you are ready to build a template for your docs, using
sphinx-quickstart::

  > sphinx-quickstart

accepting most of the defaults.  I choose "sampledoc" as the name of my
project.  cd into your new directory and check the contents::

  home:~/tmp/sampledoc> ls
  Makefile	_static		conf.py
  _build		_templates	index.rst

The index.rst is the master ReST for your project, but before adding
anything, let's see if we can build some html::

  make html

If you now point your browser to :file:`_build/html/index.html`, you
should see a basic sphinx site.

.. image:: _static/basic_screenshot.png

.. _Bayesian:

Bayesian Approach
-----------------

Now we will start to customize out docs.  Grab a couple of files from
the `web site <http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/sampledoc_tut/>`_
or svn.

The last step is to modify :file:`index.rst` to include the
:file:`getting_started.rst` file (be careful with the indentation, the
"g" in "getting_started" should line up with the ':' in ``:maxdepth``::

  Contents:

  .. toctree::
     :maxdepth: 2

     getting_started.rst

and then rebuild the docs::

  cd sampledoc
  make html
  
.. _Frequentist:

Frequentist Approach
-----------------

 .. plot:: pyplots/xsection.py
     :include-source:

.. image:: pyplots/UPC_pt_graphlog.png
 

Inserting automatically-generated plots is easy.  Simply put the
script to generate the plot in the :file:`pyplots` directory, and
refer to it using the ``plot`` directive.  First make a
:file:`pyplots` directory at the top level of your project (next to
:``conf.py``) and copy the :file:`ellipses.py`` file into it::

    home:~/tmp/sampledoc> mkdir pyplots
    home:~/tmp/sampledoc> cp ../sampledoc_tut/pyplots/ellipses.py pyplots/


You can refer to this file in your sphinx documentation; by default it
will just inline the plot with links to the source and PF and high
resolution PNGS.  To also include the source code for the plot in the
document, pass the ``include-source`` parameter::

  .. plot:: pyplots/ellipses.py
     :include-source:


In the HTML version of the document, the plot includes links to the
original source code, a high-resolution PNG and a PDF.  In the PDF
version of the document, the plot is included as a scalable PDF.

  .. plot:: pyplots/ellipses.py
     :include-source:
 

You can also inline code for plots directly, and the code will be
executed at documentation build time and the figure inserted into your
docs; the following code::

.. plot::

   import matplotlib.pyplot as plt
   import numpy as np
   x = np.random.randn(1000)
   plt.hist( x, 20)
   plt.grid()
   plt.title(r'Normal: $\mu=%.2f, \sigma=%.2f$'%(x.mean(), x.std()))
   plt.show()

produces this output:

.. plot::

  import matplotlib.pyplot as plt
  import numpy as np
  x = np.random.randn(1000)
  plt.hist( x, 20)
  plt.grid()
  plt.title(r'Normal: $\mu=%.2f, \sigma=%.2f$'%(x.mean(), x.std()))
  plt.show()


See the matplotlib `pyplot tutorial
<http://matplotlib.sourceforge.net/users/pyplot_tutorial.html>`_ and
the `gallery <http://matplotlib.sourceforge.net/gallery.html>`_ for
lots of examples of matplotlib plots.


When you reload the page by refreshing your browser pointing to
:file:`_build/html/index.html`, you should see a link to the
"Getting Started" docs, and in there this page with the screenshot.
`Voila!`

Note we used the image directive to include to the screenshot above
with::

  .. image:: _static/basic_screenshot.png


Next we'll customize the look and feel of our site to give it a logo,
some custom css, and update the navigation panels to look more like
the `sphinx <http://sphinx.pocoo.org/>`_ site itself -- see
:ref:`custom_look`.