01_hax_tutorial_part1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Learn how to use hax\n",
    "\n",
    "Aalbers and Tunnell, Feburary 2016\n",
    "\n",
    "This tutorial describes how to use the basic functionality of the `hax` analysis library from python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": "true"
   },
   "source": [
    "# Table of Contents\n",
    " <p><div class=\"lev1\"><a href=\"#Learn-how-to-use-hax\"><span class=\"toc-item-num\">1 - </span>Learn how to use hax</a></div><div class=\"lev2\"><a href=\"#Introduction\"><span class=\"toc-item-num\">1.1 - </span>Introduction</a></div><div class=\"lev2\"><a href=\"#Boilerplate-startup\"><span class=\"toc-item-num\">1.2 - </span>Boilerplate startup</a></div><div class=\"lev1\"><a href=\"#Using-mini-trees\"><span class=\"toc-item-num\">2 - </span>Using mini-trees</a></div><div class=\"lev2\"><a href=\"#Using-standard-data\"><span class=\"toc-item-num\">2.1 - </span>Using standard data</a></div><div class=\"lev2\"><a href=\"#Selecting-your-own-variables\"><span class=\"toc-item-num\">2.2 - </span>Selecting your own variables</a></div><div class=\"lev1\"><a href=\"#Looping-over-ROOT-files\"><span class=\"toc-item-num\">3 - </span>Looping over ROOT files</a></div><div class=\"lev1\"><a href=\"#Selecting-datasets\"><span class=\"toc-item-num\">4 - </span>Selecting datasets</a></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default pax output format is a ROOT file containing an event class, which is fully documented [here](http://xenon1t.github.io/pax/format.html). While you could analyze this with TTree.Draw (in python or C++), this has several disadvantages:\n",
    "  * You never get access to the actual values of the data;\n",
    "  * It is difficult to compute things that are not directly in the tree;\n",
    "  * You need to re-loop over the data every time you want to make a new plot.\n",
    "\n",
    "You can get much more flexibility by looping over the events in the ROOT file(s) you want to analyze (we will cover this in section 3 below). However, looping over all the ROOT events every time you want to adjust a plot or cut is still very inconvenient.\n",
    "\n",
    "To extract data, hax lets you make **mini-trees**, small, flat ROOT files which contain just the data you need for every event. Since a mini-tree is such a simple (tabular) structure, for python analyses you can read them into a [pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/10min.html), one of the most-used objects in data science. Since it's the fastest way to the data, we'll cover mini-trees in section 2."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Boilerplate startup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A jupyter notebook is a complete application, so you always need some startup code, which is usually the same across notebooks. In future we will hide this (since it isn't very exciting), but in case you are interested we go through it here.\n",
    "\n",
    "First, we importing the math library [numpy](https://en.wikipedia.org/wiki/NumPy)\n",
    "and the plotting library [matplotlib](https://en.wikipedia.org/wiki/Matplotlib):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The command below makes matplotlib plots actually appear in the notebook. By default they are meant to pop-up in a new window, but besides being very inconvenient, this doesn't work if you are accessing a notebook server remotely."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we set up a few more sensible defaults for matplotlib. In the future we can expand this to our very own XENON plot style..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "matplotlib.rc('font', size=16)                   # Use big fonts...\n",
    "plt.rcParams['figure.figsize'] = (12.0, 10.0)    # ... and big plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now it is time to import `hax`. This may give a \"ShimWarning\" which you can ignore (we're trying to get rid of this):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/afs/pdc.kth.se/projects/xenon/software/Anaconda3r5/envs/pax/lib/python3.4/site-packages/IPython/kernel/__init__.py:13: ShimWarning: The `IPython.kernel` package has been deprecated. You should import from ipykernel or jupyter_client instead.\n",
      "  \"You should import from ipykernel or jupyter_client instead.\", ShimWarning)\n"
     ]
    }
   ],
   "source": [
    "import hax"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "hax.config.CONFIG['main_data_paths'].append('/cfs/klemming/projects/xenon/common/PaxReprocessed_9/good')\n",
    "hax.runs.update_datasets()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, you may want to set some special the hax configuration options. For example, use:\n",
    "\n",
    "    hax.config.CONFIG['main_data_paths'].append(['/path/to/my/secret/data'])\n",
    "    hax.runs.update_datasets()\n",
    "    \n",
    "to add `/path/to/my/secret/data` to the paths hax searches for datasets."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using mini-trees"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using standard data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For basic analyses, you need only some very basic data (s1, s2, positions, etc). You can load this in as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "                                                       "
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Created minitree Basics for dataset xe100_111002_2248\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\r"
     ]
    }
   ],
   "source": [
    "#dataset = 'xe100_120402_2000'\n",
    "dataset = 'xe100_111002_2248'\n",
    "data = hax.minitrees.load(dataset)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You have now loaded in a dataframe with info from the 'Basics' minitree. The **variables and units are documented [here](http://hax.readthedocs.org/en/latest/hax.treemakers.html)**; we can get an overview like so:"
   ]
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.4.4"
  },
  "toc": {
   "toc_cell": true,
   "toc_number_sections": true,
   "toc_section_display": "block",
   "toc_threshold": 4,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}