Overview of EPRV FITS Standard Extensions

General information

1. The PRIMARY extension in any L2, L3, or L4 file generated as part of the EPRV Data Standard should contain the EPRV Data Standard FITS Header (Add link).

2. The Multiplicity keyword indicates whether or not an extension can be duplicated to have multiple HDUs based on, e.g., the number of traces.

3. The Required keyword indicates whether or not an extension must be present and meaningfully populated in the FITS file in order for the file to be compliant with the EPRV Data Standard.

Level 2 FITS Extensions

A Level 2 data file will contain the order-by-order flux, wavelength, variance, and blaze which will be split into individual extensions. If the spectrograph produces multiple traces (e.g. a calibration trace, a sky trace, and one or more science traces) then the data will also be split into one flux extension per trace, one wavelength extension per trace, etc.

At Level 2 the only correction that has already been applied to the required wavelength solution (TRACE1_WAVE) is a drift correction. The information necessary to execute common EPRV corrections to the required wavelength and flux extensions (e.g. blaze corrections and barycentric corrections) is provided in separate extensions.

Optional extensions within the Level 2 format allow for users to apply additional, custom corrections to either the flux or wavelength solution (see the CUSTOM1_TRACE1 extensions below).

This data product is intended primarily for users who are interested in the improving EPRV data reduction and post processing techinques.

HDU	Name	DataType	MinBetDepth	Multiplicity	Required	Description	Comments
0	PRIMARY	PrimaryHDU		False	True	EPRV Standard FITS HEADER (no data)
1	INSTRUMENT_HEADER	ImageHDU		False	True	Inherited instrument header (no data)	If this L2 file was translated from an instrument’s native data product then this header contains the original data header
2	RECEIPT	BinTableHDU		False	True	Table of operations that have been performed on this file
3	DRP_CONFIG	BinTableHDU		False	True	Pipeline details (settings etc) to go from native data to L2
4	EXT_DESCRIPT	BinTableHDU		False	True	Table describing contents of each extension
5	ORDER_TABLE	BinTableHDU		TRUE	TRUE	Table capturing the wavelength extent of each order	Required columns: physical echelle order; index echelle order; start wavelength [64bit]; end wavelength [64bit]
6	TRACE1_FLUX	ImageHDU		True	True	Flux in trace 1
7	TRACE1_WAVE	ImageHDU	64	True	True	wavelength solution for trace 1
8	TRACE1_VAR	ImageHDU		True	True	variance for trace 1
9	TRACE1_BLAZE	ImageHDU		True	True	blaze for trace 1
10	BARYCORR_KMS	ImageHDU		False	True	barycentric correction in km/s	Format should convey how this is applied to the wavelength solution – can be a single value in which case 1 correction for whole array; can be an array of Norders in which case there’s a different correction for each order; or can be array of Nord x Mpix in which case there’s a different correction for each pixel
11	BARYCORR_Z	ImageHDU		False	True	barycentric correction in redshift	Format should convey how this is applied to the wavelength solution – can be a single value in which case 1 correction for whole array; can be an array of Norders in which case there’s a different correction for each order; or can be array of Nord x Mpix in which case there’s a different correction for each pixel
12	BJD_TDB	ImageHDU	64	False	True	Photon weighted midpoint	Format should convey how this is applied to the wavelength solution – can be a single value in which case 1 correction for whole array; can be an array of Norders in which case there’s a different correction for each order; or can be array of Nord x Mpix in which case there’s a different correction for each pixel
13	TRACE1_DRIFT	ImageHDU		False	False	Drift measurement map in delta lambda	Format should convey how this is applied to the wavelength solution – can be a single value in which case 1 correction for whole array; can be an array of Norders in which case there’s a different correction for each order; or can be array of Nord x Mpix in which case there’s a different correction for each pixel
14	TRACE1_QUALITY	ImageHDU	UINT8	True	False	Quality of each pixel in trace 1	Format should match TRACE1_FLUX – recommend convention that 0 is the no flag value
15	EXPMETER	BinTableHDU		False	False	Table of exposure meter counts timeseries over the exposure	Table has # of columns equal to the number of wavelengths where the exposure counts are measured and number of rows equal to exposure time / exp meter cadence
16	TELEMETRY	BinTableHDU		False	False	Table of telemetry collected during the exposure	Table has 4 columns: time stamp; sensor name; value; units
17	TRACE1_TELLURIC	ImageHDU		True	False	Telluric model for trace 1	Follows same format as TRACE1_FLUX HDU; generally used for Science Object traces
18	TRACE1_SKYMODEL	ImageHDU		True	False	Sky model for trace 1	Follows same format as TRACE1_FLUX HDU
19	ANCILLARY_SPECTRUM	ImageHDU		True	False	Extension(s) that store ancillary spectra	Options include Ca II H&K if separate spectrograph used
20	IMAGE	ImageHDU		True	False	Extension(s) that store useful support images	Options include guider cam or sky monitoring or pupil image
21	CUSTOM1_TRACE1_FLUX	ImageHDU		True	False	Additionally corrected flux in trace 1	Modified flux extension that includes additional corrections such as telluric or sky corrections – should have same format as TRACE1_FLUX above
22	CUSTOM1_TRACE1_WAVE	ImageHDU		True	False	Additionally corrected wavelength solution for trace 1	Wavelength solution corresponding to USTOM1_TRACE1_FLUX – should have same format as TRACE1_WAVE above
23	CUSTOM1_TRACE1_VAR	ImageHDU		True	False	Additionally corrected variance for the flux in trace 1	Variance of the CUSTOM1_TRACE1_FLUX extension – should have same format as TRACE1_VAR above

Level 3 FITS Extensions

A Level 3 file will contain 1-D spectra that stitch together all extracted orders. The flux array will have been blaze corrected and the wavelength solution will have been both drift and barycentric corrected. The variance array will be calculated using the blaze-corrected flux.

This stitched flux extension and its corresponding wavelength and variance extensions will exist for each of the individual traces (STITCHED_CORR_TRACE1_FLUX, STITCHED_CORR_TRACE1_WAVE, and STITCHED_CORR_TRACE1_VAR). An additional set of extensions will contain the co-added flux from all science fibers, the corresponding variance based upon that co-added flux, and the appropriate wavelength solution (COADD_STITCHED_CORR_FLUX, COADD_STITCHED_CORR_WAVE, and COADD_STITCHED_CORR_VAR).

If your instrument pipeline does not already produce co-added spectra, they can be computed following Bourrier, Delisle et al., 2024. which makes use of the Bindensity package available at https://gitlab.unige.ch/jean-baptiste.delisle/bindensity. But documentation within each instrument’s page on this ReadtheDocs should note exactly what co-adding process is used to combine the individual flux extensions.

Optional extensions within the Level 3 format allow for users to apply additional, custom corrections to either the flux or wavelength arrays (see the CUSTOMCORR extensions below).

Level 3 inherits the PRIMARY extension from Level 2, along with the INSTRUMENT_HEADER, RECEIPT, and DRP_CONFIG extensions.

This data product is intended primarily for users who are interested in other types of science that can be accomplished with high resolution visible / NIR spectra. Potential examples include science related to exoplanet atmospheres or stellar astrophysics.

HDU	Name	DataType	MinBitDepth	Multiplicity	Required	Description	Comments
0	PRIMARY	PrimaryHDU		False	True	EPRV Standard FITS HEADER (no data)	Carried forward from L2 FITS file
1	INSTRUMENT_HEADER	ImageHDU		False	True	Inherited instrument header (no data)	Carried forward from L2 FITS file
2	RECEIPT	BinTableHDU		False	True	Table of operations that have been performed on this file
3	DRP_CONFIG	BinTableHDU		False	True	Pipeline details (settings etc) to go from native data to L2
4	ORDER_TABLE	BinTableHDU		False	True	Table capturing the wavelength extent of each order	Required columns: physical echelle order; index echelle order; start wavelength [64bit]; end wavelength [64bit]
5	STITCHED_CORR_TRACE1_FLUX	ImageHDU		True	True	Order stitched blaze-corrected flux in trace 1	This flux array stitches together all orders and has been blaze corrected
6	STITCHED_CORR_TRACE1_WAVE	ImageHDU	64	True	True	Order stitched BC- and drift-corrected wavelength solution for trace 1	This wavelength solution stitches together all orders adn has been both drift and barycentric corrected
7	STITCHED_CORR_TRACE1_VAR	ImageHDU		True	True	Order stitched variance for the flux in STITCHED_CORR_TRACE1_FLUX	This variance array stitches together all orders and is based on the blaze corrected flux (STITCHED_CORR_TRACE1_FLUX)
8	COMBINED_STITCHED_CORR_FLUX	ImageHDU		False	False	Order stitched and blaze-corrected flux co-added across all traces	This flux array stitches together all orders and co-adds all traces and has been blaze corrected
9	COMBINED_STITCHED_CORR_WAVE	ImageHDU	64	False	False	Order stitched BC- and drift-corrected wavelength solution	This wavelength solution stitches together all orders and has been both drift and barycentric corrected
10	COMBINED_STITCHED_CORR_VAR	ImageHDU		False	False	Order stitched variance for the combined flux in COMBINED_STITCHED_CORR_FLUX	This variance array stitches together all orders and is based on the co-added and blaze corrected flux (STITCHED_COMBINED_CORR_FLUX)
11	STITCHED_CUSTOMCORR1_TRACE1_FLUX	ImageHDU		True	False	Additional corrections made to STITCHED_CORR_TRACE1_FLUX	This could include additional corrections such as telluric or sky corrections
12	STITCHED_CUSTOMCORR1_TRACE1_WAVE	ImageHDU		True	False	Wavelength solution corresponding to STITCHED_CUSTOMCORR1_TRACE1_FLUX	Wavelength solution corresponding to the flux array in STITCHED_CUSTOMCORR1_TRACE1_FLUX
13	STITCHED_CUSTOMCORR1_TRACE1_VAR	ImageHDU		True	False	Variance corresponding to STITCHED_CUSTOMCORR1_TRACE1_FLUX	Variance of the CUSTOMCORR1_TRACE1_FLUX flux array
14	COMBINED_STITCHED_CUSTOMCORR1_FLUX	ImageHDU		True	False	Additional corrections made to COMBINED_STITCHED_CORR_FLUX	This could include additional corrections such as telluric or sky corrections
15	COMBINED_STITCHED_CUSTOMCORR1_WAVE	ImageHDU		True	False	Wavelength solution corresponding to COMBINED_STITCHED_CORR_WAVE	Wavelength solution corresponding to the flux array in COMBINED_STITCHED_CUSTOMCORR1_FLUX
16	COMBINED_STITCHED_CUSTOMCORR1_VAR	ImageHDU		True	False	Variance corresponding to COMBINED_STITCHED_CORR_VAR	Variance of the COMBINED_STITCHED_CUSTOMCORR1_FLUX flux array
17	EXT_DESCRIPT	BinTableHDU		False	True	Table describing contents of each extension

Level 4 FITS Extensions

A Level 4 file will contain derived data products such as RV measurements, cross correlation functions (CCFs), CCF metrics (e.g., FWHM, BIS), and stellar activity indicators. Only the RV measurements are required, to support non-CCF RV reduction methods.

L4 data products are expected to be derived from an L2 file, and inherit the PRIMARY, INSTRUMENT_HEADER, RECEIPT, and DRP_CONFIG extensions from that L2.

The RV extension is a Binary Table that contains the following columns: BJD_TDB, wave_start, wave_end, pixel_start, pixel_end, RV_Trace, RV_error, BC_vel, order index, echelle order Optional, additional columns include: RV_weight The wave_start and wave_end values can be set to same number if reporting central wavelength of the segment.

The header for this extension should contain RVMETHOD, RVSTART, RVSTEP, MASK keywords.

HDU	Name	DataType	Multiplicity	Required	Description	Comments
0	PRIMARY	PrimaryHDU	FALSE	TRUE	EPRV Standard FITS HEADER (no data)	Carried forward from L2 FITS file. Append RVMETHOD, BJD_TDB, RV, RVERROR header keywords
1	INSTRUMENT_HEADER	ImageHDU	FALSE	TRUE	Inherited instrument header (no data)	Carried forward from L2 FITS file
2	RECEIPT	BinTableHDU	FALSE	TRUE	Table of operations that have been performed on this file
3	DRP_CONFIG	BinTableHDU	FALSE	TRUE	Pipeline details (settings etc) to go from native data to L2
4	RV1	BinTableHDU	TRUE	TRUE	Derived Radial Velocity Measurement	Required Columns: BJD_TDB [64bit], wave_start [64bit], wave_end [64bit], pixel_start, pixel_end, RV_Trace1-N, RV_error, BC_vel, order index, echelle order Optional columns [teams can add more if they like]: pixel_start, pixel_end, order_index, echelle_order, weight, residual_drift note: weight is a roll up of multiple weighting factors (throughput, color correction, etc) applied to the RV in the same row of this table and should be defined by the instrument team in the their read the docs page
5	CCF1	ImageHDU	TRUE	FALSE	Array with same dimensionality of RV1…N, that contains the CCF that produced each RV1…N
6	DIAGNOSTICS1	BinTableHDU	TRUE	FALSE	Activity indicators, CCF metrics, etc	Does not have same dimensions as RV1/CCF1
7	CUSTOM_CCF1	ImageHDU	TRUE	FALSE	Additional CCFs from (e.g.) different masks	Additional CCF extensions could show results for different masks or different CCF calculation
8	CUSTOM_RV1	BinTableHDU	TRUE	FALSE	Derived Radial Velocity Measurement from CUSTOM_CCF1…N
9	EXT_DESCRIPT	BinTableHDU	False	True	Table describing contents of each extension