Offset TA Tools

Author: Jonathan Aguilar ([email protected])

Last update: Oct 10, 2025

Requirements

• numpy
• matplotlib
• astropy
• pySIAF

:NEW: All-Instrument Interface

This module now includes a basic graphical interface for computing the IDL coordinates of an arbitrary field of sources after centering on one of them, as well as the offset command if performing manual offset TA. See ./src/all_jwst_offset_ta/All_Instrument_Notebook.ipynb for an example using MIRI coronagraphy. The user is advised to copy this notebook to a new directory for working on their own specific use cases.

Installation

There are two ways to use these tools, after downloading the repository:

1. Navigate to the top-level directory, and run pip install ..
   • This will install two modulest that can be imported with import all_jwst_offset_ta or import miri_coron_offset_ta.
2. Nagivate to the all_jwst_offset_ta subfolder and copy the notebook and the utils.py module to whatever directory you plan to be working in.
   • In this case, the statement to import utils must be changed to import utils.
   • These files can also be copied directly from the online repository, without downloading the rest.

All-Instrument Interface Usage

For the purposes of this README, the word "aperture" is used in the same sense as it is in the SIAF (Science Instrument Aperture File) - any defined region of the telescope that can be used to command the telescope pointing. Some of these "apertures" also correspond to subarrays that are read out as data.

The "All-Instrument Interface" is much easier to use than the previous script-based version, and is recommended. Some highlights, while the README is slowly updated:

1. This is GUI-based, instead of script-based.
2. Any aperture can be chosen from any instrument, no longer just MIRI. Unfortunately, no help is given to the user to figure out which apertures are the correct ones to use. Some options are:
   • Guess based on the names;
   • Check the APERNAME keyword of data from the same observing configuration you plan to use;
   • Poke around on JDox for any mentions of the SIAF;
   • Ask an experienced JWST user (very experienced).
3. An initialization dictionary can be provided. If none is, the GUI will initialize with default values. Initialization dictionaries are useful for repeatability.
4. The SCI and ACQ target positions are intended for use with offset target acquisition (that is, TA is performed on a different target from the science target).

• If performing self-TA, use the same coordinates for the ACQ and SCI position fields.
• the acq_ra and acq_dec fields can be omitted from the initialization dictionary, in which case the SCI target positions will be copied over.

5. If you want your SCI star to land somewhere in the aperture other than the reference position, enter this in arcsec into the "Final IDL X" and "Final IDL Y" positions. Read these as, "This is the final position (in IDL X and Y) where I want my SCI target to end up"., enter this in arcsec into the "Final IDL X" and "Final IDL Y" positions. Read these fields as, "This is the final position (in IDL X and Y) where I want my SCI target to end up".

(Old format) USAGE

This library is meant to help users compute offsets in the detector frame of reference to enter into APT as Offset Special Requirements, in the case that they need to perform TA on a target other than their science target. Users should edit the if __name__ == '__main__: section at the bottom of compute_offsets.py with the coordinates of their TA and Science targets, as well as the position angle of the V3 axis of the telescope. The instructions for editing each section are written in comments in the script. This will print out appropriate X and Y offsets that can be entered into APT, along with some diagnostic information. Alternatively, the file example.py shows how to use compute_offsets.py as an imported module.

It is suggested that users make a new copy of compute_offsets.py or example.py for each variation of TA star and science target.

It can also be imported as a module after downloading the source code from github:

cd $directory
pip install .

Then from a python terminal:

> from miri_coro_offset_ta import compute_offsets

User-specified variables

slew_to, slew_from

slew_to and slew_from are dictionaries used to specify the science (SCI) and acquisition (ACQ) targets, respectively.

• The label keyword is used for annotating output text and figures.
• The position keyword is used to store an astropy SkyCoord object (SkyCoord documentation). This gives considerable flexibility in specifying the coordinates; for example, by providing a distance and proper motions, the user can propagate the positions using SkyCoord.apply_space_motion() to compute offsets for multiple epochs.

v3pa

v3pa refers to the position angle of the telescope's V3 axis at the reference position of the aperture used for the observation. If that sounds confusing, the short version is it corresponds to the angle in APT's Special Requirements -> PA -> PA Range menu if the V3PA radio button is selected. It also corresponds to the ROLL_REF header keyword (see the JWST Keyword Dictionary for keyword definitions). If you are using this library to plan observations in APT, the V3PA field should match your v3pa variable.

This is not to be confused with the PA_APER header keyword, which corresponds to the Aperture PA Range radio button and refers to the amount by which the detector-aligned coordinate system is rotated with respect to the V3 axis. It also is not to be confused with the PA_V3 header keyword, which refers to the V3 position angle at the position of the telescope boresight. Due to spherical trigonometric effects, the PA of the V3 axis varies across the telescope's focal plane and varies strongly at high and low latitudes.

Offset slews are specified along the detector axes, in units of arcsec (see https://jwst-docs.stsci.edu/jppom/special-requirements/general-special-requirements). In order to convert between the detector coordinate system and two positions on the sky, pySIAF requires information about the orientation of the telescope. Here, we provide this information using a combination of the coronagraph used (see coron_id), and position angle of the v3 axis of the telescope, measured at the chosen coronagraph's reference position.

More details about the different coordinate systems used in describing positions in the telescope can be found here: https://jwst-docs.stsci.edu/jwst-observatory-characteristics/jwst-observatory-coordinate-system-and-field-of-regard/ .

coron_id

coron_id is a string that tells the script which of the four MIRI coronagraphs will be used for the observation. Options are:

• '1065' -> '4QPM_1065'/'MIRIM_MASK1065'
• '1140' -> '4QPM_1140'/'MIRIM_MASK1140'
• '1550' -> '4QPM_1550'/'MIRIM_MASK1550'
• 'LYOT' -> '4QPM_LYOT'/'MIRIM_MASKLYOT'

show_plots

This is a switch to turn on (True) or off (False) the display of handy plots that show the TA process from the points of view of the sky and detector.

other_stars

This parameter allows you to define other targets to plot in the field of view. It takes a list, each entry of which is a dictionary of the same format as slew_from/slew_to.

plot_full

If set to True, this will also plot the MIRI Imager footprint, in addition to the coronagraph aperture. This is usefull if you have selected SUBARRAY -> FULL in APT.

Scripting parameters

The function compute_offsets takes two more arguments that are more useful if it is being imported into another script:

• verbose: a switch to print (True) or suppress (False) diagnostic text to the terminal. This text includes the offsets that should be entered into APT. Set to False if you don't want the printed output.
• return_offsets: a switch to return (True) or not (False) the numerical value of the x and y offset commands. Leave it as False if you intend to copy the offsets from the verbose output into APT, or set it to True if you want to capture the offsets in your code.

FAQs for creating your APT program

How do I choose my acquisition target?

To choose an acquisition target, you should consider the brightness, separation, and position angle:

• Brightness: it should be bright enough to achieve high SNR in the TA filter without saturating (see the ETC).
• Separation : it should be closer than the visit-splitting distance, which ranges between 30"-80" depending on the availability of guide stars for a particular target.
• Position angle: The acquisition target must be clear of diffraction spikes from nearby sources. This is especially important if the science target is very bright. WebbPSF can be used to determine if your TA target will be clear of the diffraction spikes. Determine the orientation of your system for a given PA angle using compute_offsets, which will print the IDL positions of the sources you provide.

How do I choose dates and V3PA angles?

To see available dates and V3PA angles, go to the Visit Planner window in APT and find the Reports menu at the bottom. Select a visit, and then select Total Roll Analysis for Visit. This will give you a plot of available V3 PA angles against dates, as well as a table that can be read into a script.

Do I need to calculate a separate offset for each roll?

Yes, unless your roll angle is very small or your acquisition target is very close.