Guide star data products

The FGS guiding capabilities are provided by 4 guide star functions: Identification, Acquisition, Track, and Fine Guide. Data downlinked by these functions is processed by DMS to provide uncalibrated and calibrated guide star data products. The uncalibrated products consist of raw pixel value data arrays, as well as different kinds of tabular information related to the guide stars and centroid locations of the guide star as computed by the on-board FGS Flight Software (FSW). Calibrated guide star products are created by the calwebb_guider pipeline. Briefly, the processing performed applies bad pixel masks and flat-fields the science data, as well as computing countrate images from the multiple groups within each integration contained in a given product. The countrate images, which are computed by the guider_cds step, are computed for most modes by simply differencing groups 1 and 2 in each integration and dividing by the group time.

File naming

Guide star product file names contain identifiers related to the function in use and the time at which the data were obtained. The table below lists the file name syntax used for each of the guiding functions and the related value of the EXP_TYPE keyword.

Function	EXP_TYPE	File name
Identification	FGS_ID-IMAGE	jw<pppppooovvv>_gs-id_<m>_image-uncal.fits
	FGS_ID-STACK	jw<pppppooovvv>_gs-id_<m>_stacked-uncal.fits
Acquisition	FGS_ACQ1	jw<pppppooovvv>_gs-acq1_<yyyydddhhmmss>_uncal.fits
	FGS_ACQ2	jw<pppppooovvv>_gs-acq2_<yyyydddhhmmss>_uncal.fits
Track	FGS_TRACK	jw<pppppooovvv>_gs-track_<yyyydddhhmmss>_uncal.fits
Fine Guide	FGS_FINEGUIDE	jw<pppppooovvv>_gs-fg_<yyyydddhhmmss>_uncal.fits

where the file name fields are:

jw:

mission identifier

ppppp:

program id

ooo:

observation number

vvv:

visit number

m:

ID attempt counter (1-9)

yyyydddhhmmss:

time stamp at the end of the data in the file

Uncalibrated products use the “uncal” file name suffix as shown above, while calibrated products use a “cal” suffix. The relevance of the “image” and “stacked” designations for the Identification mode products is described below.

ID mode

The “Identification” guiding function images the field of view by reading the detector in a series subarray “strips” that, collectively, cover most of the field. A total of 36 subarray strips are read out, each of which is 64 x 2048 pixels in size. Each strip has 8 pixels of overlap with its adjoining strips, resulting in a total of 2024 unique detector rows that’ve been read out. ID mode uses 2 groups per integration and 2 integrations, resulting in a total of 4 reads. Each subarray strip has its 4 reads performed before moving on to the next subarray.

DMS creates 2 different forms of products for ID mode data: one in which an image is constructed by simply stacking or butting the data from adjacent subarray strips against one another and the other in which the overlap regions of the strips are taken into account by averaging the pixel values. The first form is referred to as a “stacked” product and the second as an “image” product.

The FITS file structure for uncalibrated ID “image” products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	2024 x 2048 x 2 x 2
2	Flight Reference Stars	BINTABLE	N/A	4 cols x nstars
3	Planned Reference Stars	BINTABLE	N/A	10 cols x nstars

• SCI: 4-D data array containing the raw pixel values. The subarray overlaps have been accounted for, resulting in image dimensions of 2024 x 2048 pixels, with the 2 groups and 2 integrations stacked along the 3rd and 4th array axes.

• Flight Reference Stars: A table containing information on the actual reference stars used by the FSW. Detailed contents are listed below.

• Planned Reference Stars: A table containing information on the planned reference stars. Detailed contents are listed below.

The FITS file structure for uncalibrated ID “stacked” products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	2304 x 2048 x 2 x 2
2	Flight Reference Stars	BINTABLE	N/A	4 cols x nstars
3	Planned Reference Stars	BINTABLE	N/A	10 cols x nstars

• SCI: 4-D data array containing the raw pixel values. The subarray data are butted against one another, resulting in image dimensions of 2304 x 2048 pixels, with the 2 groups and 2 integrations stacked along the 3rd and 4th array axes.

• Flight Reference Stars: A table containing information on the actual reference stars used by the FSW. Detailed contents are listed below.

• Planned Reference Stars: A table containing information on the planned reference stars. Detailed contents are listed below.

The FITS file structure for calibrated ID “image” products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	2024 x 2048 x 1
2	ERR	IMAGE	float32	2024 x 2048 x 1
3	DQ	IMAGE	uint32	2024 x 2048
4	Flight Reference Stars	BINTABLE	N/A	4 cols x nstars
5	Planned Reference Stars	BINTABLE	N/A	10 cols x nstars
6	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. The data for the 2 integrations has been combined into a single image, as is done by the on-board FSW, resulting in a data array with NAXIS3 = 1.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• Flight Reference Stars: A table containing information on the actual reference stars used by the FSW. Detailed contents are listed below.

• Planned Reference Stars: A table containing information on the planned reference stars. Detailed contents are listed below.

• ADSF: The data model meta data.

The FITS file structure for calibrated ID “stacked” products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	2304 x 2048 x 1
2	ERR	IMAGE	float32	2304 x 2048 x 1
3	DQ	IMAGE	uint32	2304 x 2048
4	Flight Reference Stars	BINTABLE	N/A	4 cols x nstars
5	Planned Reference Stars	BINTABLE	N/A	10 cols x nstars
6	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. The data for the 2 integrations has been combined into a single image, as is done by the on-board FSW, resulting in a data array with NAXIS3=1.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• Flight Reference Stars: A table containing information on the actual reference stars used by the FSW. Detailed contents are listed below.

• Planned Reference Stars: A table containing information on the planned reference stars. Detailed contents are listed below.

• ADSF: The data model meta data.

Flight reference stars table

The structure and content of the Flight Reference Stars table is as follows.

Column Name	Data Type	Description
reference_star_id	char*2	Reference star index
id_x	float64	x position in FGS Ideal frame
id_y	float64	y position in FGS Ideal frame
count_rate	float64	count rate

Planned reference stars table

The structure and content of the Planned Reference Stars table is as follows.

Column Name	Data Type	Description
guide_star_order	int32	Guide star index within list
reference_star_id	char*12	GSC II identifier
ra	float64	ICRS RA of the star
dec	float64	ICRS Dec of the star
id_x	float64	x position in FGS Ideal frame
id_y	float64	y position in FGS Ideal frame
fgs_mag	float64	magnitude
fgs_mag_uncert	float64	magnitude uncertainty
count_rate	float64	count rate
count_rate_uncert	float64	count rate uncertainty

ACQ1 mode

The “Acquisition” guiding function ACQ1 performs 128 x 128 pixel subarray readouts of the detector, using 2 groups per integration and a total of 6 integrations. The FITS file structure for ACQ1 uncalibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	128 x 128 x 2 x 6

• SCI: 4-D data array containing the raw pixel values.

The FITS file structure for ACQ1 calibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	128 x 128 x 6
2	ERR	IMAGE	float32	128 x 128 x 6
3	DQ	IMAGE	uint32	128 x 128
4	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. Count rate images have been computed for each of the 6 integrations by differencing the 2 groups of each integration.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• ADSF: The data model meta data.

ACQ2 mode

The “Acquisition” guiding function ACQ2 performs 32 x 32 pixel subarray readouts of the detector, using 2 groups per integration and a total of 5 integrations. The FITS file structure for ACQ2 uncalibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	32 x 32 x 2 x 5

• SCI: 4-D data array containing the raw pixel values.

The FITS file structure for ACQ2 calibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	32 x 32 x 5
2	ERR	IMAGE	float32	32 x 32 x 5
3	DQ	IMAGE	uint32	32 x 32
4	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. Count rate images have been computed for each of the 5 integrations by differencing the 2 groups of each integration.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• ADSF: The data model meta data.

Track mode

The “Track” guiding function performs 32 x 32 pixel subarray readouts, the location of which can move on the detector as the FGS FSW tracks the position of the guide star. The subarray readouts are performed with a cadence of 16 Hz. Each integration consists of 2 groups, and the total number of integrations (NINTS) can be very large (in the thousands). The FITS file structure for TRACK uncalibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	32 x 32 x 2 x nints
2	Pointing	BINTABLE	N/A	12 cols x nrows
3	FGS Centroid Packet	BINTABLE	N/A	17 cols x nrows
4	Track subarray table	BINTABLE	N/A	5 cols x nrows

• SCI: 4-D data array containing the raw pixel values.

• Pointing: A table containing guide star position and jitter information. See below for details of the contents.

• FGS Centroid Packet: A table containing guide star centroiding information. See below for details of the contents.

• Track subarray table: A table containing subarray information over the duration of the product. See below for details of the contents.

The FITS file structure for TRACK calibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	32 x 32 x nints
2	ERR	IMAGE	float32	32 x 32 x nints
3	DQ	IMAGE	uint32	32 x 32
4	POINTING	BINTABLE	N/A	12 cols x nrows
5	FGS CENTROID PACKET	BINTABLE	N/A	17 cols x nrows
6	TRACK SUBARRAY TABLE	BINTABLE	N/A	5 cols x nrows
7	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. Count rate images for each integration have been computed by differencing the 2 groups in each integration.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• Pointing: A table containing guide star position and jitter information. See below for details of the contents.

• FGS Centroid Packet: A table containing guide star centroiding information. See below for details of the contents.

• Track subarray table: A table containing subarray information over the duration of the product. See below for details of the contents.

• ADSF: The data model meta data.

Pointing table

The structure and content of the Pointing table is as follows.

Column Name	Data Type	Units	Description
time	float64	milli-sec	Time since start of data file
jitter	float64	milli-arcsec	\(sqrt(delta\_ddc\_ra^2 + delta\_ddc\_dec^2)\)
delta_ddc_ra	float64	milli-arcsec	Initial DDC RA - Current
delta_ddc_dec	float64	milli-arcsec	Initial DDC Dec - Current
delta_aperture_pa	float64	milli-arcsec	Initial PA - Current
delta_v1_ra	float64	milli-arcsec	Initial V frame RA - Current
delta_v1_dec	float64	milli-arcsec	Initial V frame Dec - Current
delta_v3_pa	float64	milli-arcsec	Initial V frame PA - Current
delta_j1_ra	float64	milli-arcsec	Initial J frame RA - Current
delta_j1_dec	float64	milli-arcsec	Initial J frame Dec - Current
delta_j3_pa	float64	milli-arcsec	Initial J frame PA - Current
HGA_motion	int32	N/A	HGA state: 0 = moving, 1 = finished, 2 = offline

FGS Centroid Packet table

The structure and content of the Centroid Packet table is as follows.

Column Name	Data Type	Description
observatory_time	char*23	UTC time when packet was generated
centroid_time	char*23	Fine guidance centroid time
guide_star_position_x	float64	FGS Ideal Frame (arcsec)
guide_star_position_y	float64	FGS Ideal Frame (arcsec)
guide_star_instrument_counts_per_sec	float64	Instrument counts/sec
signal_to_noise_current_frame	float64	For current image frame
delta_signal	float64	Between current and previous frame
delta_noise	float64	Between current and previous frame
psf_width_x	int32	Bias from ideal guide star position (pixels)
psf_width_y	int32	Bias from ideal guide star position (pixels)
data_quality	int32	Centroid data quality
bad_pixel_flag	char*4	Bad pixel status for current subwindow (0/1)
bad_centroid_dq_flag	char*50	Bad centroid for current subwindow (0/1)
cosmic_ray_hit_flag	char*5	NO/YES
sw_subwindow_loc_change_flag	char*5	NO/YES
guide_star_at_detector_subwindow_boundary_flag	char*5	NO/YES
subwindow_out_of_FOV_flag	char*5	NO/YES

Track Subarray table

The Track Subarray table contains location and size information for the detector subarray window that is used during the track function to follow the guide star. The structure and content of the Track Subarray table is as follows.

Column Name	Data Type	Description
observatory_time	char*23	UTC time when packet was generated
x_corner	float64	Subarray x corner (pixels)
y_corner	float64	Subarray y corner (pixels)
x_size	int16	Subarray x size (pixels)
y_size	int16	Subarray y size (pixels)

FineGuide mode

The “FineGuide” guiding function performs 8 x 8 pixel subarray readouts, at a fixed location on the detector, and with a cadence of 16 Hz, from which the FGS FSW computes centroids for the guide star. To reduce readout noise contribution to the centroid calculation, “Fowler” sampling of the readouts is employed. Each integration consists of 4 readouts at the beginning, a signal accumulation period, and 4 readouts at the end. The detector is then reset and the readout cycle repeats for the next integration. The 4 readouts at the beginning are averaged together, the 4 readouts at the end are averaged together, and then the difference of the 2 averages is computed to form a final countrate image for each integration. This approach to creating the countrate images is used both on-board and in the calwebb_guider pipeline when the raw data are processed on the ground.

The FITS file structure for FineGuide uncalibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	uint16	8 x 8 x 8 x nints
2	Pointing	BINTABLE	N/A	12 cols x nrows
3	FGS Centroid Packet	BINTABLE	N/A	17 cols x nrows

• SCI: 4-D data array containing the raw pixel values.

• Pointing: A table containing guide star position and jitter information. See above for details of the contents.

• FGS Centroid Packet: A table containing guide star centroiding information. See above for details of the contents.

The FITS file structure for FineGuide calibrated products is as follows:

HDU	EXTNAME	HDU Type	Data Type	Dimensions
0	N/A	primary	N/A	N/A
1	SCI	IMAGE	float32	8 x 8 x nints
2	ERR	IMAGE	float32	8 x 8 x nints
3	DQ	IMAGE	uint32	8 x 8
4	POINTING	BINTABLE	N/A	12 cols x nrows
5	FGS CENTROID PACKET	BINTABLE	N/A	17 cols x nrows
6	ASDF	BINTABLE	N/A	variable

• SCI: 3-D data array containing the pixel values, in units of DN/s. Count rate images for each integration have been computed using the Fowler sampling scheme described above.

• ERR: 3-D data array containing uncertainty estimates for each pixel.

• DQ: 2-D data array containing DQ flags for each pixel.

• Pointing: A table containing guide star position and jitter information. See above for details of the contents.

• FGS Centroid Packet: A table containing guide star centroiding information. See above for details of the contents.

• ADSF: The data model meta data.