Swift MOC


Swift_TOO parameters

API Version 1.2

Author: Jamie A. Kennea (Penn State)


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 University
301 Science Park Road,
Building 2 Suite 332,
State College, PA 16801
☎ +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