swift_too module

Swift_TOO_Requests example - querying planned Swift observations

API version = 1.2, swifttools version = 2.4

Author: Jamie A. Kennea (Penn State)

The Swift_TOO_Requests (or shorthand as of swifttools 2.3, TOORequests) allows the user to query submitted Swift TOO requests. This can be used either to retrieve detail on requests that you have submitted, or details on all TOO requests.

Two important caveats:

1. Detailed information on TOOs, including Science Justification text are only retrievable if you are the TOO submitter.

2. Only details of approved TOO requests are available. TOOs that have been rejected cannot be fetched.

This is therefore useful if you wish to retrieve what you have previously submitted, or see what the current active TOOs are, so you can see if someone has already submitted a TOO for the target you are interested in.

from swifttools.swift_too import TOORequests

First example - the 20 most recent Swift TOO requests

In this example we request information on the last 20 TOO requests approved for observation by Swift. No username or shared_secret needs to be submitted for this request, however if you do submit them the result will be no different.

toos = TOORequests(limit=20)

if toos.submit():
    print("Success!")
else:
    print("Failure: {toos.status.errors}")

Success!

That should have worked, so we can now display the 20 most recent approved Swift TOOs by simply display

toos

We can also display all the information we obtained for each TOO request as follows, to display the first (and by default most recent) TOO in the list above, do the following.

toos[1]

If you want to fetch the information for a given too_id value, you get use the by_id method. Here is an example:

toos.by_id(17086)

Displaying the scheduling information for a TOO

If you are interested to know when/if a TOO has been scheduled in the Swift Planning calendar, you can obtain this information by looking that the calendar attribute. This is an instance of the Swift_Calendar class. You can display it as follows.

toos.by_id(17086).calendar

You can see here that the calendar has even more information about the TOO. This includes the start and end time of each window, the XRT and UVOT modes used, the requested exposure time per window, and the column AFST shows the amount of exposure time taken on that target during the window.

Note that a window here is a period of time for which an observation is requested to occur. If the window is a day long, that typically means that the observation can be scheduled at any time during the day. Shorter windows with specific start and end times typically denotes a time constrained observation, e.g. an observation coordinated with another telescope, or an observation where obtaining an observation at a given orbital phase is requested.

Note the AFST column is just a guide. It only shows observations taken with the window, so if an observation were taken the next day, or not completely in the window, it will not reflect the full observation time. In order to obtain information about Swift observations of any given Target, use a Swift_ObsQuery.

Public vs Private TOO Requests

So far the information we have retrieved is what is available publically. This is limited for privacy reasons, but if you have submitted a TOO yourself, you can retrieve more information. To do this you need to provide your username and shared_secret. Note that if your computer supports Python's keyring module, for storing passwords, then your secret should already be stored if you've used it before to submit a TOO request. In this case you can just give your username.

mytoo = TOORequests()
mytoo.username = "myuser"
mytoo.shared_secret = 'my_shared_secret'
mytoo.detail = True
mytoo.too_id = 16832
mytoo.submit()

True

You can now look at the detailed information from your TOO request, including non-public information. The TOO request below was submitted by the author (Jamie Kennea), so this is what is presented here.

mytoo[0]

Also the calendar for this TOO, including what was observed vs what was planned.

mytoo[0].calendar