Swift TOO API
Swift_TOO parameters
API Version 1.2
Author: Jamie A. Kennea (Penn State)
Introduction
This is a list of the parameters for the Swift_TOO class, which allows you to submit a Swift Target of Opportunity (TOO) request. Default values for parameters are given. In the case tha the default value is None, this means no default value. Note that required parameters are indicated, but some requirements are conditional on other parameters.
User identification
| Parameter | Default Value | Description (type) |
|---|---|---|
| username | None | Swift TOO username (string) |
| shared_secret | None | Swift TOO shared secret. Log in to Swift TOO page to find out / change your shared secret (string) |
Source name, type, location, position_error
Basic information describing an object. Source name, type and coordinate (either RA/Dec or astropy SkyCoord) are required parameters. Position error is optional, but should be given if available.
| Parameter | Default Value | Description (type) |
|---|---|---|
| source_name | None | Name of the object we're requesting a TOO for (string) |
| source_type | None | Type of object (e.g. "Supernova", "LMXB", "BL Lac") (string) |
| ra | None | RA(J2000) Degrees decimal (float) |
| dec | None | declination (J2000) Degrees decimal (float) |
| skycoord | None | In case the user wants to use a Astropy SkyCoord to give us the coordinates (SkyCoord) |
| poserr | 0.0 | Position error in arc-minutes (float) |
TOO Request details
Parameters which define how urgent the TOO request is, and what the primary instrument on Swift.
| Parameter | Default Value | Description (type) |
|---|---|---|
| instrument | "XRT" | Primary instrument for the observation Choices "XRT","UVOT","BAT" (string) |
| urgency | 3 | 1; Within 4 hours, 2; within 24 hours, 3; Days to a week, 4; week - month. (int) |
Observation Type
Required. Primary goal of observation. Note here that the obs_type is the parameter, which takes one of four parameters,
defined by the obs_types array.
| Parameter | Default Value | Description (type) |
|---|---|---|
| obs_type | None | Select from obs_types one of four options, e.g. too.obs_type = too.obs_types[1] |
Here are the current allowed values, which are stored in the obs_types array:
obs_types = ['Spectroscopy', 'Light Curve', 'Position', 'Timing']Description of the source brightness for various instruments
Required. Give here details of how bright the source is. Requirement is to give an answer to at least one of these parameters. Note if opt_mag is given, then opt_filt must also be supplied, which can be whatever optical filter the measurement was made in as a string.
| Parameter | Default Value | Description (type) |
|---|---|---|
| opt_mag | None | Optical magnitude (float) |
| opt_filt | None | What filter was this measured in (can be non-UVOT filters) (string) |
| xrt_countrate | None | XRT estimated counts/s (float) |
| bat_countrate | None | BAT estimated counts/s (float) |
| other_brightness | None | Any other brightness info (float) |
GRB stuff
Parameters for GRB TOOs. Required only if submitting a TOO for a GRB.
| Parameter | Default Value | Description (type) |
|---|---|---|
| grb_detector | None | Should be "Mission/Detection" (e.g "Swift/BAT, Fermi/LAT") (string) |
| grb_triggertime | None | GRB trigger date/time (datetime) |
Science Justification
Required. Textual short and long description of why Swift should perform the TOO.
| Parameter | Default Value | Description (type) |
|---|---|---|
| immediate_objective | None | One sentence explaination of TOO (string) |
| science_just | None | Note this is the Science Justification (string) |
Exposure requested time (total)
Required. Exposure time requested and justification for that exposure time.
| Parameter | Default Value | Description (type) |
|---|---|---|
| exposure | None | Note this is the user requested exposure |
| exp_time_just | None | Justificationf the exposure time (string) |
Monitoring requests
Parameters that define the length, individual exposre time and cadence for monitoring requests. Required if monitoring is requested.
| Parameter | Default Value | Description (type) | |
|---|---|---|---|
| exp_time_per_visit | None | Exposure per visit (integer seconds) | |
| num_of_visits | 1 | Number of visits (integer) | |
| monitoring_freq | None | Formatted text to describe monitoring cadence. E.g. "2 days", "3 orbits", "1 week". See | monitoring_units for valid units (string) |
Swift Guest Investigator program parameters
Required parameters if the TOO is triggering a Swift GI program.
| Parameter | Default Value | Description (type) |
|---|---|---|
| proposal | False | Is this a GI proposal? True / False |
| proposal_id | None | What is the GI proposal ID (string or integer) |
| proposal_trigger_just | None | Note this is the GI Program Trigger Criteria Justification (string) |
| proposal_pi | None | Proposal PI name (string) |
Instrument mode
Instrument configuration parameters. These are not a strict requirement as there are defaults for both UVOT and XRT modes. If a different UVOT mode than filter-of-the-day (0x9999) is given, then uvot_just becomes a requirement. slew_in_place is for observations in which a more accurate placing on of the target is needed. These are usually reserved for UVOT Grism observations.
| Parameter | Default Value | Description (type) |
|---|---|---|
| xrt_mode | 7 | 7: Photon Counting, 6: Windowed Timing, 0: Auto (self select). PC is default |
| uvot_mode | 0x9999 | Hex mode for requested UVOT filter. Default FOTD. See Cheat Sheet or https://www.swift.psu.edu/operations/mode_lookup.php for codes. |
| uvot_just | None | Text justification of UVOT filter. |
| slew_in_place | None | Perform a slew-in-place? Typically used for GRISM observation. Allows the source to be placed more accurately on the detector. |
Tiling request
These are optional, although if the error radius for a source with a poorly known source is larger than the XRT field of view, it's recommended that you pick a tiling pattern that will cover the error region. Current options are 4, 7, 19 and 37 tile patterns.
| Parameter | Default Value | Description (type) |
|---|---|---|
| tiling | None | |
| number_of_tiles | None | Set this if you want a fixed number of tiles. Traditional tiling patterns are 4,7,19,37 "circular" tilings. If you don't set this we'll calculate based on error radius. |
| exposure_time_per_tile | None | Set this if you want to have a fixed tile exposure, otherwise it'll just be exposure / number_of_tiles |
| tiling_justification | None | Text description of why tiling is justified |
Debug parameter
If this is set, sending a TOO won't actually submit it. Good for testing the API without actually submitting TOO requests. If you submit a TOO with debug, you will receive an email confirmation as if you had submitted a regular TOO request.
| Parameter | Default Value | Description (type) |
|---|---|---|
| debug | False | Enable debug mode. Allows TOOs to be submitted, without actually submitting them. |
Swift Mission Operations Center
The Pennsylvania State University301 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 NousekScience Operations: Jamie Kennea
Flight Operations: Mark Hilliard
UVOT: Michael Siegel
XRT: Jamie Kennea
Swift Partners
UK: UCL MSSL Univ. of LeicesterUSA: NASA/GSFC LANL Omitron SwRI
Italy: SSDC/ASI INAF OA-Brera