HECATE.HECATE

Classes

HECATE

Main class for HECATE operations, allowing for the easy application of the Doppler Shadow technique to high-resolution data.
class HECATE[source]

Bases: object

Main class for HECATE operations, allowing for the easy application of the Doppler Shadow technique to high-resolution data.

This class encapsulates the extraction of local spectra/CCFs, as well as the analysis of their shapes (width, intensity, RV) and behavior (linearity, for now).

Parameters:

  • planet_params (dict) – dictionary containing the following planetary parameters: orbital period, system scale, planet-to-star radius ratio, mid-transit time, eccentricity, argument of periastron, planetary inclination and spin-orbit angle.

  • stellar_params (dict) – dictionary containing the following stellar parameters: effective temperature and error, superficial gravity and error, metallicity and error, rotation period, radius and stellar inclination.

  • time (numpy array) – time of observations in BJD.

  • CCFs (numpy array) – matrix with the CCF profiles (RV, flux and flux error), with shape (N_CCFs, 3, N_points).

  • spectra (numpy array) – matrix with spectral line profiles (wavelength, flux and flux error), with shape (N_spectra, 3, N_points).

  • soap_wv (numpy array, optional) – wavelength interval [min, max] in nm for SOAP simulation. Default is [380, 788].

  • plot_soap (str, optional) – whether to plot the “simple” or “SOAP” simulated light curve. Default is None (no plot).

extract_local_CCF(model_fit, plot, save)[source]

run all steps of the Doppler Shadow extraction and returns the local CCFs. Ideal for quick extraction.

extract_local_spectral_line(model_fit_ccf, plot, line_name, wave_lims, masks_dict, save)[source]

run all steps of the Doppler Shadow extraction for spectral lines and returns the local spectra.

avg_out_of_transit_profile(profiles, x_reference, profile_type, plot, save)[source]

computes the average out-of-transit profile (CCF or spectral line).

get_profile_parameters(profiles, data_type, observation_type, model, print_output, plot_fit, wave_ctr_line, mask_x, save)[source]

computes profile parameters (central RV, width, intensity) for CCFs or spectral lines.

sysvel_correction_CCF(CCFs, model, print_output, plot_fits, plot_sys_vel, save)[source]

removes the stellar systemic velocity from the initial CCFs RVs.

_local_params_linear_fit(local_param, indices_final, title, priors, plot_nested, axes_to_fit)

tests the linearity of local CCF parameters via nested sampling from Dynesty.

plot_local_params(indices_final, local_params, master_params, suptitle, linear_fit, plot_nested, linear_fit_pairs, save)[source]

plots the local CCF parameters in function of orbital phases and mu.

Notes

This tool was based on the work of Gonçalves, E. et al. (2026) and contains a wrapper of SOAPv4 (Cristo, E. et al., 2025).

References

[1] Gonçalves, E. et al., “Exploring the surface of HD 189733 via Doppler Shadow Analysis of Planetary Transits,” Astronomy & Astrophysics, 2026

[2] Cristo, E. et al., “SOAPv4: A new step toward modeling stellar signatures in exoplanet research”, Astronomy & Astrophysics, Vol. 702, A84, 17pp., 2025

__init__(planet_params: dict, stellar_params: dict, time: numpy.array, CCFs: numpy.array, spectra: numpy.array, mu_type: str = 'weighted', ld_law: str = 'quadratic', soap_wv: numpy.array = [380, 788], plot_soap: str = None)[source]
extract_local_CCF(model_fit: str, plot: dict, rv_step: float = 0.5, save=None)[source]

Run all steps of the Doppler Shadow extraction (simulated light curve, systemic velocity correction, compute average out-of-transit CCF and subtraction) and returns the local CCFs. Ideal for quick extraction of local CCFs.

Parameters:

  • model_fit (str) – profile model to fit to CCFs.

  • plot (dict) – dictionary including boolean value for each type of plot available (SOAP, fits_initial_CCF, sys_vel, avg_out_of_transit_CCF, local_CCFs and whether to photometrical rescale).

  • save – path to save plots.

Returns:

  • local_CCFs (numpy array) – matrix with the local (in-transit) CCF profiles (RV, flux and flux error), with shape (N_CCFs, 3, N_points).

  • CCFs_flux_corr (numpy array) – matrix with all CCF profiles, only flux corrected, with shape (N_CCFs, 3, N_points)

  • CCFs_sub_all (numpy array) – matrix with all CCF profiles, flux corrected and subtracted from average out-of-transit, with shape (N_CCFs, 3, N_points).

  • average_out_of_transit_CCF (numpy array) – matrix with the average out-of-transit CCF profile, with shape (3, N_points).

extract_local_spectral_line(model_fit_ccf: str, plot: dict, line_name: str, wave_lims: list, masks_dict: dict = {'continuum': [(6538.8, 6545.8), (6546.9, 6551.4), (6575.6, 6579.8), (6581.4, 6586.05)], 'glob_norm': [(6400, 6800)], 'line_window': [(6535, 6590)], 'spec_slice': [(6450, 6650)]}, save=None)[source]

Run all steps of the Doppler Shadow extraction (simulated light curve, systemic velocity correction, compute average out-of-transit CCF and subtraction) and returns the local CCFs. Ideal for quick extraction of local CCFs.

Parameters:

  • model_fit_ccf (str) – profile model to fit to white light CCFs.

  • plot (dict) – dictionary including boolean value for each type of plot available (SOAP, fits_initial_CCF, sys_vel_CCF, sys_vel_line, avg_out_of_transit_spectra, local_spec_line).

  • line_name (str) – name of the spectral line.

  • wave_lims (list) – wavelength interval to plot in the tomography plot.

  • masks_dict (dict) – dictionary containing the wavvelength masks as lists of tuples for (1) global normalization (2) spectrum slice to save memory (3) window containing the line of interest (4) bits of spectrum continuum (5) spectral line to fit for systemic velocity correction.

  • save – path to save plots.

Returns:

  • local_spectra (numpy array) – matrix with the local (in-transit) spectral line profiles (wavelength, flux and flux error), with shape (N_spectra, 3, N_points).

  • spectra_flux_corr (numpy array) – matrix with all spectral line profiles, only flux corrected, with shape (N_spectra, 3, N_points)

  • spectra_sub_all (numpy array) – matrix with all spectral line profiles, flux corrected and subtracted from average out-of-transit, with shape (N_spectra, 3, N_points).

  • avg_out_of_transit_spectrum (numpy array) – matrix with the average out-of-transit spectral line profile, with shape (3, N_points).

sysvel_correction_CCF(CCFs: numpy.array, model: str, print_output: bool, plot_fits: bool, plot_sys_vel: bool, save: str = None)[source]

Extract the RV component due to the star’s motion around the barycentre, excluding the stellar systemic velocity. Fits a chosen profile to the CCF, then a linear model to the out-of-transit central RVs and subtracts it to all CCFs RVs.

Parameters:

  • CCFs (numpy array) – matrix with the CCF profiles (RV, flux and flux error), with shape (N_CCFs, 3, N_points).

  • model (str) – type of profile model to fit.

  • print_output (bool) – whether to print the fit output.

  • plot_fits (bool) – whether to plot the fit for each CCF.

  • plot_sys_vel (bool) – whether to plot the central RV (systemic velocity) in function of orbital phase.

  • save (str, optional) – path to save the plots.

Returns:

  • CCFs_corr (numpy array) – CCFs corrected by the systemic velocity.

  • x0_corr (numpy array) – central RVs corrected by the systemic velocity.

  • poly_coefs (numpy array) – coefficients of the linear fit to the systemic velocity.

avg_out_of_transit_profile(profiles: numpy.array, x_reference: numpy.array, profile_type: str = 'CCF', plot: bool = False, save: str = None)[source]

Computes the average out-of-transit profile (CCF or spectral line) by linearly interpolating the profiles (CCFs or sliced spectra) into a common grid. In the case of CCFs, they must be corrected by the systemic velocity before averaging. The interpolated uncertainties are propagated taking the covariances into account.

Parameters:

  • profiles (numpy array) – matrix with the out-of-transit profiles (CCFs or spectral lines), with shape (N_profiles, 3, N_points).

  • x_reference (numpy array) – grid for interpolation (RV for CCFs, wavelength for spectral lines).

  • profile_type (str) – whether the profiles are CCFs or spectral lines, as they require slightly different treatments.

  • plot (bool) – whether to plot the average out-of-transit profile.

  • save (str, optional) – path to save the plot.

Returns:

  • profile_interp (numpy array) – matrix with interpolated profiles (CCFs or spectral lines), with shape (N_profiles, 3, N_points).

  • avg_out_of_transit_profile (numpy array) – matrix with the average out-of-transit profile (CCF or spectral line), with shape (3, N_points).

get_profile_parameters(profiles: numpy.array, data_type: str, observation_type: str, model: str, print_output: bool, plot_fit: bool, wave_ctr_line: list = [(0, 0)], mask_x: numpy.ndarray = None, save=None)[source]

Computes the profile parameters of an array of CCFs or spectral line profiles.

Parameters:

  • profiles (numpy array) – matrix with profiles, with shape (N_observations, 3, N_points).

  • data_type (str) – whether it’s a CCF or spectral line profile.

  • observation_type (str) – whether it’s a local, average out-of-transit or raw CCF/spectral line.

  • model (str) – type of profile model to fit.

  • print_output (bool) – whether to print fit output.

  • plot_fit (bool) – whether to plot the fit.

  • wave_ctr_line (list, optional) – central wavelength of spectral lines.

  • mask_x (numpy array, optional) – mask intervals for fitting region.

  • save (str, optional) – path to save plot.

Returns:

profile_params – Dictionary containing: - ‘central_val’: central RV/wavelength of the input CCFs/spectral lines. Single array for single line, list of arrays for multiple lines. - ‘continuum’: continuum level of the input CCFs/spectral lines. - ‘intensity’: intensity of the input CCFs/spectral lines. Single array for single line, list of arrays for multiple lines. - ‘width’: width measure of the input CCFs/spectral lines. Single array for single line, list of arrays for multiple lines. - ‘R2’: coefficient of determination of all fits. - ‘flux_fit_params’: list of fit parameters for all profiles.

Return type:

dict

local_params_linear_fit(local_param: numpy.array, indices_final: numpy.array, title: str, priors: list, plot_nested: bool, axes_to_fit: list = None)[source]

Performs a tentative linear fit by applying nested sampling through `dynesty, comparing between a constant and unconstrained models, and then between a linear model with a positive slope and one with a negative slope. Useful for a first approximation analysis of the local CCF parameters.

Parameters:

  • local_param (numpy array) – array of a given local CCFs parameter (central RV, width, intensity).

  • indices_final (numpy array) – indices of local CCFs to use (to discard bad data).

  • title (str) – CCF parameter to use as title in the plot.

  • priors (list) – half of range of linear fit parameters (m, b) to use as priors.

  • plot_nested (bool) – whether to plot the trace and corner plots from the dynesty packages.

  • axes_to_fit (list, optional) – List of axes to fit: [“phases”, “mu”]. If None, defaults to both axes (backward compatible).

Returns:

  • phases_data (dict or None) – contains phases (‘x’), the label of phases (‘label’), grid of phases for plotting (‘x_grid’), fitted CCF parameter (‘y_fit’) as an array (value, error), grid of fitted CCF parameter (‘y_grid’) as an array (value, error) and ‘residual’ between y and y_fit as an array (value, error). None if “phases” not in axes_to_fit.

  • mu_data (dict or None) – contains mu (x), the label of mu (‘label’), grid of phases for plotting (‘x_grid’), fitted CCF parameter (‘y_fit’) as an array (value, error), grid of fitted CCF parameter (‘y_grid’) as an array (value, error) and ‘residual’ between y and y_fit as an array (value, error). None if “mu” not in axes_to_fit.

plot_local_params(indices_final: numpy.array, local_params: numpy.array, master_params: numpy.array, suptitle: str = None, linear_fit: bool = False, plot_nested: bool = False, linear_fit_pairs: list = None, mu_min_plot: float = 0.3, save=None)[source]

Plot local CCF parameters (central RV, line-width measure and line-center intensity) in function of orbital phases and mu. Optionally, a linear fit via nested sampling is tested for specified parameter-axis pairs, plotting the fit and the corresponding residuals.

Parameters:

  • indices_final (numpy array) – indices of local CCFs to use (to discard bad data).

  • local_params (numpy array) – array of local CCFs parameters (central RV, width, intensity).

  • master_params (numpy array) – average out-of-transit CCF parameters.

  • suptitle (str, optional) – title to display above the figure.

  • linear_fit (bool) – whether to perform a tentative linear fit via nested sampling on all parameters and axes.

  • plot_nested (bool) – whether to plot the trace and corner plots from the dynesty packages.

  • linear_fit_pairs (list, optional) – List of tuples specifying which (axis, parameter_index) pairs should have linear fits. Example: [(“phases”, 0), (“mu”, 1), (“phases”, 2)]. If None and linear_fit=True, fits all parameters on both axes (backward compatible). If specified, only those pairs will have linear fits.

  • mu_min_plot (float, optional) – Minimum value for the mu axis in the plots.

  • save – path to save plots.