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 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:
- 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:
- _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
Notes
Details can be found in:
and
- http://www.stsci.edu/hst/instrumentation/wfc3/documentation/
grism-resources
- 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.
- 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.
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