POSEIDON.corner =============== .. py:module:: POSEIDON.corner .. autoapi-nested-parse:: Functions to generate corner plots. Contributions from: Johannes Buchner [PyMultiNest] (C) 2013-2019 Josh Speagle [Dynesty] (MIT licensed) Ryan MacDonald [POSEIDON modifications] (2021-2025) Attributes ---------- .. autoapisummary:: POSEIDON.corner.str_type POSEIDON.corner.SQRTEPS POSEIDON.corner.comm POSEIDON.corner.rank POSEIDON.corner.global_max_hist_values POSEIDON.corner.dark_theme POSEIDON.corner.light_theme Functions --------- .. autoapisummary:: POSEIDON.corner.scale_lightness POSEIDON.corner._quantile POSEIDON.corner.resample_equal POSEIDON.corner._hist2d POSEIDON.corner.cornerplot POSEIDON.corner.generate_cornerplot POSEIDON.corner.generate_overplot Module Contents --------------- .. py:data:: str_type .. py:data:: SQRTEPS .. py:data:: comm .. py:data:: rank .. py:data:: global_max_hist_values .. py:data:: dark_theme .. py:data:: light_theme .. py:function:: scale_lightness(colour_name, scale) Scale the lightness of a colour by the given factor. :param colour_name: The name of the colour to be scaled, in matplotlib colour format. :type colour_name: str :param scale: The factor by which to scale the lightness of the colour (< 1 makes the colour darker). :type scale: float :returns: A tuple containing the RGB values of the scaled colour. :rtype: tuple .. py:function:: _quantile(x, q, weights=None) Compute (weighted) quantiles from an input set of samples. :param x: Input samples. :type x: np.array of float :param q: The list of quantiles to compute (ranging from 0 to 1). :type q: np.array of float :param weights: The associated weight from each sample. :type weights: np.array of float :returns: The weighted sample quantiles computed at 'q'. :rtype: quantiles (np.array of float) .. py:function:: resample_equal(samples, weights, rstate=None) Resample a new set of points from the weighted set of inputs, such that they all have equal weight. Each input sample appears in the output array either 'floor(weights[i] * nsamples)' or 'ceil(weights[i] * nsamples)' times, with 'floor' or 'ceil' randomly selected (weighted by proximity). Note: implements the systematic resampling method described in Hol, Schon, and Gustafsson (2006): doi:10.1109/NSSPW.2006.4378824. :param samples: Set of unequally weighted samples. :type samples: np.array of float :param weights: Corresponding weight of each sample. :type weights: np.array of float :param rstate: Numpy 'RandomState' instance. :type rstate: np.random.RandomState :returns: New set of samples with equal weights. :rtype: equal_weight_samples (np.array of float) .. py:function:: _hist2d(x, y, smooth=0.02, span=None, weights=None, levels=None, ax=None, colour='gray', plot_datapoints=False, plot_density=True, plot_contours=True, no_fill_contours=False, fill_contours=True, contour_kwargs=None, contourf_kwargs=None, data_kwargs=None, **kwargs) Internal function called by the 'cornerplot' function to generate a 2D histogram / contour of samples. :param x: Sample positions in the first dimension. :type x: np.array of float :param y: Sample positions in the second dimension. :type y: np.array of float :param smooth: Gaussian smoothing factor for 2D contours. :type smooth: float :param span: A list where each element is either a length-2 tuple containing lower and upper bounds or a float from `(0., 1.]` giving the fraction of (weighted) samples to include. If a fraction is provided, the bounds are chosen to be equal-tailed. If not specified, defaults to +/- 5σ range. Example: span = [(0., 10.), 0.95, (5., 6.)]. :type span: list of tuples or float :param weights: Weights associated with the samples. :type weights: np.array of float :param levels: The contour levels to draw. Default are [1σ, 2σ, 3σ]. :type levels: np.array of float :param ax: A matplotlib axis instance on which to add the 2-D histogram. If not provided, a figure will be generated. :type ax: matplotlib axis object :param colour: The matplotlib-style colour used to draw lines, colour cells, and contours. Default is 'gray'. :type colour: str :param plot_datapoints: Whether to plot the individual data points. Default is False. :type plot_datapoints: bool :param plot_density: Whether to draw the density colourmap. Default is True. :type plot_density: bool :param plot_contours: Whether to draw the contours. Default is True. :type plot_contours: bool :param no_fill_contours: Whether to add absolutely no filling to the contours. This differs from 'fill_contours = False', which still adds a white fill at the densest points. Default is False. :type no_fill_contours: bool :param fill_contours: Whether to fill the contours. Default is True. :type fill_contours: bool :param contour_kwargs: Any additional keyword arguments to pass to the 'contour' method. :type contour_kwargs: dict :param contourf_kwargs: Any additional keyword arguments to pass to the 'contourf' method. :type contourf_kwargs: dict :param data_kwargs: Any additional keyword arguments to pass to the 'plot' method when adding the individual data points. :type data_kwargs: dict :returns: None. .. py:function:: cornerplot(results, span=None, quantiles=[0.1587, 0.5, 0.8413], colour_plt='purple', colour_quantile='blue', smooth_hist=30, smooth_corr=0.02, hist_kwargs=None, hist2d_kwargs=None, labels=None, param_names=None, label_kwargs=None, show_titles=True, title_kwargs=None, title_fontsize=12, truths=None, truth_colour='red', truth_kwargs=None, max_n_ticks=5, top_ticks=False, use_math_text=False, verbose=False, fig=None, model_idx=None, two_sigma_upper_limits=[], two_sigma_lower_limits=[], title_vertical_padding=0.1, dark_mode=False) Generate a corner plot of the 1D and 2D marginalised posteriors. :param results: Results dictionary containing the samples and weights from a nested sampling retrieval. :type results: dict :param span: A list where each element is either a length-2 tuple containing lower and upper bounds or a float from `(0., 1.]` giving the fraction of (weighted) samples to include. If a fraction is provided, the bounds are chosen to be equal-tailed. If not specified, defaults to +/- 5σ range. Example: span = [(0., 10.), 0.95, (5., 6.)]. :type span: list of tuples or float :param quantiles: A list of fractional quantiles to overplot on the 1D marginalised posteriors as vertical dashed lines. Default is '[0.1587, 0.5, 0.8413]' (spanning the 68% / 1σ confidence interval). :type quantiles: np.array of float :param colour_plt: Matplotlib-style colour for the histograms and probability contours. :type colour_plt: str :param colour_quantile: Matplotlib-style for the vertical dashed quantile lines. :type colour_quantile: str :param smooth_hist: The standard deviation for the Gaussian kernel used to smooth the 1D histograms, expressed as a fraction of the span, if a float provided. If an integer is provided instead, this will instead default to a simple (weighted) histogram with 'bins=smooth'. Default is 30 bins. :type smooth_hist: float or int :param smooth_corr: The standard deviation for the Gaussian kernel used to smooth the 2D contours, expressed as a fraction of the span, if a float provided. Default is 2% smoothing. :type smooth_corr: float :param hist_kwargs: Extra keyword arguments to send to the 1D histograms. :type hist_kwargs: dict :param hist2d_kwargs: Extra keyword arguments to send to the 2D contours. :type hist2d_kwargs: dict :param labels: A list of names for each parameter. If not provided, the default name used when plotting will follow the math module 'x_i' style. :type labels: np.array of str :param param_names: List of parameter names used by POSEIDON for this retrieval. :type param_names: np.array of str :param label_kwargs: Extra keyword arguments that will be sent to the matplotlib axes 'set_xlabel' and 'set_ylabel' methods. :type label_kwargs: dict :param show_titles: Whether to display a title above each 1D marginalised posterior showing the median along with the upper/lower bounds associated with the 1σ confidence interval. Default is True. :type show_titles: bool :param title_kwargs: Extra keyword arguments that will be sent to the matplotlib axes 'set_title' command. :type title_kwargs: dict :param truths: A list of reference values that will be overplotted on the traces and marginalised 1D histograms as solid horizontal/vertical lines. Individual values can be exempt using 'None'. Default is 'None'. :type truths: list of float :param truth_colour: Matplotlib-style colour (either a single colour or a different value for each subplot) used when plotting 'truths'. Default is 'red'. :type truth_colour: str or list of str :param truth_kwargs: Extra keyword arguments that will be used for plotting the vertical and horizontal lines with 'truths'. :type truth_kwargs: dict :param max_n_ticks: Maximum number of ticks allowed. Default is '5'. :type max_n_ticks: int :param top_ticks: Whether to label the top (rather than bottom) ticks. Default is False. :type top_ticks: bool :param use_math_text: Whether the axis tick labels for very large/small exponents should be displayed as powers of 10 rather than using 'e'. Default is False. :type use_math_text: bool :param verbose: Whether to print the values of the computed quantiles associated with each parameter. Default is False. :type verbose: bool :param fig: If provided, overplot the traces and marginalised 1D histograms onto the provided figure. Otherwise, by default an internal figure is generated. :type fig: matplotlib figure object :param two_sigma_upper_limits: List of parameters for which the 2σ upper limit will be plotted instead of the 1σ range. :type two_sigma_upper_limits: list of str :param two_sigma_lower_limits: List of parameters for which the 2σ lower limit will be plotted instead of the 1σ range. :type two_sigma_lower_limits: list of str :param title_vertical_padding: Vertical padding for the titles for multiple overlapping corner plots. :type title_vertical_padding: float :param dark_mode: If True, uses a dark background with white text and axes. Defaults to False (light mode). :type dark_mode: bool :returns: Output corner plot. :rtype: cornerplot (matplotlib figure, matplotlib axes objects) .. py:function:: generate_cornerplot(planet, model, params_to_plot=None, retrieval_name=None, true_vals=None, colour_scheme='#984ea3', span=None, corner_name=None, two_sigma_upper_limits=[], two_sigma_lower_limits=[], N_bins=30, dark_mode=False, labels=None, colour_quantile='royalblue', label_kwargs={'fontsize': 18}) Generate giant triangle plot of doom to visualise the results of a POSEIDON retrieval. :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param model: Dictionary containing the description of the POSEIDON model. :type model: dict :param retrieval_name: Optional retrieval name suffix after the model name. :type retrieval_name: str :param true_vals: True values of parameters to overplot. :type true_vals: list of float :param colour_scheme: Desired colour for the histograms and probability contours. :type colour_scheme: str with hex code :param span: Range to plot for each parameter (overrules default +/- 5σ range). :type span: list of tuples of float :param corner_name: Optional file name prefix for the corner plot. :type corner_name: str :param two_sigma_upper_limits: List of parameters for which the 2σ upper limit will be plotted instead of the 1σ range. :type two_sigma_upper_limits: list of str :param two_sigma_lower_limits: List of parameters for which the 2σ lower limit will be plotted instead of the 1σ range. :type two_sigma_lower_limits: list of str :param N_bins: Number of bins to use for the histograms. :type N_bins: int :param dark_mode: If True, uses a dark background with white text and axes. Defaults to False (light mode). :type dark_mode: bool, optional :param labels: Custom labels for the parameters to use on the plot axes. If not provided, default LaTeX-style labels will be generated. :type labels: list of str, optional :param colour_quantile: Colour for the quantile lines on the 1D histograms. Default is 'royalblue'. :type colour_quantile: str, optional :param label_kwargs: Extra keyword arguments that will be sent to the matplotlib axes 'set_xlabel' and 'set_ylabel' methods. :type label_kwargs: dict, optional :returns: Your new triangle plot of doom. Use responsibly! :rtype: fig (matplotlib figure object) .. py:function:: generate_overplot(planet, models, params_to_plot=None, model_display_names=None, true_vals=None, truth_colour='green', colour_schemes=['royalblue', 'orangered'], span=None, overplot_name=None, annotation_text_size=20, title_font_size=12, two_sigma_upper_limits=[], two_sigma_lower_limits=[], external_samples=[], external_param_names=[], title_vertical_padding=0.1, N_bins=30, dark_mode=False) Generate overplotted giant triangle plot of doom to visualise the results of multiple POSEIDON retrievals. :param planet: Collection of planetary properties used by POSEIDON. :type planet: dict :param model: Dictionary containing the description of the POSEIDON model. :type model: dict :param retrieval_name: Optional retrieval name suffix after the model name. :type retrieval_name: str :param true_vals: True values of parameters to overplot. :type true_vals: list of float :param colour_scheme: Desired colour for the histograms and probability contours. :type colour_scheme: str with hex code :param span: Range to plot for each parameter (overrules default +/- 5σ range). :type span: list of tuples of float :param overplot_name: Optional file name prefix for the overplot. :type overplot_name: str :param two_sigma_upper_limits: List of parameters for which the 2σ upper limit will be plotted instead of the 1σ range. :type two_sigma_upper_limits: list of str :param two_sigma_lower_limits: List of parameters for which the 2σ lower limit will be plotted instead of the 1σ range. :type two_sigma_lower_limits: list of str :param external_samples: List of external samples to overplot. Each element should be a 2D array of shape (N_samples, N_params). :type external_samples: list of np.array :param external_param_names: List of parameter names for each external sample. Each element should be a 1D array of shape (N_params,). :type external_param_names: list of np.array :param title_vertical_padding: Vertical padding for the titles for multiple overlapping corner plots. :type title_vertical_padding: float :param N_bins: Number of bins to use for the histograms. :type N_bins: int :param dark_mode: If True, uses a dark background with white text and axes. Defaults to False (light mode). :type dark_mode: bool, optional :returns: Your new triangle plot of doom. Use responsibly! :rtype: fig (matplotlib figure object)