The cascade.instruments module

Top level Observatory and Instruments specific module of the CASCADe package.

class Observation[source]

Bases: object

This class handles the selection of the correct observatory and instrument classes and loads the time series data to be analyzed The observations specific parameters set during the initialization of the TSO object are used to select the observatory and instrument through a factory method and to load the specified observations into the instance of the TSO object.

Examples

The Observation calss is called during the following command:

>>> tso.execute("load_data")
property __valid_observatories

Dictionary listing the current implemented observatories, used in factory method to select a observatory specific class

property __valid_observation_type

Set listing the current implemented observation types

__do_observations(observatory)

Factory method to load the needed observatory class and methods

__get_observatory_name()

Function to load the in the .ini files specified observatory name

Returns:

ValueError – Returns error if the observatory is not specified or recognized

__check_observation_type()

Function to check of the in the .ini specified observation type valid.

Raises:

ValueError – Raises error if the specified observation type is not valid or if the tso instance is not initialized.

Observatory and Instruments specific module of the CASCADe package defining the base classes defining the properties of an Instrument or Observatory class.

class ObservatoryBase[source]

Bases: object

Observatory base class used to define the basic properties an observatory class should have

abstract property name

Name of the observatory.

abstract property location

Location of the observatory

abstract property NAIF_ID

NAIF ID of the observatory. With this the location relative to the sun and the observed target as a function of time can be determined. Needed to calculate BJD time.

abstract property observatory_instruments

The names of the instruments part of the observatory.

class InstrumentBase[source]

Bases: object

Instrument base class used to define the basic properties an instrument class should have

abstract load_data()[source]

Method which allows to load data.

abstract get_instrument_setup()[source]

Method which gets the specific setup of the used instrument.

abstract property name

Name of the instrument.

HST Observatory and Instruments specific module of the CASCADe package.

class HST[source]

Bases: ObservatoryBase

Class defining HST observatory.

This observatory class defines the instuments and data handling for the spectropgraphs of the Hubble Space telescope.

property name

Name of observatory.

Returns ‘HST’

property location

Location of observatory.

Returns ‘SPACE’

property collecting_area

Size of the collecting area of the telescope.

Returns:

4.525 m**2

property NAIF_ID

NAIF ID of observatory.

Returns -48 for HST observatory

property observatory_instruments

Instruments of the HST observatory usable with CASCADe.

Returns:

{‘WFC3’}

class HSTWFC3[source]

Bases: InstrumentBase

Defines the WFC3 instrument.

This instrument class defines the properties of the WFC3 instrument of the Hubble Space Telescope

For the instrument and observations the following valid options are available:

  • detector subarrays : {‘IRSUB128’, ‘IRSUB256’, ‘IRSUB512’, ‘GRISM128’, ‘GRISM256’, ‘GRISM512’, ‘GRISM1024’}

  • spectroscopic filters : {‘G141’, ‘G102’}

  • imaging filters{‘F139M’, ‘F132N’, ‘F167N’, ‘F126N’, ‘F130N’,

    ‘F140W’}

  • data type : {‘SPECTRUM’, ‘SPECTRAL_IMAGE’, ‘SPECTRAL_CUBE’}

  • observing strategy : {‘STARING’}

  • data products : {‘SPC’, ‘flt’, ‘COE’}

property name

Define name of instrument.

This function returns the tame of the HST instrument: ‘WFC3’

load_data()[source]

Load observational data.

This function loads the WFC3 data form disk based on the parameters defined during the initialization of the TSO object.

get_instrument_setup()[source]

Get all instrument parameters.

This funtion retrieves all relevant parameters defining the instrument and observational data setup.

Returns:

par (collections.OrderedDict) – Dictionary containg all relevant parameters

Raises:

ValueError – If obseervationla parameters are not or incorrect defined an error will be raised

get_spectra(is_background=False)[source]

Load spectral(1D) timeseries data.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

get_spectral_images(is_background=False)[source]

Get spectral image timeseries data.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral image timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

get_spectral_cubes(is_background=False)[source]

Load spectral cubes.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral image cubes timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

_create_mask_from_dq(dq_cube)[source]

Create mask from DQ cube.

Parameters:

dq_cube (TYPE) – DESCRIPTION.

Returns:

mask (TYPE) – DESCRIPTION.

Note

Standard bit values not to flag are 0, 12 and 14. Bit valiue 10 (blobs) is not set by default but can be selected not to be flagged in case of problem.

_determine_position_offset(scan_offset_x, scan_offset_y, cal_offset_x, cal_offset_y)[source]

Determine the scan offset.

Parameters:
  • scan_offset_x (TYPE) – DESCRIPTION.

  • scan_offset_y (TYPE) – DESCRIPTION.

Returns:

None.

_determine_scan_offset(scan_offset_x, scan_offset_y, cal_offset_x, cal_offset_y, scan_length, total_scan_length, scan_directions)[source]

Determine the scan offset.

Parameters:
  • scan_offset_x (TYPE) – DESCRIPTION.

  • scan_offset_y (TYPE) – DESCRIPTION.

  • scan_length ('ndarray') – Scan length covered during exposure.

  • total_scan_length ('ndarray') – Total scan length.

  • scan_directions (TYPE) – DESCRIPTION.

Returns:

None.

static _get_cube_cal_type(hdul)[source]

Determine the type of applied flux calibration of the spectral cubes.

This function checks which type of flux calibraiton has been applied to the spetral data cubes and returns the calibration type according to the values of the relevant header keywords found in the fits data files.

Parameters:

hdul ('astropy.io.fits.hdu.hdulist.HDUList')

Returns:

calType (‘str’)

Raises:

ValueError

static _is_sparse_sequence(hdul)[source]

Check fo sparse sequence.

This funtion checks for SPARSE timing sequence. If so, the first readout time is shorter than the rest and should be discarded.

Parameters:

hdul ('astropy.io.fits.hdu.hdulist.HDUList')

Returns:

isSparse (‘bool’)

_define_convolution_kernel()[source]

Define convolution kernel.

Define the instrument specific convolution kernel which will be used in the correction procedure of bad pixels.

_define_region_of_interest()[source]

Define ROI.

Defines region on detector which containes the intended target star.

_get_background_cal_data()[source]

Get all calibration data for background fit.

Get the calibration data from which the background in the science images can be determined.

Raises:

FileNotFoundError, AttributeError – An error is raised if the calibration images are not found or the background data is not properly defined.

_fit_background(science_data_in)[source]

Fit background.

Determes the background in the HST Grism data using a model for the background to the spectral timeseries data

Parameters:

science_data_in (masked quantity) – Input data for which the background will be determined

Returns:

SpectralTimeSeries (SpectralDataTimeSeries) – The fitted IR bacgound as a function of time

Notes

All details of the implemented model is described in:

http://www.stsci.edu/hst/wfc3/documents/ISRs/WFC3-2015-17.pdf

_determine_source_position_from_cal_image(calibration_image_cube, calibration_data_files)[source]

Determine the source position from the target aquicition image.

Determines the source position on the detector of the target source in the calibration image takes prior to the spectroscopic observations.

Parameters:
  • calibration_image_cube (ndarray) – Cube containing all acquisition images of the target.

  • calibration_data_files (list of str) – List containing the file names associated with the calibraton data.

Variables:

calibration_source_position (list’ of `tuple) – The position of the source in the acquisition images associated with the HST spectral timeseries observations.

_read_grism_configuration_files()[source]

Get the relevant data from the WFC3 configuration files.

Variables:
  • DYDX (list) – The parameters for the spectral trace

  • DLDP ('list`) – The parameters for the wavelength calibration

Raises:

ValueError – An error is raised if the parameters associated with the specified instrument mode can not be found in the calibration file.

_read_reference_pixel_file()[source]

Get the reference pixel.

Read the calibration file containig the definition of the reference pixel appropriate for a given sub array and or filer

Variables:

reference_pixels (collections.OrderedDict) – Ordered dict containing the reference pixels to be used in the wavelength calibration.

static _search_ref_pixel_cal_file(ptable, inst_aperture, inst_filter)[source]

Search for the reference pixel.

Search the reference pixel calibration file for the reference pixel given the instrument aperture and filter.

Parameters:
  • ptable (dict) – Calibratrion table with reference positions

  • inst_aperture (str) – The instrument aperture

  • inst_filter (str) – The instrument filter

Returns:

  • XREF (float) – X reference position for the acquisition image

  • YREF (float) – Y reference position for the acquisition image

Raises:

ValueError – An error is raises if the instrument aperture if filter is not fount in the calibration table

_get_subarray_size(calibration_data, spectral_data)[source]

Get the size of the used WFC3 subarray.

This function determines the size of the used subarray.

Parameters:
  • calibration_data

  • spectral_data

Variables:

subarray_sizes

Raises:

AttributeError

_get_wavelength_calibration()[source]

Return the WFC3 wavelength calibration.

Using the source position determined from the aquisition image this function returns the wavelength solution for the spectra.

Returns:

wave_cal (ndarray) – Wavelength calibration of the observation.

Raises:

AttributeError – An error is raised if the necessary calibration data is not yet defined.

get_spectral_trace()[source]

Get spectral trace.

Returns:

spectral_trace (collections.OrderedDict) – The spectral trace of the dispersed light (both position and wavelength)

Raises:

AttributeError – An error is raised in the necessary calibration data is not yet defined.

static _WFC3Trace(xc, yc, DYDX, xref=522, yref=522, xref_grism=522, yref_grism=522, subarray=256, subarray_grism=256)[source]

Define the spectral trace for the wfc3 grism modes.

Parameters:
  • xc

  • yc

  • DYDX

  • xref=522

  • yref=522

  • xref_grism=522

  • yref_grism=522

  • subarray=256

  • subarray_grism=256

Returns:

trace

static _WFC3Dispersion(xc, yc, DYDX, DLDP, xref=522, yref=522, xref_grism=522, yref_grism=522, subarray=256, subarray_grism=256)[source]

Convert pixel coordinate to wavelength.

Parameters:
  • xc ('float') – X coordinate of direct image centroid

  • yc ('float') – Y coordinate of direct image centroid

  • xref ('int') – Reference X coordinate of target aquisition image. Default 522

  • yref ('int') – Reference Y coordinate of target aquisition image. Default 522

  • xref_grism ('int') – Reference X coordinate of used grism spectral image. Default 522

  • yref_grism – Reference Y coordinate of used grism spectral image. Default 522

  • subarray ('int') – Used subarray of target aquisition image. Default 256

  • subarray_grism ('int') – Used subarray of spectral image. Default 256

Returns:

wavelength (‘astropy.units.core.Quantity’) – return wavelength mapping of x coordinate in micron

Notes

For details of the method and coefficient adopted see [1] and [2]. See also: http://www.stsci.edu/hst/wfc3/documents/ISRs/WFC3-2016-15.pdf

In case the direct image and spectral image are not taken with the same aperture, the centroid measurement is adjusted according to the table in: http://www.stsci.edu/hst/observatory/apertures/wfc3.html

References

Spitzer Observatory and Instruments specific module of the CASCADe package

class Spitzer[source]

Bases: ObservatoryBase

Class defining the Spitzer observatory.

This observatory class defines the instuments and data handling for the spectropgraphs of the Spitzer Space telescope

property name

Name of the observatory.

property location

Location of the observatory.

property collecting_area

Size of the collecting area of the telescope.

Returns:

0.5 m**2

property NAIF_ID

NAIF_ID of the observatory.

property observatory_instruments

All implemented instruments of the observatory.

class SpitzerIRS[source]

Bases: InstrumentBase

Class defining the IRS instrument.

This instrument class defines the properties of the IRS instrument of the Spitzer Space Telescope. For the instrument and observations the following valid options are available:

  • detectors : {‘SL’, ‘LL’}

  • spectral orders : {‘1’, ‘2’}

  • data products : {‘droop’, ‘COE’}

  • observing mode : {‘STARING’, ‘NODDED’}

  • data type : {‘SPECTRUM’, ‘SPECTRAL_IMAGE’, ‘SPECTRAL_DETECTOR_CUBE’}

property name

Reteurn instrument name.

load_data()[source]

Load data.

get_instrument_setup()[source]

Retrieve all parameters defining the instrument and data setup.

get_spectra(is_background=False)[source]

Get the 1D spectra.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

get_spectral_images(is_background=False)[source]

Get the 2D spectral images.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

Notes

Notes on FOV:

in the fits header the following relevant info is used:

  • FOVID 26 IRS_Short-Lo_1st_Order_1st_Position

  • FOVID 27 IRS_Short-Lo_1st_Order_2nd_Position

  • FOVID 28 IRS_Short-Lo_1st_Order_Center_Position

  • FOVID 29 IRS_Short-Lo_Module_Center

  • FOVID 32 IRS_Short-Lo_2nd_Order_1st_Position

  • FOVID 33 IRS_Short-Lo_2nd_Order_2nd_Position

  • FOVID 34 IRS_Short-Lo_2nd_Order_Center_Position

  • FOVID 40 IRS_Long-Lo_1st_Order_Center_Position

  • FOVID 46 IRS_Long-Lo_2nd_Order_Center_Position

Notes on timing:

  • FRAMTIME the total effective exposure time (ramp length) in seconds

_define_convolution_kernel()[source]

Define the instrument specific convolution kernel.

This function defines an instrument specific convolution kernel which will be used in the correction procedure of bad pixels.

_define_region_of_interest()[source]

Define region on detector.

This functon defines the region of interest which containes the intended target star. It defines a mask such that all data flagged or of no interest for the data calibraiton and spectral extraction.

_get_order_mask()[source]

Get the order mask.

This functions gets the mask which defines the pixels used with a given spectral order

_get_wavelength_calibration(numberOfWavelengthPixels, nodOffset)[source]

Get wavelength calibration file.

Parameters:
  • numberOfWavelengthPixels ('int')

  • nodOffset ('float')

get_detector_cubes(is_background=False)[source]

Get 3D detector cubes.

This function combines all functionallity to read fits files containing the (uncalibrated) detector cubes (detector data on ramp level) timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

Notes

Notes on timing in header:

There are several integration-time-related keywords. Of greatest interest to the observer is the “effective integration time”, which is the time on-chip between the first and last non-destructive reads for each pixel. It is called:

RAMPTIME = Total integration time for the current DCE.

The value of RAMPTIME gives the usable portion of the integration ramp, occurring between the beginning of the first read and the end of the last read. It excludes detector array pre-conditioning time. It may also be of interest to know the exposure time at other points along the ramp. The SUR sequence consists of the time taken at the beginning of a SUR sequence to condition the array (header keyword DEADTIME), the time taken to complete one read and one spin through the array (GRPTIME), and the non-destructive reads separated by uniform wait times. The wait consists of “clocking” through the array without reading or resetting. The time it takes to clock through the array once is given by the SAMPTIME keyword. So, for an N-read ramp:

RAMPTIME = 2x(N-1)xSAMPTIME

and

DCE duration = DEADTIME + GRPTIME + RAMPTIME

Note that peak-up data is not obtained in SUR mode. It is obtained in Double Correlated Sampling (DCS) mode. In that case, RAMPTIME gives the time interval between the 2nd sample and the preceeding reset.

get_spectral_trace()[source]

Get spectral trace.

Generic Observatory and Instruments specific module of the CASCADe package

class Generic[source]

Bases: ObservatoryBase

Genericobservatory class.

This observatory class defines the instuments and data handling for the spectropgraphs of a Generic observatory

property name

Set to ‘Generic’.

property location

Set to ‘UNKNOWN’.

property collecting_area

Size of the collecting area of the telescope.

Returns:

UNKNOWN

property NAIF_ID

Set to None.

property observatory_instruments

Return {‘GenericSpectrograph’}.

class GenericSpectrograph[source]

Bases: InstrumentBase

GenericSpectrograph class.

This instrument class defines the properties for a Generic spectrograph on a generic observatory

For the instrument and observations the following valid options are available:

  • data type : {‘SPECTRUM’}

  • observing strategy : {‘STARING’}

property name

‘GenericSpectrograph’.

Type:

Name of the Generic instrument

load_data()[source]

Load the observations.

This function loads data from a Generic obsevatory and instrument from disk based on the parameters defined during the initialization of the TSO object.

get_instrument_setup()[source]

Retrieve relevant parameters defining the instrument and data setup.

Returns:

par (collections.OrderedDict) – Dictionary containg all relevant parameters

Raises:

ValueError – If obseervationla parameters are not or incorrect defined an error will be raised

get_spectra(is_background=False)[source]

Read the input spectra.

This function combines all functionallity to read fits files containing the (uncalibrated) spectral timeseries, including orbital phase and wavelength information

Parameters:

is_background (bool) – if True the data represents an observaton of the IR background to be subtracted of the data of the transit spectroscopy target.

Returns:

SpectralTimeSeries (cascade.data_model.SpectralDataTimeSeries) – Instance of SpectralDataTimeSeries containing all spectroscopic data including uncertainties, time, wavelength and bad pixel mask.

Raises:

AssertionError, KeyError – Raises an error if no data is found or if certain expected fits keywords are not present in the data files.

_define_convolution_kernel()[source]

Define the instrument specific convolution kernel.

This function defines the convolution kernel which can be used in the correction procedure of bad pixels

_define_region_of_interest()[source]

Defines region on detector which containes the intended target star.

get_spectral_trace()[source]

Get spectral trace.