antaress.ANTARESS_corrections.ANTARESS_flux_balance module#
- def_Mstar(gen_dic, data_inst, inst, data_prop, plot_dic, data_dic, coord_dic)[source]#
Stellar master definition.
Defines master spectra for the star
used exclusively for flux balance corrections
either set to the mean or median of the spectra over visits, or to an input spectrum
the module is ran independently and the master saved for each exposure, so that it can be used independently for the global and local flux balance corrections
- Parameters:
TBD
- Returns:
None
- corr_Fbal(inst, gen_dic, data_inst, plot_dic, data_prop, data_dic)[source]#
Main flux balance correction routine.
Determines and applies flux balance correction.
If spectra have lost their absolute flux balance, they write as
\(F_\mathrm{obs}(w,t) = a(w,t) F(w,t)\)
where a(w,t) represents instrumental systematics, diffusion by Earth atmosphere, etc. These systematics are assumed to vary slowly with wavelength, so that the shape of the spectra is kept locally. Correcting for these low-frequency variations should then allow us to retrieve the correct shape of planetary and stellar lines.
If we neglect variations due to narrow planetary lines, assumed to be diluted when considering the spectra at low-resolution:
\[\begin{split}F_\mathrm{obs}(\mathrm{w \, in \, w_\mathrm{bin}},vis,t) &\sim a(w_\mathrm{bin},t) ( F_\mathrm{\star}(w,vis) LC_\mathrm{tr}(w_\mathrm{bin},vis,t) + F_\mathrm{\star}(w,vis) LC_\mathrm{refl}(w_\mathrm{bin},vis,t) + F_\mathrm{p}^\mathrm{therm}(w_\mathrm{bin},vis,t) ) \\ &= a(w_\mathrm{bin},t) F_\mathrm{\star}(w,vis) ( LC_\mathrm{tr}(w_\mathrm{bin},vis,t) + LC_\mathrm{refl}(w_\mathrm{bin},vis,t) + F_\mathrm{p}^\mathrm{therm}(w_\mathrm{bin},vis,t)/F_\mathrm{\star}(w,vis) ) \\ &= a(w_\mathrm{bin},t) F_\mathrm{\star}(w,vis) \delta_\mathrm{p}(w_\mathrm{bin},vis,t)\end{split}\]where we account for all contributions from the planet.
We define a reference for the unocculted star \(F_\mathrm{ref}(w,vis)\), which can either be an external (user-provided) spectrum, or a measured master spectrum. It is thus possible that \(F_\mathrm{ref}(w,vis) = C_\mathrm{ref}(w) F_\mathrm{\star}(w,vis)\), where A represents the deviation of the external spectrum from the stellar spectrum, or a combination of the a(w,t) from the spectra used to build the master. Note that the unknown scaling of the flux due to the distance to the star is implicitely included in A. The same reference can be used for all spectra obtained with a given instrument, but we obtain better results by calculating references specific to each visit. Assuming that \(C_\mathrm{ref}\) is dominated by low-frequency variations, we have \(F_\mathrm{ref}(w_\mathrm{bin},vis) = C_\mathrm{ref}(w_\mathrm{bin}) F_\mathrm{\star}(w_\mathrm{bin},vis)\)
We bin the data to smooth out noise and high-frequency variations, and to sample a(w,t) and the planetary continuum. Theoretically we would obtain a cleaner estimate of a by first calculating the spectral ratio between each exposure and the reference, and then binning the spectral ratio. In practice however the dispersion of the flux in low-SNR regions leads to spurious variations when calculating this ratio on individual pixels. We thus first bin the exposure and master spectra, and then calculate the ratio between those binned spectra.
Rather than binning the data in flux units we first scale it back to raw count units, to avoid artificially increasing the uncertainty and dispersion in a given bin. This does not bias the measurement of ‘a’, considering that:
\[\begin{split}N_\mathrm{obs}(w_\mathrm{bin},t) &= \sum(w_\mathrm{bin},F_\mathrm{obs}(w,t) dt dw/g_\mathrm{cal}(w)) \\ &\sim \sum(w_\mathrm{bin},a(w_\mathrm{bin},t) F_\mathrm{\star}(w,v) dt dw/g_\mathrm{cal}(w)) \\ &\sim a(w_\mathrm{bin},t) \delta_\mathrm{p}(w_\mathrm{bin},v,t) dt \sum(w_\mathrm{bin},F_\mathrm{\star}(w,v)/g_\mathrm{cal}(w)) \\ N_\mathrm{ref}(w_\mathrm{bin},t) &= \sum(w_\mathrm{bin},F_\mathrm{ref}(w,t) dw/g_\mathrm{cal}(w)) \\ &= \sum(w_\mathrm{bin},C_\mathrm{ref}(w_\mathrm{bin}) F_\mathrm{\star}(w,v) dw/g_\mathrm{cal}(w)) \\ &= C_\mathrm{ref}(w_\mathrm{bin}) \sum(w_\mathrm{bin},F_\mathrm{\star}(w,v) dw/g_\mathrm{cal}(w))\end{split}\]where we scale the master AFTER its calculation in the star rest frame and shift to the exposure rest frame, to prevent introducing biases
We fit a polynomial to the ratio between the binned exposure spectra and the stellar reference, scaled. \(P[w_\mathrm{bin}]\) is thus an estimate of:
\[\begin{split}N_\mathrm{obs}(w_\mathrm{bin},t)/N_\mathrm{ref}(w_\mathrm{bin},t) &= a(w_\mathrm{bin},t) \delta_\mathrm{p}(w_\mathrm{bin},v,t) dt \sum(w_\mathrm{bin},F_\mathrm{\star}(w,v)/g_\mathrm{cal}(w)) / C_\mathrm{ref}(w_\mathrm{bin}) \sum(w_\mathrm{bin},F_\mathrm{\star}(w,v) dw/g_\mathrm{cal}(w)) \\ &= a(w_\mathrm{bin},t) \delta_\mathrm{p}(w_\mathrm{bin},vis,t) dt / C_\mathrm{ref}(w_\mathrm{bin})\end{split}\]assuming that \(C_\mathrm{ref}\) is dominated by low-frequency variations, we obtain
\(P[w_\mathrm{bin}] ~ a(w_\mathrm{bin},t) \delta_\mathrm{p}(w_\mathrm{bin},vis,t)/C_\mathrm{ref}(w_\mathrm{bin})\)
We then extrapolate \(P[w_\mathrm{bin}]\) at all wavelengths w, and correct spectra using P(w), resulting in :
\(F_\mathrm{norm}(w,t) = F_\mathrm{obs}(w,t)/P(w) = F_\mathrm{\star}(w,vis) C_\mathrm{ref}(w) = F_\mathrm{ref}(w,vis)\)
low-frequency variations of planetary origins are thus removed together with the systematics, and will be re-injected during the light curve scaling
Finally, we reset the spectra to their original absolute flux level. This is done to remain as close as possible to the measured photon count, which is important in particular to their conversion into stellar CCFs, before it is necessary to rescale the spectra to the exact same flux level, which becomes necessary when analyzing the RM effect and atmospheric signals
The correction can be fitted to a smaller spectral band than the full spectrum (eg if the pipeline is set to analyze spectral lines in a given region, or to avoid ranges contaminated by spurious features). However the range selected for the fit must be large enough to capture low-frequency variations over the spectral ranges selected for analysis in the pipeline
This correction is applied here, rather than simultaneously with the transit rescaling, because it is necessary to correct for cosmics
When a measured master is used and several visits are processed, we apply first a global correction relative to the master of the visit. If requested we then apply the intra-order correction, still using the visit master as reference. Finally we apply a global correction based on the ratio between the visit master and a reference, measured at lower resolution than with the visit master. This is because deriving directly the correction from the ratio between exposure and instrument master introduces local variations (possibly due to the changes in line shape between epochs) that bias the fitted model. The two-step approach above, where the visit-to-reference correction is measured at low-resolution and high SNR, is more stable
Measuring the stellar continuum on the master and individual spectra, to then do their ratio and measure the flux balance, is not a better solution because to capture well enough the continuum profile the rollin pin has to be small enough, in which case it becomes sensitive to the wiggles. They could then be smoothed out in the continuum ratio, or through a fit with a smoothed or low-order polynomial, but then it becomes equivalent to the present solution
- Parameters:
TBD
- Returns:
None
- corrFbal_vis(iexp_group, proc_DI_data_paths, inst, vis, save_data_dir, Fbal_range_fit, FbalOrd_range_fit, dim_exp, iord_fit_list_Fbal, iord_fit_list_FbalOrd, Fbal_bin_nu, scaling_range, Fbal_mod, Fbal_deg, Fbal_smooth, FbalOrd_smooth, Fbal_clip, nord, nspec, Fbal_range_corr, plot_Fbal_corr, plot_flux_sp, FbalOrd_binw, plot_FbalOrd_corr, proc_DI_data_paths_new, FbalOrd_clip, resamp_mode, FbalOrd_deg, Fbal_expvar, mean_gcal_DI_data_paths, corr_func_vis, corr_func_vis_ord, corr_Fbal, corr_FbalOrd, Fbal_phantom_range)[source]#
Flux balance correction per visit.
Determines and applies flux balance correction in each visit.
- Parameters:
TBD
- Returns:
TBD
- corrFbal_totFr(nord, cond_def_sp_mast, scaling_range, low_wav, high_wav, dwav, flux_sp, flux_mast)[source]#
Spectrum-to-reference ratio.
Calculates the mean flux ratio between a given spectrum and a reference
over the same range as requested for the broadband flux scaling, neglecting the small shifts due to alignments
- Parameters:
TBD
- Returns:
tot_Fr_spec (float) – mean flux ratio