The cascade.exoplanet_tools module

Exoplanet Tools Module.

This Module defines the functionality to get catalog data on the targeted exoplanet and define the model ligth curve for the system. It also difines some usefull functionality for exoplanet atmosphere analysis.

Vmag = Unit("Vmag")

Definition of a generic Vband magnitude

Kmag = Unit("Kmag")

Definition of generic K band magnitude

kmag_to_jy(magnitude: Unit('Kmag'), system='Johnson')

Convert Kband Magnitudes to Jy.

Parameters:

• magnitude ('Kmag') – Input K band magnitude to be converted to Jy.

• system ('str') – optional, either ‘Johnson’ or ‘2MASS’, default is ‘Johnson’

Returns:

flux (‘astropy.units.Quantity’, u.Jy) – Flux in Jy, converted from input Kband magnitude

Raises:

AssertionError – raises error if Photometric system not recognized

jy_to_kmag(flux: Unit('Jy'), system='Johnson')

Convert flux in Jy to Kband Magnitudes.

Parameters:

• flux ('astropy.units.Quantity', 'u.Jy or equivalent') – Input Flux to be converted K band magnitude.

• system ('str') – optional, either ‘Johnson’ or ‘2MASS’, default is ‘Johnson’

Returns:

magnitude (‘astropy.units.Quantity’, Kmag) – Magnitude converted from input fkux value

Raises:

AssertionError – raises error if Photometric system not recognized

surface_gravity(MassPlanet: Unit('jupiterMass'), RadiusPlanet: Unit('jupiterRad'))

Calculate the surface gravity of planet.

Parameters:

• MassPlanet – Mass of planet in units of Jupiter mass or equivalent

• RadiusPlanet – Radius of planet in units of Jupiter radius or equivalent

Returns:

sgrav – Surface gravity in units of m s-2

scale_height(MeanMolecularMass: Unit('u'), SurfaceGravity: Unit('m / s2'), Temperature: Unit('K'))

Calculate the scaleheigth of the planet.

Parameters:

• MeanMolecularMass ('astropy.units.Quantity') – in units of mass of the hydrogen atom or equivalent

• SurfaceGravity ('astropy.units.Quantity') – in units of m s-2 or equivalent

• Temperature ('astropy.units.Quantity') – in units of K or equivalent

Returns:

ScaleHeight (‘astropy.units.Quantity’) – scaleheigth in unit of km

transit_depth(RadiusPlanet: Unit('jupiterRad'), RadiusStar: Unit('solRad'))

Transit depth estimate.

Calculates the depth of the planetary transit assuming one can neglect the emision from the night side of the planet.

Parameters:

• Planet (Radius) – Planetary radius in Jovian radii or equivalent

• Star (Radius) – Stellar radius in Solar radii or equivalent

Returns:

depth – Relative transit depth (unit less)

planck(wavelength: Unit('micron'), temperature: Unit('K'))

Return Black Body emission.

Parameters:

• wavelength ('astropy.units.Quantity') – Input wavelength in units of microns or equivalent

• temperature ('astropy.units.Quantity') – Input temperature in units of Kelvin or equivalent

Returns:

blackbody (‘astropy.units.Quantity’) – B_nu in cgs units [ erg/s/cm2/Hz/sr]

Examples

>>> import cascade
>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> from astropy.visualization import quantity_support
>>> import astropy.units as u

>>> wave = np.arange(4, 15, 0.05) * u.micron
>>> temp = 300 * u.K
>>> flux = cascade.exoplanet_tools.Planck(wave, temp)

>>> with quantity_support():
...     plt.plot(wave, flux)
...     plt.show()

equilibrium_temperature(StellarTemperature: Unit('K'), StellarRadius: Unit('solRad'), SemiMajorAxis: Unit('AU'), Albedo=0.3, epsilon=0.7)

Calculate the Equlibrium Temperature of the Planet.

Parameters:

• StellarTemperature ('astropy.units.Quantity') – Temperature of the central star in units of K or equivalent

• StellarRadius ('astropy.units.Quantity') – Radius of the central star in units of Solar Radii or equivalent

• Albedo ('float') – Albedo of the planet.

• SemiMajorAxis ('astropy.units.Quantity') – The semi-major axis of platetary orbit in units of AU or equivalent

• epsilon ('float') – Green house effect parameter

Returns:

ET (‘astropy.units.Quantity’) – Equlibrium Temperature of the exoplanet

get_calalog(catalog_name, update=True)

Get exoplanet catalog data.

Parameters:

• catalog_name ('str') – name of catalog to use, can either be ‘TEPCAT’, ‘EXOPLANETS.ORG’ or ‘NASAEXOPLANETARCHIVE’

• update ('bool') – Boolian indicating if local calalog file will be updated

Returns:

files_downloaded (‘list’ of ‘str’) – list of downloaded catalog files

parse_database(catalog_name, update=True)

Read CSV files containing exoplanet catalog data.

Parameters:

• catalog_name ('str') – name of catalog to use

• update ('bool') – Boolian indicating if local calalog file will be updated

Returns:

table_list (‘list’ of ‘astropy.table.Table’) – List containing astropy Tables with the parameters of the exoplanet systems in the database.

Note

The following exoplanet databases can be used:

The Transing exoplanet catalog (TEPCAT) The NASA exoplanet Archive The Exoplanet Orbit Database

Raises:

ValueError – Raises error if the input catalog is nor recognized

convert_spectrum_to_brighness_temperature(wavelength: Unit('micron'), contrast: Unit('%'), StellarTemperature: Unit('K'), StellarRadius: Unit('solRad'), RadiusPlanet: Unit('jupiterRad'), error: Unit('%') = None)

Convert the secondary eclipse spectrum to brightness temperature.

Parameters:

• wavelength – Wavelength in u.micron or equivalent unit.

• contrast – Contrast between planet and star in u.percent.

• StellarTemperature – Temperature if the star in u.K or equivalent unit.

• StellarRadius – Radius of the star in u.R_sun or equivalent unit.

• RadiusPlanet – Radius of the planet in u.R_jupiter or equivalent unit.

• error – (optional) Error on contrast in u.percent (standart value = None).

Returns:

• brighness_temperature – Eclipse spectrum in units of brightness temperature.

• error_brighness_temperature – (optional) Error on the spectrum in units of brightness temperature.

combine_spectra(identifier_list, path='')

Combine multiple spectra.

Convienience function to combine multiple extracted spectra of the same source by calculating a weighted averige.

Parameters:

• identifier_list ('list' of 'str') – List of file identifiers of the individual spectra to be combined

• path ('str') – path to the fits files

Returns:

combined_spectrum (‘array_like’) – The combined spectrum based on the spectra specified in the input list

extract_exoplanet_data(data_list, target_name_or_position, coord_unit=None, coordinate_frame='icrs', search_radius=<Quantity 5. arcsec>)

Extract the data record for a single target.

Parameters:

• data_list ('list' of 'astropy.Table') – List containing table with exoplanet data

• target_name_or_position ('str') – Name of the target or coordinates of the target for which the record is extracted

• coord_unit – Unit of coordinates e.g (u.hourangle, u.deg)

• coordinate_frame ('str') – Frame of coordinate system e.g icrs

• search_radius ('astropy.units.Quantity') –

Returns:

table_list (‘list’) – List containing data record of the specified planet

Examples

Download the Exoplanet Orbit Database:

>>> import cascade
>>> ct = cascade.exoplanet_tools.parse_database('EXOPLANETS.ORG',
                                                update=True)

Extract data record for single system:

>>> dr = cascade.exoplanet_tools.extract_exoplanet_data(ct, 'HD 189733 b')
>>> print(dr[0])

class lightcurve(cascade_configuration)

Bases: object

Class defining lightcurve model.

This class defines the light curve model used to model the observed transit/eclipse observations. Current valid lightcurve models: batman

Variables:

• lc ('array_like') – The lightcurve model

• par ('ordered_dict') – The lightcurve parameters

Notes

Uses factory method to pick model/package used to calculate the lightcurve model.

Raises:

ValueError – Error is raised if no valid lightcurve model is defined

Examples

To test the generation of a ligthcurve model first generate standard .ini file and initialize cascade

>>> import cascade
>>> cascade.initialize.generate_default_initialization()
>>> path = cascade.initialize.default_initialization_path
>>> cascade_param =             cascade.initialize.configurator(path+"cascade_default.ini")

Define the ligthcurve model specified in the .ini file

>>> lc_model = cascade.exoplanet_tools.lightcurve()
>>> print(lc_model.valid_models)
>>> print(lc_model.par)

Plot the normized lightcurve

>>> fig, axs = plt.subplots(1, 1, figsize=(12, 10))
>>> axs.plot(lc_model.lc[0], lc_model.lc[1])
>>> axs.set_ylabel(r'Normalized Signal')
>>> axs.set_xlabel(r'Phase')
>>> axes = plt.gca()
>>> axes.set_xlim([0, 1])
>>> axes.set_ylim([-1.1, 0.1])
>>> plt.show()

interpolated_lc_model(dataset, time_offset=0.0, *, _ray_trace_ctx=None)

Interpolate lightcurve model to observed time and wavelengths.

Parameters:

• dataset ('cascade.data_model.SpectralDataTimeSeries') – Input dataset.

• time_offset ('float') – (optional) Offset in oribital phase.

Returns:

• lcmodel_obs (‘ndarray’) – Interpolated lightcurve model.

• ld_correction_obs (‘ndarray’) – Interposlated limbdarkening correction.

return_mid_transit(dataset, time_offset=0.0, *, _ray_trace_ctx=None)

Return the mid transit (eclipse) time of a dataset.

Parameters:

• dataset ('cascade.data_model.SpectralDataTimeSeries') – Input dataset.

• time_offset ('float') – (optional) Offset in oribital phase.

Returns:

mid_transit_time (‘float’) – Mid transit time of input dataset.

class batman_model(cascade_configuration, limbdarkning_model)

Bases: object

Define the lightcurve model using the batman package.

For more details on this particular light curve modeling package for transit/eclipse see the paper by Laura Kreidberg [1].

Variables:

• lc ('array_like') – The values of the lightcurve model

• par ('ordered_dict') – The model parameters difining the lightcurve model

References

[1]

Kreidberg, L. 2015, PASP 127, 1161

static define_batman_model(InputParameter, limbdarkning_model)

Define the lightcurve model using the batman package.

This function defines the light curve model used to analize the transit or eclipse. We use the batman package to calculate the light curves.We assume here a symmetric transit signal, that the secondary transit is at phase 0.5 and primary transit at 0.0.

Parameters:

• InputParameter ('dict') – Ordered dict containing all needed inut parameter to define model

• limbdarkning_model ('cascade.exoplanet_tools.limbdarkening') –

Returns:

• tmodel (‘array_like’) – Orbital phase of planet used for lightcurve model

• lcmode (‘array_like’) – Normalized values of the lightcurve model

return_par_from_ini()

Get parametrers from initializaton file.

Get relevant parameters for lightcurve model from CASCADe intitialization files

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

return_par_from_db()

Return system parameters for exoplanet database.

Get relevant parameters for lightcurve model from exoplanet database specified in CASCADe initialization file

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

Raises:

ValueError – Raises error in case the observation type is not recognized.

masked_array_input(func)

Decorate function to check and handel masked Quantities.

If one of the input arguments is wavelength or flux, the array can be a masked Quantity, masking out only ‘bad’ data. This decorator checks for masked arrays and upon finding the first masked array, passes the data and stores the mask to be used to create a masked Quantity after the function returns.

Parameters:

func (method) – Function to be decorated

eclipse_to_transit(eclipse)

Convert eclipse spectrum to transit spectrum.

Parameters:

eclipse – Transit depth values to be converted

Returns:

transit – transit depth values derived from input eclipse values

transit_to_eclipse(transit, uncertainty=None)

Convert transit spectrum to eclipse spectrum.

Parameters:

• transit – Transit depth values to be converted

• uncertainty – optional

Returns:

eclipse – eclipse depth values derived from input transit values

class exotethys_model(cascade_configuration)

Bases: object

Defines the limbdarkening model using the exotethys package.

The class uses the exotethys package by Morello et al. [2] to define the limbdarkning coefficients used in the calculation of the light curve model for the analysis of the observed transit.

Variables:

• ld ('array_like') – The values of the limbdarkning model

• par ('ordered_dict') – The model parameters difining the limbdarkning model

References

[2]

Morello et al. 2019, (arXiv:1908.09599)

static define_exotethys_model(InputParameter)

Calculate the limbdarkning coefficients using exotethys.

Parameters:

InputParameter ('dict') – Dictionary containing all parameters defining the exotethys model.

Returns:

• wl_bands (‘list’) – List containing the wavelength bands of the exotethys model.

• ld_coefficients (‘list’) – List containing the wavelength dependent limbdarkening coefficients.

return_par_from_ini()

Get parametrers from initializaton file.

Get relevant parameters for limbdarkning model from CASCADe intitialization files

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

return_par_from_db()

Return system parameters for exoplanet database.

Get relevant parameters for limbdarkning model from exoplanet database specified in CASCADe initialization file

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

Raises:

ValueError – Raises error in case the observation type is not recognized.

class limbdarkning(cascade_configuration)

Bases: object

Class defining limbdarkning model.

This class defines the limbdarkning model used to model the observed transit/eclipse observations. Current valid lightcurve models: exotethys or a constant value

Variables:

• ld ('array_like') – The limbdarkning model

• par ('ordered_dict') – The limbdarkning parameters

Notes

Uses factory method to pick model/package used to calculate the limbdarkning model.

Raises:

ValueError – Error is raised if no valid limbdarkning model is defined

Examples

To test the generation of a limbdarkning model first generate standard .ini file and initialize cascade

>>> import cascade
>>> cascade.initialize.generate_default_initialization()
>>> path = cascade.initialize.default_initialization_path
>>> cascade_param =             cascade.initialize.configurator(path+"cascade_default.ini")

Define the limbdarkning model specified in the .ini file

>>> ld_model = cascade.exoplanet_tools.limbdarkning()
>>> print(ld_model.valid_models)
>>> print(ld_model.par)

return_par(*, _ray_trace_ctx=None)

Return input parameters.

Raises:

ValueError – A value error is raised if either the limbdarkening model or limbdarkening law is not recognized (implemented).

Returns:

par (‘collections.OrderedDict’) – Dictionary containing all parameters defing the limbdarkening model.

static return_eclips_coefficients(InputParameter)

Return zero valued limbdarkening coefficients.

Parameters:

InputParameter ('dict') – Dictionary containing the input parameters of the limbdarkening model.

Returns:

ld_coefficients (‘list’) – List of zeros (eclipse only). The length of the list is set by the type of the limbdarkening law.

return_constant_limbdarkning_from_ini(InputParameter, *, _ray_trace_ctx=None)

Return limbdarkning coefficients from input configuration file.

Parameters:

InputParameter ('dict') – Dictionary containing the input parameters of the limbdarkening model.

Returns:

ld_coefficients (‘list’) – Constant limbdarkening coefficients from the cascade configuration file.

class exotethys_stellar_model(cascade_configuration)

Bases: object

Class defining stellar model and simulated observations using exotethys.

This class usines the Exotethys package to read a stellar model from a grid of stellar models and an instrument passband to create a simple simulated spectrum of the observed star.

static define_stellar_model(InputParameter)

Calculate a steller model using exotethys.

Parameters:

InputParameter ('dict') – Input parameters defining the stellar model.

Returns:

• wave_sens (‘astropy.units.Quantity’) – Wavelength grid of the instrument sensitivity.

• sens (‘astropy.units.Quantity’) – Sensitivity of the used instrument.

• model_wavelengths (‘astropy.units.Quantity’) – Wavelength grid of stellar model.

• model_fluxes (‘astropy.units.Quantity’) – Stellar model.

• model_wavelengths_dilution_object (‘astropy.units.Quantity’) – Wavelength grid of stellar object diluting the transit signal.

• model_fluxes_dilution_object (‘astropy.units.Quantity’) – Model flux of stellar object diluting the transit signal.

return_par_from_ini()

Get parametrers from initializaton file.

Get relevant parameters for limbdarkning model from CASCADe intitialization files

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

return_par_from_db()

Return system parameters for exoplanet database.

Get relevant parameters for limbdarkning model from exoplanet database specified in CASCADe initialization file

Returns:

par (‘ordered_dict’) – input model parameters for batman lightcurve model

Raises:

ValueError – Raises error in case the observation type is not recognized.

class SpectralModel(cascade_configuration)

Bases: object

Class defining stellar model and simulated observations.

return_par()

Return input parameters.

Raises:

ValueError – If the requested limbdakening code is not recognized a value error is raised.

Returns:

par (‘collections.OrderedDict’) – Input parameters of spectral model.

determine_wavelength_shift(dataset)

Determine the general wavelength shift of spectral timeseries.

Parameters:

dataset ('cascade.data_model.SpectralDataTimeSeries') – Input spectral data time series.

Returns:

• wavelength_shift (‘astropy.units.Quantity’) – General shift in wavelength of the dispersed light compared to the expected (initial guess) position.

• error_wavelength_shift (‘astropy.units.Quantity’) – Error estimate of the fitted wavelength shift.

class DilutionCorrection(cascade_configuration)

Bases: object

Class defining the dilution correction for an observation.

return_par(*, _ray_trace_ctx=None)

Return input parameters.

Raises:

• ValueError – If the limbdarkning code is not recognized a ValueError is raised.

• AttributeError – If the DILUTION parameters are not properly defined an AttributeError is raised.

Returns:

par (‘collections.OrderedDict’) – Input parameters for the dilution model.

calculate_dilution_correcetion(*, _ray_trace_ctx=None)

Calcultate the dilution correction for the transit depth.

Returns:

• wavelength_dilution_correcetion (‘ndarray’) – Wavelength.

• dilution_correcetion (‘ndarray’) – Dilution corrction.

interpolated_dc_model(dataset, *, _ray_trace_ctx=None)

Interpolate dilution correction to observed wavelengths.

Parameters:

dataset ('cascade.data_model.SpectralDataTimeSeries') – Spectral dataset.

Returns:

None.

class spotprofile(cascade_configuration)

Bases: object

Class defining the profile of a spot crossing

This class defines the light curve of a spot crossing. It implemets a flattened Gaussian function suggested y Fraine et al 2014 to simulated the planet crossing a star spot.

Variables:

• lc ('array_like') – The lightcurve model

• par ('ordered_dict') – The lightcurve parameters

static get_spot_parameters(cascade_configuration)

Get the relevant parameters for the spot profile.

Parameters:

cascade_configuration ('cascade.configuration') – The cascade configuration.

Returns:

par (‘collections.OrderedDict’) – configuration parameters for spot profile.

return_spot_profile(dataset, *, _ray_trace_ctx=None)

Spot profile function.

Parameters:

dataset (: 'cascade.data_model.SpectralDataTimeSeries') – Input dataset.

Returns:

spot_lc (‘ndarray’) – Normalized spot lightcuve model.

_define_band_limits(wave)

Define the limits of the rebin intervals.

Parameters:

wave ('ndarray' of 'float') – Wavelengths (1D or 2D array)

Returns:

limits (‘tuple’) – lower and upper band limits

Raises:

• TypeError – When the input wavelength array has more than 2 dimensions

• ValueError – When the wavelength is not defined for each data point

_define_rebin_weights(lr0, ur0, lr, ur)

Define the weights used in spectral rebin.

Define the summation weights (i.e. the fractions of the original intervals used in the new interval after rebinning)

Parameters:

• lr0 ('ndarray') – lower limits wavelength band of new wavelength grid

• ur0 ('ndarray') – upper limits wavelength band of new wavelength grid

• lr ('ndarray') – lower limits

• ur ('ndarray') – upper limits

Returns:

weights (‘ndarray’ of ‘float’) – Summation weights used to rebin to new wavelength grid

Raises:

TypeError – When the input wavelength array has more than 2 dimensions.

_rebin_spectra(spectra, errors, weights)

Rebin spectra.

Parameters:

• spectra ('ndarray') – Input spectral data values

• errors ('ndarray') – Input error on spectral data values

• weights ('ndarray') – rebin weights

Returns:

• newSpectra (‘ndarray’) – Output spectra

• newErrors (‘ndarray’) – Output error