Telluric correction

Overview

Telluric correction is done after the main run of PypeIt, Fluxing and Coadd 1D Spectra. The algorithm for deriving the best telluric model is pretty similar with that used in the IR sensitivity function, which fits a user-defined model and telluric to a giant telluric grid. Please see Fluxing for more details.

Note that execution of pypeit_tellfit requires the atmospheric model grids to be installed on your system. See the instructions for installing these Additional Data and the PypeIt Cache.

pypeit_tellfit

The primary script is called pypeit_tellfit, which takes an input file or arguments to guide the process. There are three different object models for the fitting:

object models

The object model options are:

qso: quasar or AGN.

star: stellar object

poly: can be used for any other object by solving polynomial model.

Examples for the configuration files for each of these object models are as follows:

# User-defined tellfit parameters for a quasar at redshift seven
[tellfit]
    objmodel = qso
    redshift = 7.0
    bal_wv_min_max = 10825,12060

or

# User-defined tellfit parameters for a A0 type star
[tellfit]
    objmodel = star
    star_type = A0
    star_mag = 8.0

or

# User-defined tellfit parameters for other type target
[tellfit]
    objmodel = poly
    polyorder = 3
    fit_wv_min_max = 17000, 22000

See Parameters for details.

run

The script usage can be displayed by calling the script with the -h option:

$ pypeit_tellfit -h
usage: pypeit_tellfit [-h] [--objmodel {qso,star,poly}] [-r REDSHIFT]
                      [-g TELL_GRID] [-p PCA_FILE] [-t TELL_FILE] [--debug]
                      [--plot] [--par_outfile PAR_OUTFILE] [-v VERBOSITY]
                      [--chk_version]
                      spec1dfile

Telluric correct a spectrum

positional arguments:
  spec1dfile            spec1d or coadd file that will be used for telluric
                        correction.

options:
  -h, --help            show this help message and exit
  --objmodel {qso,star,poly}
                        science object model used in the fitting. The options
                        are:

                        qso = For quasars. You might need to set redshift,
                        bal_wv_min_max in the tell file.

                        star = For stars. You need to set star_type, star_ra,
                        star_dec, and star_mag in the tell_file.

                        poly = For other type object, You might need to set
                        fit_wv_min_max, and norder in the tell_file.

  -r REDSHIFT, --redshift REDSHIFT
                        Specify redshift. Used with the --objmodel qso option
                        above.
  -g TELL_GRID, --tell_grid TELL_GRID
                        Telluric grid. You should download the giant grid file
                        to the pypeit/data/telluric folder. It should only be
                        passed if you want to overwrite the default tell_grid
                        that is set via each spectrograph file.
  -p PCA_FILE, --pca_file PCA_FILE
                        Quasar PCA fits file with full path. The default file
                        (qso_pca_1200_3100.fits) is stored in the
                        pypeit/data/telluric folder. If you change the fits
                        file, make sure to set the pca_lower and pca_upper in
                        the tell_file to specify the wavelength coverage of your
                        model. The defaults are pca_lower=1220. and
                        pca_upper=3100.
  -t TELL_FILE, --tell_file TELL_FILE
                        Configuration file to change default telluric
                        parameters.  Note that the parameters in this file will
                        be overwritten if you set argument in your terminal.
                        The --tell_file option requires a .tell file with the
                        following format:

                            [telluric]
                                 objmodel = qso
                                 redshift = 7.6
                                 bal_wv_min_max = 10825,12060
                        OR
                            [telluric]
                                 objmodel = star
                                 star_type = A0
                                 star_mag = 8.
                        OR
                            [telluric]
                                 objmodel = poly
                                 polyorder = 3
                                 fit_wv_min_max = 9000.,9500.

  --debug               show debug plots?
  --plot                Show the telluric corrected spectrum
  --par_outfile PAR_OUTFILE
                        Name of output file to save the parameters used by the
                        fit
  -v VERBOSITY, --verbosity VERBOSITY
                        Verbosity level between 0 [none] and 2 [all]. Default:
                        1. Level 2 writes a log with filename tellfit_YYYYMMDD-
                        HHMM.log
  --chk_version         Ensure the datamodels are from the current PypeIt
                        version. By default (consistent with previous
                        functionality) this is not enforced and crashes may
                        ensue ...

Example script executions would be:

pypeit_tellfit J1342_GNIRS.fits -t gemini_gnirs.tell

or

pypeit_tellfit J1342_GNIRS.fits --objmodel qso -r 7.52

A substantial set of output are printed to the screen, and, if successful, the final spectrum is written to disk. Both input and output file are in the standard coadd1d data model format. See Coadd 1D Spectra for the current data model.

The parameters that guide the tellfit process are also written to disk for your records. The default location is telluric.par. You can choose another location with the –par_outfile option.

Command Line Options

–objmodel

Your object model, either qso, star or poly.

–tell_grid, -g

The filename of the telluric grid file. In case of spectrograph which has defined the default grid, you do not need to set this argument. You may, however, select a different grid than the instrument default using this argument.

–pca_file, -p

The full path for the qso pca pickle file. Only used in the qso model. The default is qso_pca_1200_3100.pckl which should be downloaded and put in the pypeit telluric data folder.

–tell_file, -t

The tellfit parameter file.

–redshift, -r

Redshift of your object.

–debug

show debug plots if set.

–plot

show the final telluric corrected spectrum if set.

–par_outfile

File name for the tellfit parameters used in the fit.

Parameters

qso model

The two main parameters for a qso model are redshift and bal_wv_min_max.

redshift

The redshift of your science object you want to correct telluric absorption

bal_wv_min_max

You can set a bal_wv_min_max if your quasar/AGN is a broad absorption line quasar. It is a list with even float numbers in the format of (in case of two absorption troughs): bal1_wave_min, bal1_wave_max, bal2_wave_min, bal2_wave_max.

star model

The main parameters for a star model are star_type and star_mag.

star_type

The spectra type of your star. If A0, it will use VEGA spectrum, otherwise will use a Kurucz SED model.

star_mag

V-band magnitude of your star.

poly model

The main parameters for a poly model are poly_order and fit_wv_min_max.

poly_order

The polynomial order you want to use for modeling your object

fit_wv_min_max

You can specify a list of specific regions used for the fitting, if not set it will simply use the whole spectrum. The format for this parameter is exactly same with the bal_wv_min_max defined above.

Telluric Output files

pypeit_tellfit produces two main output files, the telluric corrected spectrum and the best-fitting telluric model.

The telluric corrected spectrum has the same name as your input file, but with .fits replaced by _tellcorr.fits. It’s data model follows the general class OneSpec, such that its file extensions are:

Version: 1.0.2

Obj Key	Obj Type	Array Type	Description
`PYP_SPEC`	str		`PypeIt` spectrograph designation
`ext_mode`	str		Extraction mode (options: BOX, OPT)
`flux`	ndarray	floating	Flux array in units of counts/s or 10^-17 erg/s/cm^2/Ang; see `fluxed`
`fluxed`	bool		Boolean indicating if the spectrum is fluxed.
`ivar`	ndarray	floating	Inverse variance array (matches units of flux)
`mask`	ndarray	integer	Mask array (1=Good,0=Bad)
`obj_model`	ndarray	floating	Object model for tellurics
`sigma`	ndarray	floating	One sigma noise array, equivalent to 1/sqrt(ivar) (matches units of flux)
`spect_meta`	dict		header dict
`telluric`	ndarray	floating	Telluric model
`wave`	ndarray	floating	Wavelength array (angstroms in vacuum), weighted by pixel contributions
`wave_grid_mid`	ndarray	floating	Wavelength (angstroms in vacuum) evaluated at the bin centers of a grid that is uniformly spaced in either lambda or log10-lambda/velocity

You view the spectrum using the lt_xspec script, which loads the data and launches a GUI from the linetools package. e.g.:

lt_xspec J1342_GNIRS_tellcorr.fits

The best-fitting telluric model is a two extension fits file, where the 2nd extension is identical to one of the extensions from the Sensitivity Output File:

Version 1.0.0

HDU Name	HDU Type	Data Type	Description
`PRIMARY`	astropy.io.fits.PrimaryHDU	…	Empty data HDU. Contains basic header information.
`TELLURIC`	astropy.io.fits.BinTableHDU	…	Results of the telluric modeling

TELLURIC table

Column	Data Type	Description
`WAVE`	float64	Wavelength vector
`TELLURIC`	float64	Best-fitting telluric model spectrum
`OBJ_MODEL`	float64	Best-fitting object model spectrum
`TELL_THETA`	float64	Best-fitting telluric model parameters
`TELL_PARAM`	float64	Best-fitting telluric atmospheric parameters or PCA coefficients
`TELL_RESLN`	float64	Best-fitting telluric model spectral resolution
`TELL_SHIFT`	float64	Best-fitting shift applied to the telluric model spectrum
`TELL_STRETCH`	float64	Best-fitting stretch applied to the telluric model spectrum
`OBJ_THETA`	float64	Best-fitting object model parameters
`CHI2`	float64	Chi-square of the best-fit model
`SUCCESS`	bool	Flag that fit was successful
`NITER`	int64	Number of fit iterations
`ECH_ORDERS`	int64	Echelle order for this specrum (echelle data only)
`POLYORDER_VEC`	int64	Polynomial order for each slit/echelle (if applicable)
`IND_LOWER`	int64	Lowest index of a spectral pixel included in the fit
`IND_UPPER`	int64	Highest index of a spectral pixel included in the fit
`WAVE_MIN`	float64	Minimum wavelength included in the fit
`WAVE_MAX`	float64	Maximum wavelength included in the fit