JWST's NIRCam Coronagraphic Imaging template, available in the Astronomer’s Proposal Tool (APT), has parameters for specifying and scheduling observations.

Introduction

The NIRCam Coronagraphic Imaging template is used for the coronagraphic imaging mode of NIRCam, and this article describes allowed values for all parameters. Advice on how to choose values which optimize your science can be found in the NIRCam Coronagraphic Imaging APT Template and NIRCam Coronagraphic Imaging articles.

The NIRCam Coronagraphic Imaging template consists of the following parameters:

General Information 

The following parameters are generic to all templates, and are not discussed in this article: Observation Number,  Observation Label, Observations Comments, Target Name, ETC Wkbk. Calc. ID, and Special Requirements.

Module 

MODULE [MODULE] = A

This parameter is not user selectable, but is displayed so that the user is aware of which NIRCam module will be used.

Note for developers: APT needs to pass the module to the scripts. 

Occulting Mask 

OCCULTING MASK [CORON] = MASK210R, MASK335R, MASK430R, MASKSWB, MASKLWB

This parameter specifies the OCCULTING MASK to be used to obtain the data. Selection of a mask also specifies other parameters as shown in Table 1.

 Table 1. Occulting Mask Parameters

Target Acquisition Parameters 

The following parameters are used to define NIRCam Target Acquisition observations. Note that for Coronagraphy, the science target is generally used for the acquisition, although when necessary, an offset star may be used. For more information on defining a target acquisition specification, see Target Acquisition Parameters in the NIRCam Coronagraphic Imaging APT Template article..

Acquisition Target 

If an offset star is to be used for the target acquisition observation, select the ACQUISITION TARGET [TACQ TARGET] from the list of targets previously entered.

 When the science target is a Solar System target, the acquisition target MUST be the science target. Or, if no target acquisition is needed, select ACQUISITION TARGET to be NONE.

The ACQUISITION FILTER (F182M or F335M filter (see table) will be populated based on the selected OCCULTING MASK.

Notes for developers:

• For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to the SAME TARGET AS OBSERVATION.
• If the  acquisition  target is different from the science  target, APT should provide a warning if the distance between the ACQ and Science targets is greater than the Visit splitting distance found in the PRD. Also, if there are multiple pointings within a visit, then the rules have to apply to the greatest separation between acq target and pointing within the visit.
• If the observation target is a fixed target, remove solar system targets from the acquisition target options. If the observation target is a Solar system target, remove all options from the acquisition target list except for the observation target and NONE.
  
• NONE is a limited access parameter.

Table 1 shows the target acquisition subarray that will be used depending on the selected Occulting Mask, Target Acquisition Brightness, and Science Filters.

Table 1. Target Acquisition Subarrays (only in Module A)

Acquisition Target Brightness 

ACQ TARGET BRIGHTNESS [ACQUISITION_MODE] = BRIGHT (ND Square), FAINT

This field specifies whether the acquisition target should be acquired using one of the target-acquisition neutral density squares (appropriate for bright targets), or one of the faint-target acquisition regions, which lie between the ND squares in a clear region of the coronagraph.

Note for developers: "BRIGHT (ND Square)" is for clarity in the GUI. When chosen, APT will populate acquisition_mode as BRIGHT.

Acquisition Readout Pattern 

ACQUISITION READOUT PATTERN [TACQ PATTERN] = RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, MEDIUMDEEP2, MEDIUMDEEP8, DEEP2, DEEP8

This field specifies the readout pattern to be used to obtain the acquisition data. MEDIUMDEEP2 and MEDIUMDEEP8 are available for Cycle 4 and later.

Acquisition Number of Groups/Integration 

ACQUISITION NUMBER OF GROUPS/INTEGRATION [TACQ NGROUPS] = 3, 5, 9, 17, 33, 65 

This parameter specifies the number of groups in an integration. 

Note to developer: APT should issue a warning if values larger than 17 are entered prior to the delivery of OSS build 6.

Note that the ACQUISITION NUMBER OF INTEGRATIONS/EXPOSURE is set to 1.

Note to developers: The recommended value for Acquisition Number of Groups/Integration will be guided by values provided in the INS user documentation – APT need not check the value.

Confirmation Images 

The users have the option to select confirmation images. These are 2 identical, full-frame exposures using all 5 detectors on the selected module (A). The first one is taken before, and the second taken after, the pointing offset that moves the target from the target-acquisition position to the location behind the selected occulting mask. The filter for confirmation images is the same as the target acquisition filter. These images will be used to perform astrometric calibration of the coronagraphic science data.

For ACQUISITION TARGET=NONE, Confirmation Images are not available and the Confirmation Images option is off and disabled.

Obtain Astrometric Confirmation Images? 

OBTAIN ASTROMETRIC CONFIRMATION_IMAGES = YES (default), NO

This field specifies whether full-frame astrometric confirmation images are needed.

Note for developer: If the user selects NO, the following 3 input fields specifying the exposure parameters for these images should not be displayed.

Confirmation Image Readout Pattern 

CONFIRMATION READOUT PATTERN [CI PATTERN] = RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, DEEP2, DEEP8

This field specifies the readout pattern to be used to obtain the confirmation image data.

Confirmation Image Number of Groups/Integration

CONFIRMATION NUMBER OF GROUPS/INTEGRATION [CI_NGROUPS] specifies the number of groups in the confirmation-image integration.  The range is 1 to 10, inclusive. 

Confirmation Image Number of Integrations/Exposure

CONFIRMATION NUMBER OF INTEGRATIONS/EXPOSURE [CI NINTS] specifies the number of integrations to use for the confirmation images.  The range is 1 to 10, inclusive. 

Science Exposures 

Science Subarray 

SUBARRAY [SUBARRAY] = FULL, SUB640A210R, SUB640ASWB, SUB320A335R, SUB320A430R, SUB320ALWB, SUB400X256ALWB

This optional parameter specifies the region of the SCA that is to be read out for the science images. Table 2 shows the available subarray depending on the selected OCCULTING MASK.

Notes for developer:

If the FIDUCIAL POINT OVERRIDE  special requirement is used, several values of the special requirement should produce an error based on the selected SUBARRAY:

• NRCA4_MASKSWB_NARROW and NRCA5_MASKLWB_NARROW may not be used with the FULL subarray
• NRCA4_FULL_MASKSWB_NARROW and NRCA5_FULL_MASKLWB_NARROW may only be used with the FULL subarray
  

Table 2. Coronagraphy Subarrays Allowed for Module A

Dither Pattern

DITHER PATTERN [PRIMARY_DITHERS] = NONE (default), 5-POINT-BOX, 5-POINT-DIAMOND, 9-POINT-CIRCLE, 3-POINT-BAR, 5-POINT-BAR

This parameter specifies the dither pattern to execute. If a value other than NONE is selected, the science exposures will be repeated at each of the requested dither positions.

Note for developer: If MASK is set to MASK210R, MASK335R or MASK430R, the available choices should be 5-POINT-BOX, 5-POINT-DIAMOND, and 9-POINT-CIRCLE. If MASK is set to MASKSWB or MASKLWB, the available choices should be 3-POINT-BAR and 5-POINT-BAR. In all case, NONE should be available.

Science Filters 

Exposures are grouped by filter. For each set of exposures to be executed, specify the filters, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION,  and the NUMBER OF INTEGRATION/EXPOSURE

• For Cycle 1 proposals, observations are performed in either the Short Wavelength Channel or the Long Wavelength Channel. The filters available may be either LONG FILTER or SHORT FILTER depending on the selected mask.
• For Cycle 2 proposals, observations are performed simultaneously in both the Short Wavelength Channel and Long Wavelength Channel. Both a LONG FILTER or SHORT FILTER must be selected. 

For more information on defining an exposure specification, see Filters and Exposures in the NIRCam Coronagraphic Imaging APT Template article.

Science Filter Name

Select the filters you wish to use (SHORT FILTER and/or LONG FILTER). Filters available depend on the selected mask (see Table 3; for Cycle 2 proposals see Table 4)). For the filter bandpasses, see Filters for NIRCam Coronagraphic Imaging.  

Table 3. Filters Available for NIRCam Coronagraphic Imaging (Cycle 0, 1)

Table 4. Filters Available for NIRCam Coronagraphic Imaging (Cycle2)

Note for developers: The target location behind the MASKSWB and MASKLWB occulters is filter dependent, as detailed in Appendix H2.

Science Readout Pattern 

READOUT PATTERN [READOUT PATTERN] = RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, MEDIUMDEEP2, MEDIUMDEEP8, DEEP2, DEEP8

This field specifies the readout pattern to be used to obtain the science data. MEDIUMDEEP2 and MEDIUMDEEP8 are available for Cycle 4 and later.

Science Number of Groups/Integration

NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. The maximum value is 10 for all READOUT PATTERNs except DEEP2 and DEEP8, for which the maximum value is 20.

Note for developers: APT should use the selected READOUT PATTERN and NGROUPS to calculate the integration time (time to acquire a single integration ramp). If that time exceeds 1000 seconds, APT should issue a warning stating that “The integration time per ramp exceeds the recommended upper limit of 1000 sec, and your data may be degraded by cosmic rays.”

Science Number of Integrations/Exposure

NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] field specifies the number of times the integration is repeated. The maximum value is 1000.

PSF Reference Observations

Coronagraphic observations generally have two science observations with an APERTURE PA OFFSET between them of 1-14 degrees as well as an associated PSF reference observation. These observations should be done back-to-back using a SEQUENCE NON-INT or GROUP NON-INT special requirement. Warnings and errors will help guide the user to correctly set up these links. When the target is a background target, the PSF Reference Observations parameters are not displayed.

This is a PSF Reference Observation

Choosing this option indicates the observation is a "designated PSF Reference Observation."

  All observations with THIS IS A PSF REFERENCE OBSERVATION selected will have EXCLUSIVE ACCESS PERIOD = 0 (unless CATEGORY=COM). 

Note to developer: If this option is chosen, display on the GUI "exclusive access period will be 0 months".

PSF Reference Observations

Select one or more observations from the list provided. The list includes all observations in the proposal which are observed with the same instrument, same OCCULTING MASK, and same FILTER as the science observation. 

One or more observations must be selected, except when Proposal CATEGORY = COM, CAL, or ENG. The selected observation must be a "designated PSF Reference observation" (i.e., the THIS IS A PSF REFERENCE OBSERVATION option is selected), unless ADDITIONAL JUSTIFICATION is also selected.

Note to developer: In the list, observations should be ordered first with the ones that have This Is A PSF Reference Observation checked,  then the ones without the check.

Additional Justification

Choosing this option indicates that this observation will not have a "designated PSF Reference observation," because it is part of a self reference survey which will be described in the science justification. One or more PSF Reference Observations are still required. For more information see the "Special case: coronagraphic surveys" section in HCI APT Instructions.

Notes to developer:

• It is an error to have nothing checked in the PSF Reference Observations. And it is still an error for a science observation to only choose other science observations and not choose a designated PSF observation, but in that case choosing the Additional Justification option replaces that error with a warning that a self reference survey must be justified.
• If a "designated PSF Reference observation" is selected, Additional Justification is disabled.  
• If Additional Justification  is selected, it is un-selected when a designated observation with This Is A PSF Reference Observation checked is selected

Change log