kalepy.plot module

kalepy’s plotting submodule

This submodule containts the Corner class, and all plotting methods. The Corner class, and additional API functions are imported into the base package namespace of kalepy, e.g. kalepy.Corner and kalepy.carpet access the kalepy.plot.Corner and kalepy.plot.carpet methods respectively.

Additional options and customization:

The core plotting routines, such as draw_hist1d, draw_hist2d, draw_contour2d, etc include a fairly large number of keyword arguments for customization. The top level API methods, such as corner() or Corner.plot_data() often do not provide access to all of those arguments, but additional customization is possible by using the drawing methods directly, and optionally subclassing the Corner class to provide additional or different functionality.

Plotting API

Corner : class for corner/triangle/pair plots.
corner : method which constructs a Corner instance and plots 1D and 2D distributions.
dist1d : plot a 1D distribution with numerous possible elements (e.g. histogram, carpet, etc)
dist2d : plot a 2D distribution with numerous possible elements (e.g. histogram, contours, etc)
carpet : draw a 1D scatter-like plot to semi-quantitatively depict a distribution.
contour : draw a 2D contour plot. A wrapper of additional functionality around plt.contour
confidence : draw 1D confidence intervals using shaded bands.
hist1d : draw a 1D histogram
hist2d : draw a 2D histogram. A wrapper of additional functionality around plt.pcolormesh

class kalepy.plot.Corner(kde_data, weights=None, origin='tl', rotate=True, axes=None, labels=None, limits=None, ticks=None, **kwfig)

Bases: object

Class for creating ‘corner’ / ‘pair’ plots of multidimensional covariances.

The Corner class acts as a constructor for a matplotlib figure and axes, and coordinates the plotting of 1D and 2D distributions. The kalepy.plot.dist1d() and kalepy.plot.dist2d() methods are used for plotting the distributions. The class methods provide wrappers, and default setting for those methods. The Corner.plot method is the standard plotting method with default parameters chosen for plotting a single, multidimensional dataset. For overplotting numerous datasets, the Corner.clean or Corner.plot_data methods are better.

Examples

Load some predefined 3D data, and generate a default corner plot:

>>> import kalepy as kale
>>> data = kale.utils._random_data_3d_03()
>>> corner = kale.corner(data)

Load two different datasets, and overplot them using a kalepy.Corner instance.

>>> data1 = kale.utils._random_data_3d_03(par=[0.0, 0.5], cov=0.05)
>>> data2 = kale.utils._random_data_3d_03(par=[1.0, 0.25], cov=0.5)
>>> corner = kale.Corner(3)   # construct '3' dimensional corner-plot (i.e. 3x3 axes)
>>> _ = corner.clean(data1)
>>> _ = corner.clean(data2)

Methods

- `plot`	(the standard plotting method which, by default, includes both KDE and data elements.)
- `clean`	(minimal plots with only the KDE generated PDF in 1D and contours in 2D, by default.)
- `hist`	(minimal plots with only the data based 1D and 2D histograms, by default.)
- `plot_kde`	(plot elements with only KDE based info: the clean settings with a little more.)
- `plot_data`	(plot elements without using KDE info.)

Initialize Corner instance and construct figure and axes based on the given arguments.

Parameters:

kde_dataobject, one of the following

int D, the number of parameters/dimensions to construct a DxD corner plot.
instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.

weightsarray_like scalar (N,) or None

The weights for each data point. NOTE: only applicable when kde_data is a (D,N) dataset.

labelsarray_like str (N,) of names for each parameters.

limitsNone, or (D,2) of scalar

Specification for the limits of each axes (for each of D parameters): * None : the limits are determined automatically, * (D,2) : limits for each axis

rotatebool,

Whether or not the bottom-right-most axes should be rotated.

**kwfigkeyword-arguments passed to _figax() for constructing figure and axes.

See kalepy.plot._figax() for specifications.

__init__(kde_data, weights=None, origin='tl', rotate=True, axes=None, labels=None, limits=None, ticks=None, **kwfig)

Initialize Corner instance and construct figure and axes based on the given arguments.

Parameters:

kde_dataobject, one of the following

int D, the number of parameters/dimensions to construct a DxD corner plot.
instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.

weightsarray_like scalar (N,) or None

The weights for each data point. NOTE: only applicable when kde_data is a (D,N) dataset.

labelsarray_like str (N,) of names for each parameters.

limitsNone, or (D,2) of scalar

Specification for the limits of each axes (for each of D parameters): * None : the limits are determined automatically, * (D,2) : limits for each axis

rotatebool,

Whether or not the bottom-right-most axes should be rotated.

**kwfigkeyword-arguments passed to _figax() for constructing figure and axes.

See kalepy.plot._figax() for specifications.

clean(kde_data=None, weights=None, dist1d={}, dist2d={}, **kwargs)

Wrapper for plot_kde that sets parameters for minimalism: PDF and contours only.

Parameters:

kde_datakalepy.KDE instance, (D,N) array_like of scalars, or None

instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.
None : use the KDE/data stored during class initialization. raises ValueError if no KDE/data was provided

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

dist1ddict of keyword-arguments passed to the kale.plot.dist1d method.

dist2ddict of keyword-arguments passed to the kale.plot.dist2d method.

**kwargsadditiona keyword-arguments passed directly to Corner.plot_kde.

hist(kde_data=None, weights=None, dist1d={}, dist2d={}, **kwargs)

Wrapper for plot_data that sets parameters to only plot 1D and 2D histograms of data.

Parameters:

kde_datakalepy.KDE instance, (D,N) array_like of scalars, or None

instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.
None : use the KDE/data stored during class initialization. raises ValueError if no KDE/data was provided

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

dist1ddict of keyword-arguments passed to the kale.plot.dist1d method.

dist2ddict of keyword-arguments passed to the kale.plot.dist2d method.

**kwargsadditiona keyword-arguments passed directly to Corner.plot_kde.

legend(handles, labels, index=None, loc=None, fancybox=False, borderaxespad=0, **kwargs)

plot(kde_data=None, edges=None, weights=None, quantiles=None, limit=None, color=None, cmap=None, dist1d={}, dist2d={})

Plot with standard settings for plotting a single, multidimensional dataset or KDE.

This function coordinates the drawing of a corner plot that ultimately uses the kalepy.plot.dist1d and kalepy.plot.dist2d methods to draw parameter distributions using an instance of kalepy.kde.KDE.

Parameters:

kde_datakalepy.KDE instance, (D,N) array_like of scalars, or None

instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.
None : use the KDE/data stored during class initialization. raises ValueError if no KDE/data was provided

edgesobject specifying historgam edge locations; or None

int : the number of bins for all dimensions, locations calculated automatically
(D,) array_like of int : the number of bins for each of D dimensions
(D,) of array_like : the bin-edge locations for each of D dimensions, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension.
(X,) array_like of scalar : the bin-edge locations to be used for all dimensions
None : the number and locations of bins are calculated automatically for each dim

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

quantilesNone or array_like of scalar values in [0.0, 1.0] denoting the fractions of

data to demarkate with contours and confidence bands.

limitbool or None, whether the axes limits should be reset based on the plotted data.

If None, then the limits will be readjusted unless limits were provided on class initialization.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None:

cmap is given, then the color will be set to the cmap midpoint.
cmap is not given, then the color will be determined by the next value of the default matplotlib color-cycle, and cmap will be set to a matching colormap.

This parameter effects the color of 1D: histograms, confidence intervals, and carpet; 2D: scatter points.

cmapmatplotlib colormap specification, or None

All valid matplotlib specifications can be used, e.g. named value (like ‘Reds’ or ‘viridis’) or a matplotlib.colors.Colormap instance.
If None then a colormap is constructed based on the value of color (see above).

dist1ddict of keyword-arguments passed to the kale.plot.dist1d method.

dist2ddict of keyword-arguments passed to the kale.plot.dist2d method.

plot_data(data=None, edges=None, weights=None, quantiles=None, limit=None, color=None, cmap=None, dist1d={}, dist2d={})

Plot with default settings to emphasize the given data (not KDE derived properties).

This function coordinates the drawing of a corner plot that ultimately uses the kalepy.plot.dist1d and kalepy.plot.dist2d methods to draw parameter distributions using an instance of kalepy.kde.KDE.

Parameters:

data(D,N) array_like of scalars, kalepy.KDE instance, or None

array_like scalar (D,N) of data with D parameters and N data points.
None : use the KDE/data stored during class initialization. raises ValueError if no KDE/data was provided
instance of kalepy.kde.KDE, providing the data and KDE to be plotted.

NOTE: if a KDE instance is given, or one was stored during initilization, then the: dataset is extracted from the instance.

edgesobject specifying historgam edge locations; or None

int : the number of bins for all dimensions, locations calculated automatically
(D,) array_like of int : the number of bins for each of D dimensions
(D,) of array_like : the bin-edge locations for each of D dimensions, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension.
(X,) array_like of scalar : the bin-edge locations to be used for all dimensions
None : the number and locations of bins are calculated automatically for each dim

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

quantilesNone or array_like of scalar values in [0.0, 1.0] denoting the fractions of

data to demarkate with contours and confidence bands.

limitbool or None, whether the axes limits should be reset based on the plotted data.

If None, then the limits will be readjusted unless limits were provided on class initialization.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None:

cmap is given, then the color will be set to the cmap midpoint.
cmap is not given, then the color will be determined by the next value of the default matplotlib color-cycle, and cmap will be set to a matching colormap.

This parameter effects the color of 1D: histograms, confidence intervals, and carpet; 2D: scatter points.

cmapmatplotlib colormap specification, or None

All valid matplotlib specifications can be used, e.g. named value (like ‘Reds’ or ‘viridis’) or a matplotlib.colors.Colormap instance.
If None then a colormap is constructed based on the value of color (see above).

dist1ddict of keyword-arguments passed to the kale.plot.dist1d method.

dist2ddict of keyword-arguments passed to the kale.plot.dist2d method.

plot_kde(kde=None, edges=None, weights=None, quantiles=None, limit=None, ls='-', color=None, cmap=None, dist1d={}, dist2d={})

Plot with default settings to emphasize the KDE derived distributions.

This function coordinates the drawing of a corner plot that ultimately uses the kalepy.plot.dist1d and kalepy.plot.dist2d methods to draw parameter distributions using an instance of kalepy.kde.KDE.

Parameters:

kdekalepy.KDE instance, (D,N) array_like of scalars, or None

instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
array_like scalar (D,N) of data with D parameters and N data points.
None : use the KDE/data stored during class initialization. raises ValueError if no KDE/data was provided

edgesobject specifying historgam edge locations; or None

int : the number of bins for all dimensions, locations calculated automatically
(D,) array_like of int : the number of bins for each of D dimensions
(D,) of array_like : the bin-edge locations for each of D dimensions, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension.
(X,) array_like of scalar : the bin-edge locations to be used for all dimensions
None : the number and locations of bins are calculated automatically for each dim

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde argument is a (D,N) array_like of scalar data from which a KDE instance is created.

quantilesNone or array_like of scalar values in [0.0, 1.0] denoting the fractions of

data to demarkate with contours and confidence bands.

limitbool or None, whether the axes limits should be reset based on the plotted data.

If None, then the limits will be readjusted unless limits were provided on class initialization.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None:

cmap is given, then the color will be set to the cmap midpoint.
cmap is not given, then the color will be determined by the next value of the default matplotlib color-cycle, and cmap will be set to a matching colormap.

This parameter effects the color of 1D: histograms, confidence intervals, and carpet; 2D: scatter points.

cmapmatplotlib colormap specification, or None

All valid matplotlib specifications can be used, e.g. named value (like ‘Reds’ or ‘viridis’) or a matplotlib.colors.Colormap instance.
If None then a colormap is constructed based on the value of color (see above).

dist1ddict of keyword-arguments passed to the kale.plot.dist1d method.

dist2ddict of keyword-arguments passed to the kale.plot.dist2d method.

target(targets, upper_limits=None, lower_limits=None, lw=1.0, fill_alpha=0.1, **kwargs)

kalepy.plot.carpet(xx, weights=None, ax=None, ystd=None, yave=None, shift=0.0, limit=None, fancy=False, random='normal', rotate=False, **kwargs)

Draw a ‘carpet plot’ that shows semi-quantitatively the distribution of points.

The given data (xx) is plotted as scatter points, where the abscissa (typically x-values) are the actual locations of the data and the ordinate are generated randomly. The size and transparency of points are chosen based on the number of points. If weights are given, it the size of the data points are chosen proportionally.

NOTE: the shift argument determines the reference ordinate-value of the distribution, this is: particularly useful when numerous datasets are being overplotted.

Parameters:

xx(N,) array_like of scalar, the data values to be plotted
weightsNone or (N,) array_like of scalar, the weighting of each data-point if and: only-if the given kde_data argument is a (D,N) array_like of scalar data.
axNone or matplotlib.axis.Axis, if None the plt.gca() is used
ystdscalar or None, a measure of the dispersion in the ordinate scatter of values: If None then an appropriate value is guessed based yave or the axis limits
yavescalar or None, the baseline at which the ordinate values are generated,: This is very similar to the shift argument, determining the ordinate-offset, but in the case that ystd is not given but yave is given, then the yave value determines ystd.
shiftscalar,: A systematic ordinate shift of all data-points, particularly useful when multiple datasets are being plotted, such that one carpet plot can be offset from the other(s).
limitint or None,: Maximum number of points to draw. If more data points are provided, a limit subset of them are chosen and plotted.
fancybool,: Experimental resizing of data-points to visually emphasize outliers.
randomstr, one of [‘normal’, ‘uniform’],: How the ordinate values are randomly generated: either a uniform or normal (i.e. Gaussian).
rotatebool, if True switch the x and y values such that x becomes the ordinate.
kwargsadditional keyword-arguments passed to matplotlib.axes.Axes.scatter()

kalepy.plot.confidence(data, ax=None, weights=None, quantiles=[0.5, 0.9], median=True, rotate=False, **kwargs)

Plot 1D Confidence intervals at the given quantiles.

For each quantile q, a shaded range is plotted that includes a fration q of data values around the median. Ultimately either plt.axhspan or plt.axvspan is used for drawing.

Parameters:

data(N,) array_like of scalar, the data values around which to calculate confidence intervals
axNone or matplotlib.axes.Axes instance, if None then plt.gca() is used.
weightsNone or (N,) array_like of scalar, the weighting of each data-point if and: only-if the given kde_data argument is a (D,N) array_like of scalar data.
quantilesarray_like of scalar values in [0.0, 1.0] denoting the fractions of data to mark.
medianbool, mark the location of the median value.
rotatebool, if true switch the x and y coordinates (i.e. rotate plot 90deg clockwise).
**kwargsadditional keyword-arguments passed to plt.axhspan or plt.axvspan.

kalepy.plot.contour(data, edges=None, ax=None, weights=None, color=None, cmap=None, quantiles=None, smooth=1.0, upsample=2, pad=1, **kwargs)

Calculate and draw 2D contours.

This is a wrapper for draw_contour, which in turn wraps plt.contour. This function constructs bin-edges and calculates the histogram from which the contours are calculated.

Parameters:

data(2, N) array_like of scalars,

The data from which contours should be calculated.

edgesobject specifying historgam edge locations; or None

int : the number of bins for both dimensions, locations calculated automatically
(2,) array_like of int : the number of bins for each dimension.
(2,) of array_like : the bin-edge locations for each dimension, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension: i.e. 6 total.
(X,) array_like of scalar : the bin-edge locations to be used for both dimensions.
None : the number and locations of bins are calculated automatically.

axmatplotlib.axes.Axes instance, or None; if None then plt.gca() is used.

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None:

cmap is given, then the color will be set to the cmap midpoint.
cmap is not given, then the color will be determined by the next value of the default matplotlib color-cycle, and cmap will be set to a matching colormap.

This parameter effects the color of 1D: histograms, confidence intervals, and carpet; 2D: scatter points.

cmapmatplotlib colormap specification, color or list of colors, or None

All valid matplotlib specifications can be used, e.g. named value (like ‘Reds’ or ‘viridis’) or a matplotlib.colors.Colormap instance.
color or list of colors: matplotlib.colors.ListedColormap is constructed.
If None then a colormap is constructed based on the value of color (see above).

quantilesNone or array_like of scalar values in [0.0, 1.0] denoting the fractions of

data to demarkate with contours and confidence bands.

smoothscalar or None/False,

if scalar: The width, in histogram bins, of a gaussian smoothing filter if None or False: no smoothing.

upsampleint or None/False,

if int: the factor by which to upsample the histogram by interpolation. if None or False: no upsampling

padint, True, or None/False,

if int: the number of edge bins added to the histogram to close contours hitting the edges if true: the default padding size is used if None or False: no padding is used.

**kwargsadditiona keyword-arguments passed to kalepy.plot.draw_contour2d().

kalepy.plot.corner(kde_data, labels=None, kwcorner={}, **kwplot)

Simple wrapper function to construct a Corner instance and plot the given data.

See kalepy.plot.Corner and kalepy.plot.Corner.plot for more information.

Parameters:

kde_datakalepy.KDE instance, or (D,N) array_like of scalars

instance of kalepy.kde.KDE, providing the data and KDE to be plotted.
In this case the param argument selects which dimension/parameter is plotted if numerous are included in the KDE.
array_like scalar (D,N) of data with D parameters and N data points.

labelsNone or (D,) array_like of str, names of each parameter being plotted.

kwcornerdict, keyword-arguments passed to Corner constructor.

**kwplotadditional keyword-arguments passed to Corner.plot method.

kalepy.plot.dist1d(kde_data, ax=None, edges=None, weights=None, probability=True, param=0, rotate=False, density=None, confidence=False, hist=None, carpet=True, color=None, quantiles=None, ls=None, alpha=None, **kwargs)

Draw 1D data distributions with numerous possible components.

The components of the plot are controlled by the arguments: * density : a KDE distribution curve, * confidence : 1D confidence bands calculated from a KDE, * hist : 1D histogram from the provided data, * carpet : ‘carpet plot’ (see kalepy.plot.carpet()) showing the data as a scatter-like plot.

Parameters:

kde_datakalepy.KDE instance, (D,N) array_like of scalars, or None

instance of kalepy.kde.KDE, providing the data and KDE to be plotted. In this case the param argument selects which dimension/parameter is plotted if numerous are included in the KDE.
array_like scalar (D,N) of data with D parameters and N data points.

axmatplotlib.axes.Axes instance, or None; if None then plt.gca() is used.

edgesobject specifying historgam edge locations; or None

int : the number of bins, locations calculated automatically
array_like : the bin-edge locations
None : the number and locations of bins are calculated automatically

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

probabilitybool,

Whether distributions (hist and density) are normalized such that the sum is unity.

paramint,

If a KDE instance is provided as the kde_data argument, and it includes multiple dimensions/parameters of data, then this argument determines which parameter is plotted.

rotatebool, if true switch the x and y coordinates (i.e. rotate plot 90deg clockwise).

densitybool or None, whether the density KDE distribution is plotted or not.

If None then this is set based on what is passed as the kde_data.

confidencebool, whether confidence intervals are plotted based on the KDE distribution,

intervals are placed according to the quantiles argument.

histbool or None, whether a histogram is plotted from the given data.

If None, then the value is chosen based on the given kde_data argument.

carpetbool or number, whether or not a ‘carpet plot’ is shown from the given data.

If carpet is a number, it is the maximum number of points that are plotted.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None then the color will be determined by the next value of the default matplotlib color-cycle.

quantilesarray_like of scalar values in [0.0, 1.0] denoting the fractions of data to mark.

lsstr or None, matplotlib linestyle specification

**kwargsadditional keyword-arguments passed to plt.plot command when plotting ‘density’

and ‘hist’ components.

kalepy.plot.dist2d(kde_data, ax=None, edges=None, weights=None, params=[0, 1], quantiles=None, sigmas=None, color=None, cmap=None, smooth=None, upsample=None, pad=True, ls='-', outline=True, median=True, scatter=True, contour=True, hist=True, mask_dense=None, mask_below=True, mask_alpha=0.9)

Draw 2D data distributions with numerous possible components.

The components of the plot are controlled by the arguments: * median : the median values of each coordinate in a ‘cross-hairs’ style, * scatter : 2D scatter points of the raw data, * contour : 2D contour plot from the KDE, * hist : 2D histogram of the raw data.

These components are modified by: * mask_dense : mask over scatter points within the outer-most contour interval, * mask_below : mask out (ignore) histogram bins below a certain value.

Parameters:

kde_datakalepy.KDE instance, or (D,N) array_like of scalars

instance of kalepy.kde.KDE, providing the data and KDE to be plotted. In this case the param argument selects which dimension/parameter is plotted if numerous are included in the KDE.
array_like scalar (D,N) of data with D parameters and N data points.

axmatplotlib.axes.Axes instance, or None; if None then plt.gca() is used.

edgesobject specifying historgam edge locations; or None

int : the number of bins for both dimensions, locations calculated automatically
(2,) array_like of int : the number of bins for each dimension.
(2,) of array_like : the bin-edge locations for each dimension, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension: i.e. 6 total.
(X,) array_like of scalar : the bin-edge locations to be used for both dimensions.
None : the number and locations of bins are calculated automatically.

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

param(2,) array_like of int,

If a KDE instance is provided as the kde_data argument, and it includes multiple dimensions/parameters of data, then this argument determines which parameters are plotted.

quantilesarray_like of scalar values in [0.0, 1.0] denoting the fractions of data to contour.

sigmasarray_like of positive scalar values denoting contour levels.

colormatplotlib color specification (i.e. named color, hex or rgb) or None.

If None:

cmap is given, then the color will be set to the cmap midpoint.
cmap is not given, then the color will be determined by the next value of the default matplotlib color-cycle, and cmap will be set to a matching colormap.

This parameter effects the color of 1D: histograms, confidence intervals, and carpet; 2D: scatter points.

cmapmatplotlib colormap specification, or None

All valid matplotlib specifications can be used, e.g. named value (like ‘Reds’ or ‘viridis’) or a matplotlib.colors.Colormap instance.
If None then a colormap is constructed based on the value of color (see above).

smoothscalar or None/False, smoothing of plotted contours (only)

if scalar: The width, in histogram bins, of a gaussian smoothing filter if None or False: no smoothing.

upsampleint or None/False, upsampling of plotted contours (only)

if int: the factor by which to upsample the histogram by interpolation. if None or False: no upsampling

padint, True, or None/False,

if int: the number of edge bins added to the histogram to close contours hitting the edges if true: the default padding size is used if None or False: no padding is used.

lsstr or None, matplotlib linestyle specification for ‘contour’ and ‘mdedian’ components.

outlinebool, add outline path effects to median and contour lines

medianbool, mark the location of the median values in both dimensions (cross-hairs style).

scatterbool or number, whether to plot a 2D scatter of the data points.

If scatter is a number, it is the maximum number of scatter points plotted (including those that may be masked over). The mask_dense parameter determines if some of these points are masked over.

contourbool, whether or not contours are plotted at the given quantiles.

histbool, whether a 2D histogram is plotted from the given data.

mask_densebool, whether to mask over high-density scatter points (within the lowest contour).

mask_belowbool or scalar; whether, or the value below which, hist bins should be excluded.

If True : exclude histogram bins with less than the average weight of a data point. If weights are not given, this means exclude empty histogram bins.
If False : do not exclude any bins (i.e. include all bins).
If scalar : exclude histogram bins with values below the given value.

Notes

There is no probability argument because the normalization of the 2D distributions currently has no effect.

kalepy.plot.hist1d(data, edges=None, ax=None, weights=None, density=False, probability=False, renormalize=False, joints=True, positive=True, rotate=False, **kwargs)

Calculate and draw a 1D histogram.

This is a thin wrapper around the kalepy.plot.draw_hist1d() method which draws a histogram that has already been computed (e.g. with kalepy.utils.histogram or numpy.histogram).

Parameters:

data(N,) array_like of scalar, data to be histogrammed.

edgesobject specifying historgam edge locations; or None

int : the number of bins, locations calculated automatically
array_like : the bin-edge locations
None : the number and locations of bins are calculated automatically

axmatplotlib.axes.Axes instance, or None; if None then plt.gca() is used.

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

densitybool or None, whether the density KDE distribution is plotted or not.

If None then this is set based on what is passed as the kde_data.

probabilitybool,

Whether distributions (hist and density) are normalized such that the sum is unity. NOTE: this can be overridden by the renormalize argument.

renormalizebool or scalar, whether or to what value to renormalize the histrogram maximum.

If True : renormalize the maximum histogram value to unity. If False : do not renormalize. If scalar : renormalize the histogram maximum to this value.

jointsbool, plot the vertical connectors (‘joints’) between histogram bins; if False, only

horizontal lines are plotted for each bin.

positivebool, only plot bins with positive values.

rotatebool, if true switch the x and y coordinates (i.e. rotate plot 90deg clockwise).

**kwargsadditional keyword-arguments passed to kalepy.plot.draw_hist1d().

Any arguments not caught by draw_hist1d() are eventually passed to plt.plot() method.

Notes

TO-DO: Add scipy.binned_statistic functionality for arbitrary statistics beyond histgramming.

kalepy.plot.hist2d(data, edges=None, ax=None, weights=None, mask_below=False, **kwargs)

Calculate and draw a 2D histogram.

This is a thin wrapper around the kalepy.plot.draw_hist2d() method which draws a 2D histogram that has already been computed (e.g. with numpy.histogram2d).

Parameters:

data(2, N) array_like of scalar, data to be histogrammed.

edgesobject specifying historgam edge locations; or None

int : the number of bins for both dimensions, locations calculated automatically
(2,) array_like of int : the number of bins for each dimension.
(2,) of array_like : the bin-edge locations for each dimension, e.g. ([0, 1, 2], [0.0, 0.1, 0.2, 0.3],) would describe two bins for the 0th dimension, and 3 bins for the 1st dimension: i.e. 6 total.
(X,) array_like of scalar : the bin-edge locations to be used for both dimensions.
None : the number and locations of bins are calculated automatically.

axmatplotlib.axes.Axes instance, or None; if None then plt.gca() is used.

weightsNone or (N,) array_like of scalar, the weighting of each data-point if and

only-if the given kde_data argument is a (D,N) array_like of scalar data.

mask_belowbool or scalar; whether, or the value below which, hist bins should be excluded.

If True : exclude histogram bins with less than the average weight of a data point. If weights are not given, this means exclude empty histogram bins.
If False : do not exclude any bins (i.e. include all bins).
If scalar : exclude histogram bins with values below the given value.

**kwargsadditional keyword-arguments passed to kalepy.plot.draw_hist2d().

Any arguments not caught by draw_hist1d() are eventually passed to plt.pcolormesh().

Notes

TO-DO: Add scipy.binned_statistic functionality for arbitrary statistics beyond histgramming.