POSEIDON.high_res
=================

.. py:module:: POSEIDON.high_res


Functions
---------

.. autoapisummary::

   POSEIDON.high_res.airtovac
   POSEIDON.high_res.vactoair
   POSEIDON.high_res.read_hdf5
   POSEIDON.high_res.read_high_res_data
   POSEIDON.high_res.fit_uncertainties
   POSEIDON.high_res.blaze_correction
   POSEIDON.high_res.prepare_high_res_data
   POSEIDON.high_res.sysrem
   POSEIDON.high_res.fast_filter
   POSEIDON.high_res.make_data_cube
   POSEIDON.high_res.PCA_rebuild
   POSEIDON.high_res.fit_out_transit_spec
   POSEIDON.high_res.get_RV_range
   POSEIDON.high_res.cross_correlate
   POSEIDON.high_res.plot_CCF_phase_RV
   POSEIDON.high_res.find_nearest_idx
   POSEIDON.high_res.plot_CCF_Kp_Vsys
   POSEIDON.high_res.loglikelihood_PCA
   POSEIDON.high_res.loglikelihood_sysrem
   POSEIDON.high_res.loglikelihood_high_res
   POSEIDON.high_res.get_rot_kernel
   POSEIDON.high_res.remove_outliers
   POSEIDON.high_res.transit_model
   POSEIDON.high_res.make_injection_data


Module Contents
---------------

.. py:function:: airtovac(wlum)

.. py:function:: vactoair(wlum)

.. py:function:: read_hdf5(file_path)

.. py:function:: read_high_res_data(data_dir, names=None)

.. py:function:: fit_uncertainties(flux, n_components=5, initial_guess=[0.1, 200], Print=True)

.. py:function:: blaze_correction(flux, filter_size, Print=True)

.. py:function:: prepare_high_res_data(data_dir, name, spectrum_type, method, flux, wl_grid, phi, uncertainties=None, transit_weight=None, V_bary=None, pca_ncomp=4, sysrem_niter=15)

.. py:function:: sysrem(data_array, uncertainties, niter=15)

   SYSREM procedure adapted from https://github.com/stephtdouglas/PySysRem, originally used for detrending light curves.

   Use this function in a high resolutional rerieval.
   nord: number of spectral order.
   nphi: number of time-resolved phases.
   npix: number of wavelengths per spectral order.

   :param data_array: Blaze-corrected data of a single order.
                      Shape: (nphi x npix)
   :type data_array: 2D np.array of float
   :param uncertainties: Time and wavelength dependent uncertainties obtained from fit_uncertainties.
                         Shape: (nphi x npix)
   :type uncertainties: np.array of float
   :param Niter: Number of basis vectors to consider.
   :type Niter: int

   :returns:     2D Array representing the residuals data of a single order after filtering.
                 Shape: (nphi x npix)

             U (2D np.array of float):
                 Basis vectors obtained from SYSREM of a single vector.
                 Shape: (nphi x N_iter + 1)
   :rtype: residuals (np.array of float)


.. py:function:: fast_filter(flux, uncertainties, niter=15, Print=True)

   TODO: Add docstrings.
   Use this function in a high resolutional rerieval.

   Args:

   :returns:     The residuals data of a single order after filtering.
                 Shape: (nord x nphi x npix)

             Us (3D np.array of float):
                 Basis vectors obtained from SYSREM of a single vector.
                 Shape: (nord x nphi x N_iter+1)
   :rtype: residuals (3D np.array of float)


.. py:function:: make_data_cube(data, n_components=4)

.. py:function:: PCA_rebuild(flux, n_components=5)

.. py:function:: fit_out_transit_spec(flux, transit_weight, degree=2, spec='median', Print=True)

.. py:function:: get_RV_range(Kp_range, Vsys_range, phi)

.. py:function:: cross_correlate(Kp_range, Vsys_range, RV_range, wl, planet_spectrum, data, Print=True)

.. py:function:: plot_CCF_phase_RV(phi, RV_range, CCF_phase_RV, label=None, save_file_path=None, cmap=cmr.ember)

.. py:function:: find_nearest_idx(array, value)

   Function that will find the index of the value in the array nearest a given value

       Input: array, number

       Output: index of value in array closest to that number


.. py:function:: plot_CCF_Kp_Vsys(Kp_range, Vsys_range, CCF_Kp_Vsys, label=None, Kp_expected=None, Vsys_expected=None, RM_mask_size=10, plot_slice=False, save_file_path=None, cmap=cmr.ember)

.. py:function:: loglikelihood_PCA(V_sys, K_p, d_phi, a, wl, planet_spectrum, star_spectrum, data)

   Perform the loglikelihood calculation using Principal Component Analysis (PCA). Based on M. Line 2019.
   nord: number of spectral order.
   nphi: number of time-resolved phases.
   npix: number of wavelengths per spectral order.

   :param V_sys: The system velocity (km/s) at which we do the loglikelihood calculation.
   :type V_sys: float
   :param K_p: The Keplerian velocity (km/s) at which we do the loglikelihood calculation.
   :type K_p: float
   :param d_phi: Phase offset.
   :type d_phi: float
   :param a: Scale parameter a.
   :type a: float
   :param wl: Wavelength at which the model is defined.
   :type wl: np.array of float
   :param planet_spectrum: Observed flux of the planet (at distance = 1 pc). Should be broadened in the same way as the star_spectrum.
   :type planet_spectrum: np.array of float
   :param star_spectrum: Observed flux of the star (at distance = 1 pc). Should be broadened in the same way as the star_spectrum.
   :type star_spectrum: np.array of float
   :param data: Data dictionary read using utility.read_high_res_data. All values should be prepared beforehand.
                Has the following key-value pairss:
                    reasiduals (3D np.array of float):
                        3D Array representing the top principal components removed data.
                        Shape: (nord x nphi x npix)
                    flux (3D np.array of float):
                        3D Array representing the raw flux of data.
                        Shape: (nord x nphi x npix)
                    V_bary (np.array of float):
                        Array of time-resolved Earth-star velocity. We have absorbed V_sys into V_bary, so V_sys = V_sys_literature + d_V_sys.
                        Shape: (nphi, )
                    phi (np.array of float):
                        Array of time-resolved phases.
                        Shpae (nphi, )
   :type data: dict

   :returns:     Log-likelihood value.
             CCF_sum (float):
                 Cross-correlation value.
   :rtype: loglikelihood_sum (float)


.. py:function:: loglikelihood_sysrem(V_sys, K_p, d_phi, a, b, wl, planet_spectrum, data, star_spectrum=None)

   Perform the loglikelihood calculation using SysRem. Based on N. Gibson 2021.
   nord: number of spectral order.
   nphi: number of time-resolved phases.
   npix: number of wavelengths per spectral order.

   :param V_sys: The system velocity (km/s) at which we do the loglikelihood calculation.
   :type V_sys: float
   :param K_p: The Keplerian velocity (km/s) at which we do the loglikelihood calculation.
   :type K_p: float
   :param d_phi: Phase offset.
   :type d_phi: float
   :param a: Scale parameter for spectrum.
   :type a: float
   :param b: Scale parameter for noise. If None, calculate loglikelihood using nulled b (b that maximizes logL).
   :type b: float or None
   :param wl: Wavelength at which the model is defined.
   :type wl: np.array of float
   :param planet_spectrum: Observed flux of the planet (at distance = 1 pc). Should be broadened in the same way as the star_spectrum.
   :type planet_spectrum: np.array of float
   :param data: Data dictionary read using utility.read_high_res_data. All values should be prepared beforehand.
                Has the following key-value pairs:
                    residuals (3D np.array of float):
                        3D Array representing the residuals data after filtering.
                        Shape: (nord x nphi x npix)
                    Bs (list of 2D np.array of float):
                        A list of basis vectors returned by fast_filter.
                        Shape: (nord x nphi x npix)
                    phi (np.array of float):
                        Array of time-resolved phases.
                        Shape (nphi, )
                    transit_weight (np.array of float):
                        Transit model of the planet. A value of 1 is out of transit, and 0 is full transit.
                        Shape (nphi, )
                    uncertainties (None or 3D np.array of float):
                        Time and wavelength dependent uncertainties obtained from fit_uncertainties.
                        Can be None only if b is also None.
                        Shape: (nord x nphi x npix)
   :type data: dict

   :returns:     Loglikelihood value.
   :rtype: Loglikelihood (float)


.. py:function:: loglikelihood_high_res(wl, planet_spectrum, star_spectrum, data, spectrum_type, method, high_res_params, high_res_param_names)

   Return the loglikelihood given the observed flux, Keplerian velocity, and centered system velocity.
   Should only use this function in a high resolutional rerieval.

   :param wl: Wavelength at which the model is defined.
   :type wl: np.array of float
   :param planet_spectrum: Observed flux of the planet (at distance = 1 pc). Should be broadened in the same way as the star_spectrum.
   :type planet_spectrum: np.array of float
   :param star_spectrum: Observed flux of the star (at distance = 1 pc). Should be broadened in the same way as the star_spectrum.
   :type star_spectrum: np.array of float
   :param data: Data dictionary read using utility.read_high_res_data. All values should be prepared beforehand.
                For more information, see code spec for loglikelihood_PCA or loglikelihood_sysrem.
   :type data: dict
   :param model: Dictionary containing properties of the model.
   :type model: dict

   :returns:     Loglikelihood calculated based on which filtering method (specified in data['method']).
   :rtype: loglikelihood (float)


.. py:function:: get_rot_kernel(V_sin_i, wl, W_conv)

   Get rotational kernel given V sin(i) and wavelength grid of the forward model.

   :param V_sin_i: Projected rotational velocity of a star. The component of the rotational velocity along the line of sight, which is esponsible for broadening.
   :type V_sin_i: float
   :param wl: Wavelength grid of the forward model.
   :type wl: np.array of float
   :param W_conv: Width of the rotational kernel.
   :type W_conv: int


.. py:function:: remove_outliers(wl_grid, flux)

.. py:function:: transit_model(R_p, R_s, a, phi)

.. py:function:: make_injection_data(data, data_dir, name, wl, planet_spectrum, K_p, V_sys, method, a=None, continuum=None, W_conv=None, star_spectrum=None)