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
logging.basicConfig(level=logging.DEBUG)
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 [ ]:
apiv1.list_ivorn(n_max=5)
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 [ ]:
apiv1.list_ivorn(filters={FilterKeys.role:'observation'},
order=apiv1.OrderValues.author_datetime_desc,
n_max=5,
)
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,
order=apiv1.OrderValues.author_datetime_desc,
n_max=10,
)
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()
print ("Timestamp:\t\t\t RA, \tDec")
for grb in recent_swift_grbs:
print("{}:\t {:06.2f}, {:+07.2f}".format(
grb.author_datetime,
grb.coords[0].ra.deg,
grb.coords[0].dec.deg))
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!