POSEIDON.visuals

Plotting routines to visualise POSEIDON output.

Attributes

`linestyles`
`dark_theme`
`light_theme`

Functions

`scale_lightness`(colour_name, scale)	Scale the lightness of a colour by the given factor.
`plot_transit`(ax, R_p, R_s, b_p, r, T, phi, phi_edge, ...)	Subfunction used by the 'plot_geometry' function below. This function plots
`plot_geometry`(planet, star, model, atmosphere[, ...])	Plots two 2D slice plots through the planetary atmosphere (to scale),
`plot_geometry_spectrum_mixed`(planet, star, model, ...)	Plots two 2D slice plots through the planetary atmosphere (to scale).
`plot_PT`(planet, model, atmosphere[, show_profiles, ...])	Plot the pressure-temperature (P-T) profiles defining the atmosphere.
`plot_chem`(planet, model, atmosphere[, plot_species, ...])	Plot the mixing ratio profiles defining the atmosphere.
`set_spectrum_wl_ticks`(wl_min, wl_max[, wl_axis])	Calculates default x axis tick spacing for spectra plots in POSEIDON.
`plot_spectra`(spectra, planet[, data_properties, ...])	Plot a collection of individual model spectra. This function can plot
`plot_data`(data, planet_name[, wl_min, wl_max, y_min, ...])	Plot a collection of datasets. This function can plot transmission or
`plot_spectra_retrieved`(spectra_median, spectra_low2, ...)	Plot a collection of individual model spectra. This function can plot
`plot_PT_retrieved`(planet_name, PT_median, PT_low2, ...)	Plot retrieved Pressure-Temperature (P-T) profiles.
`plot_chem_retrieved`(planet_name, chemical_species, ...)	Plot retrieved mixing ratio profiles.
`plot_stellar_flux`(flux, wl[, wl_min, wl_max, ...])	Straightforward function to plot an emergent stellar spectrum.
`plot_histogram`(nbins, vals, colour, ax, shrink_factor, ...)	Function to plot a histogram of parameter values.
`plot_parameter_panel`(ax, param_vals, N_bins, ...)	Setup function to plot the histogram panel for a given parameter.
`plot_retrieved_parameters`(axes_in, param_vals, ...[, ...])	Plot retrieved parameters as histograms.
`elemental_ratio_samples`(all_species, X_vals, ...)	Helper function to calculate the abundance ratio between any two elements
`plot_histograms`(planet, models, plot_parameters[, ...])	Plot a set of histograms from one or more retrievals.
`vary_one_parameter_PT`(model, planet, param_name, ...)	This function is used in the tutorial notebooks to show how turning a knob

Module Contents

POSEIDON.visuals.linestyles

POSEIDON.visuals.dark_theme

POSEIDON.visuals.light_theme

POSEIDON.visuals.scale_lightness(colour_name, scale)

Scale the lightness of a colour by the given factor.

Parameters:

colour_name (str) – The name of the colour to be scaled, in matplotlib colour format.
scale (float) – The factor by which to scale the lightness of the colour (< 1 makes the colour darker).

Returns:

A tuple containing the RGB values of the scaled colour.

Return type:

tuple

POSEIDON.visuals.plot_transit(ax, R_p, R_s, b_p, r, T, phi, phi_edge, theta, theta_edge, perspective, y_p=0.0, plot_labels=True, show_star=False, annotate_Rp=False, dark_mode=False)

Subfunction used by the ‘plot_geometry’ function below. This function plots a 2D slice through an exoplanet and its atmosphere (to scale) from various observer perspectives.

Parameters:

ax (matplotlib axis object) – A matplotlib axis instance.
R_p (float) – White light planetary radius.
r (3D np.array of float) – Radial distance profile (m).
T (3D np.array of float) – Temperature profile (K).
phi (np.array of float) – Mid-sector angles (radians).
phi_edge (np.array of float) – Boundary angles for each sector (radians).
dphi (np.array of float) – Angular width of each sector (radians).
theta (np.array of float) – Mid-zone angles (radians).
theta_edge (np.array of float) – Boundary angles for each zone (radians).
dtheta (np.array of float) – Angular width of each zone (radians).
perspective (str) – Observer viewing perspective for 2D slice. (Options: terminator / day-night).
y_p (float) – Projected coordinate of planet centre from observer perspective
plot_labels (bool) – If False, removes text labels from the plot.
show_star (bool) – If True, plots the star in the background from observer perspective
annotate_Rp (bool) – If True, adds an arrow to the terminator perspective plot showing the radius of the planet (works best when show_star = True).
dark_mode (bool) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

Patch collection containing atmosphere slices and temperature colour bar. The figure itself is written to the provided axis.

Return type:

p (matplotlib PatchCollection)

POSEIDON.visuals.plot_geometry(planet, star, model, atmosphere, plot_labels=True, dark_mode=False)

Plots two 2D slice plots through the planetary atmosphere (to scale), coloured according to the temperature field. The left panel corresponds to a slice through the terminator plane, while the right panel is a slice through the north pole - observer plane.

Parameters:

planet (dict) – POSEIDON planet properties dictionary.
star (dict) – POSEIDON stellar properties dictionary (currently unused).
model (dict) – POSEIDON model properties dictionary.
atmosphere (dict) – POSEIDON atmospheric properties dictionary.
plot_labels (bool) – If False, removes text labels from the plot.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The geometric slice plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_geometry_spectrum_mixed(planet, star, model, atmosphere, spectra, y_p=0.0, plot_labels=False, show_star=True, annotate_Rp=True, data_properties=None, show_data=False, plot_full_res=True, bin_spectra=True, R_to_bin=100, wl_min=None, wl_max=None, y_min=None, y_max=None, y_unit='transit_depth', plt_label=None, colour_list=[], spectra_labels=[], data_colour_list=[], data_labels=[], data_marker_list=[], data_marker_size_list=[], wl_axis='log', figure_shape='default', legend_location='upper right', legend_box=True, dark_mode=False)

Plots two 2D slice plots through the planetary atmosphere (to scale).

Parameters:

planet (dict) – POSEIDON planet properties dictionary.
star (dict) – POSEIDON stellar properties dictionary (currently unused).
model (dict) – POSEIDON model properties dictionary.
atmosphere (dict) – POSEIDON atmospheric properties dictionary.
spectra (list) – List of spectra to plot.
y_p (float) – Projected coordinate of planet centre from observer perspective.
plot_labels (bool) – If False, removes text labels from the plot.
show_star (bool) – If True, plots the star in the background from observer perspective.
annotate_Rp (bool) – If True, adds an arrow to the terminator perspective plot showing the radius of the planet (works best when show_star = True).
data_properties (dict, optional) – Dictionary containing data properties.
show_data (bool) – If True, shows data on the right-hand side plot.
plot_full_res (bool) – If True, shows full resolution spectra.
bin_spectra (bool) – If True, bins spectra.
R_to_bin (int) – Binning spectral resolution.
wl_min (float) – Minimum wavelength for plotting.
wl_max (float) – Maximum wavelength for plotting.
y_min (float) – Minimum y-axis value for plotting.
y_max (float) – Maximum y-axis value for plotting.
y_unit (str) – Unit for y-axis. Default is ‘transit_depth’.
plt_label (str) – Label for the plot.
colour_list (list) – List of colours for plotting spectra.
spectra_labels (list) – List of labels for spectra.
data_colour_list (list) – List of colours for data points.
data_labels (list) – List of labels for data points.
data_marker_list (list) – List of markers for data points.
data_marker_size_list (list) – List of marker sizes for data points.
wl_axis (str) – Axis for wavelength.
figure_shape (str) – Shape of the figure.
legend_location (str) – Location of the legend.
legend_box (bool) – If True, shows legend box.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The geometric slice plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_PT(planet, model, atmosphere, show_profiles=[], PT_label=None, log_P_min=None, log_P_max=None, T_min=None, T_max=None, colour='darkblue', legend_location='lower left', ax=None, dark_mode=False)

Plot the pressure-temperature (P-T) profiles defining the atmosphere.

Parameters:

planet (dict) – POSEIDON planet properties dictionary.
model (dict) – POSEIDON model properties dictionary.
atmosphere (dict) – Dictionary containing atmospheric properties.
show_profiles (list, optional) –
List of profiles to plot. Default is an empty list. For a 1D model, a single P-T profile is plotted. For 2D or 3D models, the user can specify the regions for which the P-T profiles should be plotted. This is handled through ‘show_profiles’. Valid choices for 2D and 3D models:

2D Day-Night: [‘day’, ‘night’, ‘terminator’] 2D Evening-Morning: [‘morning’, ‘evening’, ‘average’] 3D: [‘evening-day’, ‘evening-night’, ‘evening-terminator’,

’morning-day’, ‘morning-night’, ‘morning-terminator’, ‘terminator-average’]

Any subset of the above can be passed via ‘show_profiles’.
PT_label (str, optional):

Label for the P-T profile.
log_P_min (float, optional):

Minimum value for the log10 pressure.
log_P_max (float, optional):

Maximum value for the log10 pressure.
T_min (float, optional):

Minimum temperature to plot.
T_max (float, optional):

Maximum temperature to plot.
colour (str, optional):

Colour of the plotted P-T profile.
legend_location (str, optional):

Location of the legend. Default is ‘lower left’.
ax (matplotlib axis object, optional) – Matplotlib axis provided externally.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Return type:

fig (matplotlib figure object)

The P-T profile plot.

POSEIDON.visuals.plot_chem(planet, model, atmosphere, plot_species=[], colour_list=[], show_profiles=[], log_X_min=None, log_X_max=None, log_P_min=None, log_P_max=None, legend_title=None, legend_location='upper right', dark_mode=False)

Plot the mixing ratio profiles defining the atmosphere.

The user specifies which chemical species to plot via the list ‘plot_species’. The colours used for each species can be specified by the user via ‘colour_list’, or else default colours will be used. This function supports plotting up to 8 chemical species.

Parameters:

planet (dict) – Dictionary containing planet properties.
model (dict) – Dictionary containing model properties.
atmosphere (dict) – Dictionary containing atmospheric properties.
plot_species (list, optional) – List of chemical species to plot. If not specified, default to all chemical species in the model (including bulk species).
colour_list (list, optional) – List of colours to use for each species in plot_species. Default is a predefined list, if the user doesn’t provide one.
show_profiles (list, optional) –
List of chemical profiles to plot. Default is an empty list. For a 1D model, a single P-T profile is plotted. For 2D or 3D models, the user can specify the regions for which the P-T profiles should be plotted. This is handled through ‘show_profiles’. Valid choices for 2D and 3D models:

2D Day-Night: [‘day’, ‘night’, ‘terminator’] 2D Evening-Morning: [‘morning’, ‘evening’, ‘average’] 3D: [‘evening-day’, ‘evening-night’, ‘evening-terminator’,

’morning-day’, ‘morning-night’, ‘morning-terminator’, ‘terminator-average’]

Any subset of the above can be passed via ‘show_profiles’.
log_X_min (float, optional) – Minimum log10 mixing ratio to plot. If not specified, the range is calculated automatically.
log_X_max (float, optional) – Minimum log10 mixing ratio to plot. If not specified, the range is calculated automatically.
log_P_min (float, optional) – Minimum log10 pressure to plot. If not specified, the range is calculated automatically.
log_P_max (float, optional) – Minimum log10 pressure to plot. If not specified, the range is calculated automatically.
legend_title (str, optional) – Title for the legend. Defaults to the model name if not provided.
legend_location (str, optional) – Location of the legend. Default is ‘upper right’.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).
Returns –

fig (matplotlib figure object):
Chemical mixing ratio plot.

POSEIDON.visuals.set_spectrum_wl_ticks(wl_min, wl_max, wl_axis='log')

Calculates default x axis tick spacing for spectra plots in POSEIDON.

Parameters:

wl_min (float) – The minimum wavelength to plot.
wl_max (float) – The maximum wavelength to plot.
wl_axis (str, optional) – The type of x-axis to use (‘log’ or ‘linear’).

Returns:

The x axis tick values for the given wavelength range.

Return type:

np.array

POSEIDON.visuals.plot_spectra(spectra, planet, data_properties=None, show_data=False, plot_full_res=True, bin_spectra=True, R_to_bin=100, plt_label=None, show_planet_name=True, wl_min=None, wl_max=None, y_min=None, y_max=None, y_unit='transit_depth', colour_list=[], spectra_labels=[], data_colour_list=[], data_labels=[], data_marker_list=[], data_marker_size_list=[], data_alpha_list=[], data_eline_alpha_list=[], data_edge_width_list=[], data_eline_colour_list=[], data_eline_width_list=[], line_width_list=[], line_style_list=[], line_alpha_list=[], text_annotations=[], annotation_pos=[], err_colour=None, wl_axis='log', figure_shape='default', show_legend=True, legend_location='upper right', legend_box=True, legend_line_size=[], legend_n_columns=0, ax=None, save_fig=True, model=None, show_data_bin_width=True, show_data_cap=True, add_retrieved_offsets=False, verbose_offsets=True, add_retrieved_error_inflation=False, xlabels=True, x_wavelength_label=True, x_tick_label=True, ylabels=True, x_tick_fontsize=12, x_label_fontsize=16, y_tick_fontsize=12, y_label_fontsize=16, x_tick_list=[], legend_fontsize=10, plt_label_fontsize=14, planet_name_fontsize=16, plot_style='standard', fill_between=[], fill_between_alpha=0.5, fill_to_spectrum=[], fill_to_spectrum_list=[], dark_mode=False)

Plot a collection of individual model spectra. This function can plot transmission or emission spectra, according to the user’s choice of ‘y_unit’.

Parameters:

spectra (list of tuples) – A list of model spectra to be plotted, each with the format (wl, spectrum).
planet (dict) – POSEIDON planet properties dictionary.
data_properties (dict, optional) – POSEIDON observational data properties dictionary.
show_data (bool, optional) – Flag indicating whether to plot the observational data.
plot_full_res (bool, optional) – Flag indicating whether to plot full resolution model spectra.
bin_spectra (bool, optional) – Flag indicating whether to bin model spectra to the resolution specified by ‘R_to_bin’.
R_to_bin (int, optional) – Spectral resolution (R = wl/dwl) to bin the model spectra to.
plt_label (str, optional) – The label for the plot.
show_planet_name (bool, optional) – Flag indicating whether to include the planet name in the top left.
wl_min (float, optional) – The minimum wavelength to plot.
wl_max (float, optional) – The maximum wavelength to plot.
y_min (float, optional) – The minimum value for the y-axis.
y_max (float, optional) – The maximum value for the y-axis.
y_unit (str, optional) – The unit of the y-axis (Options: ‘transit_depth’, ‘eclipse_depth’, ‘(Rp/Rs)^2’, ‘(Rp/R*)^2’, ‘Fp/Fs’, ‘Fp/F*’, ‘Fp’, ‘Fs’, ‘F*’).
colour_list (list, optional) – A list of colours for the model spectra.
spectra_labels (list, optional) – A list of labels for the model spectra.
data_colour_list (list, optional) – A list of colours for the observational data points.
data_labels (list, optional) – A list of labels for the observational data.
data_marker_list (list, optional) – A list of marker styles for the observational data.
data_marker_size_list (list, optional) – A list of marker sizes for the observational data.
data_alpha_list (list of float, optional) – Alpha values for the central circle colours on each data point (defaults to 1.0 if not specified).
data_eline_alpha_list (list of float, optional) – Alpha values for the error bar colours on each data point (defaults to 0.8 if not specified).
data_edge_width_list (list of float, optional) – Border line width for the central circle on each data point (defaults to 0.8 if not specified).
data_eline_colour_list (list of str, optional) – Colours for data error bars (defaults to ‘black’ if not specified).
data_eline_width_list (list of float, optional) – Line widths for error bars (defaults to 1.0 if not specified).
line_width_list (list of float, optional) – Line widths for binned spectra (defaults to 2.0 if not specified).
line_style_list (list of str, optional) – Line styles for binned spectra (defaults to ‘-’ if not specified).
line_alpha_list (list of float, optional) – Alpha values for binned spectra (defaults to 0.8 if not specified).
text_annotations (list of str, optional) – A list of text annotations for Figure decoration (e.g. molecule names)
annotation_pos (list of tuples of str, optional) – (x, y) locations of the text annotations in the previous argument.
err_colour (str, optional) – Colour of the data error bars if they are all the same (you can use data_eline_colour_list to have different colours).
wl_axis (str, optional) – The type of x-axis to use (‘log’ or ‘linear’).
figure_shape (str, optional) – The shape of the figure (‘default’ or ‘wide’ - the latter is 16:9).
show_legend (bool, optional) – If False, will not plot legend.
legend_location (str, optional) – The location of the legend (‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’,’outside right’).
legend_box (bool, optional) – Flag indicating whether to plot a box surrounding the figure legend.
legend_line_size (list of float, optional) – Size of lines in the legend. Put 1 for data points
legend_n_columns (integer) – Manually set the number of columns for the legend.
ax (matplotlib axis object, optional) – Matplotlib axis provided externally.
save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.
model (dict, optional) – POSEIDON model dictionary. Required to be defined for offsets to be added.
show_data_bin_width (bool, optional) – Flag indicating whether to plot x bin widths for data points.
show_data_cap (bool, optional) – Flag indicating whether to plot the error bar caps on the data points.
add_retrieved_offsets (bool, optional) – Plots data with retrieved offset values.
add_retrieved_error_inflation (bool, optional) – Plots data error bars including retrieved error inflation value.
offsets (verbose) – Will print out offsets applied to which datasets.
x_labels (bool) – If False, will remove x_ticks labels and Wavelength (um).
x_wavelength_label (bool) – If False, will just remove ‘Wavelength (um)
x_tick_label (bool) – If False, will just remove the x tick labels
y_labels (bool) – If False, will remove y_ticks labels and y_label.
x_tick_fontsize (int, optional) – Font size for x-axis tick labels.
x_label_fontsize (int, optional) – Font size for x-axis label.
y_tick_fontsize (int, optional) – Font size for y-axis tick labels.
y_label_fontsize (int, optional) – Font size for y-axis label.
x_tick_list (list of floats, optional) – Sets the xticks
legend_fontsize (int, optional) – Font size for the legend.
plt_label_fontsize (int, optional) – Font size for the plot label.
planet_name_fontsize (int, optional) – Font size for the planet name.
plot_style (str, optional) – (Experimental!) plot style (‘standard’ or ‘fancy’).
fill_between (list of bools, optional) – If True, spectrum will have a fill color from its line to 0 or fill_to_spectrum.
fill_between_alpha (int, optional) – Alpha of the fill region.
fill_to_spectrum (list of ints, optional) – If non-empty, will fill spectra to this spectrum (instead of 0).
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The spectra plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_data(data, planet_name, wl_min=None, wl_max=None, y_min=None, y_max=None, y_unit='transit_depth', plt_label=None, data_colour_list=[], data_labels=[], data_marker_list=[], data_marker_size_list=[], err_colour='black', wl_axis='log', figure_shape='default', legend_location='upper right', legend_box=True, show_data_bin_width=True, show_data_cap=True, data_alpha=0.8, data_edge_width=0.8, ax=None, save_fig=True, x_tick_fontsize=12, x_label_fontsize=16, y_tick_fontsize=12, y_label_fontsize=16, legend_fontsize=10, plt_label_fontsize=14, planet_name_fontsize=16, dark_mode=False)

Plot a collection of datasets. This function can plot transmission or emission datasets, according to the user’s choice of ‘y_unit’.

Parameters:

data (dict) – POSEIDON observational data properties dictionary.
planet_name (str) – Name of the planet.
wl_min (float, optional) – The minimum wavelength to plot.
wl_max (float, optional) – The maximum wavelength to plot.
y_min (float, optional) – The minimum value for the y-axis.
y_max (float, optional) – The maximum value for the y-axis.
y_unit (str, optional) – The unit of the y-axis (Options: ‘transit_depth’, ‘eclipse_depth’, ‘(Rp/Rs)^2’, ‘(Rp/R*)^2’, ‘Fp/Fs’, ‘Fp/F*’, ‘Fp’).
plt_label (str, optional) – The label for the plot.
data_colour_list (list, optional) – A list of colours for the observational data points.
data_labels (list, optional) – A list of labels for the observational data.
data_marker_list (list, optional) – A list of marker styles for the observational data.
data_marker_size_list (list, optional) – A list of marker sizes for the observational data.
err_colour (string, optional) – Colour of the data error bars (white works best for a dark background)
wl_axis (str, optional) – The type of x-axis to use (‘log’ or ‘linear’).
figure_shape (str, optional) – The shape of the figure (‘default’ or ‘wide’ - the latter is 16:9).
legend_location (str, optional) – The location of the legend (‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’, ‘outside right’).
legend_box (bool, optional) – Flag indicating whether to plot a box surrounding the figure legend.
show_data_bin_width (bool, optional) – Flag indicating whether to plot x bin widths for data points.
show_data_cap (bool, optional) – Flag indicating whether to show the caps on the data error bars.
data_alpha (float, optional) – Alpha for the central circle colours on each data point.
data_edge_width (float, optional) – Border line width for the central circle on each data point.
ax (matplotlib axis object, optional) – Matplotlib axis provided externally.
save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.
x_tick_fontsize (int, optional) – Font size for x-axis tick labels.
x_label_fontsize (int, optional) – Font size for x-axis label.
y_tick_fontsize (int, optional) – Font size for y-axis tick labels.
y_label_fontsize (int, optional) – Font size for y-axis label.
legend_fontsize (int, optional) – Font size for the legend.
plt_label_fontsize (int, optional) – Font size for the plot label.
planet_name_fontsize (int, optional) – Font size for the planet name.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The data plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_spectra_retrieved(spectra_median, spectra_low2, spectra_low1, spectra_high1, spectra_high2, planet_name, data_properties, R_to_bin=100, plt_label=None, show_ymodel=True, show_planet_name=True, wl_min=None, wl_max=None, y_min=None, y_max=None, y_unit='transit_depth', colour_list=[], spectra_labels=[], data_colour_list=[], data_labels=[], data_marker_list=[], data_marker_size_list=[], data_alpha_list=[], data_eline_alpha_list=[], data_edge_width_list=[], data_eline_colour_list=[], data_eline_width_list=[], line_width_list=[], line_style_list=[], line_alpha_list=[], binned_colour_list=[], text_annotations=[], annotation_pos=[], err_colour='black', wl_axis='log', figure_shape='default', show_legend=True, legend_location='upper right', legend_box=False, legend_line_size=[], legend_n_columns=0, ax=None, save_fig=True, model=None, show_data_bin_width=True, show_data_cap=True, sigma_to_plot=2, add_retrieved_offsets=False, verbose_offsets=True, add_retrieved_error_inflation=False, xlabels=True, ylabels=True, x_tick_fontsize=12, x_label_fontsize=16, y_tick_fontsize=12, y_label_fontsize=16, legend_fontsize=10, plt_label_fontsize=14, planet_name_fontsize=16, plot_style='standard', fill_between=[], fill_between_alpha=0.5, fill_to_spectrum=[], fill_to_spectrum_list=[], dark_mode=False)

Plot a collection of individual model spectra. This function can plot transmission or emission spectra, according to the user’s choice of ‘y_unit’.

Parameters:

spectra_median (list of tuples) – A list of median spectra to be plotted, each with the format (wl, spec_median).
spectra_low2 (list of tuples) – Corresponding list of -2σ confidence intervals on the retrieved spectra, each with the format (wl, spec_low2).
spectra_low1 (list of tuples) – Corresponding list of -1σ confidence intervals on the retrieved spectra, each with the format (wl, spec_low1).
spectra_high1 (list of tuples) – Corresponding list of +1σ confidence intervals on the retrieved spectra, each with the format (wl, spec_high1).
spectra_high2 (list of tuples) – Corresponding list of +2σ confidence intervals on the retrieved spectra, each with the format (wl, spec_high2).
planet_name (str) – Planet name to overplot on figure.
data_properties (dict, optional) – POSEIDON observational data properties dictionary.
R_to_bin (int, optional) – Spectral resolution (R = wl/dwl) to bin the model spectra to.
plt_label (str, optional) – The label for the plot.
show_ymodel (bool, optional) – Flag indicating whether to plot the median retrieved spectra binned to the data resolution.
show_planet_name (bool, optional) – Flag indicating whether to include the planet name in the top left.
wl_min (float, optional) – The minimum wavelength to plot.
wl_max (float, optional) – The maximum wavelength to plot.
y_min (float, optional) – The minimum value for the y-axis.
y_max (float, optional) – The maximum value for the y-axis.
y_unit (str, optional) – The unit of the y-axis (Options: ‘transit_depth’, ‘eclipse_depth’, ‘(Rp/Rs)^2’, ‘(Rp/R*)^2’, ‘Fp/Fs’, ‘Fp/F*’, ‘Fp’).
colour_list (list, optional) – A list of colours for the model spectra.
spectra_labels (list, optional) – A list of labels for the model spectra.
data_colour_list (list, optional) – A list of colours for the observational data points.
data_labels (list, optional) – A list of labels for the observational data.
data_marker_list (list, optional) – A list of marker styles for the observational data.
data_marker_size_list (list, optional) – A list of marker sizes for the observational data.
data_alpha_list (list of float, optional) – Alpha values for the central circle colours on each data point (defaults to 1.0 if not specified).
data_eline_alpha_list (list of float, optional) – Alpha values for the error bar colours on each data point (defaults to 0.8 if not specified).
data_edge_width_list (list of float, optional) – Border line width for the central circle on each data point (defaults to 0.8 if not specified).
data_eline_colour_list (list of str, optional) – Colours for data error bars (defaults to ‘black’ if not specified).
data_eline_width_list (list of float, optional) – Line widths for error bars (defaults to 1.0 if not specified).
line_width_list (list of float, optional) – Line widths for median spectra (defaults to 1.0 if not specified).
line_style_list (list of str, optional) – Line styles for median spectra (defaults to ‘-’ if not specified).
line_alpha_list (list of float, optional) – Alpha values for median spectra (defaults to 0.8 if not specified).
binned_colour_list (list, optional) – A list of colours for the binned models.
text_annotations (list of str, optional) – A list of text annotations for Figure decoration (e.g. molecule names)
annotation_pos (list of tuples of str, optional) – (x, y) locations of the text annotations in the previous argument.
err_colour (string, optional) – Colour of the data error bars (white works best for a dark background)
wl_axis (str, optional) – The type of x-axis to use (‘log’ or ‘linear’).
figure_shape (str, optional) – The shape of the figure (‘default’ or ‘wide’ - the latter is 16:9).
show_legend (bool, optional) – If False, will not plot legend.
legend_location (str, optional) – The location of the legend (‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’, ‘outside right’).
legend_box (bool, optional) – Flag indicating whether to plot a box surrounding the figure legend.
legend_line_size (list of float, optional) – Size of lines in the legend. Put 1 for data points
legend_n_columns (integer) – Manually set the number of columns for the legend.
ax (matplotlib axis object, optional) – Matplotlib axis provided externally.
save_fig (bool, optional) – If True, saves a PDF in the POSEIDON output folder.
model (dict, optional) – POSEIDON model dictionary. Required to be defined for offsets to be added.
show_data_bin_width (bool, optional) – Flag indicating whether to plot x bin widths for data points.
show_data_cap (bool, optional) – Flag indicating whether to plot the error bar caps on the data points.
sigma_to_plot (int, optional) – How many sigma contours to plot (0 for only median, 1 for median and 1 sigma, or 2 for median, 1 sigma, and 2 sigma).
add_retrieved_offsets (bool, optional) – Plots data with retrieved offset values.
add_retrieved_error_inflation (bool, optional) – Plots data error bars including retrieved error inflation value.
offsets (verbose) – Will print out offsets applied to which datasets.
x_labels (bool, optional) – If false, will remove x_ticks and x_label.
y_labels (bool, optional) – If false, will remove y_ticks and y_label.
legend_n_columns – Manually set the number of columns for the legend.
x_tick_fontsize (int, optional) – Font size for x-axis tick labels.
x_label_fontsize (int, optional) – Font size for x-axis label.
y_tick_fontsize (int, optional) – Font size for y-axis tick labels.
y_label_fontsize (int, optional) – Font size for y-axis label.
legend_fontsize (int, optional) – Font size for the legend.
plt_label_fontsize (int, optional) – Font size for the plot label.
planet_name_fontsize (int, optional) – Font size for the planet name.
plot_style (str, optional) – (Experimental!) plot style (‘standard’ or ‘fancy’).
fill_between (list of bools, optional) – If True, spectrum will have a fill color from its line to 0 or fill_to_spectrum.
fill_between_alpha (int, optional) – Alpha of the fill region.
fill_to_spectrum (list of ints, optional) – If non-empty, will fill spectra to this spectrum (instead of 0).
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The retrieved spectra plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_PT_retrieved(planet_name, PT_median, PT_low2, PT_low1, PT_high1, PT_high2, T_true=None, Atmosphere_dimension=1, TwoD_type=None, plt_label=None, show_profiles=[], PT_labels=[], colour_list=[], log_P_min=None, log_P_max=None, T_min=None, T_max=None, legend_location='lower left', ax=None, save_fig=True, sigma_to_plot=2, show_legend=True, custom_ticks=[], ylabels=True, retrieved_log_P_surf=[], log_P_surf_sigma_upper_lower='upper', log_P_surf_histogram_list=[], dark_mode=False)

Plot retrieved Pressure-Temperature (P-T) profiles.

Parameters:

planet_name (str) – The name of the planet.
PT_median (list of tuples) – List of tuples containing the median temperature and pressure grids for each model, each with the format (T_median, P).
PT_low2 (list of tuples) – Corresponding list of -2σ confidence intervals on the retrieved temperature, each with the format (T_low2, P).
PT_low1 (list of tuples) – Corresponding list of -1σ confidence intervals on the retrieved temperature, each with the format (T_low1, P).
PT_high1 (list of tuples) – Corresponding list of +1σ confidence intervals on the retrieved temperature, each with the format (T_high1, P).
PT_high2 (list of tuples) – Corresponding list of +2σ confidence intervals on the retrieved temperature, each with the format (T_high2, P).
T_true (np.array, optional) – True temperature profile (optional).
Atmosphere_dimension (int, optional) – Dimensionality of the atmospheric model.
TwoD_type (str, optional) – If ‘Atmosphere_dimension’ = 2, the type of 2D model (Options: ‘D-N’ for day-night, ‘E-M’ for evening-morning).
plt_label (list, optional) – List of labels for each model.
show_profiles (list, optional) – If model is 2D or 3D, which profiles to plot.
PT_labels (list, optional) – List of labels for each retrieved P-T profile.
colour_list (list, optional) –

List of colours for each retrieved P-T profile.
log_P_min (float, optional):

Minimum value for the log10 pressure.
log_P_max (float, optional):

Maximum value for the log10 pressure.
T_min (float, optional):

Minimum temperature to plot.
T_max (float, optional):

Maximum temperature to plot.
legend_location (str, optional):

Location of the legend. Default is ‘lower left’.
show_legend (bool, optional):

If False, will not show legend.
custom_ticks (list, optional) – Major and minor ticks
ylabels (bool, optional) – If False, will not plot y ticks
retrieved_log_P_surf (list, optional) – Will overplot 1 sigma P_surf (Retrieved log_P_surf, one_sigma_positive, one_sigma_negative)
log_P_surf_sigma_upper_lower (str, optional) – Will set things depending on if its an upper or lower limit or unconstrained.
log_P_surf_histogram_list (list, optional) – When plotting a histogram of the retrieved log_P_surf values, set to True for each model to be plotted.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Return type:

fig (matplotlib figure object)

The retrieved P-T profile plot.

POSEIDON.visuals.plot_chem_retrieved(planet_name, chemical_species, log_Xs_median, log_Xs_low2, log_Xs_low1, log_Xs_high1, log_Xs_high2, log_X_true=None, plot_species=[], plot_two_sigma=False, Atmosphere_dimension=1, TwoD_type=None, plt_label=None, show_profiles=[], model_labels=[], colour_list=[], log_P_min=None, log_P_max=None, log_X_min=None, log_X_max=None, chem_labels=[], legend_location='upper right', show_legend=True, ax=None, save_fig=True, sigma_to_plot=1, dark_mode=False)

Plot retrieved mixing ratio profiles.

Supports multi-region models (e.g. dayside/nightside) when the user supplies one entry per region in the log_Xs_* collections (produced by calling read_retrieved_log_X once per region and appending via plot_collection). Each region is distinguished by line style while colours denote chemical species.

Parameters:

planet_name (str) – The name of the planet.
chemical_species (list) – List of chemical species included in the model (including bulk species).
log_Xs_median (list of tuples) – List of tuples, one per region or model, each containing the median retrieved log10 mixing ratio array (N_species x N_layers) and the pressure grid, with the format (log10 X_median, P).
log_Xs_low2 (list of tuples) – Corresponding list of -2 sigma confidence intervals on the retrieved log10 mixing ratio for each region, each with the form (log10 X_low2, P).
log_Xs_low1 (list of tuples) – Corresponding list of -1 sigma confidence intervals on the retrieved log10 mixing ratio for each region, each with the form (log10 X_low1, P).
log_Xs_high1 (list of tuples) – Corresponding list of +1 sigma confidence intervals on the retrieved log10 mixing ratio for each region, each with the form (log10 X_high1, P).
log_Xs_high2 (list of tuples) – Corresponding list of +2 sigma confidence intervals on the retrieved log10 mixing ratio for each region, each with the form (log10 X_high2, P).
log_X_true (2D np.array, optional) – True log10 mixing ratio profiles for each chemical species.
plot_species (list, optional) – List of chemical species to plot. If not specified, default to all chemical species in the model (including bulk species).
plot_two_sigma (bool, optional) – If False, only plots the median and +/- 1 sigma confidence intervals for each chemical species (default behaviour to avoid clutter).
Atmosphere_dimension (int, optional) – Dimensionality of the atmospheric model (kept for backward compatibility but no longer restricts plotting).
TwoD_type (str, optional) – If ‘Atmosphere_dimension’ = 2, the type of 2D model (Options: ‘D-N’ for day-night, ‘E-M’ for evening-morning).
plt_label (str, optional) – Label used in the output filename.
show_profiles (list, optional) – If model is 2D or 3D, which profiles to plot.
model_labels (list, optional) – List of labels for each retrieved model (only used when a single region is provided). For multi-region plots use chem_labels instead.
colour_list (list, optional) – List of colours for each chemical species plotted.
log_P_min (float, optional) – Minimum value for the log10 pressure.
log_P_max (float, optional) – Maximum value for the log10 pressure.
log_X_min (float, optional) – Minimum log10 mixing ratio to plot.
log_X_max (float, optional) – Maximum log10 mixing ratio to plot.
chem_labels (list, optional) – Labels for each region entry (e.g. [‘dayside’, ‘nightside’]). If not specified, regions are numbered.
legend_location (str, optional) – Location of the legend. Default is ‘upper right’.
show_legend (bool, optional) – If True, show legend on the plot.
ax (matplotlib axis, optional) – If provided, plots on the given axis instead of creating a new figure.
save_fig (bool, optional) – If True, saves the figure to disk.
sigma_to_plot (int, optional) – How many sigma confidence regions to shade (1 or 2). Default is 1.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The retrieved mixing ratio profile plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_stellar_flux(flux, wl, wl_min=None, wl_max=None, flux_min=None, flux_max=None, flux_axis='linear', wl_axis='log', dark_mode=False)

Straightforward function to plot an emergent stellar spectrum.

Parameters:

flux (np.array) – Surface flux of the star as a function of wavelength.
wl (np.array) – Corresponding wavelength array.
wl_min (float, optional) – Minimum wavelength for x axis.
wl_max (float, optional) – Maximum wavelength for x axis.
flux_min (float, optional) – Minimum flux for y axis.
flux_max (float, optional) – Maximum flux for y axis.
flux_axis (str, optional) – ‘linear’ or ‘log’ axis scaling for the y-axis. Default is ‘linear’.
wl_axis (str, optional) – ‘linear’ or ‘log’ axis scaling for the x-axis. Default is ‘log’.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The simplest stellar flux plot you’ve ever seen.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.plot_histogram(nbins, vals, colour, ax, shrink_factor, x_max_array, alpha_hist, orientation)

Function to plot a histogram of parameter values.

Parameters:

nbins (int) – Number of bins for the histogram.
vals (list) – List of parameter values for each model.
colour (str) – Colour for the histogram.
ax (matplotlib axis object) – Axis to plot on.
shrink_factor (float) – Factor to shrink the y-axis.
x_max_array (np.array) – Array of maximum x values for scaling.
alpha_hist (float) – Alpha value for histogram bars.

Returns:

Confidence intervals for the parameter values.

Return type:

low3, low2, low1, median, high1, high2, high3

POSEIDON.visuals.plot_parameter_panel(ax, param_vals, N_bins, param_min, param_max, colour, x_max_array, alpha_hist, orientation)

Setup function to plot the histogram panel for a given parameter.

Parameters:

ax (matplotlib axis object) – Axis to plot on.
param_vals (list) – List of parameter values for each model.
N_bins (int) – Number of bins for the histogram.
param_min (float) – Minimum value for the parameter.
param_max (float) – Maximum value for the parameter.
colour (str) – Colour for the histogram.
x_max_array (np.array) – Array of maximum x values for scaling.
alpha_hist (float) – Alpha value for histogram bars.

Returns:

Lower 1σ confidence interval. median (float):

Median value.

high1 (float):: Upper 1σ confidence interval.

Return type:

low1 (float)

POSEIDON.visuals.plot_retrieved_parameters(axes_in, param_vals, plot_parameters, parameter_colour_list, retrieval_colour_list, retrieval_labels, span, truths, N_rows, N_columns, N_bins, vertical_lines, vertical_lines_colors, tick_labelsize=8, title_fontsize=12, title_vert_spacing=0.2, custom_labels=[], custom_ticks=[], alpha_hist=0.4, show_title=True, two_sigma_upper_limits_full=[], two_sigma_lower_limits_full=[], orientation='vertical', title_alpha_list=[], use_parameter_color_for_title=False, title_colour_list=[], dark_mode=False)

Plot retrieved parameters as histograms.

Parameters:

axes_in (list) – List of axes to plot on. If empty, new axes will be created.
param_vals (list) – List of parameter values for each model.
plot_parameters (list) – List of parameters to plot.
parameter_colour_list (list) – List of colours for each parameter.
retrieval_colour_list (list) – List of colours for each retrieval.
retrieval_labels (list) – List of labels for each retrieval.
span (list) – List of min and max values for each parameter.
truths (list) – True values for each parameter.
N_rows (int) – Number of rows in the plot grid.
N_columns (int) – Number of columns in the plot grid.
N_bins (list) – Number of bins for each histogram.
vertical_lines (list) – Vertical lines to plot on the histograms.
vertical_lines_colors (list) – Colours for the vertical lines.
tick_labelsize (int, optional) – Font size for tick labels. Default is 8.
title_fontsize (int, optional) – Font size for titles. Default is 12.
title_vert_spacing (float, optional) – Vertical spacing between titles. Default is 0.2.
custom_labels (list, optional) – Custom labels for the parameters. Default is empty list.
custom_ticks (list, optional) – Custom ticks for the parameters. Default is empty list.
alpha_hist (float or list of floats, optional) – Alpha value for histogram bars. Default is 0.4. Can be a list for multiple histograms stacked.
show_title (bool, optional) – Whether to show titles on the plots. Default is True.
two_sigma_upper_limits_full (1D or 2D list of str, optional) – Upper limits for two sigma confidence intervals. Default is empty list.
two_sigma_lower_limits_full (1D or 2D list of str, optional) – Lower limits for two sigma confidence intervals. Default is empty list.
use_parameter_color_for_title (bool) – If true, will use parameter color for title and constraints.
title_colour_list (list of str) – List of colours to use for titles and constraints if use_parameter_color_for_title is False.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

Returns:

The retrieved parameters plot.

Return type:

fig (matplotlib figure object)

POSEIDON.visuals.elemental_ratio_samples(all_species, X_vals, element_1, element_2)

Helper function to calculate the abundance ratio between any two elements in the atmosphere.

Example: to compute the C/O ratio, use element_1 = ‘C’ and element_2 = ‘O’.

Parameters:

all_species (np.array of str) – List of all chemical species included in the model.
X_vals (2D np.array of float) – Mixing ratio samples.
element_1 (str) – First element in ratio.
element_2 (str) – First element in ratio.

Returns:

Abundance ratio samples.

Return type:

element_ratio (np.array of float)

POSEIDON.visuals.plot_histograms(planet, models, plot_parameters, parameter_colour_list=[], retrieval_colour_list=[], retrieval_labels=[], span=[], truths=[], N_bins=[], N_rows=None, N_columns=None, axes=[], retrieval_codes=[], external_samples=[], external_param_names=[], plt_label=None, save_fig=True, show_title=True, vertical_lines=[], vertical_line_colors=[], tick_labelsize=None, title_fontsize=None, title_vert_spacing=None, custom_labels=[], custom_ticks=[], alpha_hist=0.4, two_sigma_upper_limits=[], two_sigma_lower_limits=[], orientation='vertical', title_alpha_list=[], use_parameter_color_for_title=False, title_colour_list=[], dark_mode=False)

Plot a set of histograms from one or more retrievals.

Parameters:

planet (dict) – Dictionary containing the planet properties.
models (list of dicts) – List of dictionaries containing the model properties.
plot_parameters (list of str) – List of parameters to plot.
parameter_colour_list (list of str, optional) – List of colours for each parameter.
retrieval_colour_list (list of str, optional) – List of colours for each retrieval model.
retrieval_labels (list of str, optional) – List of labels for each retrieval model.
span (list of float, optional) – Span for each parameter to plot.
truths (list of float, optional) – True values for each parameter.
N_bins (list of int, optional) – Number of bins for each histogram.
N_rows (int, optional) – Number of rows in the figure. Default is None.
N_columns (int, optional) – Number of columns in the figure. Default is None.
axes (list of matplotlib axes, optional) – List of axes to plot on. Default is empty list.
retrieval_codes (list of str, optional) – List of retrieval codes for each model. Default is empty list.
external_samples (list of np.array, optional) – List of external samples for each model. Default is empty list.
external_param_names (list of list of str, optional) – List of external parameter names for each model. Default is empty list.
plt_label (str, optional) – Label for the plot file name. Default is None.
save_fig (bool, optional) – Whether to save the figure or not. Default is True.
show_title (bool, optional) – Whether to show the title or not. Default is True.
vertical_lines (list of float, optional) – List of vertical lines to plot. Default is empty list.
vertical_line_colors (list of str, optional) – List of colors for vertical lines. Default is empty list.
tick_labelsize (int, optional) – Font size for tick labels. If None and axes provided, will auto-scale based on figure size. Default is None.
title_fontsize (int, optional) – Font size for titles. If None and axes provided, will auto-scale based on figure size. Default is None.
title_vert_spacing (float, optional) – Vertical spacing between titles. If None and axes provided, will auto-scale based on title font size. Default is None.
custom_labels (list of str, optional) – Custom labels for the parameters. Default is empty list.
custom_ticks (list of list of float, optional) – Custom ticks for the x-axis. Default is empty list.
alpha_hist (float or list of floats, optional) – Transparency for the histograms. Default is 0.4. Can be a list (for each histogram)
two_sigma_upper_limits (1D or 2D list of str, optional) – List of parameters with two sigma upper limits. Default is empty list. If 1D, will apply two_sigma_upper_limit to all models. If 2D, will only do it for specific models.
two_sigma_lower_limits (1D or 2D list of str, optional) – List of parameters with two sigma lower limits. Default is empty list. If 1D, will apply two_sigma_lower_limit to all models. If 2D, will only do it for specific models.
title_alpha_list (list of float) – If multiple models or retrievals are being plotted, can set One or more alphas in the cascade of titles on top of histogram.
use_parameter_color_for_title (bool) – If true, will use parameter color for title and constraints.
title_colour_list (list of str) – List of colours to use for titles and constraints if use_parameter_color_for_title is False.
dark_mode (bool, optional) – If True, uses a dark background with white text and axes. Defaults to False (light mode).

POSEIDON.visuals.vary_one_parameter_PT(model, planet, param_name, vary_list, P, P_ref, R_p_ref, PT_params_og, log_X_params_og, cloud_params_og, ax=None, legend_location='upper right')

This function is used in the tutorial notebooks to show how turning a knob on a parameter changes the resulting PT profile.

Parameters:

model (dict) – A specific description of a given POSEIDON model.
planet (dict) – Collection of planetary properties used by POSEIDON.
param_name (string) – Name of the parameter to vary
vary_list (array of float) – Array containing values to test
P (np.array of float) – Model pressure grid (bar).
P_ref (float) – Reference pressure (bar).
R_p_ref (float) – Planet radius corresponding to reference pressure (m).
PT_params_og (np.array of float) – Original parameters defining the pressure-temperature field.
log_X_params_og (np.array of float) – Original parameters defining the log-mixing ratio field.
cloud_params_og (np.array of float) – Original parameters defining atmospheric aerosols.
legend_location (str, optional) – The location of the legend (‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’).
ax (matplotlib axis object, optional) – Matplotlib axis provided externally.

Returns:

Outputs a plot of resultant spectra with the param_name at the vary_list values.