antaress.ANTARESS_corrections.ANTARESS_tellurics module

corr_tell_glob(tell_type, gen_dic, data_inst, inst, data_dic, data_prop, coord_dic, plot_dic, system_param)

Global telluric correction: wrap-up call.

Initializes and runs the selected telluric correction.

Parameters:

TBD

Returns:

TBD

corr_tell_autom(fixed_args, gen_dic, inst, data_inst)

Global telluric correction : automatic absorption initialization.

Initializes the automatic absorption correction.

Parameters:

TBD

Returns:

TBD

corr_tell_autom_vis(fixed_args, coord_dic, inst, vis, data_prop_vis, gen_dic, iord_list_ref, atlas_corr_ranges, data_dic, abstell_mol_dic)

Global telluric correction : automatic absorption initialization (visit).

Initializes the automatic absorption correction for a given visit.

Parameters:

TBD

Returns:

TBD

corr_tell_vis(iexp_group, airmass_group, IWV_zenith_group, temp_group, press_group, solbar2tell_specdopshift_group, star2solbar_specdopshift_group, proc_DI_data_paths, iexp_corr_list, inst, vis, tell_range_corr, iord_corr_list, calc_tell_mode, atlas_corr_ranges, dim_exp, proc_DI_data_paths_new, fixed_args, abstell_mol_dic, spectral_ref, resamp_mode, tell_CCF, tell_prop, flux_sp, mean_gcal_DI_data_paths, tell_depth_thresh, tell_width_thresh, tell_fit_sat, tell_fit_multiexp)

Global telluric correction : visit absorption correction.

Applies the chosen telluric absorption correction in a given visit.

Parameters:

TBD

Returns:

None

Run_ATC(airmass_exp, IWV_zenith_exp, temp_exp, press_exp, solbar2tell_specdopshift_exp, star2solbar_specdopshift_exp, edge_bins, cen_bins, flux_exp, cov_exp, cond_def_exp, mean_gcal_exp, inst, vis, abstell_mol_dic, spectral_ref, resamp_mode, dim_exp, iord_corr_exp, tell_CCF, tell_prop, flux_sp, fixed_args, tell_depth_thresh, tell_width_thresh, tell_fit_sat, cond_def_uncorr)

ATC function.

Adaptation of the Automatic Telluric Correction routine by R. Allart.

Parameters:

TBD

Returns:

TBD

corr_emtell_vis(iexp_group, star2solbar_specdopshift_group, proc_DI_data_paths, iexp_corr_list, inst, vis, tell_range_corr, iord_corr_list, calc_tell_mode, atlas_corr_ranges, dim_exp, proc_DI_data_paths_new, corr_tell, save_data_dir, proc_DI_data_paths_pretell)

Global telluric correction : visit emission correction.

Applies the chosen telluric emission correction in a given visit.

Parameters:

TBD

Returns:

None

corr_atlas(gen_dic, data_inst, inst, theo_dic, data_dic, coord_dic, system_param, data_prop)

Main spectral line correction routine.

Correct for telluric emission, and/or telluric absorption, and/or stellar lines in localized bands, using analytical models.

At this stage spectra have not been corrected for any broadband variations, and are still in spectral flux units. We normalize them temporarily by their exposure time, so that models can be computed as spectro-temporal flux density. For the purpose of the demonstration below, we thus consider F as being in flux density and we drop the dependency on visit v.

---

On fiber A we measure (see the corr_Fbal() function):

\[F_\mathrm{meas}^\mathrm{A}(\mathrm{\lambda \, in \, \lambda_\mathrm{band}},t) = c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) + F_\mathrm{meas,\oplus}(\lambda,t) ) \delta_\mathrm{meas,\oplus}(\lambda,t)\]

where we mask narrow planetary lines (hence the broadband dependence of \(\delta_\mathrm{p}\)), and assume a flat sky background.

We model fiber A spectrum as:

\[\begin{split}F_\mathrm{mod}^\mathrm{A}(\mathrm{\lambda \, in \, \lambda_\mathrm{band}},t) &= F_\mathrm{mod,raw}^\mathrm{A}(\mathrm{\lambda},t) sc_\mathrm{norm}^\mathrm{A}(t) \\ &= (F_\mathrm{mod,\star}(\lambda) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) + F_\mathrm{mod,\oplus}(\lambda,t)) \delta_\mathrm{mod,\oplus}(\lambda,t) sc_\mathrm{norm}^\mathrm{A}(t)\end{split}\]

where the stellar model is computed with continuum \(F_\mathrm{mod,\star}(\lambda_\mathrm{contA})\) of average unity modulated by a polynomial. The scaling factor is defined using the measured and raw model stellar continuum (ie, ranges free of stellar and telluric lines) as:

\[\begin{split}sc_\mathrm{norm}^\mathrm{A}(t) &= \frac{F_\mathrm{meas}^\mathrm{A}(\lambda_\mathrm{contA},t) }{ F_\mathrm{mod,raw}^\mathrm{A}(\lambda_\mathrm{contA},t) } \\ &= \frac{c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) }\end{split}\]

Outside telluric lines the scaled model thus has the same shape and level as the measured spectrum. If we can assume that \(F_\mathrm{sk} << F_\mathrm{\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band})\) then:

\[sc_\mathrm{norm}^\mathrm{A}(t) \sim c(\lambda_\mathrm{band},t) \frac{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }\]

Within telluric emission lines (assuming for the purpose of the demonstration that we are in the stellar continuum), the equivalence between the measured and model spectra requires:

\[\begin{split}& (F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) + F_\mathrm{mod,\oplus}(\lambda,t)) \frac{c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) } = c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) + F_\mathrm{meas,\oplus}(\lambda,t) ) \\ & ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) + F_\mathrm{mod,\oplus}(\lambda,t) \frac{c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) } = ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) + F_\mathrm{meas,\oplus}(\lambda,t) ) \\ & F_\mathrm{mod,\oplus}(\lambda,t) \frac{( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) } = F_\mathrm{meas,\oplus}(\lambda,t) \\ & F_\mathrm{mod,\oplus}(\lambda,t)= F_\mathrm{meas,\oplus}(\lambda,t) \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) + F_\mathrm{mod,sk}(t) }{( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) } \\\end{split}\]

The model telluric line thus has the same profile as the measured one but is scaled by an achromatic, time-specific factor. We can again assume that \(F_\mathrm{sk} << F_\mathrm{\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band})\), so that:

\[\begin{split}F_\mathrm{mod,\oplus}(\lambda,t) \sim F_\mathrm{meas,\oplus}(\lambda,t) \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) } \\\end{split}\]

i.e. that we model the telluric line with a systematic, time-independent bias on its absolute amplitude, which still allows capturing its temporal variations. If fiber B is fitted independently (before fiber A), the telluric model on fiber A is expressed as (see below in fiber B):

\[F_\mathrm{mod,\oplus}(\lambda,t) = F_\mathrm{mod,\oplus}^\mathrm{B}(\lambda,t) \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }{ G_\mathrm{BA} C_\mathrm{bal,*} }\]

with \(G_\mathrm{BA}\) as free parameter, and \(F_\mathrm{mod,\oplus}^\mathrm{B}(\lambda,t)\) and \(C_\mathrm{bal,*}\) derived on fiber B.

Similarly we have:

\[\begin{split}F_\mathrm{mod,sk}(t) \sim F_\mathrm{meas,sk}(t) \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) } \\\end{split}\]

In fiber B is used we can measure \(sc_\mathrm{BA}\) account for the sky background in fiber A as (see below in fiber B):

\[\begin{split}F_\mathrm{mod,sk}(t) &= sc_\mathrm{BA}(t) \frac{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) }{ G_\mathrm{BA} } \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) } \\ &= sc_\mathrm{BA}(t) \frac{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }{ G_\mathrm{BA} }\end{split}\]

---

On fiber B we measure:

\[F_\mathrm{meas}^\mathrm{B}(\mathrm{\lambda \, in \, \lambda_\mathrm{band}},t) = c(\lambda_\mathrm{band},t) G_\mathrm{BA} ( F_\mathrm{meas,sk}(t) + F_\mathrm{meas,\oplus}(\lambda,t) )\]

where \(G_\mathrm{BA}\) is the throughput ratio between fibers B and A, and the other components are assumed to be the same as on fiber A (we neglect in the demonstration the different convolution on each fiber, but they are accounted for in the module). On fiber B we do not use the same type of scaling as on fiber A because the model (and measured) continuum can be close to zero. Instead we use the continuum values measured on fiber A to define (still neglecting the sky background):

\[\begin{split}sc_\mathrm{norm}^\mathrm{B}(t) &= \frac{ F_\mathrm{meas}^\mathrm{A}(\lambda_\mathrm{contA},t)/\mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) }{ < F_\mathrm{meas}^\mathrm{A}(\lambda_\mathrm{contA},t)/\mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) > } \\ &\sim \frac{ c(\lambda_\mathrm{band},t) }{ < c(\lambda_\mathrm{band},t) > } \\\end{split}\]

We can avoid using an additional free parameter per exposure for the time-dependent sky background by measuring:

\[\begin{split}sc_\mathrm{BA}(t) &= \frac{ F_\mathrm{meas}^\mathrm{B}(\lambda_\mathrm{contB},t) }{ F_\mathrm{meas}^\mathrm{A}(\lambda_\mathrm{contA},t)/\mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) } \\ &= \frac{ c(\lambda_\mathrm{band},t) G_\mathrm{BA} F_\mathrm{meas,sk}(t) }{ c(\lambda_\mathrm{band},t) ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) + F_\mathrm{meas,sk}(t) ) / \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) } \\ &\sim \frac{ G_\mathrm{BA} F_\mathrm{meas,sk}(t) }{ ( F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) \delta_\mathrm{p}(\lambda_\mathrm{band},t) ) / \mathrm{LC}_\mathrm{theo}(\lambda_\mathrm{band},t) } \\ &= \frac{ G_\mathrm{BA} F_\mathrm{meas,sk}(t) }{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA})} \\\end{split}\]

where the continuum do not need to cover the same ranges on fibers A and B. Having a measured estimate of \(c(\lambda_\mathrm{band},t)\) (from \(sc_\mathrm{norm}^\mathrm{B}(t)\)) and \(F_\mathrm{meas,sk}(t)\) (from \(sc_\mathrm{BA}(t)\)), and expressing \(F_\mathrm{meas,\oplus}(\lambda,t)\) as a function of fiber A model (\(F_\mathrm{mod,\oplus}(\lambda,t)\)) we can then model fiber B spectrum as:

\[\begin{split}F_\mathrm{mod}^\mathrm{B}(\mathrm{\lambda \, in \, \lambda_\mathrm{band}},t) &= sc_\mathrm{norm}^\mathrm{B}(t) < c(\lambda_\mathrm{band},t) > G_\mathrm{BA} ( sc_\mathrm{BA}(t) \frac{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) }{ G_\mathrm{BA} } + F_\mathrm{mod,\oplus}(\lambda,t) \frac{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) } ) \\ &= sc_\mathrm{norm}^\mathrm{B}(t) ( sc_\mathrm{BA}(t) < c(\lambda_\mathrm{band},t) > F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) + < c(\lambda_\mathrm{band},t) > G_\mathrm{BA} F_\mathrm{mod,\oplus}(\lambda,t) \frac{ F_\mathrm{meas,\star}(\lambda_\mathrm{contA}) }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) } ) \\ &= sc_\mathrm{norm}^\mathrm{B}(t) ( C_\mathrm{bal,*} sc_\mathrm{BA}(t) + F_\mathrm{mod,\oplus}(\lambda,t) \frac{ C_\mathrm{bal,*} G_\mathrm{BA} }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) } )\end{split}\]

where the free parameters are the telluric line properties, the measured stellar continuum weighted by the average broadband flux variations across the visit (\(C_\mathrm{bal,*} = < c(\lambda_\mathrm{band},t) > F_\mathrm{meas,\star}(\lambda_\mathrm{contA})\)), and the throughput scaling \(G_\mathrm{BA}\). This approach is only possible when fitting simultaneously fibers A and B.

When fiber B is fitted independently of fiber A we do not have knowledge of \(F_\mathrm{mod,\star}(\lambda_\mathrm{contA})\) and \(G_\mathrm{BA}\). We then define the model as:

\[F_\mathrm{mod}^\mathrm{B}(\mathrm{\lambda \, in \, \lambda_\mathrm{band}},t) = sc_\mathrm{norm}^\mathrm{B}(t) ( C_\mathrm{bal,*} sc_\mathrm{BA}(t) + F_\mathrm{mod,\oplus}^\mathrm{B}(\lambda,t) )\]

where

\[F_\mathrm{mod,\oplus}^\mathrm{B}(\lambda,t) = F_\mathrm{mod,\oplus}(\lambda,t) C_\mathrm{bal,*} \frac{ G_\mathrm{BA} }{ F_\mathrm{mod,\star}(\lambda_\mathrm{contA}) }\]

since the absolute amplitude of the derived telluric lines are degenerate with \(G_\mathrm{BA}/F_\mathrm{mod,\star}(\lambda_\mathrm{contA})\). We include \(C_\mathrm{bal,*}\) in the amplitude so that it can be more easily estimated from the measured lines. In that case the derived amplitudes are used to assess the variations of the telluric intensity over the visit and inform the fit of fiber A, which has to be performed with \(G_\mathrm{BA}\) as a free parameter (since \(F_\mathrm{mod,\star}(\lambda_\mathrm{contA})\) then becomes available).

Notes

• the two fibers have different LSF, so that we model all lines with ‘intrinsic’ profiles and associated properties, which can then be used on both fibers by convolving the profiles with the relevant fiber resolution (map)

• the continuum range does not need to be common to both fibers, since they are only combined when computing \(sc_\mathrm{BA}(t)\) whose point is to estimate \(F_\mathrm{meas,sk}(t)\).

• we model but do not correct for the sky background, to avoid introducing an offset with the rest of the spectrum.

• the background flux on fiber B may not follow the same variations as the flux on fiber A, which is mainly modulated by diffusion; however, if fiber B background is constant then \(sc_\mathrm{BA}(t)\) will have \(c(\lambda_\mathrm{band},t)\) at the denominator, so that it will be disappear from the product \(sc_\mathrm{norm}^\mathrm{B}(t) sc_\mathrm{BA}(t)\) and the modelled bacground will not depend on it. Whether the true background varies or not with Earth diffusion (which may still be the case if the background comes from contamination from fiber A) thus does not matter.

Parameters:

TBD

Returns:

TBD

proc_atlas_band(comm_proc_in, mod_prop_band, fit_dic, fixed_args, fiber_exp_fit_corr_list, iexp_fit_corr_list, n_corr_unfit_list, iexp_dup_list, data_vis, solbar2star_specdopshift, tell2solbar_specdopshift, mean_bjd, data_dic, idx_exp2tr, occ_exclu_range, line_range, theo_dic, tell2star_specdopshift, nord_ref, data_format, data_prop)

ATLAS sub-routine: processing.

Sub-routine in a given spectral band, processing fiber A and/or B data and parameters.

Parameters:

TBD

Returns:

TBD

fit_atlas_band(cond_calc, fib_id, fit_dic_fib, fixed_args_fib, gen_dic, data_dic, theo_dic, fit_save)

ATLAS sub-routine: fit.

Fit to A,B, or A+B data

Parameters:

TBD

Returns:

TBD

ana_atlas_band(tell_key_list, fixed_args, inst, vis, fit_dic, fit_save, coord_dic, data_prop, save_data_dir_tellaccu, band_id, n_in_vis, idx_exp2tr, mean_bjd, ana_prop_mod, ana_mod_priors, ana_prop_idx, coord_dep, ana_prop_dic)

ATLAS sub-routine: analysis.

Sub-routine to analyze the properties of telluric lines derived from the fits.

OH emission seems to correlate well with the alt and az coordinates, with three different phases:

• during starrise (high az at the east, low alt): OH amplitude decreases sharply, after being excited during the day

• around the meridian (az around 180°, higher alt): OH amplitude varies smoothly

• during starset (low az at the west, low alt): OH amplitude increases again, being progressively excited by the sun

The variations in amplitude during those phases then probably depend on the angle between the LOS and its angle with the Sun, and on the Sun emission in the observing epoch

Parameters:

TBD

Returns:

TBD

corr_atlas_band(fixed_args, refcorr_fibID, p_final_in, corr_stl_band, iexp_corr_list_eff, isub_corr_list_eff, inst, vis, iband, nbands, data_vis, proc_DI_data_paths_new, solbar2star_specdopshift, save_data_dir_tellaccu, band_id, gen_dic, fit_range_band, cont_range_band, corr_prop_mod, corr_idx_to_mod, coord_dep, mean_bjd, nord, coord_dic, nthreads)

ATLAS sub-routine: fit.

Correct data on fiber A.

Parameters:

TBD

Returns:

TBD

sub_corr_atlas_band(iexp_corr_proc, t_exp_proc, solbar2star_specdopshift_proc, meas_fluxcont_proc, tell2star_specdopshift_proc, mod_proc, trans_tellabs_proc, flux_tellem_proc, flux_modraw_contA_proc, flux_stem_indiv_proc, trans_stabs_indiv_proc, flux_stcont_proc, flux_st_proc, iband, nbands, proc_DI_data_paths, proc_DI_data_paths_new, nord, nspec, plot_exp, corr_exp, corr_tellgen, corr_stl_band, iord_in_fit, use_sky, idx_range_kept, subcond_corr_kept, corr_stl_band_dic, inst, vis, root_dir, absL_in_vis, emL_in_vis, all_lines_prop, abstellL_in_vis, emtellL_in_vis, spectral_ref, fit_range_band, cont_range_band, band_id)

ATLAS sub-routine: correction.

Correct data on fiber A.

Parameters:

TBD

Returns:

TBD

plot_atlas_band(fixed_args, inst, vis, p_final, fit_dic, fit_range, cont_range, y_range_band, band_id)

ATLAS sub-routine: plot.

Sub-routine in a given spectral band, applied to fiber A or B data, for plotting. This mainly allows checking whether the chosen line profile models reproduce well the observed ones

Parameters:

TBD

Returns:

TBD

plot_exp_spec(inst, vis, root_dir, wav_star, flux_uncorr, err_uncorr, flux_corr, err_corr, absL_in_vis, emL_in_vis, all_lines_prop, abstellL_in_vis, emtellL_in_vis, spectral_ref, iexp_plot, iord_plot, mod_full, mod_st, mod_st_cont, mod_trans_tellabs, mod_flux_tellem, res_spec, mod_stabs_lines, mod_stem_lines, fit_range, cont_range, tell2star_specdopshift, cont_ratio, corr_exp_dic, band_id, subcond_corr_eff)