POSEIDON.instrument =================== .. py:module:: POSEIDON.instrument .. autoapi-nested-parse:: Functions to computes various instrument properties and simulate data points. Functions --------- .. autoapisummary:: POSEIDON.instrument.fwhm_instrument POSEIDON.instrument.fwhm_IRTF_SpeX POSEIDON.instrument.init_instrument POSEIDON.instrument.make_model_data POSEIDON.instrument.bin_spectrum_to_data POSEIDON.instrument.R_to_wl POSEIDON.instrument.generate_syn_data_from_user POSEIDON.instrument.generate_syn_data_from_file POSEIDON.instrument.weighted_mean POSEIDON.instrument.create_binned_down_data_from_pandexo Module Contents --------------- .. py:function:: 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. :param wl_data: Bin centre wavelengths of data points (μm). :type wl_data: np.array of float :param instrument: Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2). :type instrument: str :returns: Full width at half maximum as a function of wavelength (μm). :rtype: fwhm (np.array of float) .. py:function:: fwhm_IRTF_SpeX(wl_data) Calculate the wavelength dependent FWHM for the SpeX prism on the NASA Infrared Telescope Facility. :param wl_data: Bin centre wavelengths of data points (μm). :type wl_data: np.array of float :returns: Full width at half maximum as a function of wavelength (μm). :rtype: fwhm (np.array of float) .. py:function:: 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. :param wl: Model wavelength grid (μm). :type wl: np.array of float :param wl_data: Bin centre wavelengths of data points (μm). :type wl_data: np.array of float :param half_width: Bin half widths of data points (μm). :type half_width: np.array of float :param instrument: Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2). :type instrument: str :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. :rtype: sigma (np.array of float) .. py:function:: 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. :param spectrum: Model spectrum. :type spectrum: np.array of float :param wl: Model wavelength grid (μm). :type wl: np.array of float :param sigma: Standard deviation of PSF for each data point (grid space unit). :type sigma: np.array of float :param sensitivity: Instrument transmission function interpolated to model wavelengths. :type sensitivity: np.array of float :param bin_left: Closest index on model grid of the left bin edge for each data point. :type bin_left: np.array of int :param bin_cent: Closest index on model grid of the bin centre for each data point. :type bin_cent: np.array of int :param bin_right: Closest index on model grid of the right bin edge for each data point. :type bin_right: np.array of int :param norm: Normalisation constant of the transmission function for each data bin. :type norm: np.array of float :param photometric: If True, skip the PSF convolution (e.g. for Spitzer IRAC data). :type photometric: bool :returns: Model spectrum convolved and binned to the data resolution. :rtype: ymodel (np.array of float) .. py:function:: 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. :param spectrum: Model spectrum. :type spectrum: np.array of float :param wl: Model wavelength grid (μm). :type wl: np.array of float :param data_properties: Collection of data properties required for POSEIDON's instrument simulator (i.e. to create simulated binned data during retrievals). :type data_properties: dict :returns: Model spectrum convolved and binned to the data resolution. :rtype: ymodel (np.array of float) .. py:function:: 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. :param R_data: Spectral resolution (wl/dwl) of the data. :type R_data: float :param wl_data_min: Starting wavelength of new data grid (μm). :type wl_data_min: float :param wl_data_max: Ending wavelength of new data grid (μm). :type wl_data_max: float :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). :rtype: wl_data (np.array of float) .. py:function:: 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. :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param wl_model: Model wavelength grid (μm). :type wl_model: np.array of float :param spectrum: Model spectrum. :type spectrum: np.array of float :param data_dir: Directory where the synthetic datafile will be written. :type data_dir: str :param instrument: Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2). :type instrument: str :param R_data: Spectral resolution (wl/dwl) of the synthetic dataset. :type R_data: float :param err_data: Precision of the synthetic dataset, assumed constant with wl (ppm). :type err_data: float :param wl_start: Starting wavelength of the synthetic dataset (μm). :type wl_start: float :param wl_end: Ending wavelength of the synthetic dataset (μm). :type wl_end: float :param label: Optional descriptive label to add to file name. :type label: str :param Gauss_scatter: If True, applies Gaussian scatter with 1σ = err_data. :type Gauss_scatter: bool :returns: None. .. py:function:: 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. :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param wl_model: Model wavelength grid (μm). :type wl_model: np.array of float :param spectrum: Model spectrum. :type spectrum: np.array of float :param data_dir: Directory where the synthetic datafile will be written. :type data_dir: str :param instrument: Instrument name corresponding to the dataset (e.g. WFC3_G141, JWST_NIRSpec_PRISM, JWST_NIRISS_SOSS_Ord2). :type instrument: str :param R_to_bin: Output spectral resolution for rebinning each instrument's data. :type R_to_bin: list of float :param N_trans: Number of transits observed by each instrument. :type N_trans: list of float :param label: Optional descriptive label to add to file name. :type label: str :param Gauss_scatter: If True, applies Gaussian scatter with 1σ = err_data. :type Gauss_scatter: bool :returns: None. .. py:function:: weighted_mean(data, err) calculates the weighted mean for data points data with std devs. err By: Munazza Alam, Harvard University (2018) .. py:function:: create_binned_down_data_from_pandexo(file_name, wl, R_to_bin, stored_directory, saved_directory, is_miri=True)