Finding and installing useful tools

We’ll start by installing two useful tools for working with VOEvents in the Python programming language. It’s impossible to provide comprehensive instructions for every possible operating system, but the good news is that the tools are generally pretty easy to install. We’ll discuss then general principles, and provide step-by-step instructions for common platforms—you should be able to adapt these to your own system.

Broadly speaking, there are two possible approaches you can take to getting an appropriate set of tools on your system: you can either build & install them yourself—the “conventional” way—or use some sort of prepackaged environment which has everything you need already installed in it. This document focuses on the first option, but includes a brief discussion of the second approach.

Background and dependencies

In general, we suggest relying on package management tools where possible, rather than attempting to compile everything from scratch. For Python packages, we’ll use pip; for system libraries, use a package manager appropriate to your operating system (APT for Debian, Ubuntu and related systems; Macports or Homebrew on OS X, etc). If you don’t have permission to use one of these systems, ask your system administrator nicely (or, better, get yourself a cheap-as-chips VM from Amazon EC2 or Digital Ocean or similar).

Note that we depend on Python 2.7; not all of the tools described have yet been ported to Python 3. This is unfortunate, but you can help.

We suggest using Virtualenv to create an isolated environment for installing the Python packages we’ll need. That means you don’t need any special privileges, and you can blow the whole thing away and start over when you make a mistake simply by running rm.

In addition to Python, pip and Virtualenv, you will need to install libxml2 and libxslt. You’ll need the header files for zlib (the library itself was almost certainly installed along with your operating system). You’ll also find IPython useful for following along with our examples. This is a good time to look into package managers, as mentioned above. On Ubuntu 14.04.2:

$ sudo apt-get update
$ sudo apt-get install libxml2-dev libxslt-dev zlib1g-dev python-dev python-pip python-virtualenv ipython

Or with OS X using Macports, try:

$ sudo port selfupdate
$ sudo port install libxml2 libxslt python27 py27-pip py27-virtualenv py27-ipython

# Use the software we've just installed as the default versions
$ sudo port select python python27
$ sudo port select pip pip27
$ sudo port select virtualenv virtualenv27
$ sudo port select ipython ipython27

Similar incantations should work on other systems. Next, create a Virtualenv for working in and activate it. The name is arbitrary; call it whatever you like:

$ virtualenv voevent-venv
New python executable in voevent-venv/bin/python
Installing setuptools, pip...done.
$ . voevent-venv/bin/activate

You will need to source the activate script in this way every time you want to use this environment.

Reading and writing VOEvents: voevent-parse

For manipulating the contents of VOEvents, we’ll use the voevent-parse library. After you have set up and activated your Virtualenv, as above, installing voevent-parse is easy using pip:

$ pip install voevent-parse

The compilation will take a few moments. Then you can check if it is properly installed by running:

$ ipython
[...]
In [1]: import voeventparse

In [2]: voeventparse.__version__
Out[2]: 0.7.0

If you aren’t familiar with the IPython shell, it’s worth your while to spent a few minutes getting used to it at this point.

This document will provide an introduction to using voevent-parse, but for the full story you should refer to its fine documentation.

Sending and receiving VOEvents: Comet

For transmitting VOEvents using VTP, we’ll use Comet (Swinbank, 2014). Installation proceeds in just the same way as for voevent-parse:

$ pip install comet

Unlike voevent-parse, Comet is not a library you will import into Python, but is rather invoked through twistd, a stand alone tool. You can check that it is installed by running:

$ twistd comet --help
Usage: twistd [options] comet [options]
Options:
  -r, --receive                   Listen for TCP connections from authors.
  -b, --broadcast                 Re-broadcast VOEvents received.
[...]

It’s also worth running the Comet test suite to check that everything has been installed properly:

$ trial comet
comet.handler.test.test_relay
  EventRelayTestCase
      test_interface ...                  [OK]
          test_name ...                   [OK]
[...]
Ran 144 tests in 0.443s

PASSED (successes=144)

All tests should succeed.

Again, this guide will cover the basics of using Comet, but it is well worth your while to read its documentation.

An alternative approach: containerization

Note

This section was contributed by Casey Law.

Finally, you can use docker to quickly build all of the above for use in a Jupyter (IPython) notebook. Docker uses “containerization” (a kind of virtual machine) to build entire operating systems and save you a lot of work. If you choose to go this route, you’ll need to install docker. Then download the Dockerfile for the docker notebook to an empty directory and run:

$ docker build -t notebook .
$ docker run -d -p 8888:8888 -v ~/jupyter-notebooks/:/ipynb notebook

Note that ~/jupyter-notebooks is a stand-in for the path to a place on your file system where you’d like to save your notebooks. The docker run command start the Jupyter notebook server running the entire VOEvent environment. You can find the notebook by pointing your browser at http://192.168.59.103:8888.