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.

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

HDU Name

HDU Type

Data Type

Description

PRIMARY

astropy.io.fits.PrimaryHDU

Empty data HDU. Contains basic header information.

Spectrum

astropy.io.fits.BinTableHDU

Single spectrum data; see OneSpec.

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