POSEIDON.utility ================ .. py:module:: POSEIDON.utility .. autoapi-nested-parse:: Various miscellaneous functions. Functions --------- .. autoapisummary:: POSEIDON.utility.create_directories POSEIDON.utility.prior_index POSEIDON.utility.prior_index_GPU POSEIDON.utility.interp_GPU POSEIDON.utility.prior_index_V2 POSEIDON.utility.closest_index POSEIDON.utility.closest_index_GPU POSEIDON.utility.size_profile POSEIDON.utility.get_id_within_node POSEIDON.utility.shared_memory_array POSEIDON.utility.read_data POSEIDON.utility.read_spectrum POSEIDON.utility.read_PT_file POSEIDON.utility.read_chem_file POSEIDON.utility.bin_spectrum POSEIDON.utility.write_spectrum POSEIDON.utility.write_retrieved_spectrum POSEIDON.utility.write_retrieved_PT POSEIDON.utility.write_retrieved_log_X POSEIDON.utility.read_retrieved_spectrum POSEIDON.utility.read_retrieved_PT POSEIDON.utility.read_retrieved_log_X POSEIDON.utility.plot_collection POSEIDON.utility.round_sig_figs POSEIDON.utility.confidence_intervals POSEIDON.utility.write_params_file POSEIDON.utility.write_samples_file POSEIDON.utility.find_str POSEIDON.utility.generate_latex_param_names POSEIDON.utility.return_quantiles POSEIDON.utility.write_summary_file POSEIDON.utility.write_MultiNest_results POSEIDON.utility.get_vmr POSEIDON.utility.make_latex_table_from_results POSEIDON.utility.mock_missing Module Contents --------------- .. py:function:: create_directories(base_dir, planet_name) Create various directories used by POSEIDON, such as output folders to store retrieval results. :param base_dir: Directory where the output directory will be created. :type base_dir: str :param planet_name: Identifier for planet object (e.g. HD209458b). :type planet_name: str :returns: None .. py:function:: prior_index(value, grid, start=0) Search a grid to find the previous index closest to a specified value (i.e. the index of the grid where the grid value is last less than the value). This function assumes the input grid monotonically increases. :param value: Value for which the prior grid index is desired. :type value: float :param grid: Input grid. :type grid: np.array of float :param start: Optional start index when existing knowledge is available. :type start: int :returns: Prior index of the grid corresponding to the value. :rtype: index (int) .. py:function:: prior_index_GPU(value, grid) GPU variant of the 'prior_index' function. Search a grid to find the previous index closest to a specified value (i.e. the index of the grid where the grid value is last less than the value). This function assumes the input grid monotonically increases. :param value: Value for which the prior grid index is desired. :type value: float :param grid: Input grid. :type grid: np.array of float :returns: Prior index of the grid corresponding to the value. :rtype: index (int) .. py:function:: interp_GPU(x_value, x, y) Linear interpolation using a GPU. :param x_value: x value for which y is desired. :type x_value: float :param x: Input x grid. :type x: np.array of float :param y: Input y grid. :type y: np.array of float :returns: Linearly interpolated value of y evaluated at x_value. :rtype: y_interp (float) .. py:function:: prior_index_V2(value, grid_start, grid_end, N_grid) Find the previous index of a *uniformly spaced* grid closest to a specified value. When a uniform grid can be assumed, this function is much faster than 'prior_index' due to there being no need for a loop. However, for non-uniform grids one should still default to 'prior_index'. This function assumes the input grid monotonically increases. :param value: The value for which the prior grid index is desired. :type value: float :param grid_start: The value at the left edge of the uniform grid (array[0]). :type grid_start: float :param grid_start: The value at the right edge of the uniform grid (array[-1]). :type grid_start: float :param N_grid: The number of points on the uniform grid. :type N_grid: int :returns: Prior index of the grid corresponding to the value. :rtype: (int) .. py:function:: closest_index(value, grid_start, grid_end, N_grid) Same as 'prior_index_V2', but for the closest index (i.e. can also round up). :param val: The value for which closest index is desired. :type val: float :param grid_start: The value at the left edge of the uniform grid (array[0]). :type grid_start: float :param grid_start: The value at the right edge of the uniform grid (array[-1]). :type grid_start: float :param N_grid: The number of points on the uniform grid. :type N_grid: int :returns: The index of the uniform grid closest to 'value'. :rtype: (int) .. py:function:: closest_index_GPU(value, grid_start, grid_end, N_grid) GPU variant of the 'closest_index' function. Same as 'prior_index_V2', but for the closest index (i.e. can also round up). :param val: The value for which closest index is desired. :type val: float :param grid_start: The value at the left edge of the uniform grid (array[0]). :type grid_start: float :param grid_start: The value at the right edge of the uniform grid (array[-1]). :type grid_start: float :param N_grid: The number of points on the uniform grid. :type N_grid: int :returns: The index of the uniform grid closest to 'value'. :rtype: (int) .. py:function:: size_profile(arr) Profile the disk storage size of a numpy array. The resultant size in Megabytes is printed to the terminal. :param arr: Any numpy array. :type arr: np.array :returns: None .. py:function:: get_id_within_node(comm, rank) .. py:function:: shared_memory_array(rank, comm, shape) Creates a numpy array shared in memory across multiple cores. Adapted from : https://stackoverflow.com/questions/32485122/shared-memory-in-mpi4py .. py:function:: read_data(data_dir, fname, wl_unit='micron', bin_width='half', spectrum_unit='(Rp/Rs)^2', skiprows=None) Read an external dataset file. The expected file format is: wavelength | bin half width | spectrum | error on spectrum :param data_dir: Path to the directory containing the data file. :type data_dir: str :param fname: File name of data file. :type fname: str :param wl_unit: Unit of wavelength column (first column in file) (Options: micron (or equivalent) / nm / A / m) :type wl_unit: str :param bin_width: Whether bin width (second column) is half or full width (Options: half / full). :type bin_width: str :param spectrum_unit: Unit of spectrum (third column) and spectrum errors (fourth column) (Options: (Rp/Rs)^2 / Rp/Rs / Fp/Fs / Fp (or equivalent units)). :type spectrum_unit: str :param skiprows: The number of rows to skip (e.g. use 1 if file has a header line). :type skiprows: int :returns: Bin centre wavelengths of data points (μm). half_bin (np.array of float): Bin half widths of data points (μm). spectrum (np.array of float): Transmission or emission spectrum dataset. err (np.array of float): 1σ error bar on spectral data. :rtype: wl_data (np.array of float) .. py:function:: read_spectrum(fname, wl_unit='micron', skiprows=None) Read a previously computed spectrum from the POSEIDON output folder (POSEIDON_output/planet_name/spectra). :param fname: File path and name of spectrum file (e.g. './my_file.txt') :type fname: str :param wl_unit: Unit of wavelength column (first column in file) (Options: micron (or equivalent) / nm / A / m). :type wl_unit: str :param skiprows: The number of rows to skip (e.g. use 1 if file has a header line). :type skiprows: int :returns: Model wavelength grid (μm). spectrum (np.array of float): Transmission or emission spectrum. :rtype: wavelength (np.array of float) .. py:function:: read_PT_file(PT_file_dir, PT_file_name, P_grid, P_unit='bar', P_column=None, T_column=None, skiprows=None) Read an external file containing the temperature as a function of pressure. :param PT_file_dir: Directory containing the pressure-temperature file. :type PT_file_dir: str :param PT_file_name: Name of pressure-temperature profile file. :type PT_file_name: str :param P_grid: POSEIDON model pressure grid (to interpolate external profile onto). :type P_grid: np.array of float :param P_unit: Pressure unit in external file (Options: bar / Pa / atm). :type P_unit: str :param P_column: File column containing the pressure. :type P_column: int :param T_column: File column containing the temperature. :type T_column: int :param skiprows: The number of rows to skip (e.g. use 1 if file has a header line). :type skiprows: int :returns: Temperature profile from external file interpolated onto the POSEIDON model's pressure grid (K). :rtype: T_interp (np.array of float) .. py:function:: read_chem_file(chem_file_dir, chem_file_name, P_grid, chem_species_in_file, chem_species_in_model, P_unit='bar', skiprows=None) Read an external file containing mixing ratios as a function of pressure. :param chem_file_dir: Directory containing the mixing ratio file. :type chem_file_dir: str :param chem_file_name: Name of mixing ratio file. :type chem_file_name: str :param P_grid: POSEIDON model pressure grid (to interpolate mixing ratios onto). :type P_grid: np.array of float :param chem_species_in_file: The chemical species included in the external file. :type chem_species_in_file: list of str :param chem_species_in_model: The chemical species included in the POSEIDON model. :type chem_species_in_model: list of str :param P_unit: Pressure unit in external file (Options: bar / Pa / atm). :type P_unit: str :param skiprows: The number of rows to skip (e.g. use 1 if file has a header line). :type skiprows: int :returns: Mixing ratio profiles from external file interpolated onto the POSEIDON model's pressure grid. Only includes the chemical species specified in the POSEIDON model (i.e. chem_species_in_model). :rtype: X_interp (2D np.array of float) .. py:function:: bin_spectrum(wl_native, spectrum_native, R_bin, err_data=[]) Bin a model spectrum down to a specific spectral resolution. This is a wrapper around the Python package SpectRes (for details on the resampling algorithm, see https://arxiv.org/abs/1705.05165). :param wl_native: Input wavelength grid (μm). :type wl_native: np.array of float :param spectrum_native: Input spectrum. :type spectrum_native: np.array of float :param R_bin: Spectral resolution (R = wl/dwl) to re-bin the spectrum onto. :type R_bin: float or int :param err_data: 1σ errors on the spectral data. :type err_data: np.array of float :returns: New wavelength grid spaced at R = R_bin (μm). spectrum_binned (np.array of float): Re-binned spectrum at resolution R = R_bin. err_binned (np.array of float): Re-binned errors at resolution R = R_bin. :rtype: wl_binned (np.array of float) .. py:function:: write_spectrum(planet_name, model_name, spectrum, wl) Writes a given model spectrum. .. py:function:: write_retrieved_spectrum(retrieval_name, wl, spec_low2, spec_low1, spec_median, spec_high1, spec_high2) ADD DOCSTRING .. py:function:: write_retrieved_PT(retrieval_name, P, T_low2, T_low1, T_median, T_high1, T_high2, region_name=None) Write the retrieved P-T profile confidence intervals to a text file. :param retrieval_name: Name of the retrieval run. :type retrieval_name: str :param P: Model pressure grid (bar). :type P: np.array of float :param T_low2: Temperature confidence intervals at each pressure level. :type T_low2: np.array of float :param T_low1: Temperature confidence intervals at each pressure level. :type T_low1: np.array of float :param T_median: Temperature confidence intervals at each pressure level. :type T_median: np.array of float :param T_high1: Temperature confidence intervals at each pressure level. :type T_high1: np.array of float :param T_high2: Temperature confidence intervals at each pressure level. :type T_high2: np.array of float :param region_name: If provided, appends a region label to the output filename (e.g. 'dayside', 'nightside', 'evening', 'morning'). :type region_name: str, optional .. py:function:: write_retrieved_log_X(retrieval_name, chemical_species, P, log_X_low2, log_X_low1, log_X_median, log_X_high1, log_X_high2, region_name=None) Write the retrieved mixing ratio profile confidence intervals to a text file. :param retrieval_name: Name of the retrieval run. :type retrieval_name: str :param chemical_species: Chemical species included in the model. :type chemical_species: list of str :param P: Model pressure grid (bar). :type P: np.array of float :param log_X_low2: Log-mixing-ratio confidence intervals for each species at each pressure level. :type log_X_low2: np.array of float :param log_X_low1: Log-mixing-ratio confidence intervals for each species at each pressure level. :type log_X_low1: np.array of float :param log_X_median: Log-mixing-ratio confidence intervals for each species at each pressure level. :type log_X_median: np.array of float :param log_X_high1: Log-mixing-ratio confidence intervals for each species at each pressure level. :type log_X_high1: np.array of float :param log_X_high2: Log-mixing-ratio confidence intervals for each species at each pressure level. :type log_X_high2: np.array of float :param region_name: If provided, appends a region label to the output filename (e.g. 'dayside', 'nightside', 'evening', 'morning'). :type region_name: str, optional .. py:function:: read_retrieved_spectrum(planet_name, model_name, retrieval_name=None) ADD DOCSTRING .. py:function:: read_retrieved_PT(planet_name, model_name, retrieval_name=None, region_name=None) Read the retrieved P-T profile confidence intervals from a text file. :param planet_name: The name of the planet. :type planet_name: str :param model_name: The name of the model. :type model_name: str :param retrieval_name: The name of the retrieval run. If None, defaults to model_name. :type retrieval_name: str, optional :param region_name: If provided, reads the region-specific P-T file (e.g. 'dayside', 'nightside', 'evening', 'morning'). :type region_name: str, optional :returns: Pressure grid (bar). T_low2, T_low1, T_median, T_high1, T_high2 (np.array of float): Temperature confidence intervals at each pressure level. :rtype: P (np.array of float) .. py:function:: read_retrieved_log_X(planet_name, model_name, retrieval_name=None, region_name=None) Read the retrieved mixing ratio profile confidence intervals from a text file. :param planet_name: The name of the planet. :type planet_name: str :param model_name: The name of the model. :type model_name: str :param retrieval_name: The name of the retrieval run. If None, defaults to model_name. :type retrieval_name: str, optional :param region_name: If provided, reads the region-specific log_X file (e.g. 'dayside', 'nightside', 'evening', 'morning'). :type region_name: str, optional :returns: Pressure grid (bar). chemical_species (np.array of str): Chemical species included in the model. log_X_low2, log_X_low1, log_X_median, log_X_high1, log_X_high2 (np.array of float): Log-mixing-ratio confidence intervals for each species. :rtype: P (np.array of float) .. py:function:: plot_collection(new_y, new_x, collection=[]) Convenient function to combine distinct spectra and wavelength grids into a single object for plotting purposes. .. py:function:: round_sig_figs(value, sig_figs) Round a quantity to a specified number of significant figures. .. py:function:: confidence_intervals(sample_draws, array, length, integer=False) Order posterior samples to create 1 & 2 sigma contours + median values. .. py:function:: write_params_file(param_names, results_prefix) Write file containing a single column listing the free parameters used in a retrieval. This file can be read in later when generating corner plots at a future time. .. py:function:: write_samples_file(samples, param_names, n_params, results_prefix) Write file containing the equally weighted posterior samples for each free parameter in a retrieval. .. py:function:: find_str(string, substring) Find positional index within a string where a substring starts. .. py:function:: generate_latex_param_names(param_names) Generate LaTeX code for an array of parameters for use in plots. .. py:function:: return_quantiles(stats, param, i, radius_unit, spectrum_type, quantile='1 sigma') Extract the median, +/- N sigma (specified by 'quantile'), string formatter and units for a given free parameter. Note: 'quantile' supports 1, 2, 3, or 5 sigma. .. py:function:: write_summary_file(results_prefix, planet_name, retrieval_name, sampling_algorithm, n_params, N_live, ev_tol, param_names, stats, ln_Z, ln_Z_err, reduced_chi_square, chi_square, dof, best_fit_params, wl, R, instruments, datasets, radius_unit, spectrum_type) Write a file summarising the main results from a POSEIDON retrieval. Contains the key model stats (Bayesian evidence and best-fitting chi^2) and the +/- 1, 2, 3, and 5 sigma constraints, alongside other helpful information for future reference. .. py:function:: write_MultiNest_results(planet, model, data, retrieval_name, N_live, ev_tol, sampling_algorithm, wl, R, ymodel_best, spectrum_type) Process raw retrieval output into human readable output files. .. py:function:: get_vmr(name, mol, planet_name) Gets the vmr from the results.txt file :param name: model name :type name: string :param mol: name of parameters to grab :type mol: string :param planet_name: name of planet (to load results file) :type planet_name: string :returns: The vmr of the variable (or just the value before the +/-) sig1, sig2 (float): Upper and lower 1 sigma values :rtype: vmr (float) .. py:function:: make_latex_table_from_results(model_names_array, variables, planet_name) Gets the vmr from the results.txt file :param model_names_array: model names for each model to print out :type model_names_array: array of string :param variables: name of parameters to grab :type variables: array of string :param planet_name: name of planet (to load results file) :type planet_name: string :returns: Prints out a latex friendly table .. py:function:: mock_missing(name)