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.

On this page

Using the APT

Download the APT file associated with this Example Science Program, "NIRSpec_IFU_FS_NEAs_042019.aptx". This APT file was created with APT version 27.1. There may be inconsistencies or warnings with other versions of APT.

Step 1: Fill Out Proposal Information

Main article: JWST Moving Targets in APT

For the Scientific Category, you should select Solar System. Clicking the +/- button next to Science Keywords brings up a list of keywords to choose from. The keywords that best apply to this example program are Chemical Composition and Minor Planets. There is no need to select an Alternate Category. The remainder of the Proposal Information window is generic and is filled out the same way for fixed and moving target proposals.

An error (red X) is present on the Proposal Information page due to the absence of a PDF Attachment. For a real proposal, this attachment will include the science and technical justifications and is a necessary component of the proposal. For the purposes of this Example Science Program, we have not included an attachment and this error can be ignored.



Step 2: Enter Proposed Targets

Main articles: 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.



Step 3: Creating Observations in APT

Main article: 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."



Step 4: Fill In APT Observation Template for NIRSpec Fixed Slit Spectroscopy

Main article: 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 = NRS
    • 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.
  • 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 = NRSRAPID
    • Groups/Int = 384
    • 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.

(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 = NRS
    • Acq Groups/Int = 3 (fixed value)
    • Acq Integrations/Exp = 1 (fixed value)
  • Choose the S200A1 Slit and the Subarray will populate itself with SUBS200A1.
  • 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 = NRSRAPID
    • Groups/Int = 384
    • Integrations/Exp = 1
  • Remember that the Exposures per specification in the ETC workbook corresponds to the number of dithers.
  • Leave Autocal set to NONE.



Step 5: 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). This should only be considered when observing satellites around giant planets where significant flux contamination could occur from the giant planet on the MSA; obtaining a Leakcal observation in this situation would allow for the contamination to be removed later. For point sources away from bright extended sources, the Leakcal overhead can be avoided.



Step 6: Define Special Requirements

Main articles: General Special RequirementsTiming Special RequirementsSolar System Special RequirementsOverheads for Moving Targets

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 (constrained to occur within a window 1 hour or less) and so will not be charged the 1-hour 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).



Step 7: Run Visit Planner

Main Article: APT Visit Planner

Click on the Visit Planner icon in the APT GUI and make sure the Observation Folder with all 3 NEA observations is highlighted. As of APT 27.0.1, the default Visit Planner windows do not cover the assumed Cycle 1 dates. To change these dates:

  • First select the Visit Planner icon in the top tool bar.
  • Go to the Visit Planner menu.
  • Select Set Processing Date Range.
  • Input the assumed Cycle 1 dates (October 1, 2021-September 30, 2022). 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.



Step 8: Run Smart Accounting

Main article: 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.

The proposal is now complete! If this were a real proposal, you would attach the Science Justification as a PDF and click on the Submission icon, then follow any instructions provided after that.



Published

 

Latest updates