NIRCam External Flat Template Parameters

JWST's NIRCam External Flat template, available in the Astronomer’s Proposal Tool (APT), is used for calibration observations for the NIRCam instrument.

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 External Flat template is to be used for all Flat-field observations using external targets. Note that this type of operation can be obtained as prime or as a parallel to normal science observations.

The NIRCam External Flat template consists of the following parameters:

FieldDetailsValuesNotes
General Information
Observation Numberassign observation number

number


Observation Label 
 
provide observation labeltextoptional
Observations Commentsprovide observation commentstextoptional
Target Nameselect Target Namechoose from listfrom Target List
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information
Target Nameselect Target Namechoose from listfrom Target List, if PRIME
Pointing Typeselect the type of pointingchoose PRIME or PARALLEL
Science Exposures
Module

select Module

choose A, B, or All


Subarray

select Subarray

choose from list


Dither Patterns
Primary Dither Typeselect Dither Typechoose from list
Primary Dithersselect number of stepschoose from listfor FULL only
Primary Dithersselect number of stepschoose from listfor INTRAMODULE only
Primary Dithersselect number of stepschoose from listfor INTRASCA only
Dither Sizeselect dither sizechoose from listfor INTRASCA only
Subpixel Positionsselect subpixel positions1, 2, 3 ...




Pupils

select pupil name

choose from list


Filters

select filter name

choose from list


Readout Pattern

select readout pattern

choose from list


Number of Groups/Integration

specify number of groups per integration

number

  

Number of Integrations/Exposure

specify number of integrations per exposure

number

  

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,  and Special Requirements. 

Target Name

Select the TARGET NAME [TBD] from the list of targets previously entered (see list of targets). (warning) If POINTING TYPE = PARALLEL, TARGET NAME = NONE. If POINTING TYPE = PRIME, NONE is not available.

Pointing Type

POINTING TYPE  = PARALLEL (default), PRIME

This parameter enables the user to control whether the data will be obtained in parallel like other calibrations, or as a primary observation like regular science.

Note for developers:

If PRIME, make TARGET NAME required, make the default “None Selected,” and remove the NONE option (so the user is prompted to select a target). Give an error if the PARALLEL special requirement is present.

If PARALLEL, set TARGET NAME = NONE (not changeable), set PRIMARY DITHER TYPE = NONE, set SUBPIXEL POSITIONS = 1, and add a PARALLEL special requirement. Give an error if the PARALLEL special requirement is not present.

Module 

MODULE [MODULE] = A, B, ALL

This parameter specifies the module to be used to obtain the data.

Subarray

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

This parameter specifies the region of the SCA that is to be read out. Subarrays other than FULL are only allowed if MODULE = B. If selecting SUB400P, SUB160P, or SUB64P, only one short wavelength SCA and the long wavelength SCA will be read out.

Dither Patterns

The following parameters define the dither patterns for NIRCam External Flats. (warning) If POINTING TYPE = PARALLEL, PRIMARY DITHER TYPE=NONE.

Primary Dither Type

PRIMARY DITHER TYPE [DITHER_FOV] = NONE, FULL, INTRAMODULE, INTRASCA

This parameter specifies the type of primary dither pattern.

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

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.

 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 covering the 40" module gap.

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.

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.

Note for developers: see NIRCam Dither Details for dithering details.

Filters  

For each exposure to be executed , specify the PUPIL, FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, and NUMBER OF INTEGRATIONS/EXPOSURE.

Pupils

Select the PUPILs [PUPILSHORT, PUPILLONG] (see Table 1 and Table 2) you wish to use (one for the Short Wavelength and one for the Long Wavelength cameras). If POINTING TYPE is specified as PARALLEL, only one long and one short pupil may be selected.

Table 1. Pupils Available for NIRCam Short Wavelength Camera Observations

PupilCenter Wavelength λ0 (mm)Filter Bandpass Δλ (mm)Comment

CLEAR



Imaging pupil

MASKRND



Round mask

MASKBAR



Bar mask

MASKIPR



Internal Phase Retrieval Wedge (for External Flat only)

F162M

1.62

0.151

CO (6-3)

F164N

1.64

0.016

Fe II

GDHS0



Dispersed Hartman Sensor 0 degrees

GDHS60



Dispersed Hartman Sensor 60 degrees

PINHOLES



(for Focus only)

WLP8



Weak Lens (-8 waves defocus)

WLM8



Weak lens (+8 waves defocus)


Table 2. Pupils Available for NIRCam Long Wavelength Camera Observations

PupilCenter Wavelength λ0 (mm)Filter Bandpass Δλ (mm)Comment

CLEAR



Imaging pupil

MASKRND



Round mask

MASKBAR



Bar mask

MASKIPR



Internal Phase Retrieval Wedge (for External Flat only)

F323N

3.23

0.032

H2

F405N

4.05

0.041

Brα

F466N

4.66

0.047


F470N

4.70

0.047


GRISMR



Spectrum parallel to detector rows (V2)

GRISMC



Spectrum parallel to detector columns (V3)

PINHOLES



(for Focus only)

Filters     

Select the name of each FILTER [FILTSHORT, FILTLONG] pair (see Table 3 and Table 4  ) that you wish to use. If POINTING TYPE is specified as PARALLEL, only one long and one short filter may be selected.

Table 3. Filters Available for NIRCam Short Wavelength Camera Observations     

FilterCenter Wavelength λ0 (mm)Filter Bandpass Δλ (mm)Comment

F070W

0.70

0.175


F090W

0.90

0.225


F115W

1.15

0.288


F150W

1.50

0.375


F150W2

1.50

1.000


F200W

2.00

0.500


F140M

1.14

0.140


F182M

1.82

0.221


F210M

2.10

0.210


F187N

1.87

0.019

F212N

2.12

0.021

H2

WLP4



Weak Lens, +4 waves defocus

F277W

2.77

0.693


F322W2

3.22

1.610


F356W

3.56

0.890


F444W

4.44

1.110


F250M

2.50

0.167


F300M

3.00

0.300


F335M

3.35

0.335


F360M

3.60

0.360


F410M

4.10

0.410


F430M

4.30

0.200


F460M

4.60

0.200


F480M

4.80

0.400


Table 4. Filters Available for NIRCam Long Wavelength Camera Observations    

FilterCenter Wavelength λ0 (mm)Filter Bandpass Δλ (mm)Comment

F277W

2.77

0.693


F322W2

3.22

1.610


F356W

3.56

0.890


F444W

4.44

1.110


F250M

2.50

0.167


F300M

3.00

0.300


F335M

3.35

0.335


F360M

3.60

0.360


F410M

4.10

0.410


F430M

4.30

0.200


F460M

4.60

0.200


F480M

4.80

0.400



Note for developers: The following tables summarize the allowed Filter Wheel + Pupil Wheel element combinations in the NIRCam Short Wavelength and Long Wavelength channels, respectively. Checks on the validity of these combinations should be implemented in the APT template. Table elements “ok” can be selected, elements “W” will generate a warning, and elements “E” will generate an error; the PAPPA and Flat/Dark elements (“D”) are disallowed and cannot be selected by the user since no (or no significant) external light will reach the detectors if the Flat/Dark (PAPPA) element is in the beam.

 Filter Wheel and Pupil Wheel Element Combinations - Short Wavelength Channels 

Short Wavelength Channel

Pupil wheel (grouped by function)
ClearFlatfield/DarkCoronagraph 1 (round)Coronagraph 2 (bar)F164NF162MPINHOLESWL 1 (+8)WL 2 (-8)GDHS0GDHS60MASKIPR
Filter WheelF170W

ok

D

E

E

E

E

D

W

W

E

E

W

F090W

ok

D

E

E

E

E

D

W

W

E

E

W

F115W

ok

D

E

E

E

E

D

W

W

W

W

W

F150W

ok

D

E

E

ok

E

D

W

W

W

W

W

F200W

ok

D

ok

ok

E

E

D

W

W

W

W

W

F212N

ok

D

ok

ok

E

E

D

ok

ok

W

W

ok

WLP4

ok

D

E

E

E

E

D

ok

ok

E

E

ok

F187N

ok

D

ok

ok

E

E

D

ok

ok

W

W

W

F210M

ok

D

ok

ok

E

E

D

W

W

W

W

W

F182M

ok

D

ok

ok

E

E

D

W

W

W

W

W

F140M

ok

D

E

E

E

E

D

W

W

ok

ok

W

F150W2

ok

D

E

E

ok

ok

D

W

W

ok

ok

W


Filter Wheel and Pupil Wheel Element Combinations - Long Wavelength Channels   

Long wavelength channelPupil wheel (grouped by function)
ClearFlat/DarkCoronagraph 1 (round)Coronagraph 2 (bar)F323NF405NF466NF470NOutward PinholesGrismR (V2)GrismC (V3)MASKIPR
Filter Wheel F277Wok

D

W

ok

E

E

E

E

D

ok

ok

W

F356W

ok

D

ok

ok

ok

E

E

E

D

ok

ok

W

F444W

ok

D

ok

ok

E

ok

ok

ok

D

ok

ok

W

F300M

ok

D

ok

ok

E

E

E

E

D

W

W

W

F480M

ok

D

E

ok

E

E

W

W

D

W

W

W

F410M

ok

D

ok

ok

E

W

E

E

D

ok

ok

W

F360M

ok

D

ok

ok

E

E

E

E

D

W

W

W

F430M

ok

D

ok

ok

E

E

E

E

D

W

W

W

F460M

ok

D

ok

ok

E

E

W

E

D

W

W

W

F250M

ok

D

W

ok

E

E

E

E

D

W

W

W

F335M

ok

D

ok

ok

W

E

E

E

D

W

W

W

F322W2

ok

D

W

W

ok

E

E

E

D

ok

ok

W

Readout Pattern

READOUT PATTERN [READOUT PATTERN] = MEDIUM2 (default), RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, 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. The default value is 10. (warning)See Table 5 for the values as a function of READOUT PATTERN.

Number of Integrations/Exposure

NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] field specifies the number of times the integration is repeated. (warning)See Table 5 for the values as a function of READOUT PATTERN.

Table 5. Number of Integrations/Exposure and Groups/Integration for NIRCam External Flats

Readout PatternNumber of Groups/IntegrationNumber of Integrations/Exposure
RAPID1-101-10
RAPID (MODULES=ALL)

2

1

1-2

1-20

BRIGHT11-101-10
BRIGHT21-101-10
BRIGHT2 (MODULES=ALL)2-101-10
SHALLOW21-101-10
SHALLOW41-101-10
MEDIUM21-101-10
MEDIUM81-101-10
DEEP21-201-10
DEEP81-201-10

Change log

Version 5 (April 17, 2019)

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


Version 4 (August 2, 2018)

  1. PR 79707 -  updated Pointing Type section and Target Name section


Version 3 (April 9, 2018)

  1. PR 89484 - updated exposure constraints for RAPID, BRIGHT2


Version 2 (September 21, 2017)

  1. PR 88129 - added new options for subpixel dithers


Version 1 (April 10, 2017)

  1. This is the converted Word File from Chapter 29.
  2. PR 86996   - updated dithers