Swift_TOO
parametersThis 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.
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) |
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) |
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) |
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']
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) |
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) |
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) |
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) |
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) |
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 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. |
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 |
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. |