Finish up tutorial 4.

docs/requirements.txt

@@ -1,3 +1,5 @@
 sphinx
 jupyter
-voevent-parse
+voevent-parse
+matplotlib
+networkx

docs/source/notebooks/tutorial1.ipynb

@@ -5,7 +5,8 @@
    "metadata": {},
    "source": [
     "# Getting started with *voeventdb.remote*\n",
-    "In this notebook, we will cover the basics of working with voeventdb.remote, and give a quick tour of the sorts of data you can retrieve."
+    "\n",
+    "#### In this notebook, we will cover the basics of working with voeventdb.remote, and give a quick tour of the sorts of data you can retrieve."
    ]
   },
   {
@@ -124,7 +125,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -136,7 +137,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -155,7 +156,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -194,7 +195,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -213,7 +214,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -255,7 +256,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -273,7 +274,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [
@@ -292,7 +293,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "collapsed": false
    },
    "outputs": [],
    "source": [

docs/source/notebooks/tutorial2.ipynb

@@ -7,7 +7,7 @@
     "# Narrowing your query and digging into your results\n",
     "We previously covered the basics of working with voeventdb.remote in tutorial 1. \n",
     "\n",
-    "In this notebook, we'll demonstrate the use of filters to narrow down your query, and demonstrate the 'helper classes' you can use to easily access the details of a particular packet."
+    "#### In this notebook, we'll demonstrate how to use combinations of filters to narrow down your query, and demonstrate the 'helper classes' you can use to easily access the details of a particular packet."
    ]
   },
   {
@@ -98,15 +98,17 @@
    "outputs": [],
    "source": [
     "## To see the list of filters, you can use tab-completion:\n",
+    "## (Uncomment the following line and try it for yourself)\n",
     "# FilterKeys.\n",
-    "## Or the ipython doc-lookup magic, by prefixing with ``??``:\n",
+    "## Or the ipython doc-lookup magic, by prefixing with ``??`` and running the cell:\n",
     "# ??FilterKeys"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "### Filtering by role\n",
     "So: we were trying to filter out the test-packets. ``FilterKeys.role`` sounds promising. To apply a filter, or multiple filters, we simply define a dictionary with the filters we want to apply, and then pass it to the relevant query-function, like this:"
    ]
   },
@@ -136,6 +138,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "### Filtering by date\n",
     "That results in a much shorter list, containing only scientifically interesting streams. Still, those numbers are pretty large (mainly for *Swift*). It might be useful to get a smaller representative sample. How many packets will we get if we limit our query to a single week?"
    ]
   },
@@ -173,6 +176,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "### Filtering by stream\n",
     "Ok, so there's still a lot of *Swift* packets there. Let's take a look at a sample of those, and see if we can break them up further. First, lets add another filter to limit our query to just *Swift* packets."
    ]
   },
@@ -184,7 +188,7 @@
    },
    "outputs": [],
    "source": [
-    "my_filters[FilterKeys.stream]='nasa.gsfc.gcn/SWIFT'\n",
+    "my_filters[FilterKeys.stream] = 'nasa.gsfc.gcn/SWIFT'\n",
     "my_filters"
    ]
   },
@@ -210,6 +214,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "### Filters can be used across different query-endpoints\n",
     "Not particularly helpful, but at least everything is working as expected. Now, the neat thing about the voeventdb filters is that they can be applied to **any** query-endpoint - we can just re-use the filter-dictionary with the ``apiv1.ivorn`` function to get back a list of IVORNs:"
    ]
   },
@@ -255,6 +260,8 @@
    "source": [
     "Now we're getting somewhere! We can clearly see the subcategories of Swift packets - BAT alerts, XRT positions, UVOT followup, etc. \n",
     "\n",
+    "### Filtering by IVORN substring\n",
+    "\n",
     "We can use this knowledge to refine our filters, by filtering on a *substring* of the IVORN, using the ``ivorn_contains`` filter. For example, we might want to filter to just those IVORNs containing XRT positions (**note this filter is case-sensitive**):"
    ]
   },
@@ -287,7 +294,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As in tutorial 1, we can inspect the details of any given packet - we'll take a look at the first one. This packet makes a good example, as it includes details of the event co-ordinates and timestamp, and also references an earlier VOEvent:"
+    "As in tutorial 1, we can inspect the details of any given packet using the ``synopsis`` endpoint - we'll take a look at the first one. This packet makes a good example, as it includes details of the event co-ordinates and timestamp, and also references an earlier VOEvent:"
    ]
   },
   {
@@ -332,15 +339,15 @@
    "outputs": [],
    "source": [
     "xrt_synopsis = Synopsis(synopsis_dict)\n",
-    "# Prints with nicer formatting:\n",
+    "# Prints with nicer formatting, ordering of values:\n",
     "print(xrt_synopsis)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can easily access the values (with the ever-handy IPython autocompletion):"
+    "Now we can easily access the values (with the ever-handy IPython autocompletion):"
    ]
   },
   {
@@ -399,7 +406,7 @@
    },
    "outputs": [],
    "source": [
-    "# List of 1, in this case. Grab the first (only) element:\n",
+    "# List of 1, in this case. Grab the first (and only) element:\n",
     "sky_event = xrt_synopsis.sky_events[0]"
    ]
   },
@@ -446,12 +453,43 @@
     "print(sky_event.position.ra.hms)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Advanced usage: specifying multiple values for the same filter\n",
+    "Before we move on, it's worth mentioning that some filters can take on multiple values. This is specified by defining the filter-value as a list - for example, to return all VOEvents with a role of 'observation' or 'utility' we can use the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "my_filters = {apiv1.FilterKeys.role: ['observation','utility']}\n",
+    "apiv1.stream_count(my_filters)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "How does this work? Well, we can think of each entry in the list defining a separate filter.\n",
+    "For the `role` value, these filters are combined in the logical 'OR' sense, so we get back combined counts for both 'observation' and 'utility' packets. You can check whether a filter accepts multiple values, and if they are combined via logical 'OR' or 'AND', by checking the \n",
+    "[filter-definitions page](http://voeventdb.readthedocs.org/en/latest/apiv1/queryfilters.html) and looking for the ``combinator`` attribute. \n",
+    "\n",
+    "(If this sounds confusing, don't worry - it can safely be ignored unless you're planning to use really tricky queries.)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Coming next ...\n",
-    "We've seen how to narrow our search, locate packets of interest, and pull up the details. \n",
+    "We've seen how to narrow our search, locate packets of interest, and use helper-classes to easily access packet details. \n",
     "In the next tutorial, we'll cover different ways of finding *related* VOEvents."
    ]
   }