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 jointly fits a user-defined object model and atmospheric absorption model to the spectrum.

The default telluric model is derived from a large pre-computed grid of simulated atmospheric transmission spectra computed using the LBLRTM code (v12.17), including HITRAN 2016 molecular line parameters delivered by the AER Line File v3.8.1, via a modified version of the TelFit python interface. The models were computed for the locations of six different observatories, covering a wide range of altitudes, and sampling from realistic ranges of airmass, ground-level humidity/pressure/temperature, and perturbations of the abundances of several molecular species. This model grid was then decomposed into basis vectors using Principal Component Analysis (PCA) applied to the arcsinh of the absorption optical depth. By default, the first 5 basis vectors are used in the fitting, but any number from 1 up to 10 can be specified (see below).

The spectrum is jointly fitted to the object model multiplied by a model for the atmospheric absorption, which consists of the telluric model described above convolved by instrument resolution and shifted/stretched along the spectral direction to account for uncertainties in the wavelength calibration (as well as correct for the heliocentric velocity offset).

Model Telluric Spectra

PCA spectra

The available PCA files (recommended) are:

File	Size	Last Modified (UTC)
TellPCA_3000_10500_R120000.fits	36.0 MiB	2023-12-13 13:47:02
TellPCA_3000_26000_R10000.fits	6.0 MiB	2023-12-13 13:47:40
TellPCA_3000_26000_R15000.fits	8.5 MiB	2023-12-13 13:47:54
TellPCA_3000_26000_R25000.fits	13.5 MiB	2023-12-13 13:48:07
TellPCA_9300_55100_R60000.fits	25.1 MiB	2023-12-13 13:48:19

The file names are TellPCA_{lambda start}_{lambda end}_R{resolution}.fits; e.g., TellPCA_3000_10500_R120000.fits has a spectral range from 3,000–10,500 angstroms with a spectral resolution of \(\lambda/\Delta\lambda\) = 120,000.

To use these spectra, the minimum parameters are, e.g.:

[telluric]
    tellgridfile = TellPCA_3000_10500_R120000.fits
    teltype = pca

Note that most spectrographs set defaults for these, meaning you don’t necessarily need to include them in your pypeit file; i.e., they only need to be included if you want to change the defaults.

Atmospheric parameter grids

The available atmospheric grid files are:

File	Size	Last Modified (UTC)
TelFit_LasCampanas_3100_26100_R20000.fits	7.7 GiB	2022-04-09 12:58:52
TelFit_Lick_3100_11100_R10000.fits	5.4 GiB	2022-04-18 22:50:22
TelFit_MaunaKea_3100_26100_R20000.fits	7.7 GiB	2022-04-09 12:58:12
TelFit_Paranal_NIR_9800_25000_R25000.fits	4.4 GiB	2022-04-18 23:06:59
TelFit_Paranal_VIS_4900_11100_R25000.fits	3.5 GiB	2022-04-18 23:13:38

The file names are TelFit_{site}_{lambda start}_{lambda_end}_R{resolution}.fits; e.g., TelFit_MaunaKea_3100_26100_R20000.fits samples atmospheric parameters appropriate for Maunakea, has a spectral range from 3,100–26,100 angstroms, and a spectral resolution of \(\lambda/\Delta\lambda\) = 20,000.

To use these spectra, the minimum parameters are, e.g.:

[telluric]
    tellgridfile = TelFit_MaunaKea_3100_26100_R20000.fits
    teltype = grid

Note the atmospheric grid files are very large (multiple GiB). Because of this and other general improvements to the associated modeling procedures, we do not recommend you use these atmospheric grids, and use the PCA-based models instead. These files, and the associated modeling code, are primarily made available to allow users to compare to previous results.

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
[telluric]
    objmodel = qso
    redshift = 7.0
    bal_wv_min_max = 10825,12060

or

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

or

# User-defined tellfit parameters for other type target
[telluric]
    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] [-v VERBOSITY] [--log_file LOG_FILE]
                      [--log_level LOG_LEVEL] [--objmodel {qso,star,poly}]
                      [-r REDSHIFT] [-g TELL_GRID] [-p PCA_FILE] [-t TELL_FILE]
                      [--debug] [--plot] [--par_outfile PAR_OUTFILE]
                      [--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
  -v, --verbosity VERBOSITY
                        Verbosity level, which must be 0, 1, or 2. Level 0
                        includes warning and error messages, level 1 adds
                        informational messages, and level 2 adds debugging
                        messages and the calling sequence.
  --log_file LOG_FILE   Name for the log file. If set to "default", a default
                        name is used. If None, a log file is not produced.
  --log_level LOG_LEVEL
                        Verbosity level for the log file. If a log file is
                        produce and this is None, the file log will match the
                        console stream log.
  --objmodel {qso,star,poly}
                        The object model to be used for telluric fitting.
                        Currently the options are: ``qso``, ``star``, and
                        ``poly``. For ``qso``, you might need to set
                        ``redshift`` and ``bal_wv_min_max``. For ``star``, you
                        must set ``star_type``, ``star_ra``, ``star_dec``, and
                        ``star_mag``. For ``poly``, you might need to set
                        ``fit_wv_min_max`` and ``norder``.
  -r, --redshift REDSHIFT
                        The redshift for the object model. This is currently
                        only used by the QSO model.
  -g, --tell_grid TELL_GRID
                        File with the telluric model spectra to use. Generally,
                        these do not need to be set; reasonable defaults are
                        provided for each spectrograph. Due to their size, the
                        files are not included with the released pypeit package;
                        instead the code downloads each file into your cache as
                        needed. If this parameter is set in your pypeit file, it
                        can be the path to a local file (which must have the
                        correct format), or it can be the name of the specific
                        cache file to use (e.g.,
                        TellPCA_3000_26000_R10000.fits).
  -p, --pca_file PCA_FILE
                        qso_pca_1200_3100.fits
  -t, --tell_file TELL_FILE
                        Configuration file to change default telluric
                        parameters.  The format is identical to any telluric
                        parameters in your pypeit file.  See the PypeIt
                        parameter documentation.  For example, the ".tell" file
                        could have the following:

                            [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
  --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 model file. In case of spectrographs which have defined a default model, you do not need to set this argument. You may, however, select a different model 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

teltype

There are two options to model the atmospheric absorption, pca (default) and grid (legacy). Both options are based on atmospheric radiative transfer models as described above. See also Atmospheric Models.

The pca option uses the PCA decomposition of a massive grid of atmospheric models run for many different observatories, and should thus work for just about any observatory.

The grid option corresponds to the default method used in earlier versions of PypeIt, and uses grids of pre-computed observatory-specific atmospheric models.

telgridfile

There are different TellPCA files available corresponding to different (maximum) spectral resolutions and wavelength ranges. All spectrographs which default to the IR telluric method have the suitable file as the default value of telgridfile. It is important to remember that, if the user wants to use grids of pre-computed observatory-specific atmospheric models (TelFit files), teltype parameter must be changed accordingly.

tell_npca

The default number of PCA vectors used is 5, but tell_npca can be increased up to 10 in case more flexibility is required in the telluric model. Has no effect if teltype = grid is specified.

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 pypeit_show_1dspec.

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