Distribution plots

The main user-facing methods documented in Joint distribution plots and One-dimensional distributions dispatch individual one- and two-dimensional distribution plotting to the methods documented in Low-level plotting functions. These in turn make use of the density estimation methods in Density estimation.

The methods in Joint distribution plots and One-dimensional distributions, which generate plots for multiple distributions at once, allow some arguments to be specified for individual datasets and variables or for all at once. The semantics of this “broadcasting” for each function argument are indicated by its type annotation, which are described in Broadcasting semantics.

Joint distribution plots

excee.compare_2d_dists(dsets, cols=None, *, rows=None, var_names=None, rowcols=None, colors=None, bins=None, smooth=None, bounds=None, density_kwargs=None, levels=None, axes_scale='linear', limits='auto', limit_pad=1, kwargs_1d=None, kwargs_2d=None, exclude_1d_idx=None, exclude_2d_idx=None, ci_kind='auto', default_ci_kind='eti', ci_prob=None, show_titles=True, title_kwargs=None, fig=None, **kwargs)[source]

Compare one- and two-dimensional marginal distributions among datasets.

This method plots multiple distributions at once, calling plot_joint_dist() for each, but it may be equivalently used for a single distribution by simply passing a list containing a single dataset. There is therefore little reason to use plot_joint_dist() itself, but its documentation provides more details for some parameters.

Parameters:

  • dsets (Sequence[DataSpec]) – Sequence of datasets to compare.

  • cols (Sequence[str] | None) – Names of variables to plot along the columns. Defaults to the union of all keys present in the elements of dsets.

  • rows (Sequence[str] | None) – Names of variables to plot along the rows. Defaults to cols.

  • var_names (Sequence[str] | None) – Alternative specification of variable names for both rows and cols if cols is not passed.

  • rowcols (ArrayLike[__annotationlib_name_1__] | None) – Explicit 2D array of variable pairs. Overrides rows and cols. See plot_joint_dist().

  • colors (Sequence[ColorType] | None) – Sequence of colors used for each dataset.

  • bins (BroadcastableToVarsAndDatasets[int] | None) – Bin count/grid size for the 2D histogram/kernel density estimate. Defaults to None, in which case it is determined as described in plot_2d_dist().

  • smooth (BroadcastableToVarsAndDatasets[float] | None) – Smoothing factor for kernel density estimates that multiplies the estimated optimal bandwidth. Defaults to 0 (plotting raw histograms without KDE smoothing).

  • bounds (BroadcastableToVarsAndDatasets[BoundsTuple] | None) – Interval of variables’ prior support. Automatically inferred if not passed.

  • density_kwargs (BroadcastableToDatasets[Mapping[str, Any]] | None) – Additional keyword arguments passed to compute_1d_density() and compute_2d_density().

  • levels (Sequence[float] | None) – Mass levels to display for two-dimensional distributions. Defaults to the \(1\) and \(2 \sigma\) levels of a 2D normal (\(39.3\%\) and \(86.5\%\)).

  • axes_scale (BroadcastableToVarsAndDatasets[AxesScale]) – Axes scales. Defaults to "linear" for all variables.

  • limits (Mapping[str, LimitsSpecifiers] | Literal['auto'] | None) –

    Axes limits. Can be specified as

    • "auto" to automatically determine limits with get_inclusive_limits_from_2d_levels()

    • None to leave unmodified

    • or on a per-variable basis with a Mapping of (all or a subset of) var_names to LimitsSpecifierss.

    Defaults to "auto" for any of var_names not explicitly specified.

  • limit_pad (float) – Padding applied to automatically determined limits, in standard deviations. Defaults to 1.

  • kwargs_1d (BroadcastableToDatasets[Mapping[str, Any]] | None) – Additional keyword arguments passed to plot_1d_dist().

  • kwargs_2d (BroadcastableToDatasets[Mapping[str, Any]] | None) – Additional keyword arguments passed to plot_2d_dist().

  • exclude_1d_idx (Sequence[int] | None) – Indices of datasets to exclude from one-dimensional distribution plots.

  • exclude_2d_idx (Sequence[int] | None) – Indices of datasets to exclude from two-dimensional distribution plots.

  • ci_kind (BroadcastableToVarsAndDatasets[CIKind | None]) – Type of credible interval to display. Defaults to "auto", in which case it is automatically decided by decide_ci_kind().

  • default_ci_kind (Literal['hdi', 'eti']) – Fallback credible interval type if ci_kind is "auto" and decide_ci_kind() does not detect a one-sided distribution.

  • ci_prob (BroadcastableToVarsAndDatasets[float] | None) – Probability mass enclosed by depicted credible intervals.

  • show_titles (bool) – Whether to display titles with credible interval summaries on one-dimensional distribution plots.

  • title_kwargs (Mapping[str, Any] | None) – Formatting keyword arguments for axes titles, which are passed as expected by make_ci_str() and add_stacked_title().

  • fig (Figure | None) – Existing Figure figure to draw on. If None, a new figure is created.

  • **kwargs (Any) – Additional keyword arguments passed to plot_joint_dist().

Return type:

tuple[Figure, ndarray[Axes]]

excee.plot_joint_dist(data, rows=None, cols=None, *, var_names=None, rowcols=None, color=None, weights=None, skip_1d=False, skip_2d=False, ensure_1d_dists=True, reverse=False, bins=None, smooth=None, bounds=None, ess=None, density_kwargs=None, levels=None, limits=None, axes_scale='linear', sideways_hists=False, remove_1d_spines=True, ticks=None, max_n_ticks=5, top_ticks=False, rotate_ticks=True, configure_tick_locators=True, labels=None, label_kwargs=None, show_titles=False, title_kwargs=None, plot_ci=True, ci_kind='auto', default_ci_kind='eti', ci_prob=None, truths=None, truth_marker='s', truth_kwargs=None, fig=None, resize_fig=False, panel_dim=2, whspace=0, kwargs_1d=None, **kwargs_2d)[source]

Plot one- and two-dimensional marginal distributions for a single dataset.

Parameters:

  • data (DataSpec | ArrayLike) – Dataset to plot. Can be a Dataset, DataTree, Mapping, or ndarray.

  • rows (Sequence[str] | None) – Names of variables to plot along the rows. Defaults to cols.

  • cols (Sequence[str] | None) – Names of variables to plot along the columns. Defaults to all keys present in data.

  • var_names (Sequence[str] | None) – Alternative specification of variable names for both rows and cols if cols is not passed.

  • rowcols (ArrayLike[__annotationlib_name_1__] | None) – Explicit 2D array of variable pairs. Overrides rows and cols.

  • color (ColorType | None) – Color for all plot elements.

  • weights (ArrayLike | None) – Dataset weights (not currently handled).

  • skip_1d (bool) – Whether to skip plotting one-dimensional distributions (but retain them in the panel layout).

  • skip_2d (bool) – Whether to skip plotting two-dimensional distributions (but retain them in the panel layout).

  • ensure_1d_dists (bool) – Whether to include one-dimensional marginal distributions in the panel layout, even if not explicitly specified as a (row, col) combination.

  • reverse (bool) – Whether to reverse the ordering of the grid.

  • bins (BroadcastableToVars[int] | None) – Bin count for two-dimensional densities. Defaults to None, in which case it is determined as described in plot_2d_dist().

  • smooth (BroadcastableToVars[float] | None) – Smoothing factor for kernel density estimates that multiplies the estimated optimal bandwidth. Defaults to 0 (plotting raw histograms without KDE smoothing).

  • bounds (Mapping[str, BoundsTuple] | None) – Interval of variables’ prior support. Automatically inferred if not passed.

  • ess (Mapping[str, float] | None) – Effective sample sizes used for kernel density bandwidth estimation.

  • density_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to compute_1d_density() and compute_2d_density().

  • levels (Sequence[float] | None) – Mass levels to display for two-dimensional distributions. Defaults to the \(1\) and \(2 \sigma\) levels of a 2D normal (\(39.3\%\) and \(86.5\%\)).

  • limits (Mapping[str, tuple[float, float]] | None) – Axes limits, specified as a Mapping of variable names to tuple of floats. Missing keys default to the limits of the sample.

  • axes_scale (BroadcastableToVars[AxesScale]) – Axes scales. Defaults to "linear" for all variables.

  • sideways_hists (bool) – Whether to orient one-dimensional histograms horizontally when plotted on the right edge of the grid.

  • remove_1d_spines (bool) – Whether to remove unneeded spines and tick labels from one-dimensional marginal panels.

  • ticks (Mapping[str, Sequence[float]] | None) – Manual tick locations, specified as a Mapping of variable names to Sequences of floats.

  • max_n_ticks (int) – Maximum number of ticks to display per axis.

  • top_ticks (bool) – Whether to place ticks on the top or right edges of the grid.

  • rotate_ticks (bool) – Whether to rotate tick labels by 45 degrees.

  • configure_tick_locators (bool) – Whether to automatically configure tick locators based on axes_scale and max_n_ticks.

  • labels (Sequence[str] | None) – Axes labels corresponding to the columns of ndarray input for data. If not passed, labels are determined from xarray metadata (xarray.DataArray.attrs), defaulting to the keys of data.

  • label_kwargs (Mapping[str, Any] | None) – Keyword arguments passed to set_xlabel() and set_ylabel().

  • show_titles (bool) – Whether to display titles with credible interval summaries on one-dimensional distribution plots.

  • title_kwargs (Mapping[str, Any] | None) – Formatting keyword arguments for axes titles, which are passed as expected by make_ci_str() and add_stacked_title().

  • plot_ci (bool) – Whether to plot credible intervals on one-dimensional marginal distributions.

  • ci_kind (BroadcastableToVars[CIKind | None]) – Type of credible interval to display. Defaults to "auto", in which case it is automatically decided by decide_ci_kind().

  • default_ci_kind (Literal['hdi', 'eti']) – Fallback credible interval type if ci_kind is "auto" and decide_ci_kind() does not detect a one-sided distribution.

  • ci_prob (BroadcastableToVars[float] | None) – Probability mass enclosed by depicted credible intervals.

  • truths (Mapping[str, float] | Sequence[float] | None) – True values to display as horizontal/vertical lines.

  • truth_marker (str) – Marker style used to indicate true values in two-dimensional distributions.

  • truth_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to matplotlib plotting functions for true values.

  • fig (Figure | None) – Existing Figure figure to draw on. If None, a new figure is created.

  • resize_fig (bool) – Whether to automatically resize the figure to fit the grid based on panel_dim.

  • panel_dim (float) – Physical width and height of each subplot panel in inches. Used if resize_fig is True or fig is None.

  • whspace (float) – Width/height spacing between subplots.

  • kwargs_1d (Mapping[str, Any] | None) – Additional keyword arguments passed to plot_1d_dist().

  • **kwargs_2d (Any) – Additional keyword arguments passed to plot_2d_dist().

Return type:

tuple[Figure, ndarray[Axes]]

excee.test_smoothing(dset, bins_unsmoothed=20, bins_smoothed=256, *, smooth=1, color='k', color_unsmoothed='r', fill_contours=False, shade_background=False, limit_pad=0.5, kwargs_2d=None, **kwargs)[source]

One-dimensional distributions

excee.compare_1d_dists(dsets, *, var_names=None, smooth=1, limits='auto', limit_sigma=3, ncol=4, **kwargs)[source]

Compare one-dimensional marginal distributions among datasets for multiple variables by panel via a thin wrapper of compare_2d_dists().

Parameters:

  • dsets (Sequence[DataSpec]) – Sequence of datasets to compare.

  • var_names (Sequence[str] | None) – Names of variables to plot, one per panel. Defaults to the union of all keys present in the elements of dsets.

  • smooth (BroadcastableToVarsAndDatasets[float]) – Smoothing factor for kernel density estimates that multiplies the estimated optimal bandwidth. Unlike compare_2d_dists(), defaults to 1.

  • limits (Mapping[str, LimitsSpecifiers] | Literal['auto'] | None) – Axes limits, as described in compare_2d_dists() with the exception that automatically determined axes limits use get_inclusive_limits().

  • limit_sigma (float) – Extent of automatically determined axes limits as a number of standard deviations from the median.

  • ncol (int) – Maximum number of columns in the plot grid.

  • **kwargs (Any) – Additional keyword arguments passed to compare_2d_dists().

Return type:

tuple[Figure, ndarray[Axes]]

excee.compare_violin(dsets, *, var_names=None, side_labels=None, colors=None, alphas=None, limits='auto', limit_sigma=3, bins=1024, smooth=1, bounds=None, axes_scale='linear', ci_kind='eti', default_ci_kind='eti', ncol=4, fig=None, density_kwargs=None, fill_kwargs=None, **kwargs)[source]

Compare one-dimensional marginal distributions among datasets for multiple variables with vertically stacked violin plots.

Parameters:
Return type:

tuple[Figure, ndarray[Axes]]

excee.plot.plot_violin(ax, arys, *, input_kind='sample', colors=None, alphas=1, bins=1024, smooth=1, bounds=None, axes_scale='linear', density_kwargs=None, fill_kwargs=None, relative_height=1, title_pad=0.3, interviolin_pad=0.5, gap_fraction=0.0025, show_titles=True, title_kwargs=None, plot_ci=True, ci_kind='eti', default_ci_kind='eti', include_long_names=False, label=None, limit_xpad_fraction=0.01, min_x_upper_label=-inf, max_x_lower_label=inf, side_labels=None, side_label_kwargs=None, side_label_pad=0.0075)[source]

Plot vertically stacked violin plots.

Parameters:

  • ax (Axes) – Axis on which to draw the distributions.

  • arys (Sequence[ArrayLike | DataArray | None]) – Sequence of sets of samples.

  • input_kind (BroadcastableToDatasets[Literal['sample', 'density']]) – Whether the input data represents raw "sample"s or an evaluated "density".

  • colors (Sequence[ColorType] | None) – Sequence of colors used for each distribution.

  • alphas (BroadcastableToDatasets[float]) – Transparency of the violin plots.

  • bins (BroadcastableToDatasets[int]) – Grid size for kernel density estimates. Defaults to 1024.

  • smooth (BroadcastableToDatasets[float]) – Smoothing factor for kernel density estimates that multiplies the estimated optimal bandwidth. Defaults to 1. Must be greater than zero.

  • bounds (BroadcastableToDatasets[BoundsTuple | None]) – Interval of variables’ prior support. Automatically inferred if not passed.

  • axes_scale (AxesScale) – Axes scales. Defaults to "linear".

  • density_kwargs (BroadcastableToDatasets[Mapping[str, Any]] | None) – Additional keyword arguments passed to compute_1d_density().

  • fill_kwargs (BroadcastableToDatasets[Mapping[str, Any]] | None) – Additional keyword arguments passed to fill_between().

  • relative_height (float) – Height of the violin relative to the font size.

  • title_pad (float) – Padding between the density and its title, in units of the font size.

  • interviolin_pad (float) – Padding between adjacent violin plots (including titles, if present), in units of the font size.

  • gap_fraction (float) – Fraction of the total x-axis span used for gaps around the median.

  • show_titles (bool) – Whether to display titles with credible interval summaries.

  • title_kwargs (Mapping[str, Any] | None) – Formatting keyword arguments for titles.

  • plot_ci (bool) – Whether to plot credible intervals as highlighted regions.

  • ci_kind (BroadcastableToDatasets[CIKind | None]) – Type of credible interval to display.

  • default_ci_kind (Literal['eti', 'hdi']) – Fallback credible interval type if ci_kind is "auto".

  • include_long_names (bool) – Whether to include parameter names in the titles.

  • label (str | None) – Label to use for the title if include_long_names=True.

  • limit_xpad_fraction (float) – Padding between violin limits and their labels, as a fraction of the x-axis span.

  • min_x_upper_label (float) – Minimum x coordinate for upper limit labels.

  • max_x_lower_label (float) – Maximum x coordinate for lower limit labels.

  • side_labels (Sequence[str | None] | None) – Labels to display to the left of each violin plot.

  • side_label_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to text() for side labels.

  • side_label_pad (float) – Padding between side labels and the axis edge.

Return type:

Axes

Helper functions

excee.plot.get_1d_level(sigma)[source]
excee.plot.get_2d_level(sigma)[source]
excee.plot.get_inclusive_limits(dsets, quantiles=None, sigma=2.5)[source]
excee.plot.get_inclusive_limits_from_2d_levels(dsets, levels, pad=1)[source]

Low-level plotting functions

excee.plot.dist.plot_1d_dist(ax, data, color, *, weights=None, ess=None, axes_scale='linear', bins=None, smooth=None, bounds=None, plot_ci=True, ci_kind='auto', default_ci_kind='eti', ci_prob=None, quantile_kwargs=None, norm='relative', side='bottom', label=None, alpha=None, ci_alpha=None, line_kwargs=None, fill_kwargs=None, density_kwargs=None, **kwargs)[source]

Plot a one-dimensional distribution from samples.

Parameters:

  • ax (Axes) – Axis on which to draw the distribution.

  • data (ArrayLike) – Samples.

  • color (ColorType) – Color for plot and title elements.

  • weights (ArrayLike | None) – Sample weights (not currently handled).

  • ess (float | None) – Effective sample size used for bandwidth calculation. If not passed, it is computed as needed.

  • axes_scale (AxesScale) – Axes scales. Defaults to "linear".

  • bins (int | None) – Bin count/grisize for the histogram/kernel density estimate. Defaults to None, in which case it is set to 40 is smooth = 0 and 1024 otherwise.

  • smooth (float | None) – Smoothing factor for kernel density estimates that multiplies the estimated optimal bandwidth. Defaults to 0 (plotting a raw histogram without KDE smoothing).

  • bounds (BoundsTuple | None) – Interval of variables’ prior support. Automatically inferred if not passed.

  • plot_ci (bool) – Whether to plot credible intervals as a shaded region.

  • ci_kind (CIKind | None) – Type of credible interval to display. Defaults to "auto", in which case it is automatically decided by decide_ci_kind().

  • default_ci_kind (Literal['eti', 'hdi']) – Fallback credible interval type if ci_kind is "auto" and decide_ci_kind() does not detect a one-sided distribution.

  • ci_prob (float | None) – Probability mass enclosed by depicted credible intervals.

  • quantile_kwargs (Mapping[str, Any] | None) – Additional keyword arguments for the vertical line marking the median/mode.

  • norm (Literal['relative', 'density']) – Normalization of the density. "relative" scales the distribution to its peak value, whereas "density" plots the normalized density.

  • side (Literal['bottom', 'top', 'left', 'right']) – Axis edge on which to plot the distribution.

  • alpha (float | None) – Transparency of the fill for the full distribution.

  • ci_alpha (float | None) – Transparency of the fill for the credible interval.

  • line_kwargs (Mapping[str, Any] | None) – Additional arguments passed to plot() for the kernel density estimate.

  • fill_kwargs (Mapping[str, Any] | None) – Additional arguments passed to fill_between() for the kernel density estimate fill.

  • density_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to compute_1d_density().

  • **kwargs (Any) – Additional keyword arguments passed to bar() or plot().

  • label (str | None)

Return type:

Axes

excee.plot.dist.plot_2d_dist(ax, data, color, *, weights=None, axes_scale='linear', bins=None, smooth=None, bounds=None, plot_datapoints=False, datapoint_kwargs=None, density_kwargs=None, **kwargs)[source]

Plot a two-dimensional distribution from samples.

Parameters:

  • ax (Axes) – Axis on which to draw the distribution.

  • data (ArrayLike) – Samples. First axis must have length 2, corresponding to (x, y) coordinates.

  • color (ColorType) – Color for plot and title elements.

  • weights (ArrayLike | None) – Sample weights (not currently handled).

  • axes_scale (AxesScale | Sequence[AxesScale]) – Axes scales. Defaults to "linear".

  • bins (int | Sequence[int] | None) – Bin count/grid size for the 2D histogram/kernel density estimate. Defaults to None, in which case it is set to 20 if smooth = 0 and 256 otherwise.

  • smooth (float | Sequence[float] | None) – Smoothing factor for the kernel density estimate that multiplies the estimated optimal bandwidth. Defaults to 0 (plotting a raw histogram without KDE smoothing).

  • bounds (BoundsTuple | Sequence[BoundsTuple] | None) – Interval of variables’ prior support. Automatically inferred if not passed.

  • plot_datapoints (bool) – Whether to plot samples as scatter.

  • datapoint_kwargs (Mapping[str, Any] | None) – Additional arguments passed to plot() for plotting datapoints.

  • density_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to compute_2d_density().

  • **kwargs (Any) – Additional keyword arguments passed to plot_2d_density().

Return type:

Axes

excee.plot.dist.plot_2d_density(ax, X, Y, pdf, color, *, levels=None, plot_contours=True, fill_contours=True, plot_density=False, gapcolor=None, gap_linestyle='--', fill_alphas=None, alpha_offset=0.5, shade_background=True, contour_kwargs=None, contourf_kwargs=None, pcolormesh_kwargs=None)[source]

Plot a two-dimensional density from a grid, like the output of compute_2d_density().

Parameters:

  • ax (Axes) – Axis on which to draw the distribution.

  • X (ArrayLike) – X coordinates of the grid.

  • Y (ArrayLike) – Y coordinates of the grid.

  • pdf (ArrayLike) – Probability density on the grid.

  • color (ColorType) – Color for plot elements.

  • levels (Sequence[float] | None) – Mass levels to display for two-dimensional distributions. Defaults to the \(1\) and \(2 \sigma\) levels of a 2D normal (\(39.3\%\) and \(86.5\%\)).

  • plot_contours (bool) – Whether to draw contour level boundaries (with contour()). Defaults to True.

  • fill_contours (bool) – Whether to fill contour levels (with contourf()). Defaults to True.

  • plot_density (bool) – Whether to plot the density itself (with pcolormesh()). Ignored unless fill_contours=False. Defaults to False.

  • gapcolor (ColorType | None) – Color used to draw dashed contours on top of solid contours Defaults to None (no dashing with alternating colors).

  • gap_linestyle (LineStyleType) – Line style used for the gap color.

  • fill_alphas (Sequence[float] | None) – Sequence of transparency values to apply for each filled contour level.

  • alpha_offset (float) – Offset used in default choice of transparencies for filling of consecutive contour levels. Ignored if fill_alphas is provided. Defaults to 0.5.

  • shade_background (bool) – Whether to fill all contour levels in the background (to prevent other plot elements appearing beneath transparent contour fill).

  • contour_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to contour().

  • contourf_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to contourf().

  • pcolormesh_kwargs (Mapping[str, Any] | None) – Additional keyword arguments passed to pcolormesh() for the density plot.

Return type:

Axes