Swift TOO API
Swift MOC

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
ToO ID Object Name Instrument Right Ascenscion (J2000) Declination (J2000) UVOT Mode (Approved) XRT Mode (Approved) Time Submitted Requester Urgency Begin date End date Primary Target ID
17089 2MASS J10225172-3226044 XRT 155.71545833333 -32.434638888889 0x9999 PC 2022-03-27 17:16:57 de Martino 4 2022-04-04 2022-04-04 15103
17088 AT2022ffv UVOT 54.1236583 -35.28935 0x223f PC 2022-03-27 17:04:44 Jacobson-Galan 2 2022-03-28 2022-04-05 15102
17087 AT2022ffg UVOT 153.45092916667 18.127325 0x223f PC 2022-03-27 15:27:57 Milne 2 2022-03-28 2022-04-01 15101
17086 WISEAJ045649.80-203748.0 UVOT 74.20751953125 -20.629974365234 0x015a PC 2022-03-27 08:49:27 Liu 3 2022-04-01 2022-04-15 14135
17085 2021eyw UVOT 190.999875 62.330083333333 0x223f PC 2022-03-25 19:20:33 Siebert 2 2022-03-27 2022-04-06 15099
17083 1ES 1741+196 XRT 265.99095833333 19.585833333333 0x30ed PC 2022-03-25 17:43:39 Falcone 3 2022-04-06 2022-04-06 40639
17082 1ES 1727+502 XRT 262.07758333333 50.219583333333 0x30ed PC 2022-03-25 17:39:50 Falcone 3 2022-04-05 2022-04-05 33709
17081 PG 1553+113 XRT 238.9294 11.1901 0x30ed PC 2022-03-25 17:37:46 Falcone 3 2022-04-04 2022-04-04 35021
17080 H1426+428 XRT 217.135871 42.672513 0x30ed PC 2022-03-25 17:34:57 Falcone 3 2022-04-01 2022-04-01 30375
17079 PKS 1424+240 XRT 216.7516 23.8 0x30ed PC 2022-03-25 17:32:44 Falcone 3 2022-03-31 2022-03-31 41539
17078 1ES 1218+304 XRT 185.3414 30.177 0x30ed PC 2022-03-25 17:29:44 Falcone 3 2022-03-30 2022-03-30 30376
17077 W Com XRT 185.3820343 28.2329159 0x30ed PC 2022-03-25 17:26:51 Falcone 3 2022-03-29 2022-03-29 35018
17076 SN2022qh UVOT 164.83354166667 -43.268658333333 0x223f PC 2022-03-25 13:59:49 Roy 3 2022-03-30 2022-04-11 15100
17075 RBS0690 XRT 121.36102625 75.573622222222 0x9999 PC 2022-03-25 11:09:42 Foffano 4 2022-04-04 2022-04-04 39145
17074 NGC 4151 XRT 182.6357449 39.4057299 0x30ed PC 2022-03-25 05:38:37 Middei 3 2022-03-29 2022-04-06 34455
17073 PKS 2155-304 XRT 329.71666666667 -30.225555555556 0x30ed PC 2022-03-24 15:10:35 Kapanadze 3 2022-03-30 2022-04-17 30795
17072 Mrk421 XRT 166.11380791667 38.208832777778 0x308f WT 2022-03-24 14:05:37 Paneque 3 2022-03-27 2022-03-27 31540
17071 WISEA J005739.96-850721.9 XRT 14.415 -85.1224 0x223f PC 2022-03-24 13:10:52 Krumpe 3 2022-03-30 2022-03-30 15098
17070 WISEA J124028.32-230926.7 XRT 190.11792 -23.15722 0x223f PC 2022-03-24 12:36:50 Krumpe 3 2022-03-29 2022-03-29 15025
17069 S5 1803+78 XRT 270.1903 78.4678 0x9999 PC 2022-03-24 11:00:26 Prince 3 2022-03-29 2022-04-06 36393

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]
Parameter Value
ToO ID 17088
Requester Jacobson-Galan
Time Submitted 2022-03-27 17:04:44
Urgency 2
Object Name AT2022ffv
Type or Classification Supernova
Right Ascenscion (J2000) 54.1236583
Declination (J2000) -35.28935
Position Error (90% confidence - arcminutes) 0
Exposure Time per Visit (s) 1000
Number of Visits 5
Total Exposure (s) 5000
Instrument UVOT
XRT Mode (Approved) PC
UVOT Mode (Approved) 0x223f
Primary Target ID 15102

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)
Parameter Value
ToO ID 17086
Requester Liu
Time Submitted 2022-03-27 08:49:27
Urgency 3
Object Name WISEAJ045649.80-203748.0
Type or Classification X-Ray Transient
Right Ascenscion (J2000) 74.20751953125
Declination (J2000) -20.629974365234
Position Error (90% confidence - arcminutes) 0
Exposure Time per Visit (s) 3000
Number of Visits 3
Total Exposure (s) 9000
Instrument UVOT
XRT Mode (Approved) PC
UVOT Mode (Approved) 0x015a
Primary Target ID 14135

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
# Start Stop XRT Mode UVOT Mode Exposure (s) AFST (s)
0 2022-04-01 00:00:00 2022-04-02 00:00:00 PC 0x015a 3000 0
1 2022-04-08 00:00:00 2022-04-09 00:00:00 PC 0x015a 3000 0
2 2022-04-15 00:00:00 2022-04-16 00:00:00 PC 0x015a 3000 0

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]
Parameter Value
ToO ID 16832
Requester Kennea
Time Submitted 2022-01-05 12:00:19
Urgency 2
Object Name SXP 15.6
Type or Classification Be Binary System
Right Ascenscion (J2000) 12.228890419006
Declination (J2000) -73.829299926758
Position Error (90% confidence - arcminutes) 0
Science Justification We wish to continue to monitor the brightness of SXP 15.6 in it's current outburst which was still ongoing as of Dec 30, . We request an initial observation ASAP, as the most recent observation with S-CUBED (Jan 4th) appeared to show a rebrightening. In addition we request resumption of monitoring until pole constraint.
XRT Estimated Rate (c/s) 0.15
Exposure Time per Visit (s) 2000
Number of Visits 4
Total Exposure (s) 8000
Monitoring Cadence 2 day
Immediate Objective Continue to monitor the brightness of SXP 15.6. We request an initial observation ASAP.
Exposure Time Justification 2ks allows for accurate measurement of flux and spectrum.
Instrument XRT
What is Driving the Exposure Time? Light Curve
XRT Mode (Approved) PC
UVOT Mode (Approved) 0x9999
Primary Target ID 34599

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

mytoo[0].calendar
# Start Stop XRT Mode UVOT Mode Exposure (s) AFST (s)
0 2022-01-05 00:00:00 2022-01-06 00:00:00 PC 0x9999 2000 1995.0
1 2022-01-07 00:00:00 2022-01-08 00:00:00 PC 0x9999 2000 2265.0
2 2022-01-09 00:00:00 2022-01-10 00:00:00 PC 0x9999 2000 1960.0
3 2022-01-11 00:00:00 2022-01-12 00:00:00 PC 0x9999 2000 1359.0

Swift Mission Operations Center

The Pennsylvania State University
301 Science Park Road,
Building 2 Suite 332,
State College, PA 16801
USA
☎ +1 (814) 865-6834
📧 swiftods@swift.psu.edu

Swift MOC Team Leads

Mission Director: John Nousek
Science Operations: Jamie Kennea
Flight Operations: Mark Hilliard
UVOT: Michael Siegel
XRT: Jamie Kennea