The swift_too Python module - Quickstart

API Version 2 (swifttools 4.0)

Author: Jamie A. Kennea (Penn State)

Introduction

The swift_too module implements a client for the Swift TOO API in Python. This allows, amongst other things, for the construction and submission of Target of Opportunity (TOO) requests to NASA's Neil Gehrels Swift Observatory. TOO requests are created using the Swift_TOO class. In addition to TOO requests, the swift_too module also allows the user to query past Swift observations using the Swift_ObsQuery class, and calculate the visibility of a fixed celestial object with Swift_VisQuery.

Starting with swifttools 4.0, the API has been redesigned as a modern RESTful service (API v2). Requests are submitted directly over HTTPS and responses are returned synchronously — there is no job queue and no polling required. Authentication uses your username and shared secret, which are passed on the Swift_TOO object as before.

Authentication is handled by setting username and shared_secret directly on the Swift_TOO object before submitting, as shown in the example below.

Note: Most query endpoints are available without authentication, using the implicit anonymous user. You will not be able to submit TOO requests anonymously, but all other queries remain available. Please don't hard-code credentials into public code!

Example usage

from swifttools.swift_too import Swift_TOO

# Initiate the Swift_TOO class
too = Swift_TOO()

# Credentials
too.username = "example_too_user"
too.shared_secret = "your_shared_secret"

# The relevant details of the object to observe
too.source_name = "SMC X-3"  # Typical name of source
too.ra = 13.023439           # Right ascension in decimal degrees
too.dec = -72.434508         # Declination in decimal degrees
too.source_type = "Be/XRB"   # Short description of source class

# Estimate of how bright it is
too.xrt_countrate = 0.1         # XRT counts/s
too.obs_type = too.obs_types[1] # "Light Curve" — options: ["Spectroscopy","Light Curve","Position","Timing"]

# Science Justification
too.science_just = ("SMC X-3 has gone into outburst again! We wish to track the flux, "
                    "spectral and temporal (pulsar timing) evolution of this outburst. "
                    "This is only the third outburst of SMC X-3 detected since 1980. ")

# Exposure description
too.exp_time_per_visit = 3000  # Must be in seconds
too.monitoring_freq = "2 days" # Options: seconds, minutes, hours, days, weeks, orbit
too.num_of_visits = 14         # Monitor the source for 28 days

# Exposure time justification
too.exp_time_just = ("3ks per observation will allow us to monitor "
                     "this exciting new outburst of this well known Be/XRB. "
                     "We request 14 observations in order to cover the first "
                     "month of the outburst.")

# Urgency
too.urgency = 2  # Observations needed within 24 hours

The TOO is now ready to submit. You can run a quick internal validation first:

if too.validate():
    print("TOO is good to go!")
else:
    print("Uh-oh!")

If everything looks good, submit the TOO to Swift. submit() also runs validate() before sending:

if too.submit():
    print("TOO submitted successfully")
else:
    print("Sorry, there was a problem with the submission")

On success the status is available directly on the object:

print(too.status)

A successful submission sets status to Accepted and populates too_id with the unique identifier for your TOO request. Any errors or warnings are reported in too.status.errors and too.status.warnings. A rejected request will set status to Rejected and list the reasons in errors.