The cascade.TSO module

The TSO module is the main module of the CASCADe package.

The classes defined in this module define the time series object and all routines acting upon the TSO instance to extract the spectrum of the transiting exoplanet.

class TSOSuite(*init_files, path=None)

Bases: object

Transit Spectroscopy Object Suite class.

This is the main class containing the light curve data of and transiting exoplanet and all functionality to calibrate and analyse the light curves and to extractthe spectrum of the transiting exoplanet.

Parameters:

• init_files (list of str) – List containing all the initialization files needed to run the CASCADe code.

• path ('pathlib.Path' or 'str') – Path extension to the defult path to the initialization files.

Raises:

ValueError – Raised when commands not recognized as valid

Examples

To make instance of TSOSuite class

>>> tso = cascade.TSO.TSOSuite()

execute(command, *init_files, path=None)

Excecute the pipeline commands.

This function checks if a command is valid and excecute it if True.

Parameters:

• command (str) – Command to be excecuted. If valid the method corresponding to the command will be excecuted

• *init_files (tuple of str) – Single or multiple file names of the .ini files containing the parameters defining the observation and calibration settings.

• path (str) – (optional) Filepath to the .ini files, standard value in None

Raises:

ValueError – error is raised if command is not valid

Examples

Example how to run the command to reset a tso object:

>>> tso.execute('reset')

initialize_tso(*init_files, path=None)

Initialize the tso obect.

This function initializess the TSO object by reading in a single or multiple .ini files

Parameters:

• *init_files (tuple of str) – Single or multiple file names of the .ini files containing the parameters defining the observation and calibration settings.

• path (str or ‘pathlib.Path’) – (optional) Filepath to the .ini files, standard value in None

Variables:

cascade_parameters – cascade.initialize.initialize.configurator

Raises:

FileNotFoundError – Raises error if .ini file is not found

Examples

To initialize a tso object excecute the following command:

>>> tso.execute("initialize", init_flle_name)

reset_tso()

Reset initialization of TSO object by removing all loaded parameters.

Examples

To reset the tso object excecute the following commend:

>>> tso.execute("reset")

load_data()

Load the observations into the tso object.

Load the transit time series observations from file, for the object, observatory, instrument and file location specified in the loaded initialization files

Variables:

observation (cascade.instruments.ObservationGenerator.Observation) – Instance of Observation class containing all observational data

Examples

To load the observed data into the tso object:

>>> tso.execute("load_data")

subtract_background()

Subtract the background from the observations.

Subtract median background determined from data or background model from the science observations.

Variables:

isBackgroundSubtracted (bool) – True if background is subtracted

Raises:

AttributeError – In case no background data is defined

Examples

To subtract the background from the spectral images:

>>> tso.execute("subtract_background")

filter_dataset()

Filter dataset.

This task used directional filters (edge preserving) to identify and flag all bad pixels and create a cleaned data set. In addition a data set of filtered (smoothed) spectral images is created.

To run this task the follwoing configuration parameters nood to be set:

• cascade_parameters.observations_data

• cascade_parameters.processing_sigma_filtering

In case the input data is a timeseries of 1D spectra addtionally the following parameters need to be set:

• cascade_parameters.processing_nfilter

• cascade_parameters.processing_stdv_kernel_time_axis_filter

In case of spectral images or cubes, the following configuration parameters are needed:

• cascade_parameters.processing_max_number_of_iterations_filtering

• cascade_parameters.processing_fractional_acceptance_limit_filtering

• cascade_parameters.cascade_use_multi_processes

Returns:

None.

Variables:

• cpm.cleanedDataset (SpectralDataTimeSeries) – A cleaned version of the spctral timeseries data of the transiting exoplanet system

• cpm.ilteredDataset ('SpectralDataTimeSeries') – A filtered (smoothed) version of the spctral timeseries data of the transiting exoplanet system

Raises:

AttributeError – In case needed parameters or data are not set an error is reaised.

Examples

To sigma clip the observation data stored in an instance of a TSO object, run the following example:

>>> tso.execute("filter_dataset")

determine_source_movement()

Deternine the relative movement during the timeseries observation.

This function determines the position of the source in the slit over time and the spectral trace. If the spectral trace and position are not already set, this task determines the telescope movement and position. First the absolute cross-dispersion position and initial spectral trace shift are determined. Finally, the relative movement of the telescope us measured using a cross corelation method.

To run this task the following configuration parameters need to be set:

• cascade_parameters.processing_quantile_cut_movement

• cascade_parameters.processing_order_trace_movement

• cascade_parameters.processing_nreferences_movement

• cascade_parameters.processing_main_reference_movement

• cascade_parameters.processing_upsample_factor_movement

• cascade_parameters.processing_angle_oversampling_movement

• cascade_parameters.cascade_verbose

• cascade_parameters.cascade_save_path

Variables:

• spectral_trace (ndarray) – The trace of the dispersed light on the detector normalized to its median position. In case the data are extracted spectra, the trace is zero.

• position (ndarray) – Postion of the source on the detector in the cross dispersion directon as a function of time, normalized to the median position.

• median_position (float) – median source position.

Raises:

AttributeError – Raises error if input observational data or type of data is not properly difined.

Examples

To determine the position of the source in the cross dispersion direction from the in the tso object loaded data set, excecute the following command:

>>> tso.execute("determine_source_movement")

correct_wavelengths()

Correct wavelengths.

This task corrects the wavelength solution for each spectral image in the time series. the following configuration parameters have to be set:

• cascade_parameters.cascade_verbose

• cascade_parameters.observations_data

The following product from the determine_source_movement task is required:

• cpm.spectral_movement

Returns:

None.

Variables:

• observation.dataset (SpectralDataTimeSeries) – Updated spectral dataset.

• cpm.filtered_dataset (SpectralDataTimeSeries) – Updated cleaned dataset

• cpm.cleaned_dataset (SpectralDataTimeSeries) – Updated filtered dataset

Raises:

AttributeError – Raises error if input observational data or type of data is not properly difined.

Note

1D spectra are assumed to be already corrected.

Examples

To correct the wavelengths for the observed, cleaned and filtered datasets, excecute the following command:

>>> tso.execute("correct_wavelengths")

set_extraction_mask()

Set the spectral extraction mask.

Set mask which defines the area of interest within which a transit signal will be determined. The mask is set along the spectral trace with a fixed width in pixels specified by the processing_nextraction parameter.

The following configureation parameters need to be set:

• cascade_parameters.processing_nextraction

The following data product set by the determine_source_movement task is needed for this task to be able to run:

• cpm.spectral_trace

• cpm.position

• cpm.med_position

Returns:

None

Variables:

cpm.extraction_mask (ndarray) – In case data are Spectra : 1D mask In case data are Spectral images or cubes: cube of 2D mask

Raises:

AttributeError – Raises error if the width of the mask or the source position and spectral trace are not defined.

Notes

The extraction mask is defined such that all True values are not used following the convention of numpy masked arrays

Examples

To set the extraction mask, which will define the sub set of the data from which the planetary spectrum will be determined, sexcecute the following command:

>>> tso.execute("set_extraction_mask")

check_wavelength_solution()

Check general wavelength solution.

Returns:

None.

extract_1d_spectra()

Extract 1d spectra from spectral images.

This task extracts the 1D spectra from spectral images of cubes. For this both an aperture extraction as well as an optimal extraction is performed. For the aperture extraction, a constant width mask along the spectral trace is used. For optimal extraction we use the definition by Horne 1986 [1] though our implementation to derive the extraction profile and flagging of ‘bad’ pixels is different.

To run this task the following tasks have to be executed prior to this tasks:

• filter_dataset

• determine_source_movement

• correct_wavelengths

• set_extraction_mask

The following configuration parameters are required:

• cascade_parameters.cascade_save_path

• cascade_parameters.observations_data

• cascade_parameters.cascade_verbose

• cascade_parameters.processing_rebin_factor_extract1d

• observation.dataset_parameters

Returns:

None.

Variables:

• observation..dataset_optimal_extracted (SpectralDataTimeSeries) – Time series of optimally extracted 1D spectra.

• observation.dataset_aperture_extracted (SpectralDataTimeSeries) – Time series of apreture extracted 1D spectra.

• cpm.extraction_profile ('ndarray')

• cpm.extraction_profile_mask ('ndarray' of type 'bool')

Raises:

AttributeError, AssertionError – An error is raised if the data and cleaned data sets are not defined, the source position is not determined or of the parameters for the optimal extraction task are not set in the initialization files.

Notes

We use directional filtering rather than a polynomial fit along the trace as in the original paper by Horne 1986 to determine the extraction profile

References

[1]

Horne 1986, PASP 98, 609

Examples

To extract the 1D spectra of the target, excecute the following command:

>>> tso.execute("extract_1d_spectra")

calibrate_timeseries()

Run the causal regression model.

To calibrate the input spectral light curve data and to extract the planetary signal as function of wavelength a linear model is fit to the lightcurve data for each wavelength.

Variables:

calibration_results (SimpleNamespace) – The calibration_results attribute contains all calibrated data and auxilary data.

Raises:

AttributeError – an Error is raised if the nessecary steps to be able to run this task have not been executed properly or if the parameters for the regression model have not been set in the initialization files.

Examples

To create a calibrated spectral time series and derive the planetary signal execute the following command:

>>> tso.execute("calibrate_timeseries")

save_results()

Save results.

Raises:

AttributeError –

Examples

To save the calibrated spectrum, execute the following command:

>>> tso.execute("save_results")

combine_observations(target_name, observations_ids, path=None, verbose=True, use_resolution='nominal')

Combine with CASCADe calibrated individual observations into one spectrum.

Parameters:

• target_name ('str') – Name of the target.

• observations_ids ('list' of 'str') – Unique idensifier for each observations to be combined.

• path ('str' or 'pathlib.Path', optional) – Path to data. The default is None.

• verbose ('bool', optional) – Flag, if True, will cause CASCAde to produce verbose output (plots). The default is True.

• use_higher_resolution ('str', optional) – The default is ‘nominal’. Can have values ‘lower’, ‘nominal’, ‘higher’

Returns:

None.

combine_timeseries(target_name, observations_ids, file_extension, meta_list, path=None, verbose=True)

Combine and rebin spectral timeseries to common wavelength grid.

Parameters:

• target_name ('str') – DESCRIPTION.

• observations_ids ('list') – DESCRIPTION.

• file_extension ('str') – DESCRIPTION.

• meta_list ('list') – DESCRIPTION.

• path ('str' or 'pathlib.Path', optional) – DESCRIPTION. The default is None.

• verbose ('bool', optional) – DESCRIPTION. The default is True.

Returns:

• rebinned_datasets (‘dict’) – Rebinned datasets

• band_averaged_datasets (‘dict’) – Band averaged spectral datasets

• datasets_dict (‘dict’) – Input datasets

_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