Source code for arviz.plots.distplot

# pylint: disable=unexpected-keyword-arg
"""Plot distribution as histogram or kernel density estimates."""
import numpy as np
import xarray as xr

from import InferenceData
from ..rcparams import rcParams
from .plot_utils import get_plotting_function

[docs] def plot_dist( values, values2=None, color="C0", kind="auto", cumulative=False, label=None, rotated=False, rug=False, bw="default", quantiles=None, contour=True, fill_last=True, figsize=None, textsize=None, plot_kwargs=None, fill_kwargs=None, rug_kwargs=None, contour_kwargs=None, contourf_kwargs=None, pcolormesh_kwargs=None, hist_kwargs=None, is_circular=False, ax=None, backend=None, backend_kwargs=None, show=None, **kwargs, ): r"""Plot distribution as histogram or kernel density estimates. By default continuous variables are plotted using KDEs and discrete ones using histograms Parameters ---------- values : array-like Values to plot from an unknown continuous or discrete distribution. values2 : array-like, optional Values to plot. If present, a 2D KDE or a hexbin will be estimated. color : string valid matplotlib color. kind : string, default "auto" By default ("auto") continuous variables will use the kind defined by rcParam ``plot.density_kind`` and discrete ones will use histograms. To override this use "hist" to plot histograms and "kde" for KDEs. cumulative : bool, default False If true plot the estimated cumulative distribution function. Defaults to False. Ignored for 2D KDE. label : string Text to include as part of the legend. rotated : bool, default False Whether to rotate the 1D KDE plot 90 degrees. rug : bool, default False Add a `rug plot <>`_ for a specific subset of values. Ignored for 2D KDE. bw : float or str, optional If numeric, indicates the bandwidth and must be positive. If str, indicates the method to estimate the bandwidth and must be one of "scott", "silverman", "isj" or "experimental" when ``is_circular`` is False and "taylor" (for now) when ``is_circular`` is True. Defaults to "experimental" when variable is not circular and "taylor" when it is. quantiles : list, optional Quantiles in ascending order used to segment the KDE. Use [.25, .5, .75] for quartiles. contour : bool, default True If True plot the 2D KDE using contours, otherwise plot a smooth 2D KDE. fill_last : bool, default True If True fill the last contour of the 2D KDE plot. figsize : (float, float), optional Figure size. If `None` it will be defined automatically. textsize : float, optional Text size scaling factor for labels, titles and lines. If `None` it will be autoscaled based on `figsize`. Not implemented for bokeh backend. plot_kwargs : dict Keywords passed to the pdf line of a 1D KDE. Passed to :func:`arviz.plot_kde` as ``plot_kwargs``. fill_kwargs : dict Keywords passed to the fill under the line (use fill_kwargs={'alpha': 0} to disable fill). Ignored for 2D KDE. Passed to :func:`arviz.plot_kde` as ``fill_kwargs``. rug_kwargs : dict Keywords passed to the rug plot. Ignored if ``rug=False`` or for 2D KDE Use ``space`` keyword (float) to control the position of the rugplot. The larger this number the lower the rugplot. Passed to :func:`arviz.plot_kde` as ``rug_kwargs``. contour_kwargs : dict Keywords passed to the contourplot. Ignored for 1D KDE. contourf_kwargs : dict Keywords passed to :meth:`matplotlib.axes.Axes.contourf`. Ignored for 1D KDE. pcolormesh_kwargs : dict Keywords passed to :meth:`matplotlib.axes.Axes.pcolormesh`. Ignored for 1D KDE. hist_kwargs : dict Keyword arguments used to customize the histogram. Ignored when plotting a KDE. They are passed to :meth:`matplotlib.axes.Axes.hist` if using matplotlib, or to :meth:`bokeh.plotting.figure.quad` if using bokeh. In bokeh case, the following extra keywords are also supported: * ``color``: replaces the ``fill_color`` and ``line_color`` of the ``quad`` method * ``bins``: taken from ``hist_kwargs`` and passed to :func:`numpy.histogram` instead * ``density``: normalize histogram to represent a probability density function, Defaults to ``True`` * ``cumulative``: plot the cumulative counts. Defaults to ``False``. is_circular : {False, True, "radians", "degrees"}, default False Select input type {"radians", "degrees"} for circular histogram or KDE plot. If True, default input type is "radians". When this argument is present, it interprets the values passed are from a circular variable measured in radians and a circular KDE is used. Inputs in "degrees" will undergo an internal conversion to radians. Only valid for 1D KDE. ax : matplotlib_axes or bokeh_figure, optional Matplotlib or bokeh targets on which to plot. If not supplied, Arviz will create its own plot area (and return it). backend : {"matplotlib", "bokeh"}, default "matplotlib" Select plotting backend. backend_kwargs :dict, optional These are kwargs specific to the backend being used, passed to :func:`matplotlib.pyplot.subplots` or :class:`bokeh.plotting.figure`. For additional documentation check the plotting method of the backend. show : bool, optional Call backend show function. Returns ------- axes : matplotlib axes or bokeh figure See Also -------- plot_posterior : Plot Posterior densities in the style of John K. Kruschke's book. plot_density : Generate KDE plots for continuous variables and histograms for discrete ones. plot_kde : 1D or 2D KDE plot taking into account boundary conditions. Examples -------- Plot an integer distribution .. plot:: :context: close-figs >>> import numpy as np >>> import arviz as az >>> a = np.random.poisson(4, 1000) >>> az.plot_dist(a) Plot a continuous distribution .. plot:: :context: close-figs >>> b = np.random.normal(0, 1, 1000) >>> az.plot_dist(b) Add a rug under the Gaussian distribution .. plot:: :context: close-figs >>> az.plot_dist(b, rug=True) Segment into quantiles .. plot:: :context: close-figs >>> az.plot_dist(b, rug=True, quantiles=[.25, .5, .75]) Plot as the cumulative distribution .. plot:: :context: close-figs >>> az.plot_dist(b, rug=True, quantiles=[.25, .5, .75], cumulative=True) """ values = np.asarray(values) if isinstance(values, (InferenceData, xr.Dataset)): raise ValueError( "InferenceData or xarray.Dataset object detected," " use plot_posterior, plot_density or plot_pair" " instead of plot_dist" ) if kind not in ["auto", "kde", "hist"]: raise TypeError(f'Invalid "kind":{kind}. Select from {{"auto","kde","hist"}}') if kind == "auto": kind = "hist" if values.dtype.kind == "i" else rcParams["plot.density_kind"] dist_plot_args = dict( # User Facing API that can be simplified values=values, values2=values2, color=color, kind=kind, cumulative=cumulative, label=label, rotated=rotated, rug=rug, bw=bw, quantiles=quantiles, contour=contour, fill_last=fill_last, figsize=figsize, textsize=textsize, plot_kwargs=plot_kwargs, fill_kwargs=fill_kwargs, rug_kwargs=rug_kwargs, contour_kwargs=contour_kwargs, contourf_kwargs=contourf_kwargs, pcolormesh_kwargs=pcolormesh_kwargs, hist_kwargs=hist_kwargs, ax=ax, backend_kwargs=backend_kwargs, is_circular=is_circular, show=show, **kwargs, ) if backend is None: backend = rcParams["plot.backend"] backend = backend.lower() plot = get_plotting_function("plot_dist", "distplot", backend) ax = plot(**dist_plot_args) return ax