petitRADTRANS.math ================== .. py:module:: petitRADTRANS.math .. autoapi-nested-parse:: Stores useful mathematical functions. Functions --------- .. autoapisummary:: petitRADTRANS.math.bayes_factor2sigma petitRADTRANS.math.box_car_conv petitRADTRANS.math.calculate_chi2 petitRADTRANS.math.calculate_reduced_chi2 petitRADTRANS.math.calculate_uncertainty petitRADTRANS.math.compute_resolving_power petitRADTRANS.math.convolve petitRADTRANS.math.convolve_and_sample_variable_resolution_breads petitRADTRANS.math.feature_scaling petitRADTRANS.math.filter_spectrum_with_spline petitRADTRANS.math.gaussian_weights1d petitRADTRANS.math.gaussian_weights_running petitRADTRANS.math.linear_spline_interpolation petitRADTRANS.math.longitude2phase petitRADTRANS.math.mean_uncertainty petitRADTRANS.math.median_uncertainties petitRADTRANS.math.normalize petitRADTRANS.math.phase2longitude petitRADTRANS.math.prt_resolving_space petitRADTRANS.math.resolving_space petitRADTRANS.math.running_mean petitRADTRANS.math.sigma2bayes_factor Module Contents --------------- .. py:function:: bayes_factor2sigma(bayes_factor: float) -> float | numpy.typing.NDArray[numpy.floating] Convert a Bayes factor, or "evidence", into a sigma significance. For Bayes factor higher than exp(25), the function is approximated with a square root function. Note: sometimes algorithms return the "log-evidence", or ln(z). The Bayes factor is z. Source: Benneke et al. 2013 https://iopscience.iop.org/article/10.1088/0004-637X/778/2/153 Molliere part by Paul Mollière. :param bayes_factor: Bayes factor (aka "evidence") :return: sigma significance .. py:function:: box_car_conv(array: numpy.typing.NDArray, points: numpy.typing.NDArray) -> numpy.typing.NDArray .. py:function:: calculate_chi2(data: float | numpy.typing.NDArray, model: float | numpy.typing.NDArray, uncertainties: float | numpy.typing.NDArray) -> float .. py:function:: calculate_reduced_chi2(data: float | numpy.typing.NDArray, model: float | numpy.typing.NDArray, uncertainties: float | numpy.typing.NDArray, degrees_of_freedom: int = 0) -> float | numpy.typing.NDArray .. py:function:: calculate_uncertainty(derivatives: numpy.typing.NDArray, uncertainties: numpy.typing.NDArray, covariance_matrix: numpy.typing.NDArray = None) -> numpy.typing.NDArray | None Calculate the uncertainty of a function f(x, y, ...) with uncertainties on x, y, ... and Pearson's correlation coefficients between x, y, ... The function must be (approximately) linear with its variables within the uncertainties of said variables. For independent variables, set the covariance matrix to identity. Uncertainties can be asymmetric, in that case for N variables, use a (N, 2) array for the uncertainties. Asymmetric uncertainties are handled **the wrong way** (see source 2), but it is better than nothing. Sources: 1. https://en.wikipedia.org/wiki/Propagation_of_uncertainty 2. https://phas.ubc.ca/~oser/p509/Lec_10.pdf 3. http://math.jacobs-university.de/oliver/teaching/jacobs/fall2015/esm106/handouts/error-propagation.pdf Args: derivatives: Partial derivatives of the function with respect to each variable (df/dx, df/dy, ...) uncertainties: Uncertainties of each variable (either a 1D-array or a 2D-array containing - and + unc.) covariance_matrix: Covariance matrix between the variables, by default set to the identity matrix Returns: A size-2 array containing the - and + uncertainties of the function .. py:function:: compute_resolving_power(array: numpy.typing.NDArray[numpy.floating]) -> float Compute the mean resolving power of an array. Args: array: A 1-D array. Returns: The mean resolving power of the array. .. py:function:: convolve(input_wavelength, input_flux, instrument_res) This function convolves a model spectrum to the instrumental wavelength using the provided data_resolution Args: input_wavelength : numpy.ndarray The wavelength grid of the model spectrum input_flux : numpy.ndarray The flux as computed by the model instrument_res : float :math:`\\lambda/\\Delta \\lambda`, the width of the gaussian kernel to convolve with the model spectrum. Returns: flux_lsf The convolved spectrum. .. py:function:: convolve_and_sample_variable_resolution_breads(wavelengths, resolutions, model_wavelengths, model_fluxes, num_sigma=3) Simulate the observations of a model. Convolves the model with a variable Gaussian LSF, sampled at each desired spectral channel. From Jerry Xuan circa 2024, https://github.com/jruffio/breads Args: wavelengths: np.ndarray The wavelengths desired (length of N_output) resolutions: np.ndarray The spectral resolving power at each wavelength (length of N_output) model_wavelengths: np.ndarray The wavelengths of the model (length of N_model) model_fluxes: np.ndarray The fluxes of the model (length of N_model) num_sigma: float Number of +/- sigmas to evaluate the LSF to. Returns: output_model: np.ndarray the fluxes in each of the wavelength channels (length of N_output) .. py:function:: feature_scaling(array: numpy.typing.NDArray, min_value: float = 0.0, max_value: float = 1.0) -> numpy.typing.NDArray Bring all values of array between a min and max value. Args: array: array to normalize min_value: target minimum value max_value: target maximum value Returns: The normalized array with values between min_value and max_value. .. py:function:: filter_spectrum_with_spline(wavelengths, fluxes, uncertainties=None, x_nodes=None, m_spline=None) Use spline interpolation produce a high-pass filtered version of the input spectrum. From BREADS, BSD 3-Clause License Copyright (c) 2024, jruffio https://github.com/jruffio/breads Args: wavelengths: np.ndarray Wavelengths of the input spectrum fluxes: np.ndarray Fluxes of the input spectrum uncertainties: np.ndarray Uncertainties of the input spectrum x_nodes: np.ndarray Nodes for the spline interpolation as np.ndarray in the same units as wavelengths. x_nodes can also be a list of ndarrays/list to model discontinous functions. m_spline: np.ndarray Pre-computed spline matrix. If None, it will be computed from x_nodes and wavelengths. Returns: high_pass_filtered_fluxes: np.ndarray High-pass filtered fluxes of the input spectrum .. py:function:: gaussian_weights1d(sigma: float, truncate: float = 4.0) -> numpy.typing.NDArray Compute a 1D Gaussian convolution kernel. To be used with scipy.ndimage.convolve1d. Based on scipy.ndimage gaussian_filter1d and _gaussian_kernel1d. Args: sigma: Standard deviation for Gaussian kernel. truncate: Truncate the filter at this many standard deviations. Returns: .. py:function:: gaussian_weights_running(sigmas: numpy.typing.NDArray, truncate: float = 4.0) -> numpy.typing.NDArray Compute 1D Gaussian convolution kernels for an array of standard deviations. Based on scipy.ndimage gaussian_filter1d and _gaussian_kernel1d. Args: sigmas: Standard deviations for Gaussian kernel. truncate: Truncate the filter at this many standard deviations. Returns: .. py:function:: linear_spline_interpolation(x_knots: numpy.typing.NDArray[numpy.floating], x_samples: numpy.typing.NDArray[numpy.floating], spline_degree: Literal[1, 2, 3, 4, 5] = 3) Compute a spline based linear model. If Y = [y1, y2, ...] are the values of the function at the location of the node [x1, x2, ...]. np.dot(M,Y) is the interpolated spline corresponding to the sampling of the x-axis (x_samples) From BREADS, BSD 3-Clause License Copyright (c) 2024, jruffio https://github.com/jruffio/breads Args: x_knots: np.ndarray List of nodes for the spline interpolation as np.ndarray in the same units as x_samples. x_knots can also be a list of ndarrays/list to model discontinous functions. x_samples: np.ndarray Vector of x values. ie, the sampling of the data. spline_degree: int Degree of the spline interpolation (default: 3). if np.size(x_knots) <= spline_degree, then spline_degree = np.size(x_knots)-1 Returns: M: Matrix of shape (D, N) with D the size of x_samples and N the total number of nodes. .. py:function:: longitude2phase(longitude: float) .. py:function:: mean_uncertainty(uncertainties: numpy.typing.NDArray) -> float Calculate the uncertainty of the mean of an array. Args: uncertainties: individual uncertainties of the averaged array Returns: The uncertainty of the mean of the array .. py:function:: median_uncertainties(uncertainties: numpy.typing.NDArray) -> float Calculate the uncertainty of the median of an array. Demonstration: uncertainty ~ standard deviation = sqrt(variance) = sqrt(V) V_mean / V_median = 2 * (N - 1) / (pi * N); (see source) => V_median = V_mean * pi * N / (2 * (N - 1)) => uncertainty_median = uncertainty_mean * sqrt(pi * N / (2 * (N - 1))) Source: https://mathworld.wolfram.com/StatisticalMedian.html Args: uncertainties: individual uncertainties of the median of the array Returns: The uncertainty of the median of the array .. py:function:: normalize(array: numpy.typing.NDArray, axis: int = None) -> numpy.typing.NDArray .. py:function:: phase2longitude(phase: float, rad2deg: bool = False) .. py:function:: prt_resolving_space(start, stop, resolving_power) -> numpy.typing.NDArray Return numbers evenly spaced at the specified resolving power. Args: start: The starting value of the sequence. stop: The end value of the sequence. resolving_power: Resolving power of the sample Returns: Samples spaced following the specified resolving power. .. py:function:: resolving_space(start, stop, resolving_power) .. py:function:: running_mean(x: numpy.typing.NDArray, n: int) -> numpy.typing.NDArray .. py:function:: sigma2bayes_factor(sigma: float) -> float Convert a sigma significance into a Bayes factor, or "evidence". Note: sometimes algorithms return the "log-evidence", or ln(z). The Bayes factor is z. Source: Benneke et al. 2013 https://iopscience.iop.org/article/10.1088/0004-637X/778/2/153 :param sigma: sigma significance :return: Bayes factor (aka "evidence")