swift_too
moduleswifttools
version = 2.4The 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:
Detailed information on TOOs, including Science Justification text are only retrievable if you are the TOO submitter.
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
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 |
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
.
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 |