pyrolite.plot.density
Kernel desnity estimation plots for geochemical data.
- pyrolite.plot.density.density(arr, ax=None, logx=False, logy=False, bins=25, mode='density', extent=None, contours=[], percentiles=True, relim=True, cmap=<matplotlib.colors.ListedColormap object>, shading='auto', vmin=0.0, colorbar=False, **kwargs)[source]
Creates diagramatic representation of data density and/or frequency for either binary diagrams (X-Y) or ternary plots. Additional arguments are typically forwarded to respective
matplotlib
functionspcolormesh()
,hist2d()
,hexbin()
,contour()
, andcontourf()
(see Other Parameters, below).
- Parameters
arr (
numpy.ndarray
) – Dataframe from which to draw data.ax (
matplotlib.axes.Axes
, None) – The subplot to draw on.logx (
bool
, False) – Whether to use a logspaced grid on the x axis. Values strictly >0 required.logy (
bool
, False) – Whether to use a logspaced grid on the y axis. Values strictly >0 required.bins (
int
, 20) – Number of bins used in the gridded functions (histograms, KDE evaluation grid).mode (
str
, ‘density’) – Different modes used here: [‘density’, ‘hexbin’, ‘hist2d’]extent (
list
) – Predetermined extent of the grid for which to from the histogram/KDE. In the general form (xmin, xmax, ymin, ymax).contours (
list
) – Contours to add to the plot, wheremode='density'
is used.percentiles (
bool
, True) – Whether contours specified are to be converted to percentiles.relim (
bool
,True
) – Whether to relimit the plot based on xmin, xmax values.cmap (
matplotlib.colors.Colormap
) – Colormap for mapping surfaces.vmin (
float
, 0.) – Minimum value for colormap.shading (
str
, ‘auto’) – Shading to apply to pcolormesh.colorbar (
bool
, False) – Whether to append a linked colorbar to the generated mappable image.Note
The following additional parameters are from
matplotlib.pyplot.pcolormesh()
.
- Other Parameters
C (array-like) – The mesh data. Supported array shapes are:
(M, N) or M*N: a mesh with scalar data. The values are mapped to colors using normalization and a colormap. See parameters norm, cmap, vmin, vmax.
(M, N, 3): an image with RGB values (0-1 float or 0-255 int).
(M, N, 4): an image with RGBA values (0-1 float or 0-255 int), i.e. including transparency.
The first two dimensions (M, N) define the rows and columns of the mesh data.
X, Y (array-like, optional) –
The coordinates of the corners of quadrilaterals of a pcolormesh:
(X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1]) ●╶───╴● │ │ ●╶───╴● (X[i, j], Y[i, j]) (X[i, j+1], Y[i, j+1])Note that the column index corresponds to the x-coordinate, and the row index corresponds to y. For details, see the Notes section below.
If
shading='flat'
the dimensions of X and Y should be one greater than those of C, and the quadrilateral is colored due to the value atC[i, j]
. If X, Y and C have equal dimensions, a warning will be raised and the last row and column of C will be ignored.If
shading='nearest'
or'gouraud'
, the dimensions of X and Y should be the same as those of C (if not, a ValueError will be raised). For'nearest'
the colorC[i, j]
is centered on(X[i, j], Y[i, j])
. For'gouraud'
, a smooth interpolation is caried out between the quadrilateral corners.If X and/or Y are 1-D arrays or column vectors they will be expanded as needed into the appropriate 2D arrays, making a rectangular grid.
norm (str or ~matplotlib.colors.Normalize, optional) – The normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling is used, mapping the lowest value to 0 and the highest to 1.
If given, this can be one of the following:
An instance of .Normalize or one of its subclasses (see Colormap normalization).
A scale name, i.e. one of “linear”, “log”, “symlog”, “logit”, etc. For a list of available scales, call matplotlib.scale.get_scale_names(). In that case, a suitable .Normalize subclass is dynamically generated and instantiated.
vmin, vmax (float, optional) – When using scalar data and no explicit norm, vmin and vmax define the data range that the colormap covers. By default, the colormap covers the complete value range of the supplied data. It is an error to use vmin/vmax when a norm instance is given (but using a str norm name together with vmin/vmax is acceptable).
edgecolors ({‘none’, None, ‘face’, color, color sequence}, optional) – The color of the edges. Defaults to ‘none’. Possible values:
‘none’ or ‘’: No edge.
None:
rcParams["patch.edgecolor"]
will be used. Note that currentlyrcParams["patch.force_edgecolor"]
has to be True for this to work.‘face’: Use the adjacent face color.
A color or sequence of colors will set the edge color.
The singular form edgecolor works as an alias.
alpha (float, default: None) – The alpha blending value, between 0 (transparent) and 1 (opaque).
snap (bool, default: False) – Whether to snap the mesh to pixel boundaries.
rasterized (bool, optional) – Rasterize the pcolormesh when drawing vector graphics. This can speed up rendering and produce smaller files for large data sets. See also /gallery/misc/rasterization_demo.
Note
The following additional parameters are from
matplotlib.pyplot.hist2d()
.
- Other Parameters
x, y (array-like, shape (n, )) – Input values
range (array-like shape(2, 2), optional) – The leftmost and rightmost edges of the bins along each dimension (if not specified explicitly in the bins parameters):
[[xmin, xmax], [ymin, ymax]]
. All values outside of this range will be considered outliers and not tallied in the histogram.density (bool, default: False) – Normalize histogram. See the documentation for the density parameter of ~.Axes.hist for more details.
weights (array-like, shape (n, ), optional) – An array of values w_i weighing each sample (x_i, y_i).
cmin, cmax (float, default: None) – All bins that has count less than cmin or more than cmax will not be displayed (set to NaN before passing to ~.Axes.pcolormesh) and these count values in the return value count histogram will also be set to nan upon return.
Note
The following additional parameters are from
matplotlib.pyplot.hexbin()
.
- Other Parameters
x, y (array-like) – The data positions. x and y must be of the same length.
C (array-like, optional) – If given, these values are accumulated in the bins. Otherwise, every point has a value of 1. Must be of the same length as x and y.
gridsize (int or (int, int), default: 100) – If a single int, the number of hexagons in the x-direction. The number of hexagons in the y-direction is chosen such that the hexagons are approximately regular.
Alternatively, if a tuple (nx, ny), the number of hexagons in the x-direction and the y-direction. In the y-direction, counting is done along vertically aligned hexagons, not along the zig-zag chains of hexagons; see the following illustration.
To get approximately regular hexagons, choose \(n_x = \sqrt{3}\,n_y\).
xscale ({‘linear’, ‘log’}, default: ‘linear’) – Use a linear or log10 scale on the horizontal axis.
yscale ({‘linear’, ‘log’}, default: ‘linear’) – Use a linear or log10 scale on the vertical axis.
mincnt (int >= 0, default: *None*) – If not None, only display cells with at least mincnt number of points in the cell.
marginals (bool, default: *False*) – If marginals is True, plot the marginal density as colormapped rectangles along the bottom of the x-axis and left of the y-axis.
Note
The following additional parameters are from
matplotlib.pyplot.contour()
.
- Other Parameters
X, Y (array-like, optional) – The coordinates of the values in Z.
X and Y must both be 2D with the same shape as Z (e.g. created via numpy.meshgrid), or they must both be 1-D such that
len(X) == N
is the number of columns in Z andlen(Y) == M
is the number of rows in Z.X and Y must both be ordered monotonically.
If not given, they are assumed to be integer indices, i.e.
X = range(N)
,Y = range(M)
.Z ((M, N) array-like) – The height values over which the contour is drawn. Color-mapping is controlled by cmap, norm, vmin, and vmax.
levels (int or array-like, optional) – Determines the number and positions of the contour lines / regions.
If an int n, use ~matplotlib.ticker.MaxNLocator, which tries to automatically choose no more than n+1 “nice” contour levels between minimum and maximum numeric values of Z.
If array-like, draw contour lines at the specified levels. The values must be in increasing order.
Note
The following additional parameters are from
matplotlib.pyplot.contourf()
.
- Other Parameters
X, Y (array-like, optional) – The coordinates of the values in Z.
X and Y must both be 2D with the same shape as Z (e.g. created via numpy.meshgrid), or they must both be 1-D such that
len(X) == N
is the number of columns in Z andlen(Y) == M
is the number of rows in Z.X and Y must both be ordered monotonically.
If not given, they are assumed to be integer indices, i.e.
X = range(N)
,Y = range(M)
.Z ((M, N) array-like) – The height values over which the contour is drawn. Color-mapping is controlled by cmap, norm, vmin, and vmax.
levels (int or array-like, optional) – Determines the number and positions of the contour lines / regions.
If an int n, use ~matplotlib.ticker.MaxNLocator, which tries to automatically choose no more than n+1 “nice” contour levels between minimum and maximum numeric values of Z.
If array-like, draw contour lines at the specified levels. The values must be in increasing order.
- Returns
matplotlib.axes.Axes
– Axes on which the densityplot is plotted... seealso:: –
Functions:
Notes
The default density estimates and derived contours are generated based on kernel density estimates. Assumptions around e.g. 95% of points lying within a 95% contour won’t necessarily be valid for non-normally distributed data (instead, this represents the approximate 95% percentile on the kernel density estimate). Note that contours are currently only generated; for mode=”density”; future updates may allow the use of a histogram basis, which would give results closer to 95% data percentiles.
Todo
- Allow generation of contours from histogram data, rather than just
the kernel density estimate.
- Implement an option and filter to ‘scatter’ points below the minimum threshold
or maximum percentile contours.