API¶

This page is under construction. Only a few available methods are shown.

class mpltern.ternary.TernaryAxes(*args, ternary_scale=1.0, corners=None, rotation=None, **kwargs)¶

A ternary graph projection, where the input dimensions are t, l, r. The plot starts from the top and goes anti-clockwise.

set_tlabel(tlabel, fontdict=None, labelpad=None, *, loc=None, **kwargs)¶

Set the label for the t-axis.

Parameters

tlabelstr: The label text.
labelpadfloat, default: :rc:`axes.labelpad`: Spacing in points from the Axes bounding box including ticks and tick labels. If None, the previous value is left as is.
loc{‘left’, ‘center’, ‘right’}, default: :rc:`xaxis.labellocation`: The label position. This is a high-level alternative for passing parameters x and horizontalalignment.

Other Parameters

**kwargs.Text properties: .Text properties control the appearance of the label.

See also

text: Documents the properties supported by .Text.

set_llabel(llabel, fontdict=None, labelpad=None, *, loc=None, **kwargs)¶

Set the label for the l-axis.

Parameters

llabelstr: The label text.
labelpadfloat, default: :rc:`axes.labelpad`: Spacing in points from the Axes bounding box including ticks and tick labels. If None, the previous value is left as is.
loc{‘left’, ‘center’, ‘right’}, default: :rc:`xaxis.labellocation`: The label position. This is a high-level alternative for passing parameters x and horizontalalignment.

Other Parameters

**kwargs.Text properties: .Text properties control the appearance of the label.

See also

text: Documents the properties supported by .Text.

set_rlabel(rlabel, fontdict=None, labelpad=None, *, loc=None, **kwargs)¶

Set the label for the r-axis.

Parameters

rlabelstr: The label text.
labelpadfloat, default: :rc:`axes.labelpad`: Spacing in points from the Axes bounding box including ticks and tick labels. If None, the previous value is left as is.
loc{‘left’, ‘center’, ‘right’}, default: :rc:`xaxis.labellocation`: The label position. This is a high-level alternative for passing parameters x and horizontalalignment.

Other Parameters

**kwargs.Text properties: .Text properties control the appearance of the label.

See also

text: Documents the properties supported by .Text.

axtline(x=0, ymin=0, ymax=1, **kwargs)¶

Add a equi-t line across the axes.

Parameters

xfloat, default: 0: x position in data coordinates of the equi-t line.
yminfloat, default: 0: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.
ymaxfloat, default: 1: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.

Returns

~matplotlib.lines.Line2D

Other Parameters

**kwargs

Valid keyword arguments are .Line2D properties, except for ‘transform’:

%(Line2D:kwdoc)s

See also

axtspan: Add a equi-t span across the axis.

axlline(x=0, ymin=0, ymax=1, **kwargs)¶

Add a equi-l line across the axes.

Parameters

xfloat, default: 0: x position in data coordinates of the equi-l line.
yminfloat, default: 0: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.
ymaxfloat, default: 1: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.

Returns

~matplotlib.lines.Line2D

Other Parameters

**kwargs

Valid keyword arguments are .Line2D properties, except for ‘transform’:

%(Line2D:kwdoc)s

See also

axlspan: Add a equi-l span across the axis.

axrline(x=0, ymin=0, ymax=1, **kwargs)¶

Add a equi-r line across the axes.

Parameters

xfloat, default: 0: x position in data coordinates of the equi-r line.
yminfloat, default: 0: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.
ymaxfloat, default: 1: Should be between 0 and 1, 0 being one end of the plot, 1 the other of the plot.

Returns

~matplotlib.lines.Line2D

Other Parameters

**kwargs

Valid keyword arguments are .Line2D properties, except for ‘transform’:

%(Line2D:kwdoc)s

See also

axrspan: Add a equi-r span across the axis.

axtspan(xmin, xmax, ymin=0, ymax=1, **kwargs)¶

Add a span for the bottom coordinate.

Parameters

xminfloat: Lower limit of the top span in data units.
xmaxfloat: Upper limit of the top span in data units.
yminfloat, optional, default: 0: Lower limit of the span from end to end in relative (0-1) units.
ymaxfloat, optional, default: 1: Upper limit of the span from end to end in relative (0-1) units.

Returns

~matplotlib.patches.Polygon

Other Parameters

**kwargs~matplotlib.patches.Polygon properties
%(Polygon:kwdoc)s

See also

axlspan: Add a span for the left coordinate.
axrspan: Add a span for the right coordinate.

axlspan(xmin, xmax, ymin=0, ymax=1, **kwargs)¶

Add a span for the left coordinate.

Parameters

xminfloat: Lower limit of the left span in data units.
xmaxfloat: Upper limit of the left span in data units.
yminfloat, optional, default: 0: Lower limit of the span from end to end in relative (0-1) units.
ymaxfloat, optional, default: 1: Upper limit of the span from end to end in relative (0-1) units.

Returns

~matplotlib.patches.Polygon

Other Parameters

**kwargs~matplotlib.patches.Polygon properties
%(Polygon:kwdoc)s

See also

axtspan: Add a span for the top coordinate.
axrspan: Add a span for the right coordinate.

axrspan(xmin, xmax, ymin=0, ymax=1, **kwargs)¶

Add a span for the right coordinate.

Parameters

xminfloat: Lower limit of the right span in data units.
xmaxfloat: Upper limit of the right span in data units.
yminfloat, optional, default: 0: Lower limit of the span from end to end in relative (0-1) units.
ymaxfloat, optional, default: 1: Upper limit of the span from end to end in relative (0-1) units.

Returns

~matplotlib.patches.Polygon

Other Parameters

**kwargs~matplotlib.patches.Polygon properties
%(Polygon:kwdoc)s

See also

axtspan: Add a span for the top coordinate.
axlspan: Add a span for the left coordinate.

hexbin(t, l, r, C=None, gridsize=100, bins=None, xscale='linear', yscale='linear', extent=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, edgecolors='face', reduce_C_function=<function mean>, mincnt=None, marginals=False, **kwargs)¶

Make a 2D hexagonal binning plot of points t, l, r.

If C is None, the value of the hexagon is determined by the number of points in the hexagon. Otherwise, C specifies values at the coordinate (t[i], l[i], r[i]). For each triangle, these values are reduced using reduce_C_function.

Parameters

t, l, rarray-like

The data positions. t, l, and r must be of the same length.

Carray-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 t, l, and r.

gridsizeint, default: 100

Number of hexagons in one direction between min and max. In mpltern, all the three directions have the same gridsize.

bins‘log’ or int or sequence, default: None

Discretization of the hexagon values.

If None, no binning is applied; the color of each hexagon directly corresponds to its count value.
If ‘log’, use a logarithmic scale for the colormap. Internally, \(log_{10}(i+1)\) is used to determine the hexagon color. This is equivalent to norm=LogNorm().
If an integer, divide the counts in the specified number of bins, and color the hexagons accordingly.
If a sequence of values, the values of the lower bound of the bins to be used.

xscale{‘linear’, ‘log’}, default: ‘linear’

Ignored in mpltern and always linear scales on all three axes.

yscale{‘linear’, ‘log’}, default: ‘linear’

Ignored in mpltern and always linear scales on all three axes.

mincntint > 0, default: None

If not None, only display cells with more than mincnt number of points in the cell.

marginalsbool, default: False

Ignored in mpltern.

extent6-tuple of float, default: None

The limits of the bins (tmin, tmax, lmin, lmax, rmin, rmax). The default assigns the limits based on tlim, llim, rlim.

Returns

~matplotlib.collections.PolyCollection

A .PolyCollection defining the hexagonal bins.

.PolyCollection.get_offsets contains a Mx2 array containing the x, y positions of the M hexagon centers.
.PolyCollection.get_array contains the values of the M hexagons.

Other Parameters

%(cmap_doc)s

%(norm_doc)s

%(vmin_vmax_doc)s

alphafloat between 0 and 1, optional

The alpha blending value, between 0 (transparent) and 1 (opaque).

linewidthsfloat, default: None

If None, defaults to 1.0.

edgecolors{‘face’, ‘none’, None} or color, default: ‘face’

The color of the hexagon edges. Possible values are:

‘face’: Draw the edges in the same color as the fill color.
‘none’: No edges are drawn. This can sometimes lead to unsightly unpainted pixels between the hexagons.
None: Draw outlines in the default color.
An explicit color.

reduce_C_functioncallable, default: numpy.mean

The function to aggregate C within the bins. It is ignored if C is not given. This must have the signature:

def reduce_C_function(C: array) -> float

Commonly used functions are:

numpy.mean: average of the points
numpy.sum: integral of the point values
numpy.amax: value taken from the largest point

dataindexable object, optional

DATA_PARAMETER_PLACEHOLDER

**kwargs~matplotlib.collections.PolyCollection properties

All other keyword arguments are passed on to .PolyCollection:

%(PolyCollection:kwdoc)s

See also

tribin: 2D histogram triangular bins

tribin(t, l, r, C=None, gridsize=100, bins=None, xscale='linear', yscale='linear', extent=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, edgecolors='face', reduce_C_function=<function mean>, mincnt=None, marginals=False, **kwargs)¶

Make a 2D triangular binning plot of points t, l, r.

If C is None, the value of the triangle is determined by the number of points in the triangle. Otherwise, C specifies values at the coordinate (t[i], l[i], r[i]). For each triangle, these values are reduced using reduce_C_function.

Parameters

t, l, rarray-like

The data positions. t, l, and r must be of the same length.

Carray-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 t, l, and r.

gridsizeint, default: 100

Number of triangles in one direction between min and max. In mpltern, all the three directions have the same gridsize.

bins‘log’ or int or sequence, default: None

Discretization of the hexagon values.

If None, no binning is applied; the color of each triangle directly corresponds to its count value.
If ‘log’, use a logarithmic scale for the colormap. Internally, \(log_{10}(i+1)\) is used to determine the triangle color. This is equivalent to norm=LogNorm().
If an integer, divide the counts in the specified number of bins, and color the triangles accordingly.
If a sequence of values, the values of the lower bound of the bins to be used.

xscale{‘linear’, ‘log’}, default: ‘linear’

Ignored in mpltern and always linear scales on all three axes.

yscale{‘linear’, ‘log’}, default: ‘linear’

Ignored in mpltern and always linear scales on all three axes.

mincntint > 0, default: None

If not None, only display cells with more than mincnt number of points in the cell.

marginalsbool, default: False

Ignored in mpltern.

extent6-tuple of float, default: None

The limits of the bins (tmin, tmax, lmin, lmax, rmin, rmax). The default assigns the limits based on tlim, llim, rlim.

Returns

~matplotlib.collections.PolyCollection

A .PolyCollection defining the triangular bins.

.PolyCollection.get_offsets contains a Mx2 array containing the x, y positions of the M triangle centers.
.PolyCollection.get_array contains the values of the M triangles.

Other Parameters

%(cmap_doc)s

%(norm_doc)s

%(vmin_vmax_doc)s

alphafloat between 0 and 1, optional

The alpha blending value, between 0 (transparent) and 1 (opaque).

linewidthsfloat, default: None

If None, defaults to 1.0.

edgecolors{‘face’, ‘none’, None} or color, default: ‘face’

The color of the triangle edges. Possible values are:

‘face’: Draw the edges in the same color as the fill color.
‘none’: No edges are drawn. This can sometimes lead to unsightly unpainted pixels between the triangles.
None: Draw outlines in the default color.
An explicit color.

reduce_C_functioncallable, default: numpy.mean

The function to aggregate C within the bins. It is ignored if C is not given. This must have the signature:

def reduce_C_function(C: array) -> float

Commonly used functions are:

numpy.mean: average of the points
numpy.sum: integral of the point values
numpy.amax: value taken from the largest point

dataindexable object, optional

DATA_PARAMETER_PLACEHOLDER

**kwargs~matplotlib.collections.PolyCollection properties

All other keyword arguments are passed on to .PolyCollection:

%(PolyCollection:kwdoc)s

See also

hexbin: 2D histogram hexagonal bins