Page tree

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.

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 Observationindicate if PSF

PSF Reference Observationsselect PSF observationschoose from list
Additional Justificationindicate that there will be no specific PSF Obs

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 .

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.

Note for developers: For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to the SAME TARGET AS OBSERVATION.

Note for developers: If the  acquisition  target is different from the science  target, APT should provide an error 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.

Note for developers: 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.

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.

Astrometric Confirmation Image 

OBTAIN ASTROMETRIC CONFRIMATION_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] = SUB320, SUB640, FULL

This optional parameter specifies the region of the SCA that is to be read out for the science images.

Note for developer: If MASK=MASKSWB or MASK210R, the choices presented should be SUB640 or FULL. If MASK=MASKLWB, MASK335R, or MASK430R, the choices presented should be SUB320 or FULL.

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 FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION,  and the NUMBER OF INTEGRATION/EXPOSURE

. For more information on defining an exposure specification, see Filters and Exposures.

Science Filter Name

Select the name of the FILTER [FILTLONG or FILTSHORT] from Table 2 that you wish to use; for the filter bandpasses, see Filters for NIRCam coronagraphic imaging  (warning)A maximum of 6 filters, appropriate for the MASK chosen, may be specified for any Observation.

Table 2. Filters Available for NIRCam Coronagraphic Imaging

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


 The selection of MASK determines whether the short or long camera is used, and this limits the choice of filters.

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. Warning and errors will help guide the user to correctly set up these links.

 This is a PSF Reference Observation 

Choosing this option indicates that this observation is a PSF observation.

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

PSF Reference Observations    

If this is a science observation, designated PSF Reference Observations must be selected from this list. (The exception is for a "self reference survey" where all observations serve as PSF observations for each other. In this case select the science observations which will be used.)

Note to developer: Only list observations which use the same instrument, same coronagraphic mask, and same filter (ordered so that ones with the PSF Reference Observation checked come first and then the ones without the check).

Additional Justification 

Choosing this option indicates that this observation will not have a separate designated PSF observation because it is part of a self reference survey which will be described in the science justification.

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

Change log

 Click here to expand...

General Notes

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

Change Log

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.

Keywords

JWST NIRCam Coronagraphic Imaging Template

JWST NIRCam Coronagraphic Imaging template parameters

Format definitions

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

(warning)Red text indicates restrictions on a parameter.

Brown text indicates notes for the developers.

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

On this page

JWST Proposal Parameters

Change log

Change log