Tutorial 5 - Ordering and n-results limits

We’ve now covered all the endpoints provided by voeventdb.

** This notebook briefly demonstrates how to apply list-orderings and number-of-results limits. **

We use a motivating example - displaying a short list of recent GRB alerts.

In [ ]:
from __future__ import print_function
import voeventdb.remote as vr
import voeventdb.remote.apiv1 as apiv1
from voeventdb.remote.apiv1 import FilterKeys
from voeventdb.remote.helpers import Synopsis
from datetime import datetime, timedelta
import pytz

import logging

List ordering

When using the voeventdb list-query endpoints, we can control ordering using the order parameter. So for example, if we simply request the first 5 IVORNs with no modifiers, we get the first entries inserted into the database:

In [ ]:

In this case, whatever happened to arrive just after the database was switched on. But, we can change the ordering, choosing from one of the order-values. For example, to retrieve the most recent ‘observation’ VOEvents, we’ll request the list in ‘author-datetime descending’ order:

In [ ]:

Retrieving recent GRB events

With this last feature, we can start using voeventdb for applications such as reviewing the most recent alerts, and perhaps even planning our follow-up. Suppose we want to retrieve the 10 most-recent GRB-event alerts from the Swift BAT:

In [ ]:
filters = { FilterKeys.ivorn_contains: 'BAT_GRB',
            FilterKeys.role: 'observation'}
now = datetime.utcnow()
recent_swift_grb_ivorns = apiv1.list_ivorn(filters,
recent_swift_grbs = [Synopsis(apiv1.packet_synopsis(i)) for i in recent_swift_grb_ivorns]

Let’s view a summary table, displaying just the dates and co-ords:

In [ ]:
print("Recent GRBs as of {}:".format(now))
print ("Timestamp:\t\t\t RA, \tDec")
for grb in recent_swift_grbs:
    print("{}:\t {:06.2f}, {:+07.2f}".format(

Wrapping up

That about covers all the major features of voeventdb, as demonstrated using the voeventdb.remote client-library. Comments, questions, bug-reports and other contributions are all welcomed - you can leave a note on the issue tracker or find more contact details at http://4pisky.org/voevents/.

And finally…

We’ve covered how to get data out of voeventdb - but not what to do with the data when you’ve got it. The examples notebook demonstrates a few basic ideas - see next!