Detailed API documentation#
The main user-facing function is corner.corner()
but the lower level
functions corner.hist2d()
and corner.quantile()
are also
documented here.
- corner.corner(data, bins=20, *, range=None, axes_scale='linear', weights=None, color=None, hist_bin_factor=1, smooth=None, smooth1d=None, labels=None, label_kwargs=None, titles=None, show_titles=False, title_quantiles=None, title_fmt='.2f', title_kwargs=None, truths=None, truth_color='#4682b4', scale_hist=False, quantiles=None, verbose=False, fig=None, max_n_ticks=5, top_ticks=False, use_math_text=False, reverse=False, labelpad=0.0, hist_kwargs=None, group='posterior', var_names=None, filter_vars=None, coords=None, divergences=False, divergences_kwargs=None, labeller=None, **hist2d_kwargs)#
Make a sick corner plot showing the projections of a data set in a multi-dimensional space. kwargs are passed to hist2d() or used for matplotlib styling.
- Parameters:
data (obj) – Any object that can be converted to an
arviz.InferenceData
object. Refer to documentation ofarviz.convert_to_dataset
for details.bins (int or array_like[ndim,]) – The number of bins to use in histograms, either as a fixed value for all dimensions, or as a list of integers for each dimension.
group (str) – Specifies which InferenceData group should be plotted. Defaults to
'posterior'
.var_names (list) – Variables to be plotted, if
None
all variable are plotted. Prefix the variables by ~ when you want to exclude them from the plot.filter_vars ({
None
,"like"
,"regex"
}) – IfNone
(default), interpretvar_names
as the real variables names. If"like"
, interpretvar_names
as substrings of the real variables names. If"regex"
, interpretvar_names
as regular expressions on the real variables names. A lapandas.filter
.coords (mapping) – Coordinates of
var_names
to be plotted. Passed toarviz.Dataset.sel
.divergences (bool) – If
True
divergences will be plotted in a different color, only ifgroup
is either'prior'
or'posterior'
.divergences_kwargs (dict) – Any extra keyword arguments to send to the
overplot_points
when plotting the divergences.labeller (arviz.Labeller) – Class providing the method
make_label_vert
to generate the labels in the plot. Read the ArviZ label guide for more details and usage examples.weights (array_like[nsamples,]) – The weight of each sample. If None (default), samples are given equal weight.
color (str) – A
matplotlib
style color for all histograms.hist_bin_factor (float or array_like[ndim,]) – This is a factor (or list of factors, one for each dimension) that will multiply the bin specifications when making the 1-D histograms. This is generally used to increase the number of bins in the 1-D plots to provide more resolution.
smooth (float) – The standard deviation for Gaussian kernel passed to scipy.ndimage.gaussian_filter to smooth the 2-D and 1-D histograms respectively. If None (default), no smoothing is applied.
smooth1d (float) – The standard deviation for Gaussian kernel passed to scipy.ndimage.gaussian_filter to smooth the 2-D and 1-D histograms respectively. If None (default), no smoothing is applied.
labels (iterable (ndim,)) –
A list of names for the dimensions.
Deprecated since version 2.2.1: If a
xs
is apandas.DataFrame
and ArviZ is installed, labels will default to column names. This behavior will be removed in version 3; either use ArviZ data structures instead or passlabels=dataframe.columns
manually.label_kwargs (dict) – Any extra keyword arguments to send to the set_xlabel and set_ylabel methods. Note that passing the labelpad keyword in this dictionary will not have the desired effect. Use the labelpad keyword in this function instead.
titles (iterable (ndim,)) – A list of titles for the dimensions. If None (default), uses labels as titles.
show_titles (bool) – Displays a title above each 1-D histogram showing the 0.5 quantile with the upper and lower errors supplied by the quantiles argument.
title_quantiles (iterable) – A list of 3 fractional quantiles to show as the the upper and lower errors. If None (default), inherit the values from quantiles, unless quantiles is None, in which case it defaults to [0.16,0.5,0.84]
title_fmt (string) – The format string for the quantiles given in titles. If you explicitly set
show_titles=True
andtitle_fmt=None
, the labels will be shown as the titles. (default:.2f
)title_kwargs (dict) – Any extra keyword arguments to send to the set_title command.
range (iterable (ndim,)) – A list where each element is either a length 2 tuple containing lower and upper bounds or a float in range (0., 1.) giving the fraction of samples to include in bounds, e.g., [(0.,10.), (1.,5), 0.999, etc.]. If a fraction, the bounds are chosen to be equal-tailed.
axes_scale (str or iterable (ndim,)) – Scale (
"linear"
,"log"
) to use for each data dimension. If only one scale is specified, use that for all dimensions.truths (iterable (ndim,)) – A list of reference values to indicate on the plots. Individual values can be omitted by using
None
.truth_color (str) – A
matplotlib
style color for thetruths
makers.scale_hist (bool) – Should the 1-D histograms be scaled in such a way that the zero line is visible?
quantiles (iterable) – A list of fractional quantiles to show on the 1-D histograms as vertical dashed lines.
verbose (bool) – If true, print the values of the computed quantiles.
plot_contours (bool) – Draw contours for dense regions of the plot.
use_math_text (bool) – If true, then axis tick labels for very large or small exponents will be displayed as powers of 10 rather than using e.
reverse (bool) – If true, plot the corner plot starting in the upper-right corner instead of the usual bottom-left corner
labelpad (float) – Padding between the axis and the x- and y-labels in units of the fraction of the axis from the lower left
max_n_ticks (int) – Maximum number of ticks to try to use
top_ticks (bool) – If true, label the top ticks of each axis
fig (~matplotlib.figure.Figure) – Overplot onto the provided figure object, which must either have no axes yet, or
ndim * ndim
axes already present. If not set, the plot will be drawn on a newly created figure.hist_kwargs (dict) – Any extra keyword arguments to send to the 1-D histogram plots.
**hist2d_kwargs – Any remaining keyword arguments are sent to
corner.hist2d()
to generate the 2-D histogram plots.
- Returns:
fig – The
matplotlib
figure instance for the corner plot.- Return type:
~matplotlib.figure.Figure
- corner.hist2d(x, y, bins=20, range=None, axes_scale=['linear', 'linear'], weights=None, levels=None, smooth=None, ax=None, color=None, quiet=False, plot_datapoints=True, plot_density=True, plot_contours=True, no_fill_contours=False, fill_contours=False, contour_kwargs=None, contourf_kwargs=None, data_kwargs=None, pcolor_kwargs=None, new_fig=True, force_range=False, **kwargs)#
Plot a 2-D histogram of samples.
- Parameters:
x (array_like[nsamples,]) – The samples.
y (array_like[nsamples,]) – The samples.
axes_scale (iterable (2,)) – Scale (
"linear"
,"log"
) to use for each dimension.quiet (bool) – If true, suppress warnings for small datasets.
levels (array_like) – The contour levels to draw. If None, (0.5, 1, 1.5, 2)-sigma equivalent contours are drawn, i.e., containing 11.8%, 39.3%, 67.5% and 86.4% of the samples. See https://corner.readthedocs.io/en/latest/pages/sigmas/
ax (matplotlib.Axes) – A axes instance on which to add the 2-D histogram.
plot_datapoints (bool) – Draw the individual data points.
plot_density (bool) – Draw the density colormap.
plot_contours (bool) – Draw the contours.
no_fill_contours (bool) – Add no filling at all to the contours (unlike setting
fill_contours=False
, which still adds a white fill at the densest points).fill_contours (bool) – Fill the contours.
contour_kwargs (dict) – Any additional keyword arguments to pass to the contour method.
contourf_kwargs (dict) – Any additional keyword arguments to pass to the contourf method.
data_kwargs (dict) – Any additional keyword arguments to pass to the plot method when adding the individual data points.
pcolor_kwargs (dict) – Any additional keyword arguments to pass to the pcolor method when adding the density colormap.
- corner.quantile(x, q, weights=None)#
Compute sample quantiles with support for weighted samples.
Note
When
weights
isNone
, this method simply calls numpy’s percentile function with the values ofq
multiplied by 100.- Parameters:
x (array_like[nsamples,]) – The samples.
q (array_like[nquantiles,]) – The list of quantiles to compute. These should all be in the range
[0, 1]
.weights (Optional[array_like[nsamples,]]) – An optional weight corresponding to each sample. These
- Returns:
quantiles – The sample quantiles computed at
q
.- Return type:
array_like[nquantiles,]
- Raises:
ValueError – For invalid quantiles;
q
not in[0, 1]
or dimension mismatch betweenx
andweights
.
- corner.overplot_lines(fig, xs, reverse=False, **kwargs)#
Overplot lines on a figure generated by
corner.corner
- Parameters:
fig (Figure) – The figure generated by a call to
corner.corner()
.xs (array_like[ndim]) – The values where the lines should be plotted. This must have
ndim
entries, wherendim
is compatible with thecorner.corner()
call that originally generated the figure. The entries can optionally beNone
to omit the line in that axis.reverse (bool) – A boolean flag that should be set to ‘True’ if the corner plot itself was plotted with ‘reverse=True’.
**kwargs – Any remaining keyword arguments are passed to the
ax.axvline
method.
- corner.overplot_points(fig, xs, reverse=False, **kwargs)#
Overplot points on a figure generated by
corner.corner
- Parameters:
fig (Figure) – The figure generated by a call to
corner.corner()
.xs (array_like[nsamples, ndim]) – The coordinates of the points to be plotted. This must have an
ndim
that is compatible with thecorner.corner()
call that originally generated the figure.reverse (bool) – A boolean flag that should be set to ‘True’ if the corner plot itself was plotted with ‘reverse=True’.
**kwargs – Any remaining keyword arguments are passed to the
ax.plot
method.