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.

Red text indicates restrictions on a parameter.

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:

Field	Details	Values	Notes
General Information
Observation Number	assign observation number	number
Observation Label	provide observation label	text	optional
Observations Comments	provide observation comments	text	optional
Target Name	select Target Name	choose from list	from Target List
Special Requirements	specify special requirements	choose from list	if needed
Template Specific Information
Target Name	select Target Name	choose from list	from Target List, if PRIME
Pointing Type	select the type of pointing	choose PRIME or PARALLEL
Science Exposures
Module	select Module	choose A, B, or All
Subarray	select Subarray	choose from list
Dither Patterns
Primary Dither Type	select Dither Type	choose from list
Primary Dithers	select number of steps	choose from list	for FULL only
Primary Dithers	select number of steps	choose from list	for INTRAMODULE only
Primary Dithers	select number of steps	choose from list	for INTRASCA only
Dither Size	select dither size	choose from list	for INTRASCA only
Subpixel Positions	select subpixel positions	1, 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). 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. 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

Pupil	Center Wavelength λ₀(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

Pupil	Center Wavelength λ₀(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	H₂
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

Filter	Center Wavelength λ₀(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	Pα
F212N	2.12	0.021	H₂
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

Filter	Center Wavelength λ₀(mm)	Filter Bandpass Δλ (mm)
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)
Short Wavelength Channel		Clear	Flatfield/Dark	Coronagraph 1 (round)	Coronagraph 2 (bar)	F164N	F162M	PINHOLES	WL 1 (+8)	WL 2 (-8)	GDHS0	GDHS60	MASKIPR
Filter Wheel	F170W	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 channel		Pupil wheel (grouped by function)
Long wavelength channel		Clear	Flat/Dark	Coronagraph 1 (round)	Coronagraph 2 (bar)	F323N	F405N	F466N	F470N	Outward Pinholes	GrismR (V2)	GrismC (V3)	MASKIPR
Filter Wheel	F277W	ok	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. 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. 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 Pattern	Number of Groups/Integration	Number of Integrations/Exposure
RAPID	1-10	1-10
RAPID (MODULES=ALL)	2 1	1-2 1-20
BRIGHT1	1-10	1-10
BRIGHT2	1-10	1-10
BRIGHT2 (MODULES=ALL)	2-10	1-10
SHALLOW2	1-10	1-10
SHALLOW4	1-10	1-10
MEDIUM2	1-10	1-10
MEDIUM8	1-10	1-10
DEEP2	1-20	1-10
DEEP8	1-20	1-10

Change log

Version 5 (April 17, 2019)

Editorial change (moved change log to main article).

Version 4 (August 2, 2018)

PR 79707 - updated Pointing Type section and Target Name section

Version 3 (April 9, 2018)

PR 89484 - updated exposure constraints for RAPID, BRIGHT2

Version 2 (September 21, 2017)

PR 88129 - added new options for subpixel dithers

Version 1 (April 10, 2017)

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

JWST Proposal Parameters

NIRCam External Flat Template Parameters

Introduction

General Information

Target Name

Pointing Type

Module

Subarray

Dither Patterns

Primary Dither Type

None

Full

Primary Dithers

Intramodule

Primary Dithers

Intrasca

Primary Dithers

Dither Size

Subpixel Positions

Filters

Pupils

Filters

Readout Pattern

Number of Groups/Integration

Number of Integrations/Exposure

Change log