POSEIDON.instrument

Functions to computes various instrument properties and simulate data points.

Module Contents

Functions

fwhm_instrument(wl_data, instrument)

Evaluate the full width at half maximum (FWHM) for the Point Spread

fwhm_IRTF_SpeX(wl_data)

Calculate the wavelength dependent FWHM for the SpeX prism on the NASA

init_instrument(wl, wl_data, half_width, instrument)

Initialise required properties for a specific instrument.

make_model_data(spectrum, wl, sigma, sensitivity, ...)

Produce binned model points at the same wavelengths and spectral resolution

bin_spectrum_to_data(spectrum, wl, data_properties)

Generate the equivalent model predicted spectrum at the spectral resolution

R_to_wl(R_data, wl_data_min, wl_data_max)

Convert a given spectral resolution to the equivalent set of wavelengths

generate_syn_data_from_user(planet, wl_model, ...[, ...])

Generate and write to file a synthetic dataset with a user specified

generate_syn_data_from_file(planet, wl_model, ...[, ...])

Generate and write to file a synthetic dataset with the same precision as
POSEIDON.instrument.fwhm_instrument(wl_data, instrument)

Evaluate the full width at half maximum (FWHM) for the Point Spread Function (PSF) of a given instrument mode at each bin centre wavelength.

FWHM (μm) = wl (μm) / R_native

This assumes a Gaussian PSF with FWHM = native instrument spectral resolution.

Parameters:

  • wl_data (np.array of float) – Bin centre wavelengths of data points (μm).

  • instrument (str) – Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2).

Returns:

Full width at half maximum as a function of wavelength (μm).

Return type:

fwhm (np.array of float)

POSEIDON.instrument.fwhm_IRTF_SpeX(wl_data)

Calculate the wavelength dependent FWHM for the SpeX prism on the NASA Infrared Telescope Facility.

Parameters:

wl_data (np.array of float) – Bin centre wavelengths of data points (μm).

Returns:

Full width at half maximum as a function of wavelength (μm).

Return type:

fwhm (np.array of float)

POSEIDON.instrument.init_instrument(wl, wl_data, half_width, instrument)

Initialise required properties for a specific instrument.

This function conducts the following steps:

  1. Read in the instrument sensitivity functions.

  2. Read in FWHM of the instrument PSF.

  3. Find the indices on the model wavelength grid closest to the bin centre of each data point and the corresponding left/right bin edges.

  4. Pre-compute the integral of the sensitivity function over each bin (i.e. a normalising factor).

These values are then stored for later usage, so this function need only be run once at the beginning of a retrieval.

Parameters:

  • wl (np.array of float) – Model wavelength grid (μm).

  • wl_data (np.array of float) – Bin centre wavelengths of data points (μm).

  • half_width (np.array of float) – Bin half widths of data points (μm).

  • instrument (str) – Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2).

Returns:

Standard deviation of PSF for each data point (grid space unit). fwhm (np.array of float):

Full width at half maximum as a function of wavelength (μm).

sensitivity (np.array of float):

Instrument transmission function interpolated to model wavelengths.

bin_left (np.array of int):

Closest index on model grid of the left bin edge for each data point.

bin_cent (np.array of int):

Closest index on model grid of the bin centre for each data point.

bin_right (np.array of int):

Closest index on model grid of the right bin edge for each data point.

norm (np.array of float):

Normalisation constant of the transmission function for each data bin.

Return type:

sigma (np.array of float)

POSEIDON.instrument.make_model_data(spectrum, wl, sigma, sensitivity, bin_left, bin_cent, bin_right, norm, photometric=False)

Produce binned model points at the same wavelengths and spectral resolution as the observed data for a single instrument.

This function conducts the following steps:

  1. Convolve the model with the instrument PSF for each data point.

  2. Integrate the convolved spectrum over the instrument sensitivity function.

  3. Produce binned model points via normalisation of the sensitivity function.

For photometric bands, step (1) is not necessary.

Parameters:

  • spectrum (np.array of float) – Model spectrum.

  • wl (np.array of float) – Model wavelength grid (μm).

  • sigma (np.array of float) – Standard deviation of PSF for each data point (grid space unit).

  • sensitivity (np.array of float) – Instrument transmission function interpolated to model wavelengths.

  • bin_left (np.array of int) – Closest index on model grid of the left bin edge for each data point.

  • bin_cent (np.array of int) – Closest index on model grid of the bin centre for each data point.

  • bin_right (np.array of int) – Closest index on model grid of the right bin edge for each data point.

  • norm (np.array of float) – Normalisation constant of the transmission function for each data bin.

  • photometric (bool) – If True, skip the PSF convolution (e.g. for Spitzer IRAC data).

Returns:

Model spectrum convolved and binned to the data resolution.

Return type:

ymodel (np.array of float)

POSEIDON.instrument.bin_spectrum_to_data(spectrum, wl, data_properties)

Generate the equivalent model predicted spectrum at the spectral resolution of the data. This function serves as a wrapper, unpacking the POSEIDON data_properties dictionary and calling ‘make_model_data’ to handle the binning for each instrument separately.

Parameters:

  • spectrum (np.array of float) – Model spectrum.

  • wl (np.array of float) – Model wavelength grid (μm).

  • data_properties (dict) – Collection of data properties required for POSEIDON’s instrument simulator (i.e. to create simulated binned data during retrievals).

Returns:

Model spectrum convolved and binned to the data resolution.

Return type:

ymodel (np.array of float)

POSEIDON.instrument.R_to_wl(R_data, wl_data_min, wl_data_max)

Convert a given spectral resolution to the equivalent set of wavelengths and bin half-widths.

Parameters:

  • R_data (float) – Spectral resolution (wl/dwl) of the data.

  • wl_data_min (float) – Starting wavelength of new data grid (μm).

  • wl_data_max (float) – Ending wavelength of new data grid (μm).

Returns:

New wavelength grid spaced with the desired spectral resolution (μm). half_width_data (np.array of float):

Half bin width for the new wavelength grid (μm).

Return type:

wl_data (np.array of float)

POSEIDON.instrument.generate_syn_data_from_user(planet, wl_model, spectrum, data_dir, instrument, R_data=100, err_data=50, wl_start=1.1, wl_end=1.8, label=None, Gauss_scatter=True)

Generate and write to file a synthetic dataset with a user specified spectral resolution, precision, and wavelength range. Gaussian scatter can be optionally disabled, with the data lying on the binned model points.

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

  • wl_model (np.array of float) – Model wavelength grid (μm).

  • spectrum (np.array of float) – Model spectrum.

  • data_dir (str) – Directory where the synthetic datafile will be written.

  • instrument (str) – Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2).

  • R_data (float) – Spectral resolution (wl/dwl) of the synthetic dataset.

  • err_data (float) – Precision of the synthetic dataset, assumed constant with wl (ppm).

  • wl_start (float) – Starting wavelength of the synthetic dataset (μm).

  • wl_end (float) – Ending wavelength of the synthetic dataset (μm).

  • label (str) – Optional descriptive label to add to file name.

  • Gauss_scatter (bool) – If True, applies Gaussian scatter with 1σ = err_data.

Returns:

None.

POSEIDON.instrument.generate_syn_data_from_file(planet, wl_model, spectrum, data_dir, data_properties, R_to_bin=[], N_trans=[], label=None, Gauss_scatter=True)

Generate and write to file a synthetic dataset with the same precision as an externally provided file. The synthetic dataset can optionally be rebinned and/or scaled by 1/sqrt(N) for additional transits. Rebinning or additional transits will adjust the data precision accordingly. If no rebinning is requested, the synthetic dataset will have the same wavelength grid as the external file. The user can also disable Gaussian scattering, in which case the data will coincide with the binned model points.

Parameters:

  • planet (dict) – Collection of planetary properties used by POSEIDON.

  • wl_model (np.array of float) – Model wavelength grid (μm).

  • spectrum (np.array of float) – Model spectrum.

  • data_dir (str) – Directory where the synthetic datafile will be written.

  • instrument (str) – Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2).

  • R_to_bin (list of float) – Output spectral resolution for rebinning each instrument’s data.

  • N_trans (list of float) – Number of transits observed by each instrument.

  • label (str) – Optional descriptive label to add to file name.

  • Gauss_scatter (bool) – If True, applies Gaussian scatter with 1σ = err_data.

Returns:

None.