`POSEIDON.utility`

Various miscellaneous functions.

Module Contents

Functions

`create_directories`(base_dir, planet_name)	Create various directories used by POSEIDON, such as output folders
`prior_index`(value, grid[, start])	Search a grid to find the previous index closest to a specified value (i.e.
`prior_index_GPU`(value, grid)	GPU variant of the 'prior_index' function.
`interp_GPU`(x_value, x, y)	Linear interpolation using a GPU.
`prior_index_V2`(value, grid_start, grid_end, N_grid)	Find the previous index of a uniformly spaced grid closest to a specified
`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).
`closest_index_GPU`(value, grid_start, grid_end, N_grid)	GPU variant of the 'closest_index' function.
`size_profile`(arr)	Profile the disk storage size of a numpy array. The resultant size in
`get_id_within_node`(comm, rank)
`shared_memory_array`(rank, comm, shape)	Creates a numpy array shared in memory across multiple cores.
`read_data`(data_dir, fname[, wl_unit, bin_width, ...])	Read an external dataset file. The expected file format is:
`read_spectrum`(planet_name, fname[, wl_unit])	Read a previously computed spectrum from the POSEIDON output folder
`read_PT_file`(PT_file_dir, PT_file_name, P_grid[, ...])	Read an external file containing the temperature as a function of pressure.
`read_chem_file`(chem_file_dir, chem_file_name, P_grid, ...)	Read an external file containing mixing ratios as a function of pressure.
`bin_spectrum`(wl_native, spectrum_native, R_bin[, err_data])	Bin a model spectrum down to a specific spectral resolution.
`write_spectrum`(planet_name, model_name, spectrum, wl)	Writes a given model spectrum.
`write_retrieved_spectrum`(retrieval_name, wl, ...)	ADD DOCSTRING
`write_retrieved_PT`(retrieval_name, P, T_low2, T_low1, ...)	ADD DOCSTRING
`write_retrieved_log_X`(retrieval_name, ...)	ADD DOCSTRING
`read_retrieved_spectrum`(planet_name, model_name[, ...])	ADD DOCSTRING
`read_retrieved_PT`(planet_name, model_name[, ...])	ADD DOCSTRING
`read_retrieved_log_X`(planet_name, model_name[, ...])	ADD DOCSTRING
`plot_collection`(new_y, new_x[, collection])	Convenient function to combine distinct spectra and wavelength
`round_sig_figs`(value, sig_figs)	Round a quantity to a specified number of significant figures.
`confidence_intervals`(sample_draws, array, length[, ...])	Order posterior samples to create 1 & 2 sigma contours + median values.
`write_params_file`(param_names, results_prefix)	Write file containing a single column listing the free parameters
`write_samples_file`(samples, param_names, n_params, ...)	Write file containing the equally weighted posterior samples for
`find_str`(string, substring)	Find positional index within a string where a substring starts.
`generate_latex_param_names`(param_names)	Generate LaTeX code for an array of parameters for use in plots.
`return_quantiles`(stats, param, i, radius_unit[, quantile])	Extract the median, +/- N sigma (specified by 'quantile'), string
`write_summary_file`(results_prefix, planet_name, ...)	Write a file summarising the main results from a POSEIDON retrieval.
`write_MultiNest_results`(planet, model, data, ...)	Process raw retrieval output into human readable output files.
`mock_missing`(name)

POSEIDON.utility.create_directories(base_dir, planet_name)

Create various directories used by POSEIDON, such as output folders to store retrieval results.

Parameters:

base_dir (str) – Directory where the output directory will be created.
planet_name (str) – Identifier for planet object (e.g. HD209458b).

Returns:

None

POSEIDON.utility.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.

Parameters:

value (float) – Value for which the prior grid index is desired.
grid (np.array of float) – Input grid.
start (int) – Optional start index when existing knowledge is available.

Returns:

Prior index of the grid corresponding to the value.

Return type:

index (int)

POSEIDON.utility.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.

Parameters:

value (float) – Value for which the prior grid index is desired.
grid (np.array of float) – Input grid.

Returns:

Prior index of the grid corresponding to the value.

Return type:

index (int)

POSEIDON.utility.interp_GPU(x_value, x, y)

Linear interpolation using a GPU.

Parameters:

x_value (float) – x value for which y is desired.
x (np.array of float) – Input x grid.
y (np.array of float) – Input y grid.

Returns:

Linearly interpolated value of y evaluated at x_value.

Return type:

y_interp (float)

POSEIDON.utility.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.

Parameters:

value (float) – The value for which the prior grid index is desired.
grid_start (float) – The value at the left edge of the uniform grid (array[0]).
grid_start – The value at the right edge of the uniform grid (array[-1]).
N_grid (int) – The number of points on the uniform grid.

Returns:

Prior index of the grid corresponding to the value.

Return type:

(int)

POSEIDON.utility.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).

Parameters:

val (float) – The value for which closest index is desired.
grid_start (float) – The value at the left edge of the uniform grid (array[0]).
grid_start – The value at the right edge of the uniform grid (array[-1]).
N_grid (int) – The number of points on the uniform grid.

Returns:

The index of the uniform grid closest to ‘value’.

Return type:

(int)

POSEIDON.utility.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).

Parameters:

val (float) – The value for which closest index is desired.
grid_start (float) – The value at the left edge of the uniform grid (array[0]).
grid_start – The value at the right edge of the uniform grid (array[-1]).
N_grid (int) – The number of points on the uniform grid.

Returns:

The index of the uniform grid closest to ‘value’.

Return type:

(int)

POSEIDON.utility.size_profile(arr)

Profile the disk storage size of a numpy array. The resultant size in Megabytes is printed to the terminal.

Parameters:: arr (np.array) – Any numpy array.
Returns:: None

POSEIDON.utility.get_id_within_node(comm, rank)

POSEIDON.utility.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

POSEIDON.utility.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

Parameters:

data_dir (str) – Path to the directory containing the data file.
fname (str) – File name of data file.
wl_unit (str) – Unit of wavelength column (first column in file) (Options: micron (or equivalent) / nm / A / m)
bin_width (str) – Whether bin width (second column) is half or full width (Options: half / full).
spectrum_unit (str) – Unit of spectrum (third column) and spectrum errors (fourth column) (Options: (Rp/Rs)^2 / Rp/Rs / Fp/Fs / Fp (or equivalent units)).
skiprows (int) – The number of rows to skip (e.g. use 1 if file has a header line).

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.

Return type:

wl_data (np.array of float)

POSEIDON.utility.read_spectrum(planet_name, fname, wl_unit='micron')

Read a previously computed spectrum from the POSEIDON output folder (POSEIDON_output/planet_name/spectra).

Parameters:

planet_name (str) – Identifier for planet object (e.g. HD209458b).
fname (str) – Name of spectrum file.
wl_unit (str) – Unit of wavelength column (first column in file) (Options: micron (or equivalent) / nm / A / m)

Returns:

Model wavelength grid (μm). spectrum (np.array of float):

Transmission or emission spectrum.

Return type:

wavelength (np.array of float)

POSEIDON.utility.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.

Parameters:

PT_file_dir (str) – Directory containing the pressure-temperature file.
PT_file_name (str) – Name of pressure-temperature profile file.
P_grid (np.array of float) – POSEIDON model pressure grid (to interpolate external profile onto).
P_unit (str) – Pressure unit in external file (Options: bar / Pa / atm).
P_column (int) – File column containing the pressure.
T_column (int) – File column containing the temperature.
skiprows (int) – The number of rows to skip (e.g. use 1 if file has a header line).

Returns:

Temperature profile from external file interpolated onto the POSEIDON model’s pressure grid (K).

Return type:

T_interp (np.array of float)

POSEIDON.utility.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.

Parameters:

chem_file_dir (str) – Directory containing the mixing ratio file.
chem_file_name (str) – Name of mixing ratio file.
P_grid (np.array of float) – POSEIDON model pressure grid (to interpolate mixing ratios onto).
chem_species_in_file (list of str) – The chemical species included in the external file.
chem_species_in_model (list of str) – The chemical species included in the POSEIDON model.
P_unit (str) – Pressure unit in external file (Options: bar / Pa / atm).
skiprows (int) – The number of rows to skip (e.g. use 1 if file has a header line).

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).

Return type:

X_interp (2D np.array of float)

POSEIDON.utility.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).

Parameters:

wl_native (np.array of float) – Input wavelength grid (μm).
spectrum_native (np.array of float) – Input spectrum.
R_bin (float or int) – Spectral resolution (R = wl/dwl) to re-bin the spectrum onto.
err_data (np.array of float) – 1σ errors on the spectral data.

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.

Return type:

wl_binned (np.array of float)

POSEIDON.utility.write_spectrum(planet_name, model_name, spectrum, wl): Writes a given model spectrum.

POSEIDON.utility.write_retrieved_spectrum(retrieval_name, wl, spec_low2, spec_low1, spec_median, spec_high1, spec_high2): ADD DOCSTRING

POSEIDON.utility.write_retrieved_PT(retrieval_name, P, T_low2, T_low1, T_median, T_high1, T_high2): ADD DOCSTRING

POSEIDON.utility.write_retrieved_log_X(retrieval_name, chemical_species, P, log_X_low2, log_X_low1, log_X_median, log_X_high1, log_X_high2): ADD DOCSTRING

POSEIDON.utility.read_retrieved_spectrum(planet_name, model_name, retrieval_name=None): ADD DOCSTRING

POSEIDON.utility.read_retrieved_PT(planet_name, model_name, retrieval_name=None): ADD DOCSTRING

POSEIDON.utility.read_retrieved_log_X(planet_name, model_name, retrieval_name=None): ADD DOCSTRING

POSEIDON.utility.plot_collection(new_y, new_x, collection=[]): Convenient function to combine distinct spectra and wavelength grids into a single object for plotting purposes.

POSEIDON.utility.round_sig_figs(value, sig_figs): Round a quantity to a specified number of significant figures.

POSEIDON.utility.confidence_intervals(sample_draws, array, length, integer=False): Order posterior samples to create 1 & 2 sigma contours + median values.

POSEIDON.utility.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.

POSEIDON.utility.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.

POSEIDON.utility.find_str(string, substring): Find positional index within a string where a substring starts.

POSEIDON.utility.generate_latex_param_names(param_names): Generate LaTeX code for an array of parameters for use in plots.

POSEIDON.utility.return_quantiles(stats, param, i, radius_unit, 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.

POSEIDON.utility.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)

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.

POSEIDON.utility.write_MultiNest_results(planet, model, data, retrieval_name, N_live, ev_tol, sampling_algorithm, wl, R): Process raw retrieval output into human readable output files.

POSEIDON.utility.mock_missing(name)

POSEIDON.utility

Module Contents

Functions

`POSEIDON.utility`