Step-by-Step APT Guide for NIRSpec IFU and Fixed Slit Observations of Near-Earth Asteroids

This article provides a walk-through of the construction of an APT file for an example moving target program to observe near-Earth asteroids (NEAs) and should be read after NIRSpec IFU and Fixed Slit Observations of Near-Earth Asteroids and Step-by-Step ETC Guide for NIRSpec IFU and Fixed Slit Observations of Near-Earth Asteroids.

Dated material

This example was created pre-launch, and the APT has been updated since its creation. You may see differences in the appearance of the APT GUI and/or the warnings and errors in APT from what is shown herein.

Please refer to JWST Example Science Programs for more information.

On this page

Using the APT

A filled out APT file can be accessed via the menu options File → JWST Example Science Proposals → NIRISS → 34 NIRSpec IFU and Fixed Slit Observations of Near Earth Asteroids in APT. The APT file was created with version 27.3. There may be inconsistencies or additional warnings or errors with other versions of APT.

Fill Out Proposal Information

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

See also: Moving Target APT Instructions

After opening APT, select "New JWST Proposal" under the "New Document" pull-down menu. On the Proposal Information page, enter Title, Abstract, and Category of proposal and keep Cycle number at its default value.




Enter Proposed Targets

See also: Solar System TargetsSolar System Standard TargetsTutorial on Creating Solar System Targets in APT

(3908) Nyx

  • Click on the Targets folder in the tree editor on the left side of the APT file.
  • Then click on the New Solar System Target button. This creates a Solar System Targets subfolder, with the new target you created called "1 Unnamed Target."
  • Select "1 Unnamed Target."
  • For this example proposal, let's make (3908) Nyx the first target. Type "NYX" into the Name in the Proposal box; the Name for the Archive box will be filled in automatically later.
  • From the Keyword dropdown, select Asteroid.
  • The Description can contain anything, but cannot be left empty; for this example, type "Near-Earth Asteroid."
  • Our NEA targets are all point sources, so select No in the Extended dropdown menu.

There are three options for defining a Level 1 Type moving target in the APT: Standard TargetComet, or Asteroid. The list of standard targets is composed of planets, dwarf planets, and their satellites, and can be found in the Solar System Standard Targets article. None of our NEA targets are included in this list. The Comet and Asteroid options work in a similar way, and the Asteroid option should be used for any non-cometary minor bodies. The process of defining an asteroid is as follows:

  • After selecting Asteroid from the Level 1 Type dropdown menu for Nyx, you will be taken to a new window with a target resolver and empty boxes for orbital parameters.
  • In the box titled Search (Name, NAIF ID, or Primary Designation), type either "Nyx" or "3908".
  • Click on the magnifying glass icon on the right-hand side. APT will communicate with JPL/Horizons to retrieve information on Nyx (be aware that this step requires an Internet connection).
  • A dialog box will pop up showing that APT successfully connected with JPL/Horizons and retrieved information on Nyx; click OK.
  • Check the box for Use Horizons for Orbital Elements Retrieval and click OK on the next dialog box; this fills in the boxes for all the orbital parameters.

(1221) Amor

Follow the same process above to create a (1221) Amor target.

(1915) Quetzalcoatl

Follow the same process above to create a (1915) Quetzalcoatl target.



Creating Observations in APT

See also: Tutorial on Creating Solar System Observations in APT

(3908) Nyx

  • In the tree editor, highlight the Observations folder and click on the New Observation Folder button. This creates a new subfolder with a new observation (called "Observation 1") already inside it.
  • Select "Observation 1."
  • The Label is the name of the observation, and we will call Observation 1 "NIRSpec Fixed Slit: (3908) Nyx."

(1221) Amor

  • In the tree editor, highlight the Observations folder and select the New button above the tree editor. 
  • Select New Observation.
  • Select "Observation 2."
  • Change the Label of Observation 2 to "NIRSpec Fixed Slit: (1221) Amor."

(1915) Quetzalcoatl

  • In the tree editor, highlight the Observations folder and select the New button above the tree editor. 
  • Select New Observation.
  • Select "Observation 3."
  • Change the Label of Observation 3 to "NIRSpec IFU: (1915) Quetzalcoatl."



Fill In APT Observation Template for NIRSpec Fixed Slit Spectroscopy

See also: NIRSpec Fixed Slit Spectroscopy APT Template

(3908) Nyx

  • Select the "NIRSpec Fixed Slit w/o TA" observation (Observation 1).
  • For the Instrument, select NIRSpec.
  • For the Template, select NIRSpec Fixed Slit Spectroscopy.
  • Select "1 NYX" as the Target.
  • Set the TA Method to WATA and fill in the relevant values based on the TA calculation in the ETC workbook (applicable to both Nyx and Amor):
    • Acq Target = Same Target as Observation (fixed value)
    • Acq Subarray = SUB2048
    • AcqFilter = CLEAR
    • Acq Readout Pattern = NRSRAPIDD6
    • Acq Groups/Int = 3 (fixed value)
    • Acq Integrations/Exp = 1 (fixed value)
  • Under Target Acquisition Parameters, there is a box titled Acq ETC Wkbk.Calc ID. This is where you would put the ID number and calculation number of the ETC workbook used to compute the TA parameters, as discussed in the JWST APT-ETC Connectivity article. Leaving this box blank results in a warning, however, an APT file can be successfully submitted with this warning. For this Example Science Program, we do not include a value in this box because each downloaded copy of the ETC workbook associated with this program will have a unique ID number. Providing the ID number of a workbook for which you do not have access to will result in a "404: Not found" error in your browser when clicking the ETC button in the APT.
  • Choose the S200A1 Slit and the Subarray will populate itself with SUBS200A1. Change this to FULL.
  • Select 3 in the Primary Dither Parameters dropdown.
  • Select NONE from the Sub-Pixel Pattern dropdown menu.
  • Click the Add button for the Gratings/Filters box.
  • The Grating/FilterReadout PatternGroups/Int, and Integrations/Exp can be copied exactly from the ETC workbook into the APT file:
    • Grating/Filter = Prism/CLEAR
    • Readout Pattern = NRSIRS2RAPID
    • Groups/Int = 40
    • Integrations/Exp = 1
  • Remember that the Exposures per specification in the ETC workbook corresponds to the number of dithers.
  • Leave Autocal set to NONE.

According to the NIRSpec Fixed Slit Spectroscopy APT Template article, selecting the WAVECAL option in the Autocal column adds significant overheads to an observation and is unnecessary because the wavelength solution is expected to be stable. See also the article on NIRSpec Auto-Cals.

(1221) Amor

  • Select the "NIRSpec Fixed Slit w/ TA" observation (Observation 2).
  • For the Instrument, select NIRSpec.
  • For the Template, select NIRSpec Fixed Slit Spectroscopy.
  • Select "2 AMOR" as the Target.
  • Set the TA Method to WATA and fill in the relevant values based on the TA calculation in the ETC workbook (applicable to both Nyx and Amor).
    • Acq Target = Same Target as Observation (fixed value)
    • Acq Subarray = SUB2048
    • AcqFilter = CLEAR
    • Acq Readout Pattern = NRSRAPIDD6
    • Acq Groups/Int = 3 (fixed value)
    • Acq Integrations/Exp = 1 (fixed value)
  • Choose the S200A1 Slit and the Subarray will populate itself with SUBS200A1. Change this to FULL.
  • Select 3 in the Primary Dither Parameters dropdown.
  • Select NONE from the Sub-Pixel Pattern dropdown menu.
  • Click the Add button for the Gratings/Filters box.
  • The Grating/FilterReadout PatternGroups/Int, and Integrations/Exp can be copied exactly from the ETC workbook into the APT file:
    • Grating/Filter = Prism/CLEAR
    • Readout Pattern = NRSIRS2RAPID
    • Groups/Int = 40
    • Integrations/Exp = 1
  • Remember that the Exposures per specification in the ETC workbook corresponds to the number of dithers.
  • Leave Autocal set to NONE.



Fill In APT Observation Template for NIRSpec IFU Spectroscopy

(1915) Quetzalcoatl

  • Select the "NIRSpec IFU w/o TA" observation (Observation 3).
  • For the Instrument, select NIRSpec.
  • For the Template, select NIRSpec IFU Spectroscopy.
  • Select "3 QUETZALCOATL" as the Target.
  • Set TA Method to NONE, since we will not be doing TA for this target.
  • The decision tree for the IFU on the NIRSpec Dithering Recommended Strategies would suggest that the best option for the (1915) Quetzalcoatl observation is the 4-POINT-NOD in the Dither Type dropdown because the source is faint and compact. However, this dither pattern requires that TA be used because the positions are widely separated on the detector; the source must first be accurately placed in the center of the IFU aperture in order for this pattern to keep the source in the aperture at every position. We are choosing not to do TA for this observation both to decrease the total time and because the NEA may not fall within the WATA aperture. Thus, the better option for (1915) Quetzalcoatl is actually the 4-POINT-DITHER, which has a smaller separation between all of the dither positions. This will reduce the chance that any of the dither positions place the target outside the aperture.
  • Click the Add button for the Gratings/Filters box.
  • The Grating/FilterReadout PatternGroups/Int, and Integrations/Exp can be copied exactly from the ETC workbook into the APT file:
    • Grating/Filter = Prism/CLEAR
    • Readout Pattern = NRSIRS2RAPID
    • Groups/Int = 123
    • Integrations/Exp = 1
  • Remember that the Exposures per specification in the ETC workbook corresponds to the number of dithers.
  • For all observations, leave Autocal set to NONE.

  • Leave the Leakcal box unchecked.

The IFU-specific Leakcal calibration would add significant overheads to the IFU calculation and is unnecessary. See NIRSpec MSA Leakage Correction for IFU Observations and NIRSpec MSA Leakage Subtraction Recommended Strategies.



Define Special Requirements

See also: General Special RequirementsTiming Special RequirementsSolar System Special RequirementsMoving Target Overheads

For this example program, we will specify a New Distance Observing Window solar system special requirement (referred to as a Solar System Target Window in the APT) for each NEA. The brightness of the NEA targets changes significantly, sometimes by a whole magnitude or more, when they are within JWST's field of regard. This distance constraint will ensure that the targets are observed when they are brighter; there is no apparent magnitude constraint in the APT. Alternatively, a Timing Special Requirement could be specified to achieve the same result.

To create a distance constraint:

  • Select an observation and click on the Solar System Target Windows tab.
  • Click on the Add Observing Window button; a dropdown menu will appear.
  • Select the third option from the top, New Distance Observing Window. This brings up a dialog box.
  • From the Within This Window? dropdown, select Within.
  • From the Object 1 dropdown, select the the NEA target corresponding to that observation.
  • From the Object 2 dropdown, select JWST.
  • From the Condition (>, <, Min, Max) dropdown, select LESS THAN. (JWST is an option in the Object 1 and Object 2 dropdown menus and can be found after all the planets and dwarf planets near the top of the list.)
  • The last box, for Distance (AU), is specific for each NEA target:
    • The distance constraint for (3908) Nyx will apply to both periods when the NEA is within JWST's field of regard. We select a distance of less than 2.15 AU to ensure that the target is within 0.1 mag of the V=22.0 used in the ETC.
    • (1221) Amor is brighter than the other targets and the range of apparent magnitudes is not as large. Placing a distance constraint of less than 1.9 AU from JWST ensures that it can be observed within 0.1 mag of the V=22.0 that was used in the ETC.
    • In order to observe (1915) Quetzalcoatl within 0.1 mag of the V=24.0 value that was used in the ETC, a distance constraint of less than 2.3 AU from JWST must be specified. This NEA is the faintest and so the distance constraint results in the tightest observing window.

Overheads

The APT calculates and reports overheads for all observations. The observations in this example program are not considered time-critical and so will not be charged the additional overhead. Nor are they target of opportunity (ToO) observations. With only one observation per target, smart accounting will not result in any time savings.

The only moving target-specific overheads that will be incurred for this example program are for the initialization of guide star acquisition and tracking. One 90-second overhead will be applied for each observation (for a total of 270 seconds), and 30-seconds for each dither (the number of dithers for each observation is the number of dither positions minus one, so there are 7 dithers in this program, resulting in an additional 210 seconds). Thus the total additional overhead for this moving target program is 480 seconds (8 minutes).



Run Visit Planner

See also: APT Visit Planner

Update (July 2023): This example program was constructed prior to the launch of JWST in December 2021 and the dates were originally chosen to represent the start of Cycle 1, assuming a March 2021 launch. In the latest version of APT (2023.3.4), the Visit Planner does not return any visibility for these dates that occur in the past, but does return windows for the default date range. This issue should not affect the usefulness of this example program as an exercise in proposal preparation. The steps below are still valid for updating the Visit Planner processing date range, but we instead recommend running the Visit Planner with the more recent default date range.

Click on the Visit Planner icon in the APT GUI and make sure the Observation Folder with all 3 NEA observations is highlighted. If the default Visit Planner windows do not cover the specified dates (October 1, 2021, to September 30, 2022), follow the steps below:

  • First select the Visit Planner icon in the top tool bar.
  • Go to the Visit Planner menu.
  • Select Set Processing Date Range.
  • Input the specified date range. Keep in mind that this date range will only be valid for the current session; if you close the APT and reopen it, you will have to re-input these values.
  • Click the Update Display button.



Run Smart Accounting

See also: APT Smart Accounting

Click on the Smart Accounting button or select the Force Run Smart Accounting option from the Visit Planner menu. Even though smart accounting will not reduce the overheads for this particular proposal, it is required to be run prior to submission.



Latest updates

  • A few updates for Cycle 3 proposers.

  •  
    Minor wording changes.
Originally published