##############################
### CEERS Data Release 0.7 ###
##############################

Date Released: 3 October 2023

Here we provide the CEERS team's reductions of CEERS NIRSpec MSA observations.
In December 2022 (CEERS observing epoch 2), NIRSpec was the prime instrument 
for six pointings (4, 5, 7, 8, 9 and 10) with NIRCam imaging in coordinated 
parallel mode. The December PRISM observations in pointings 9 and 10 were 
impacted by bright stray light from an MSA short, and the affected data are 
not included in this release. Rescheduled PRISM observations were executed 
in February, using different coordinate centers and position angles than the 
original pointings 9 and 10. The February PRISM pointings are numbered 11 
and 12.

These data products will be available soon at MAST as High Level Science 
Products via DOI 10.17909/z7p0-8481.


############
### Summary

Instrument: NIRSpec
Mode: Multi-Object Spectroscopy
Calibration Pipeline Used: jwst v1.8.5
CRDS Context pmap: 1029
Target: NIRSpec pointings 4, 5, 7, 8, 9, 10, 11, 12
Dispersers/Filters: G140M/F100LP, G235M/F170LP and G395M/F290LP (R~1000); 
                    PRISM/CLEAR (R~100)
Readout: NRSIRS2
Observation specification: 14 groups, 1 integration
Dithers: 3 shutter slitlet nod pattern

Contact: Pablo Arrabal Haro (parrabalh@gmail.com)
         Mark Dickinson (mark.dickinson@noirlab.edu)


#################################
### CEERS NIRSpec observations

CEERS NIRSpec Multi-Shutter Assembly (MSA) observations were mostly executed 
in December 2022 ("CEERS epoch 2").  Prism observations of two fields 
(NIRSpec9 and NIRSpec10) were severely impacted by an MSA short, which caused 
bright stray light illumination over a significant portion of the field of 
view.  Observations of fields 9 and 10 with the medium resolution gratings 
were not affected by the short. We have not included the affected prism data 
in DR0.7, although some useful information can be recovered for some objects.  
The failed observations were rescheduled in February 2023 ("CEERS epoch 3") 
with a different telescope roll angle and at different pointing centers, 
which we designate as NIRSpec11 and NIRSpec12.  

The locations of the NIRSpec fields are shown in the observation layout 
figures available at the CEERS website 
(https://ceers.github.io/obs.html#layout_figures).

CEERS NIRSpec observations use the NIRSpec medium resolution gratings (MR or 
Mgrat) and the low-resolution prism.  The NIRSpec pointings observed with each 
disperser are:

G140M+F100LP   Pointings 4, 5, 7, 8, 9, 10
G235M+F170LP   Pointings 4, 5, 7, 8, 9, 10
G395M+F290LP   Pointings 4, 5, 7, 8, 9, 10
PRISM+CLEAR    Pointings 4, 5, 7, 8, 11, 12

For a given NIRSpec pointing, the observations with the MR gratings and the 
prism use different MSA configurations, observing different targets, although 
some objects were observed with both modes. The MR targets were observed with 
all three grating+filter combinations.

The MSA plans used 3-shutter slitlets, and the observations were executed 
using the standard 3-shutter nodding pattern.  In some cases, additional 
objects from the MSA catalog fell into open shutters during one or more nods;  
these objects may not have received the full exposure time that the planned 
targets received.  (We provide a file slits_double_objects.dat with a list of 
these cases; see discussion under Auxiliary Files.)  For objects observed in 
all three nod positions, the effective on-target integration time is 3064.667s.
The effective exposure time is recorded in the header keyword EFFEXPTM.  

The pipeline generates another keyword, XPOSURE, but we have noted that this 
value is incorrect for some objects, particularly for spectra that are split 
across both NIRSpec detectors (identifiable by DETECTOR = MULTIPLE in the 
headers). We recommend considering only the EFFEXPTM values.  STScI reports
 that this issue has been fixed for newer versions of the Calibration Pipeline.


#####################################
### Data reduction and calibration

The NIRSpec data were reduced using the JWST Calibration Pipeline version 
1.8.5 (Bushouse et al. 2022, DOI:10.5281/zenodo.7429939). The spectra were 
reduced using CRDS context jwst_1029.pmap.  Most processing used standard 
pipeline parameters. Here we give some relevant specifics, including 
deviations from standard processing:

Nodded background subtraction was employed (pipeline step = 'background').

Modified 'jump' parameters for an improved "snowball" correction.
  - det1.jump.expand_large_events = True
  - det1.jump.after_jump_flag_dn1 = 0
  - det1.jump.after_jump_flag_time1 = 0
  - det1.jump.after_jump_flag_dn2 = 0
  - det1.jump.after_jump_flag_time2 = 0
  - det1.jump.min_sat_area = 15.0
  - det1.jump.min_jump_area = 15.0
  - det1.jump.expand_factor = 2.0

The pipeline was instructed that all targets should be treated as point 
sources (SRCTYPE = 'POINT').  This has two main consequences:
  - Each 1D spectrum (x1d) is extracted from the 2D spectral data file (s2d) 
    over a specified range of pixels in the cross-dispersion (y-axis) 
    direction (boxcar extraction)
  - The extracted 1D (x1d) spectra have units of flux density (Jy), rather 
    than surface brightness.

Extraction apertures (from s2d to x1d) for each object were determined by 
interactive visual inspection and were specified explicitly for pipeline step 
'extract_1d'.  Most faint galaxies are compact, and the extraction apertures 
adopted for nearly all objects have heights ranging from 3 to 6 pixels 
(scale = 0.10 arcsec/pixel), with a median value of 4 pixels.

The default pipeline pathloss (aka slit loss) correction was employed.  That 
calibration is based primarily on pre-flight modeling, and assumes that the 
targets are point sources.  For sources that are significantly extended, this 
correction will likely be incomplete.

Flux calibration uses the default reference files for the adopted CRDS context.
These are a mix of ground and in-flight calibrations. Comparison between 
spectroscopic and photometric fluxes (when available) is recommended if 
accurate flux calibration and slit loss correction is required.


#########################
### Directory Contents

Spectra for each pointing are stored in separate directories, with 
subdirectories for each disperser. The directory names and filenames follow 
the format:
    [pointing]/[disperser]/hlsp_ceers_jwst_nirspec_[pointing]-[msa-id]_[disperser]_v0.7_[ext].fits
where:
  - [pointing] is one of 'nirspec4', 'nirspec5', 'nirspec7', 'nirspec8', 
        'nirspec9', 'nirspec10', 'nirspec11' or 'nirspec12'
  - [disperser] is one of 'g140m', 'g235m', 'g395m', or 'prism'
  - [msa-id] is a 6 digit identification number for the source
  - [ext] is one of:
    - 's2d': rectified 2D spectrum in units of MJy/px
    - 'x1d': extracted 1D spectrum using a boxcar extraction in a custom 
        aperture. Wavelength in microns, flux density in Jy
    - 'x1d-masked': same as x1d but with artifacts masked. Masked pixels are 
        set to NaN. Wavelength in microns, flux density in Jy

Combined MR 3-grating spectra:

Additionally, data products combining data from all three MR gratings into a 
single spectrum are available in the [pointing]/comb-mgrat directories:
  [pointing]/comb-mgrat/hlsp_ceers_jwst_nirspec_[pointing]-[msa-id]_comb-mgrat_v0.7_[ext].fits
where [ext] is one of 's2d' and 'x1d-masked'

For the combined 3-grating spectra, data from the individual MR gratings are 
resampled to a common wavelength vector in the overlapping regions, adopting 
the wavelength sampling of the longer wavelength grating. Flux values in the 
overlap regions are the average of the individual grating values weighted by 
the flux errors, excluding pixels affected by masked artifacts.  

For the combined 3-grating x1d spectra, only the WAVELENGTH, FLUX, and 
FLUX_ERROR values are combined in the overlap regions. Other columns from the 
x1d FITS data tables (e.g., FLUX_VAR_POISSON) have values taken from the 
original spectra in the non-overlap regions, and generally NaN values in the 
overlap regions.

Please note that most of the header information in the combined 3-grating 
products is copied from the headers of the G395M data, and does not attempt 
to present characteristics of the combined 3-grating data.  For the combined 
3-grating s2d files, most of the FITS extensions have valid information for 
the combined data, except for HDRTAB and ASDF. 

Under rare circumstances, the 2D spectra (s2d files) for a given object in the 
three MR gratings can have different sizes in the cross-dispersion (spatial) 
direction.  In some cases, the difference in sizes is of order one pixel, but 
in some cases one grating may have a y-dimension that is roughly 10 pixels 
shorter than the other two gratings.  We do not yet fully understand the reason 
for this, but in any case the source spectrum is generally well centered in 
the s2d files for all three gratings, so the spectra can be successfully 
extracted and combined.  We have taken into account the different sizes of the 
s2d files when we combine the three gratings to produce the comb-mgrat 2D 
products. However, in a few cases, there can be a shift of one pixel in the 
spatial direction for a portion of the comb-mgrat 2D spectrum.  In such cases, 
this shift does not affect the combined 3-grating (comb-mgrat) 1D spectrum, as 
that is not extracted from the combined 2D spectrum.  Instead, the 3-grating 1D
spectrum is produced from a combination of the separate 1D spectra for the 
three MR gratings, each extracted using its individual custom extraction 
aperture, each of the same size and correctly positioned.

Auxiliary files:
  - CEERS_NIRSpec_MSA_master_yield_v0.7.csv - The MSA yield file provides the 
        MSA ID (6 digit unique number across all pointings) and RA,Dec for 
        each source. It also specfies the pointing and disperser coverage 
        for each source
  - slits_double_object.dat - A list of cases where a multi-shutter MSA "slit" 
        includes two objects from the MSA planning catalog.  Central_target 
        gives the MSA ID for the target for which the slit was intended, and 
        Companion gives the MSA ID for the additional target that also falls 
        on open MSA shutters.  Note that it is sometimes the case that the 
        Companion was not observed in all three nod positions, and therefore 
        has reduced effective exposure time.
  - [pointing]/*_Mgrat_custaper.csv  - table of custom aperture extraction 
        windows used for MR grating extractions for each source
  - [pointing]/*_prism_custaper.csv  - table of custom aperture extraction 
        windows used for PRISM extractions for each source
  - [pointing]/[disperser]/plots_2D+1D - plots showing the 1D and 2D spectra 
        for all sources and dispersers


####################
### File structure

Rectified 2D spectra (*_s2d.fits) are multi-extension fits files with 10 
extensions:
  0. PRIMARY header
  1. SCI  - 2D data array (MJy/pixel)
  2. ERR  - 2D array of uncertainties, given as standard deviation
            constructed as the sum in quadrature of the resampled variance maps
  3. WHT  - 2D weight image giving the relative weight of the output pixels
  4. CON  - 2D context image, encoding info about which input exposures
            contribute to each output pixel
  5. VAR_POISSON  - 2D variance array based on Poisson noise only
  6. VAR_RNOISE  - 2D variance array based on read noise only
  7. VAR_FLAT  - 2D variance array based on uncertainty in the flat-field
  8. HDRTAB  - table containing metadata (FITS keyword values) for all the
               input exposures
  9. ASDF  - metadata for the JWST data model

Extracted 1D spectra (*_x1d.fits, *_x1d-masked.fits) are multi-extension fits 
files with 3 extensions:
  0. PRIMARY header
  1. EXTRACT1D  - table (one row per extracted spectral element in the 
     dispersion direction) with the following columns:
      - WAVELENGTH (um) 
      - FLUX (Jy) 
      - FLUX_ERROR (Jy)
      - FLUX_VAR_POISSON (Jy^2)
      - FLUX_VAR_RNOISE (Jy^2)
      - FLUX_VAR_FLAT (Jy^2)
    # Note that all surface brightness columns (SURF_BRIGHT, SB_*) are set 
    # to zero because sources are treated as point sources
      - SURF_BRIGHT (MJy/sr) 
      - SB_ERROR (MJy/sr)
      - SB_VAR_POISSON ((MJy/sr)^2)
      - SB_VAR_RNOISE ((MJy/sr)^2)
      - SB_VAR_FLAT ((MJy/sr)^2)
      - DQ  (DQ flags)
      - BACKGROUND (MJy/sr)
      - BKGD_ERROR (MJy/sr)
      - BKGD_VAR_POISSON ((MJy/sr)^2)
      - BKGD_VAR_RNOISE ((MJy/sr)^2)
      - BKGD_VAR_FLAT ((MJy/sr)^2)
      - NPIXELS  - number of pixels included in source extraction region
  2. ASDF  - metadata for the JWST data model