swift_too module

Swift_ObsQuery example - querying past Swift observations

API version = 1.2, swifttools version = 2.4

Author: Jamie A. Kennea (Penn State)

The Swift_ObsQuery class allows for querying the database of observations have have already been performed by Swift, otherwise known as the "As-Flown Science Timeline" (AFST). Note this will only fetch observations that have already been performed, not scheduled observations.

%matplotlib inline
import matplotlib.pyplot as plt
from swifttools.swift_too import ObsQuery
from time import sleep
import numpy as np

Constructing the query

Note: As of swifttools version 2.2, you do not need to pass username or shared_secret keywords, they will default to anonymous. This is the recommended usage for anything except a TOO request.

First example, how often has Swift observed the binary system SS 433? Well, I can't remember the RA/Dec off the top of my head, so let's look it up...

New features in swifttools 2.3

swifttools 2.3 supports a new class called Swift_Resolve. You can use this to do name resolution, i.e. converting the name of a target into coordinates. However, it's also built into classes that take RA/Dec now, so you can just pass it using the name parameters.

Another new feature of 2.3, there are now shorthand names for classes, so you can omit the Swift_ when calling the class, changing it to just ObsQuery.

query = ObsQuery()
query.name = "SS 433"

Now you can see the coordinates, as either RA/Dec or astropy's SkyCoord, using the attributes ra, dec and skycoord (if astropy is installed). For example:

query.skycoord

<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
    (287.95651875, 4.98272889)>

RA/Dec is stored by the TOO API in decimal degrees, in J2000 epoch as this is the epoch Swift uses

print(f"RA/Dec(J2000) = {query.ra:.4f}, {query.dec:.4f}")

RA/Dec(J2000) = 287.9565, 4.9827

Looks legit. However, we can also set RA/Dec the old fashioned way

query.ra, query.dec = 287.9565, 4.9827

Note that skycoord will remain correct even if you changed the ra and dec properties.

query.skycoord

<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
    (287.9565, 4.9827)>

Swift_ObsQuery has a default search radius which is....

print(f"Default search radius = {query.radius:.3f} degrees")

Default search radius = 0.197 degrees

That's 12 arcminutes, which is the approximate field of view of Swift's X-ray Telescope (XRT). We can narrow that down a bit, so we only get matches that are in the center of the field of view (FOV), and also in UVOT which has a smaller FOV.

query.radius = 5 / 60  # 5 arc-minutes, as the units for radius are degrees

Submitting the query

OK let's query the Swift timeline to see how many observations it's taken. This might take a few seconds to process. query method will return True if everything is OK, False if there is a problem. If there is a problem, simply look at the contents of the status attribute.

if query.submit():
    print("Success!")
else:
    print(f"Fail or timeout? {query.status}")

Success!

Looks like that worked, let's take a look at the status attribute anyway.

query.status

Examining the results of the query

So how many observations has Swift taken of this target?

print(f"This many: {len(query)}")

This many: 77

That's a lot of damage. Here's a thing to remember, every entry in this is a single snapshot of observation. As Swift is in a low Earth orbit, it means that a snapshot is typically max 30 mins, or sometimes a bit longer (~44 mins), so a long exposure will consist of multiple snapshots. Observations are grouped by obsid (a 12 digit number with leading zeros), so snapshots with the same obsid are part of the same planned observation.

query

Wow that is a lot of observations.

Pointing Accuracy

Here's an interesting thing about Swift, it doesn't point very accurately. This is because the ACS system sacrifices accuracy for speed. The goal is to get the object of interest into the field of view of XRT and UVOT, not at the boresight. As a result, the pointing direction be typically up to 3 arcminutes off the requested pointing direction. Note that for each entry listed above, we give an ra and dec value, so let's check out the variation:

plt.figure()
plt.plot(
    [float(entry.ra) for entry in query], [float(entry.dec) for entry in query], "+"
)
plt.plot(
    [entry.ra_object for entry in query], [entry.dec_object for entry in query], "X"
)
plt.xlabel("RA(J2000)")
plt.ylabel("Dec(J2000)")
_ = plt.title(f"{query.name} pointing scatter")

As you can see there's a lot of variation of the pointing direction. Each entry also has a values ra_object, dec_object, which give the decimal degrees values of the requested pointing direction for each observation. This typically will be the coordinates of the Target of the Observation, but sometimes if offsets are applied for any reason, it might differ.

The ra_object/dec_object values aren't necessarily going to be for the object you queried on. In fact there can be multiple values of ra_point/dec_point if the queried field lies inside multiple pointings.

Although the RA/Dec are returned in J2000 decimal degrees, they're also returned as skycoords. However, ra_object and dec_object are not so we will have to convert those to SkyCoords manually.

query[0].skycoord

<SkyCoord (FK5: equinox=J2000.000): (ra, dec) in deg
    (287.994, 4.972)>

Sometimes ra_object, dec_object cannot be determined, so the value will be 'None'. I'm going to filter those out so we can do some comparing.

from astropy.coordinates import SkyCoord
import astropy.units as u

sc = SkyCoord([entry.skycoord for entry in query if entry.ra_point != None])
scp = SkyCoord(
    [entry.ra_point for entry in query if entry.ra_point != None],
    [entry.dec_point for entry in query if entry.ra_point != None],
    frame="fk5",
    unit=(u.deg, u.deg),
)

I made an array of ra_point/dec_point so we can evaluate how accurately Swift actually pointed at this target. Let's make a histogram of the pointing offsets.

plt.figure()
plt.hist(sc.separation(scp).arcmin, bins=30)
plt.ylabel("Number of pointings")
plt.xlabel("Offset from requested pointing direction (arc-minutes)")
print(f"Median offset value = {np.median(sc.separation(scp).arcmin):0.2f} arc-minutes")

Median offset value = 2.17 arc-minutes

So you'll see that the median offset here is around 2 arc-minutes, with a pretty big scatter, and there may even be some large outliers.

Grouping Snapshots into Observations

Let's take a look at an individual entry to see what information is being returned by this query.

query[0]

So some useful information here. Firstly remember each entry represents a snapshot of Swift data, that is data taken in a single orbit of observations. Typically data that you obtain from the SDC will be grouped by observation, and those observations can contain many snapshots. Observations have a unique target ID (target ID) and segment (seg) numbers. These typically are combined into a Observation Number (obsnum), which in the SDC format will look like a concatibation of the target ID, and segment, with padding zeros, e.g.:

print(
    f"Target ID = {query[0].targetid}, segment = {query[0].seg}, ObservationID = {query[0].obsnum}"
)

Target ID = 35190, segment = 1, ObservationID = 00035190001

If you're interested in all the observations under a particular Observation ID, then there's a property called "observations" that contains a dictionary of all observations on an Observation ID basis. Let's look at the summary of this dictionary by just printing out all the entries.

query.observations

You can see that now the summary shows the details for an entire observation, with the begin and end times being those of associated with the first and last observation of that Observation ID, and the exposure time being the total. Importantly due to orbit gaps, the exposure time is not just end minus begin. Each entry in the observations dictionary contains details on the individual segments also. Note that Observation ID is a string, given as it is formatted with padding zeros. For example:

query.observations["00035190015"]

If we want to see what snapshots make up a particular observation, it's easy:

query.observations["00035190015"].snapshots

You can query the exposure and other infomation for the combined snapshots in the Observation ID.

query.observations["00035190015"].exposure

datetime.timedelta(seconds=7830)

Note that the result here is a datetime timedelta object. You can easily get the seconds as an integer or convert to an astropy TimeDelta object.

query.observations["00035190015"].exposure.seconds

7830

from astropy.time import TimeDelta

TimeDelta(query.observations["00035190015"].exposure)

<TimeDelta object: scale='None' format='datetime' value=2:10:30>

Note that there is no RA/Dec (ra/dec) for an observation, only the requested pointing direction (ra_point/dec_point), because actual RA/Dec will be different for each snapshot, so delve into the individual snapshots for those.

query.observations["00035190015"].ra_point, query.observations["00035190015"].dec_point

(287.9565, 4.982667)

Instrument Configuration

All observations for a given Observation ID will have the same instrument configuration. Let's check those out.

print(
    f"XRT mode = {query.observations['00035190015'].xrt}, UVOT mode = {query.observations['00035190015'].uvot}"
)

XRT mode = Auto, UVOT mode = 0x20ed

In this case the XRT mode is Auto, which means that XRT itself decides whether to be in PC or WT mode, based on the brightness of sources in the central 200x200 pixels of the detector, roughly the central 8.5 arcmin x 8.5 arcmin box. Because of this we can't determine what mode XRT will have actually taken the data in without looking at it. However for many observation, the mode is fixed, here you will see results like so:

print(f"XRT mode = {query.observations['00035190037'].xrt}")

XRT mode = PC

As this is PC mode, we can guarantee that the data are taken in PC mode.

For UVOT the mode above is a hex number 0x20ed. There are a large number of modes that can be used with UVOT, given it's many different combinations of filters, exposure windows, etc. Luckily you can query what this mode means using the UVOT_mode class. We can quickly display a table showing details of the mode as follows:

from swifttools.swift_too import UVOT_mode

UVOT_mode(uvotmode=query.observations["00035190015"].uvot)

UVOT Mode: 0x20ed