NIRCam Imaging Template Parameters

JWST's NIRCam 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 Imaging template is used for the direct 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 Imaging APT Template article.

The NIRCam Imaging template consists of the following parameters:

FieldDetailsValues Notes
General Information   
 Observation Numberassign observation number

number


 Observation Label provide observation labeltextoptional
Observation Comments provide 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
Mosaic Propertiesspecify mosaic parametersnumberif needed
 Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Science Exposures
select module

B or ALL


select subarray

choose from list


select aperture

choose from list


Dither Patterns
select Dither Type

choose from list


select number of steps

choose from list

for FULL only
Primary Dithersselect number of stepschoose from listfor FULLBOX only
Primary Dithersselect number of stepschoose from listfor INTRAMODULEX only
Primary Dithersselect number of stepschoose from listfor INTRAMODULEBOX only
select number of steps

choose from list

for INTRAMODULE only
select number of steps

choose from list

for INTRASCA only
select dither size

choose from list

for INTRASCA only
Primary Dithersselect number of stepschoose from listfor SUBARRAY_DITHER only
Subpixel Dither Typeselect subpixel dither typeSTANDARD, SMALL-GRID-DITHER
select subpixel positions

1, 2, 3...

for STANDARD only
Small Grid Dithersselect the small grid dither patternchoose from listfor SMALL-GRID-DITHER only
Filters
select filter name(s)

choose from list


select readout pattern

choose from list


specify number of groups/integration

number


specify number of integrations/exposure

number


General Information 

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

Science Exposures 

Module 

MODULE [MODULE] = B, ALL

This parameter specifies the module(s) to be used to obtain the data.

Subarray 

SUBARRAY [SUBARRAY] = FULL, FULLP, SUB64P, SUB160, SUB160P, SUB320, SUB400P, SUB640

This parameter specifies the region of the SCA detector that is to be read out.

(warning) Subarrays other than FULL can only be specified if MODULE is B.

 For more details about these subarrays, see Subarray in NIRCam Imaging APT Template.

Note to developer: If SUBARRAY= SUB64P, provide a diagnostic warning with the following text:

"The overlap of the SW and LW FOVs for the SUB64P subarrays is 1.16 x 1.87 arcseconds. Your target is likely to be displaced from the center of that region by 0.3 - 0.45 arcseconds (1-sigma). Consider using dithers or a mosaic to guarantee full spatial coverage of your target, and adequate sky coverage around it, in both channels. Use of the Time Series template, which includes target acquisition, will provide very accurate positioning, but does not offer dither or mosaic options."

Target Placement


TARGET PLACEMENT= MODULE GAP (default), MODULE A(A3 CORNER), MODULE B(B4 CORNER)

Select where the target will be placed relative to the detectors (see NIRCam Imaging APT Template).

Dither Patterns 

Most NIRCam Imaging observations will require dithering; see Dither Parameters in the NIRCam Imaging APT Template  article for details.

Primary Dither Type 

PRIMARY DITHER TYPE [DITHER_FOV] = NONE, FULL, FULLBOX, INTRAMODULE, INTRAMODULEX, INTRAMODULEBOX, INTRASCA, SUBARRAY_DITHER

This parameter specifies the type of primary dither pattern.

For observations with a single dither point, APT provides a warning. Total Dithers are displayed on the Filters table. The warning is not provided if the NIRCam Imaging observation is in a pure parallel, or is non-prime in a coordinated parallel with a prime that is not dithered.

Note to developer: PRIMARY DITHER TYPE should be a required field, and there should be no default value (i.e. do not make NONE the default).

Note to developer: If SUBARRAY=FULL and MODULE=ALL, do not offer PRIMARY DITHER TYPE=SUBARRAY_DITHER. If SUBARRAY=FULL and MODULE=B, do not offer PRIMARY DITHER TYPE=FULL or FULLBOX. If SUBARRAY=SUB640, SUB320, or SUB160 and MODULE=B offer only PRIMARY DITHER TYPE=INTRASCA, INTRAMODULEBOX,  or SUBARRAY_DITHER. If SUBARRAY=SUB400P, SUB160P, or SUB64P and MODULE=B offer only PRIMARY DITHER TYPE=INTRAMODULEBOX or SUBARRAY_DITHER.

None 

This value indicates no dithering will be performed. 

Full  

The following parameter is needed to specify the FULL dither.

Primary Dithers  

PRIMARY DITHERS [PRIMARY_DITHERS] = 3TIGHT, 3, 6, 9, 15, 21, 27, 36, 45

This parameter indicates the number of steps in the primary dither.

Fullbox 

The following parameter is needed to specify the FULLBOX dither.

Primary Dithers  

PRIMARY DITHERS [PRIMARY_DITHERS] 2TIGHTGAPS, 3TIGHTGAPS, 4TIGHT, 4, 5TIGHT, 6TIGHT, 6, 8NIRSPEC

This parameter indicates the number of steps in the primary dither.

Intramodulex 

The following parameter is needed to specify the INTRAMODULEX dither.

Primary Dithers  

PRIMARY DITHERS [PRIMARY_DITHERS] 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16

This parameter indicates the number of steps in the primary dither.

Intramodulebox 

The following parameter is needed to specify the INTRAMODULEBOX dither.

Primary Dithers  

PRIMARY DITHERS [PRIMARY_DITHERS] 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16

This parameter indicates the number of steps in the primary dither.

Intramodule 

The following parameter is needed to specify the INTRAMODULE dither. 

Primary Dithers 

PRIMARY DITHERS [PRIMARY_DITHERS] 3, 4, 6, 8, 12, 16

This parameter specifies the number of primary dither points.

Intrasca 

The following parameters are needed to specify the INTRASCA dither.

Note to developer: Populate CAMERA=SHORT until the details are worked out.

Primary Dithers 

PRIMARY DITHERS [PRIMARY_DITHERS] = 2, 3, 4

, 5,  7, 9, 13, 17, 25

This parameter specifies the number of primary dither points.

Dither Size 

DITHER SIZE [DITHER_SIZE] = 8" (SMALL), 16" (MEDIUM), 24" (LARGE)

This parameter specifies the size of the dither pattern.

Note to developer: Change to add the size to the name can be for the GUI only and the original value can be what goes to the database.

Subarray_dither 

The following parameter is needed to specify the SUBARRAY_DITHER dither.

Primary Dithers  

PRIMARY DITHERS [PRIMARY_DITHERS] 2, 3, 4

This parameter indicates the number of steps in the primary dither.

Subpixel Dither Type 

SUBPIXEL DITHER TYPE [SUBPIXEL_DITHER_TYPE] = STANDARD (default) , SMALL-GRID-DITHER

 This parameter specifies the subpixel dither type.

Standard 

The following parameter is needed to specify the STANDARD subpixel dither.

Subpixel Positions 

SUBPIXEL POSITIONS [SUBPIXEL_POSITIONS] = 1 (default) , 2, 3, 4, 5 , 7, 9, 12, 16, 20, 24, 30, 36, 48, 64

This parameter specifies the secondary dither points used for every primary dither point and is allowed for all PRIMARY DITHER TYPE values, including NONE.

Small Grid Dither 

The following parameter is needed to specify the SMALL-GRID-DITHER subpixel dither.

Small Grid Dithers   

SMALL-GRID-DITHER [SMALL_GRID_DITHER] = 1 (default), 2, 3, 4, 5, 6, 7, 8, 9

This parameter specifies the secondary dither points used for every primary dither point and is allowed for all PRIMARY DITHER TYPE values, including NONE.

Note to developer: see NIRCam Dither Details for dithering details.

Filters 

Exposures are grouped by filter pairs; for the filter bandpasses, see NIRCam Filters. For each set of exposures to be executed at each position in a dither pattern, specify the FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION,  and the NUMBER OF INTEGRATIONS/EXPOSURE.  Note that only one exposure duration is specified, and this will be used with both the long- and short-wavelength cameras, despite the fact that they will have different filters. For more information on defining an exposure specification, see Filters and Exposures in the NIRCam Imaging APT Template article. 

Filter Name 

Select the name of each FILTER [FILTLONG, FILTSHORT] pair you wish to use (one for the Long Wavelength and one for the Short Wavelength cameras; see Table 1)

. If the MODULE is ALL, the same filter pair will be used in both modules.


 Table 1. Filters Available for NIRCam Imaging

Short Wavelength Camera Filter


Long Wavelength Camera Filter
Single Filters
Single Filters

F070W


F277W

F090W


F322W2

F115W


F356W

F150W


F444W

F150W2


F250M

F200W


F300M

F140M


F335M

F182M


F360M

F210M


F410M

F187N


F430M

F212N


F460M



F480M




Crossed Filters
Crossed Filters

F162M+F150W2


F323N+F322W2

F164N+F150W2


F405N+F444W



F466N+F444W



F470N+F444W

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

Number of Groups/Integration 

NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration

. (warning)See  Table 2 for the values as a function of READOUT PATTERN.

 Table 2. Number of Groups/Integration for Imaging Observations

Readout PatternNumber of Groups/Integration

Number of Integrations/Exposure (SUBARRAY = FULL)

Number of Integrations/Exposure

(all other SUBARRAYs)
RAPID (MODULES=B)

1-10

1-10

1-200

RAPID

(MODULES=ALL)

2

1

1-2

1-20

N/A

N/A

BRIGHT1

1-10

 1-10

1-200
BRIGHT2 (MODULES=B)

1-10

1-10

1-200

BRIGHT2

(MODULES=ALL)

2-10
1-10

N/A

SHALLOW2

1-10

1-10

1-200
SHALLOW4

1-10

1-10

1-200
MEDIUM2

1-10

1-10

1-200
MEDIUM8

1-10

1-10

1-200
DEEP2

1-20

1-10

1-200
DEEP8

1-20

1-10

1-200

Number of Integrations/Exposure 

NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] field specifies the number of times the integration is repeated

. (warning)See Table 2   for the values as a function of READOUT PATTERN. 

Change log

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


 

  1. PROPINSTJWST-88319 Added warning to Primary Dither Type section.
  2. PROPINSTJWST-91623 In Target Placement section, added Parallel exception and updated option wording.


February 24, 2023

  1. PROPINSTJWST-91364 Added Target Placement section.


Version 8 (April 17, 2019)

  1. Editorial change (moved change log to main article).
  2. PROPINSTJWST-89050 Added FULLP to Subarray section.


Version 7 (November 5, 2018

  1. PROPINSTJWST-90328 - Updated developer note in Primary Dither Type section to include INTRAMODULEBOX.


Version 6 (April 18, 2018)

  1. PR 89484 - updated exposure constraints for RAPID, BRIGHT2
  2. PR 89616 - added Dev note to Subarrays


Version 5 (December 26, 2017)

  1. PR 88130 - updated limits on Number of Integrations/Group


Version 4 (October 9, 2017)

  1. PR 88124 - added dither patterns
  2. PR 88129 - added new options for subpixel dithers
  3. PR 87466 - added INTRASCA for MODULE=ALL
  4. PR 87895 - updated Exposure field labels to Groups/Integration and Integrations/Exposure


Version 3 (May 11, 2017)

  1. PR 86336 - added developer note on Primary Dither Type
  2. PR 86336 - removed options for Intramodule dither, Primary Dither Types
  3. PR 86336 - put CAMERA for Intrasca dithers in cross-out text
  4. PR 86336 - enhanced the names of the Dither Size values for Intrasca dithers
  5. PR 86336 - removed options for Intrasca dither, Primary Dither Types
  6. PR 86336 - added Subpixel Dither Type parameter
  7. PR 86336 - changed Subpixel Positions to be for Standard only
  8. PR 86994 - removed Module A


Version 2 (September 1, 2016)

PR 85443 - added subarrays SUB64P, SUB160P, SUB400P


Version 1 (March 28, 2016)

This is the converted Word File from Chapter 20.