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	MinBitDepth	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	Table has columns: time; code release; branch name; commit hash; function; args; status.
3	DRP_CONFIG	BinTableHDU		False	True	Pipeline details (settings etc) to go from native data to L2	Table has one column where each row captures a config entry
4	EXT_DESCRIPT	BinTableHDU		False	True	Table describing contents of each extension	Table has two columns and each one row contains the name of an extension in the HDU and then a string description of what is in that extension
5	ORDER_TABLE	BinTableHDU		False	True	Table capturing the wavelength extent of each order in Trace 1	Required columns: physical echelle order, index echelle order, start wavelength, end wavelength.
6	TRACE1_FLUX	ImageHDU		True	True	Flux in trace 1	Shape is NxM where N is number of orders (NUMORDER keyword in PRIMARY header) and M is the number of pixels in the dispersion direction.
7	TRACE1_WAVE	ImageHDU	64	True	True	Wavelength solution for trace 1	Shape matches TRACE1_FLUX. Wavelengths should be in vaccuum. Set any undefined wavelength values - e.g. orders that are not currently extracted - to be NaN.
8	TRACE1_VAR	ImageHDU		True	True	Variance for trace 1	Shape matches TRACE1_FLUX
9	TRACE1_BLAZE	ImageHDU		True	True	Blaze for trace 1	Shape matches TRACE1_FLUX. Use the BLZNORM keyword in the TRACE1_BLAZE extension header to identify whether or not the blaze has been normalized.
10	BARYCORR_KMS	ImageHDU		False	True	barycentric correction in km/s	Shape 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 is a different correction for each order; or can be array of Nord x Mpix in which case there is a different correction for each pixel
11	BARYCORR_Z	ImageHDU		False	True	barycentric correction in redshift	Shape approach matches BARRYCORR_KMS
12	BJD_TDB	ImageHDU	64	False	True	Photon weighted midpoint	Shape approach matches BARRYCORR_KMS
13	TRACE1_DRIFT	ImageHDU		False	False	Drift measurement map in delta lambda	Shape approach matches BARRYCORR_KMS
14	TRACE1_QUALITY	ImageHDU	8	True	False	Quality of each pixel in trace 1	Shape matches 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 number 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	Shape matches TRACE1_FLUX. Generally used for Science Object traces
18	TRACE1_SKYMODEL	ImageHDU		True	False	Sky model for trace 1	Shape matches TRACE1_FLUX. Generally used for Science Object traces
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 custom corrected flux for trace 1	Could include additional corrections such as telluric or sky corrections. Shape matches TRACE1_FLUX.
22	CUSTOM1_TRACE1_WAVE	ImageHDU	64	True	False	Wavelength solution corresponding to STITCHED_CUSTOMCORR1_SCI_FLUX	Wavelength solution corresponding to CUSTOM1_TRACE1_FLUX. Shape matches TRACE1_FLUX. Wavelengths should be in vaccuum. Set any undefined wavelength values - e.g. orders that are not currently extracted - to be NaN.
23	CUSTOM1_TRACE1_VAR	ImageHDU		True	False	Variance corresponding to CUSTOM1_TRACE1_FLUX	Variance of the CUSTOM1_TRACE1_FLUX flux array. Shape matches TRACE1_FLUX.

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. Append BLZCORR; LMPCORR; SEDCORR; INTERPMD; FLXNRMMD; and DISPCORR 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	Table has columns: time; code release; branch name; commit hash; function; args; status.
3	DRP_CONFIG	BinTableHDU		False	True	Pipeline details (settings etc) to go from native data to L2	Table has one column where each row captures a config entry.
4	EXT_DESCRIPT	BinTableHDU		False	True	Table describing contents of each extension	Table has two columns and each one row contains the name of an extension in the HDU and then a string description of what is in that extension
5	ORDER_TABLE	BinTableHDU		False	True	Table capturing the wavelength extent of each order in Trace 1	Required columns: physical echelle order; index echelle order; start wavelength; end wavelength.
6	STITCHED_CORR_SCI_FLUX	ImageHDU		True	True	Order stitched and blaze-corrected flux co-added across all science traces	Shape should be a 1D array. If instrument only produces 1 science trace then this is the flux extension that gets populated.
7	STITCHED_CORR_SCI_WAVE	ImageHDU	64	True	True	Order stitched barycentric- and drift-corrected wavelength solution	Shape matches STITCHED_CORR_SCI_FLUX. If instrument only produces 1 science trace then this is the wavelength extension that gets populated.
8	STITCHED_CORR_SCI_VAR	ImageHDU		True	True	Order stitched variance for STITCHED_CORR_SCI_FLUX	Shape matches STITCHED_CORR_SCI_FLUX. If instrument only produces 1 science trace then this is the variance extension that gets populated.
9	STITCHED_CORR_TRACE1_FLUX	ImageHDU		True	False	Order stitched and blaze-corrected flux in trace 1	Shape should be a 1D array. If instrument only produces 1 science trace then leave empty and only populate the STITCHED_CORR_SCI_FLUX extension.
10	STITCHED_CORR_TRACE1_WAVE	ImageHDU	64	True	False	Order stitched barycentric- and drift-corrected wavelength solution corresponding to STITCHED_CORR_TRACE1_FLUX	Shape matches STITCHED_CORR_TRACE1_FLUX. Wavelengths should be in vaccuum. If instrument only produces 1 science trace then leave empty and only populate the STITCHED_CORR_SCI_WAVE extension.
11	STITCHED_CORR_TRACE1_VAR	ImageHDU		True	False	Order stitched variance corresponding to STITCHED_CORR_TRACE1_FLUX	Shape matches STITCHED_CORR_TRACE1_FLUX. If instrument only produces 1 science trace then leave empty and only populate the STITCHED_CORR_SCI_VAR extension.
12	STITCHED_CUSTOMCORR1_SCI_FLUX	ImageHDU		True	False	Additionally custom corrected flux	This could include additional corrections such as telluric or sky corrections. Shape matches STITCHED_CORR_SCI_FLUX.
13	STITCHED_CUSTOMCORR1_SCI_WAVE	ImageHDU	64	True	False	Wavelength solution corresponding to STITCHED_CUSTOMCORR1_SCI_FLUX	Wavelength solution corresponding to the flux array in STITCHED_CUSTOMCORR1_SCI_FLUX. Wavelengths should be in vaccuum. Shape matches STITCHED_CORR_SCI_FLUX.
14	STITCHED_CUSTOMCORR1_SCI_VAR	ImageHDU		True	False	Variance corresponding to STITCHED_CUSTOMCORR1_SCI_FLUX	Variance of the STITCHED_CUSTOMCORR1_SCI_FLUX array. Shape matches STITCHED_CORR_SCI_FLUX.
15	STITCHED_CUSTOMCORR1_TRACE1_FLUX	ImageHDU		True	False	Additionally custom corrected flux for trace 1	This could include additional corrections such as telluric or sky corrections. Shape matches STITCHED_CORR_TRACE1_FLUX.
16	STITCHED_CUSTOMCORR1_TRACE1_WAVE	ImageHDU	64	True	False	Wavelength solution corresponding to STITCHED_CUSTOMCORR1_TRACE1_FLUX	Wavelength solution corresponding to the flux array in STITCHED_CUSTOMCORR1_TRACE1_FLUX. Wavelengths should be in vaccuum. Shape matches STITCHED_CORR_TRACE1_FLUX.
17	STITCHED_CUSTOMCORR1_TRACE1_VAR	ImageHDU		True	False	Variance corresponding to STITCHED_CUSTOMCORR1_TRACE1_FLUX	Variance of STITCHED_CUSTOMCORR1_TRACE1_FLUX array. Shape matches STITCHED_CORR_TRACE1_FLUX.

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 RV1 extension is a Binary Table that contains the following columns: BJD_TDB, RV, RV_ERR, BERV, WAVE_START, WAVE_END. Optional, additional columns include: PIXEL_START, PIXEL_END, ORDER_INDEX, ECHELLE_ORDER, WEIGHT, RESIDUAL_DRIFT. The WAVE_START and WAVE_END values can be set to same number if reporting central wavelength of the segment.

The header for the RV1 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 BJDTDB; RV; RVERR; BERV; RVMETHOD; and SYSVEL 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	Table has columns: time; code release; branch name; commit hash; function; args; status.
3	DRP_CONFIG	BinTableHDU	False	True	Pipeline details (settings etc) to go from native data to L2	Table has one column where each row captures a config entry.
4	EXT_DESCRIPT	BinTableHDU	False	True	Table describing contents of each extension	Table has two columns and each one row contains the name of an extension in the HDU and then a string description of what is in that extension.
5	RV1	BinTableHDU	True	True	Derived Radial Velocity Measurement	Required Columns: BJD_TDB (64bit); RV from Trace1…N; RV_Error; BC_Velocity; Wave_Start (64bit); Wave_End (64bit). Optional columns [teams can add more if they like]: pixel_start; pixel_end; order_index; echelle_order; weight; residual_drift.
6	CCF1	ImageHDU	True	False	CCFs from which RV1…N were derived	Same shape as RV1…N. Contains the CCF(s) that produced each RV1…N value.
7	DIAGNOSTICS1	BinTableHDU	True	False	Activity indicators; CCF metrics; etc	Table containing useful diagnostic measurements. Does not have same dimensions as RV1/CCF1. Suggested structure is to have columns for : BJD_TDB; metric_name; value; and error.
8	CUSTOM_CCF1	ImageHDU	True	False	Additional CCFs from (e.g.) different masks	Additional CCF extensions; used to capture results from different masks or different CCF calculation methods.
9	CUSTOM_RV1	BinTableHDU	True	False	Derived Radial Velocity Measurement from CUSTOM_CCF1…N	Additional RV extensions; used to capture RV values corresponding to CUSTOM_CCF1…N