NIRCam Coronagraphic Imaging Template Parameters

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

Introduction

Purple text indicates the parameter is Limited Access.

Boldface italics type indicates the name of an APT parameter or a value for a parameter.

(warning)Red text indicates restrictions on a parameter.

(red star) Black text indicates an important note.

Brown text indicates notes for the developers.

Green text indicates the name of the parameter used by Commanding.

Items in brackets - <value> - are required values.

Items in square brackets - [<value>] - are optional.

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:

FieldDetailsValues Notes
General Information   
Observation Numberassign observation number

number


Observation Label provide observation labeltextoptional
Observation Commentsprovide observation commentstextoptional
Target Nameselect Target Namechoose from listfrom Target List

ETC Wkbk. Calc. ID

specify ETC Workbook Calculation IDnumberfor science exposures (optional) and target acquisition exposures
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Moduledefault valueA
select coronagraphic mask

choose from list


Target Acquisition Exposures
select target name

choose from list

if offset target used
Acquisition Target Brightnessselect target brightness typeBRIGHT, FAINT
select readout pattern

choose from list


specify number of groups per integration

number


Confirmation Images
Obtain Astrometric Confirmation Imagesselect if confirmation images neededYES, NO

Confirmation Readout Pattern

select readout patternchoose from listonly if OBTAIN ASTROMETRIC CONFIRMATION IMAGE = YES
Confirmation Number of Groups/Integrationspecify number of groups per integration
 numberonly if OBTAIN ASTROMETRIC CONFIRMATION IMAGE = YES
Confirmation Number of Integrations/Exposurespecify number of integrations/exposurenumberonly if OBTAIN ASTROMETRIC CONFIRMATION IMAGE = YES
Science Exposures
Science Subarrayselect subarraychoose from list
Dither Patternselect small grid dither patternchoose from list
select filter name

choose from list


select readout pattern

choose from list


specify number of groups per integration

number


specify number of integrations per exposure

number


PSF Reference Observations
This is a PSF Reference Observationselect checkboxcheckboxindicates the observation is a "designated PSF reference observation"
PSF Reference Observationsselect observationschoose from list
Additional Justificationselect checkboxcheckboxindicates self-referenced survey; justification must be submitted with proposal

General Information 

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

Coronagraphic Mask 

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

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

 Table 1. Coronagraphic Mask Parameters

Coronagraphic MaskShapeCameraTarget Acquisition FilterTarget Acquisition Subarray  
MASK210RRoundShortF210M128x128
MASKSWBBarShortF210M
128x128





MASK335RRoundLongF335M64x64
MASK430RRoundLongF335M64x64
MASKLWBBarLongF335M64x64

Target Acquisition Exposure 

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 CORONAGRAPHIC 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 Coronagraph Mask, Target Acquisition Brightness, and Science Filters.

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

Coronagraph Mask [CORON]

TACQ BRIGHTNESS [TACQ BRIGHTNESS]

Science Filters [FILTSHORT] or [FILTLONG]

Subarray

MASK210R

BRIGHT

All filters

SUBNDA210R

MASK335R

BRIGHT

All filters

SUBNDA335R

MASK430R

BRIGHT

All filters

SUBNDA430R

MASKSWB

BRIGHT

F182M

F187M

F200W

SUBNDASWBS

MASKSWB

BRIGHT

F210M

F212N

SUBNDASWBL

MASKLWB

BRIGHT

F250M

F300M

F335M

F360M

F410M

F430M

F277W

F356W

F444W

SUBNDALWBS

MASKLWB

BRIGHT

F460M

F480M

SUBNDALWBL

MASK210R

FAINT

All filters

SUBFSA210R

MASK335R

FAINT

All filters

SUBFSA335R

MASK430R

FAINT

All filters

SUBFSA430R

MASKSWB

FAINT

All filters

SUBFSASWB

MASKLWB

FAINT

All filters

SUBFSALWB

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, DEEP2, DEEP8

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

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 coronagraphic 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.

Astrometric Confirmation Image 

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.  (warning)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.  (warning)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 Coronagraph 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

Coronagraph Mask [CORON]

Subarrays

MASK210R

FULL, SUB640A210R

MASKSWB

FULL, SUB640ASWB

MASK335R

FULL, SUB320A335R

MASK430R

FULL, SUB320A430R

MASKLWB

FULL, SUB400X256ALWB

Small Grid Dithers 

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)

Short Wavelength Camera
Long Wavelength Camera
MaskFilter
MaskFilter
MASKSWB or MASK210R

F182M


MASKLWB

F250M


F210M



F300M


F187N



F335M


F1212N



F360M


F200W



F410M


 

F430M

 




F460M


 



F480M





F277W




F356W




F444W








MASK335RF250M




F300M





F335M





F360M




F410M




F430M




F460M




F480M




F356W




F444W




F322W2








MASK430RF250M




F300M




F335M




F360M




F410M





F430M





F460M




F480M




F356W




F444W




F322W2


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

SHORT FILTERS

LONG FILTERS BY MASK

(all masks)

MASK210R

MASKSWB

MASK335R

MASK430R

MASKLWB

F182M

F210M

F187N

F212N

F200W

F250M

F300M

F335M

F360M

F410M

F430M

F460M

F480M

F356W

F444W

F322W2

F250M

F300M

F335M

F360M

F410M

F430M

F460M

F480M

F277W

F356W

F444W

F250M

F300M

F335M

F360M

F410M

F430M

F460M

F480M

F356W

F444W

F322W2

F250M

F300M

F335M

F360M

F410M

F430M

F460M

F480M

F356W

F444W

F322W2

F250M

F300M

F335M

F360M

F410M

F430M

F460M

F480M

F277W

F356W

F444W


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, DEEP2, DEEP8

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

Science Number of Groups/Integration

NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. (warning)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. (warning)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 the SEQUENCE 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."

 (warning) 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 CORONAGRAPHIC MASK, and same FILTER as the science observation. 

One or more observations must be selected, except when Proposal CATEGORY = COM, CAL, or ENGThe 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

The initial version of this chapter was based on the Preliminary Definition of Observing Templates for JWST Science Programs (Fullerton, Nov. 28, 2007) and the NIRCam OCD (Sahu, V4, Jan 2008).

 

  1. PROPINSTJWST-91639 Added note to Confirmation Images section to clarify Confirmation Images are not available when TA=NONE.


 

  1. PROPINSTJWST-91594 In Table 2 removed references to cycle-dependent subarrays.


November 20, 2022

  1. PROPINSTJWST-91566  Updated Science Filters and Science Filter Name sections with new simultaneous SW/LW observations and cycle dependence.


October 18, 2022

  1. PROPINSTJWST-91564 Updated subarray SUB400X256ALWB in Table 2.


July 21, 2022

  1. PROPINSTJWST-91531 Added new values to SUBARRAY section.


May 19, 2022

  1. PROPINSTJWST-91518 Added red note in PSF Reference Observation section documenting PSF Reference Observation is required except for COM, CAL and ENG.


Version 16 (May 6, 2022)

  1. PROPINSTJWST-91468 In Acquisition Target section developer note, changed "error" to "warning" for visit splitting.


Version 15 (October 19, 2021)

  1. PROPINSTJWST-91488 Added user facing red warning to PSF Reference Observations section.


Version 14 (June 16, 2021)

  1. PROPINSTJWST-91457 Added developer note in SUBARRAY section about providing errors for certain values of FIDUCIAL POINT OVERRIDE special requirement.
  2. Editorial change - Anchor links fixed in parameter table by removing pagename from link.


Version 13 (August 19, 2020)

  1. PROPINSTJWST-91420 - In Acquisition Target section, changed TA option NONE to purple text to indicate LAP. Condensed developer notes into bulleted list.


Version 12 (December 3, 2019)

  1. PROPINSTJWST-87008 - Added tables of subarrays to Acquisition Target section and Science Subarrays sections.


Version 11 (April 17, 2019)

  1. Editorial change (moved change log to main article).


Version 10 (December 21, 2018)

  1. PROPINSTJWST-91122 - Added developer note  in Acquisition Target section restricting acquisition target options for fixed vs. solar system observations.


Version 9 (October 2, 2018)

  1. PR 90409 - Updated Science filter name section with new masks
  2. PR 90969 -  Updated Acquisition Target Brightness section


Version 8 (December 26, 2017)

  1. PR 89483 - added restriction on Acq Target for SS observations


Version 7 (September 25, 2017)

  1. PR 88501 - revised limit on NINTs
  2. PR 88629 - revised text on exclusive access


Version 6 (August 24, 2017)

  1. PR 86708 - added new filters for MASK335R and MASK430R
  2. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure


Version 5 (May 11, 2017)

  1. PR 86572 - revised limits on NINTs
  2. PR 87783 - revised limits on TA NGroups
  3. PR 83561 - added SGD


Version 4 (February 21, 2017)

  1. PR 87071 - removed mosaic option
  2. PR 83117 - added PSF Reference Observation section


Version 3 (December 20, 2016)

  1. PR 85863 - updated developer note for Acquisition Target
  2. PR 85608 - updated TA parameters


Version 2 (November 14, 2016)

  1. PR 83513 - added Module
  2. PR 83513 - updated list of filters (TA and science)
  3. PR 84378 - updated number of groups for TA 
  4. PR 83513 - added TA
  5. PR 83513 - added Confirmation Images
  6. PR 83513 - added Subarray parameter
  7. PR 83513 - added Small Grid Dithers


Version 1 (March 29, 2016)

This is the converted Word File from Chapter 21.