Description

Class:: WfssContamStep
Alias:: wfss_contam

The Wide Field Slitless Spectroscopy (WFSS) contamination correction (wfss_contam) step is applied to grism exposures in an attempt to correct effects due to overlapping spectral traces, which often happens in observations of crowded fields. It is to be applied to individual grism exposures in the latter stages of the calwebb_spec2 pipeline.

Briefly, source fluxes from a direct image of the field are used to simulate grism spectra for each source. Each source spectrum is then corrected for contamination by subtracting the simulated spectra of nearby sources. Details of the procedures and all input/output products are given in the following sections.

Inputs

The method utilized to perform the correction requires several input data products, including:

The grism data to be corrected. The step is applied near the end of the calwebb_spec2 pipeline, after the application of the extract_2d and srctype steps, but before the photom step. Thus individual 2D cutouts exist for each identified source in the grism image, and the data are still in units of countrate.
The resampled direct image (i2d product) of the field, usually obtained from the same WFSS observation as the grism image. The name of the direct image to use is retrieved from the “DIRIMAGE” keyword in the input grism image, which should’ve been populated at the beginning of the calwebb_spec2 pipeline from an entry in the “spec2” input ASN file.
The segmentation map (segm product) created from the direct image during calwebb_image3 processing. The name of the segmentation map to use is retrieved from the “SEGMFILE” keyword in the input grism image, which should’ve been populated at the beginning of the calwebb_spec2 pipeline from an entry in the “spec2” input ASN file.

The Method

Here we describe the steps used to perform the contamination correction:

First, a full-frame intermediate image, matching the size and shape of the grism image to be corrected, is created and populated with simulated spectra of all known sources in the field. The simulated spectra are created as follows:
1. The segmentation (segm) file is searched for pixels with non-zero values and lists of pixels belonging to each source are created.
2. The fluxes of each pixel in the lists are loaded from the direct image (i2d), creating a list of per-pixel flux values for each source.
3. A list of wavelength values is created for each source, which will be used to create the simulated spectra. The wavelength values span the range given by minimum and maximum wavelengths read from the WAVELENGTHRANGE reference file and are order-dependent.
4. The direct image pixel locations and wavelengths for each source are transformed into dispersed pixel locations within the grism image using the WCS transforms of the input grism image.
5. The flux of each direct image pixel belonging to each source is “dispersed” into the list of grism image pixel locations, thus creating a simulated spectrum.
6. The initial simulated spectra are in flux-calibrated units, so each spectrum is divided by the sensitivity curve from the PHOTOM reference file, to convert the simulated spectra to units of countrates, thus matching the units of the observed grism data.
7. The simulated spectrum for each source is stored in the full-frame image.
8. Steps c-g are repeated for all spectral orders defined in the WAVELENGTHRANGE reference file.
2D cutouts are created from the full-frame simulated grism image, matching the cutouts of each source in the input grism data.
For each source cutout, the simulated spectrum of the primary source is removed from the simulated cutout, leaving only the simulated spectra of any nearby contaminating sources.
The simulated contamination cutout is subtracted from the observed source cutout, thereby removing the signal from contaminating spectra. If polynomial fitting is enabled, see the section on Polynomial Flux Modeling below for details on how this modifies steps 3 & 4.

Outputs

There is one primary output and two optional outputs from the step:

The primary output is the contamination-corrected grism data, in the form of a MultiSlitModel data model. In the calwebb_spec2 pipeline flow, this data model is passed along to the photom step for further processing.
If the step argument --save_simulated_image is set to True, the full-frame image containing all simulated spectra (the result of step 1 above) is saved to a file. See Step Arguments.
If the step argument --save_contam_images is set to True, the simulated contamination cutouts (the result of step 3 above) are saved to a file. See Step Arguments.

Polynomial Flux Modeling

By default, each source is simulated with a spectrally flat flux model - that is, the flux at every wavelength is taken directly from the direct image pixel values. When the step argument --polyfit_degree is set to an integer N, the step fits a spectral model to each source. The procedure is:

In addition to the standard flat-spectrum simulation (the constant, degree-0 term), N additional grism-frame images are simulated for each source, where for the ith simulation from i = 1 to i = N, the spectral flux distribution is assumed to follow the ith order Legendre polynomial. Legendre polynomials were chosen because they form an orthogonal basis set, which makes the fitter prefer smaller coefficients instead of oscillating large positive and negative coefficients. Recall that each dispersed-image pixel represents a linear combination of the contribution of several direct-image pixels at different wavelengths. These basis functions therefore must be computed before the dispersed image is discretized onto a pixel grid, i.e., just after the dispersion calculation.
For each source, the observed 2D spectrum is fit as a linear combination of these \(N+1\) basis images, i.e.

\[\text{observed} \approx c_0 \cdot B_0 + c_1 \cdot P_1(\lambda) + \cdots + c_N \cdot P_N(\lambda)\]

where \(B_0\) is the flat-spectrum simulation and \(P_k(\lambda)\) is the simulation driven by the \(k\)-th order Legendre polynomial flux model. The coefficients \(c_k\) are determined using a linear least-squares fit with L2 regularization, the strength of which is set by the step argument --l2_alpha. The regularization helps to keep the coefficients small, guarding against physically implausible flux distributions.
The fitted coefficients are checked to see if the fitted constant term coefficient, \(c_0\), deviates from unity by more than a threshold set by the step argument --rejection_threshold. If it does, the fit is rejected and the contamination estimate for that source is not updated on that iteration. This is used to avoid fits “blowing up” in cases where the polynomial fit has returned an unphysical total flux level, which typically occurs if background subtraction was imperfect or if the source sits in a highly contaminated region.
If a good solution was found, the best-fit linear combination replaces the original simulation for that source, and this spectrally corrected simulation is used in the contamination model to be applied before the subsequent iteration. If no good solution was found, the original flat-spectrum simulation is not modified.
The simulated contamination from all other sources is subtracted from each observed slit, and the resulting contamination-corrected slit is used as the “observed data” for the next iteration of the fit. Note that each iteration starts the fitting over from the original basis images; the fitted coefficients from the previous iteration are not used as a starting point.

The --n_iterations argument controls how many times the polynomial fit is repeated. On the first iteration the observed spectrum still contains contamination from neighboring sources; on subsequent iterations it is replaced by the contamination-corrected spectrum from the previous pass, so the polynomial flux fit is less biased by contamination from other sources. In practice, the polynomial fit typically converges for only relatively isolated sources on the first iteration, but the second iteration allows almost all sources to be fit even for test data in crowded fields. n_iterations > 3 typically does not provide much additional improvement. Iteration has no effect when --polyfit_degree is not set.

Multiprocessing

The step can make use of multiple CPU cores to speed up the simulation of the dispersed spectra. In short, the direct image pixels to be processed are divided into chunks that are distributed to the available CPU cores. Each core processes its assigned chunk of pixels, and the results are combined into the final full-frame simulated grism image. The number of cores to use can be set using the step argument --maximum_cores, and the maximum number of direct image pixels to be processed at once can be set using the step argument --max_pixels_per_chunk; see Step Arguments. See Running the JWST pipeline: Multiprocessing for more details and examples of how to run a pipeline step with multiprocessing enabled.