Description

Class:: jwst.group_scale.GroupScaleStep
Alias:: group_scale

The group_scale step rescales pixel values in raw JWST science data products to correct for instances where on-board frame averaging did not result in the proper downlinked values.

When multiple frames are averaged together on-board into a single group, the sum of the frames is computed and then the sum is divided by the number of frames to compute the average. Division by the number of frames is accomplished by simply bit-shifting the sum by an appropriate number of bits, corresponding to the decimal value of the number of frames. For example, when 2 frames are averaged into a group, the sum is shifted by 1 bit to achieve the equivalent of dividing by 2, and for 8 frames, the sum is shifted by 3 bits. The number of frames that are averaged into a group is recorded in the NFRAMES header keyword in science products and the divisor that was used is recorded in the FRMDIVSR keyword.

This method results in the correct average only when NFRAMES is a power of 2. When NFRAMES is not a power of 2, the next largest divisor is used to perform the averaging. For example, when NFRAMES=5, a divisor of 8 (bit shift of 3) is used to compute the average. This results in averaged values for each group that are too low by the factor NFRAMES/FRMDIVSR. This step rescales the pixel values by multiplying all groups in all integrations by the factor FRMDIVSR/NFRAMES.

The step decides whether rescaling is necessary by comparing the values of the NFRAMES and FRMDIVSR keywords. If they are equal, then the on-board averaging was computed correctly and this step is skipped. In this case, the calibration step status keyword S_GRPSCL is set to “SKIPPED.” If the keyword values are not equal, rescaling is applied and the S_GRPSCL keyword is set to “COMPLETE”.

It is assumed that this step is always applied to raw data before any other processing is done to the pixel values and hence rescaling is applied only to the SCI data array of the input product. It assumes that the ERR array has not yet been populated and hence there’s no need for rescaling that array. The input GROUPDQ and PIXELDQ arrays are not affected by this step.

MIRI FASTGRPAVG mode

The MIRI detector readout pattern “FASTGRPAVG” results in individual frames being averaged together into a group, but the on-board averaging process is done differently than for other instruments. This results in a situation where the FRMDIVSR keyword gets assigned a value of 4, while NFRAMES still has a value of 1, despite the fact that 4 frames were actually averaged together to produce each downlinked group. This mismatch in keyword values would cause the group_scale step to think that rescaling needs to be applied.

To work around this issue, the original values of the number of frames per group and the number of groups per integration that are downlinked from the instrument are stored in the special keywords “MIRNFRMS” and “MIRNGRPS”, respectively, so that their values are preserved. During Stage 1 processing in the pipeline, the value of the NFRAMES keyword is computed from MIRNFRMS * FRMDIVSR. The result is that when 4 frames are averaged together on board, both NFRAMES and FRMDIVSR will have a value of 4, which allows the group_scale step to correctly determine that no rescaling of the data is necessary.