pyrolite.util.plot

Utility functions for working with matplotlib.

Parameters:

DEFAULT_CONT_COLORMAP (matplotlib.colors.ScalarMappable) – Default continuous colormap.

DEFAULT_DICS_COLORMAP (matplotlib.colors.ScalarMappable) – Default discrete colormap.

USE_PCOLOR (bool) – Option to use the matplotlib.pyplot.pcolor() function in place of matplotlib.pyplot.pcolormesh().

pyrolite.util.plot.axes

Functions for creating, ordering and modifying Axes.

pyrolite.util.plot.axes.get_ordered_axes(fig)[source]

Get the axes from a figure, which may or may not have been modified by pyrolite functions. This ensures that ordering is preserved.

pyrolite.util.plot.axes.get_axes_index(ax)[source]

Get the three-digit integer index of a subplot in a regular grid.

Parameters:

ax (matplotlib.axes.Axes) – Axis to to get the gridspec index for.

Returns:

Rows, columns and axis index for the gridspec.

Return type:

tuple

pyrolite.util.plot.axes.replace_with_ternary_axis(ax)[source]

Replace a specified axis with a ternary equivalent.

Parameters:

ax (Axes)

Returns:

tax

Return type:

TernaryAxes

pyrolite.util.plot.axes.label_axes(ax, labels=[], **kwargs)[source]

Convenience function for labelling rectilinear and ternary axes.

Parameters:

ax (Axes) – Axes to label.

labels (list) – List of labels: [x, y] | or [t, l, r]

pyrolite.util.plot.axes.axes_to_ternary(ax)[source]

Set axes to ternary projection after axis creation. As currently implemented, note that this will replace and reorder axes as acecessed from the figure (the ternary axis will then be at the end), and as such this returns a list of axes in the correct order.

Parameters:

ax (Axes | list (Axes)) – Axis (or axes) to convert projection for.

Returns:

axes

Return type:

list' (:class:`~matplotlib.axes.Axes, class:~mpltern.ternary.TernaryAxes)

pyrolite.util.plot.axes.check_default_axes(ax)[source]

Simple test to check whether an axis is empty of artists and hasn’t been rescaled from the default extent.

Parameters:

ax (matplotlib.axes.Axes) – Axes to check for artists and scaling.

Return type:

bool

pyrolite.util.plot.axes.check_empty(ax)[source]

Simple test to check whether an axis is empty of artists.

Parameters:

ax (matplotlib.axes.Axes) – Axes to check for artists.

Return type:

bool

pyrolite.util.plot.axes.init_axes(ax=None, projection=None, minsize=1.0, **kwargs)[source]

Get or create an Axes from an optionally-specified starting Axes.

Parameters:

ax (Axes) – Specified starting axes, optional.

projection (str) – Whether to create a projected (e.g. ternary) axes.

minsize (float) – Minimum figure dimension (inches).

Returns:

ax

Return type:

Axes

pyrolite.util.plot.axes.share_axes(axes, which='xy')[source]

Link the x, y or both axes across a group of Axes.

Parameters:

axes (list) – List of axes to link.

which (str) – Which axes to link. If x, link the x-axes; if y link the y-axes, otherwise link both.

pyrolite.util.plot.axes.get_twins(ax, which='y')[source]

Get twin axes of a specified axis.

Parameters:

ax (matplotlib.axes.Axes) – Axes to get twins for.

which (str) – Which twins to get (shared 'x', shared 'y' or the concatenatation of both, 'xy').

Return type:

list

Notes

This function was designed to assist in avoiding creating a series of duplicate axes when replotting on an existing axis using a function which would typically create a twin axis.

pyrolite.util.plot.axes.subaxes(ax, side='bottom', width=0.2, moveticks=True)[source]

Append a sub-axes to one side of an axes.

Parameters:

ax (matplotlib.axes.Axes) – Axes to append a sub-axes to.

side (str) – Which side to append the axes on.

width (float) – Fraction of width to give to the subaxes.

moveticks (bool) – Whether to move ticks to the outer axes.

Returns:

Subaxes instance.

Return type:

matplotlib.axes.Axes

pyrolite.util.plot.axes.add_colorbar(mappable, **kwargs)[source]

Adds a colorbar to a given mappable object.

Source: http://joseph-long.com/writing/colorbars/

Parameters:

mappable – The Image, ContourSet, etc. to which the colorbar applies.

Return type:

matplotlib.colorbar.Colorbar

Todo

Where no mappable specificed, get most recent axes, and check for collections etc

pyrolite.util.plot.density

Functions for dealing with kernel density estimation.

ivar USE_PCOLOR:: Option to use the matplotlib.pyplot.pcolor() function in place of matplotlib.pyplot.pcolormesh().
vartype USE_PCOLOR:: bool

pyrolite.util.plot.density.get_axis_density_methods(ax)[source]

Get the relevant density and contouring methods for a given axis.

Parameters:: ax (matplotlib.axes.Axes | mpltern.ternary.TernaryAxes) – Axis to check.
Returns:: Relevant functions for this axis.
Return type:: pcolor, contour, contourf

pyrolite.util.plot.density.percentile_contour_values_from_meshz(z, percentiles=[0.95, 0.66, 0.33], resolution=1000)[source]

Integrate a probability density distribution Z(X,Y) to obtain contours in Z which correspond to specified percentile contours. Contour values will be returned with the same order as the inputs.

Parameters:

z (numpy.ndarray) – Probability density function over x, y.
percentiles (numpy.ndarray) – Percentile values for which to create contours.
resolution (int) – Number of bins for thresholds between 0. and max(Z)

Returns:

labels (list) – Labels for contours (percentiles, if above minimum z value).
contours (list) – Contour height values.

Todo

This may error for a list of percentiles where one or more requested values are below the miniumum threshold. The exception handling should be updated to cater for arrays - where some of the values may be above the minimum.

pyrolite.util.plot.density.plot_Z_percentiles(*coords, zi=None, percentiles=[0.95, 0.66, 0.33], ax=None, extent=None, fontsize=8, cmap=None, colors=None, linewidths=None, linestyles=None, contour_labels=None, label_contours=True, **kwargs)[source]

Plot percentile contours onto a 2D (scaled or unscaled) probability density distribution Z over X,Y.

Parameters:

coords (numpy.ndarray) – Arrays of (x, y) or (a, b, c) coordinates.
z (numpy.ndarray) – Probability density function over x, y.
percentiles (list) – Percentile values for which to create contours.
ax (matplotlib.axes.Axes, None) – Axes on which to plot. If none given, will create a new Axes instance.
extent (list, None) – List or np.ndarray in the form [-x, +x, -y, +y] over which the image extends.
fontsize (float) – Fontsize for the contour labels.
cmap (matplotlib.colors.ListedColormap) – Color map for the contours and contour labels.
colors (str | list) – Colors for the contours, can optionally be specified in place of cmap.
linewidths (str | list) – Widths of contour lines.
linestyles (str | list) – Styles for contour lines.
contour_labels (dict | list) – Labels to assign to contours, organised by level.
label_contours :class:`bool` – Whether to add text labels to individual contours.

Returns:

Plotted and formatted contour set.

Return type:

matplotlib.contour.QuadContourSet

Notes

When the contours are percentile based, high percentile contours tend to get washed our with colormapping - consider adding different controls on coloring, especially where there are only one or two contours specified. One way to do this would be via the string based keyword argument colors for plt.contour, with an adaption for non-string colours which post-hoc modifies the contour lines based on the specified colours?

pyrolite.util.plot.density.conditional_prob_density(y, x=None, logy=False, resolution=5, bins=50, yextent=None, rescale=True, mode='binkde', ret_centres=False, **kwargs)[source]

Estimate the conditional probability density of one dependent variable.

Parameters:

y (numpy.ndarray) – Dependent variable for which to calculate conditional probability P(y | X=x)
x (numpy.ndarray, None) – Optionally-specified independent index.
logy (bool) – Whether to use a logarithmic bin spacing on the y axis.
resolution (int) – Points added per segment via interpolation along the x axis.
bins (int) – Bins for histograms and grids along the independent axis.
yextent (tuple) – Extent in the y direction.
rescale (bool) – Whether to rescale bins to give the same max Z across x.
mode (str) –

Mode of computation.

If mode is "ckde", use statsmodels.nonparametric.KDEMultivariateConditional() to compute a conditional kernel density estimate. If mode is "kde", use a normal gaussian kernel density estimate. If mode is "binkde", use a gaussian kernel density estimate over y for each bin. If mode is "hist", compute a histogram.
ret_centres (bool) – Whether to return bin centres in addtion to histogram edges, e.g. for later contouring.

Returns:

x bin edges xe, y bin edges ye, histogram/density estimates Z. If ret_centres is True, the last two return values will contain the bin centres xi, yi.

Return type:

tuple of numpy.ndarray

pyrolite.util.plot.export

Functions for export of figures and figure elements from matplolib.

pyrolite.util.plot.export.save_figure(figure, name='fig', save_at='', save_fmts=['png'], **kwargs)[source]: Save a figure at a specified location in a number of formats.

pyrolite.util.plot.export.save_axes(ax, name='fig', save_at='', save_fmts=['png'], pad=0.0, **kwargs)[source]

Save either a single or multiple axes (from a single figure) based on their extent. Uses the save_figure procedure to save at a specific location using a number of formats.

Todo

Add legend to items

pyrolite.util.plot.export.get_full_extent(ax, pad=0.0)[source]

Get the full extent of an axes, including axes labels, tick labels, and titles. Text objects are first drawn to define the extents.

Parameters:

ax (matplotlib.axes.Axes) – Axes of which to check items to get full extent.
pad (float | tuple) – Amount of padding to add to the full extent prior to returning. If a tuple is passed, the padding will be as above, but for x and y directions, respectively.

Returns:

Bbox of the axes with optional additional padding.

Return type:

matplotlib.transforms.Bbox

pyrolite.util.plot.export.path_to_csv(path, xname='x', yname='y', delim=',', linesep='\n')[source]

Extract the verticies from a path and write them to csv.

Parameters:

path (matplotlib.path.Path | tuple) – Path or x-y tuple to use for coordinates.
xname (str) – Name of the x variable.
yname (str) – Name of the y variable.
delim (str) – Delimiter for the csv file.
linesep (str) – Line separator character.

Returns:

String-representation of csv file, ready to be written to disk.

Return type:

str

pyrolite.util.plot.grid

Gridding and binning functions.

pyrolite.util.plot.grid.bin_centres_to_edges(centres, sort=True)[source]

Translates point estimates at the centres of bins to equivalent edges, for the case of evenly spaced bins.

Todo

This can be updated to unevenly spaced bins, just need to calculate outer bins.

pyrolite.util.plot.grid.bin_edges_to_centres(edges)[source]: Translates edges of histogram bins to bin centres.

pyrolite.util.plot.grid.ternary_grid(data=None, nbins=10, margin=0.001, force_margin=False, yscale=1.0, tfm=<function <lambda>>)[source]

Construct a graphical linearly-spaced grid within a ternary space.

Parameters:

data (numpy.ndarray) – Data to construct the grid around ((samples, 3)).
nbins (int) – Number of bins for grid.
margin (float) – Proportional value for the position of the outer boundary of the grid.
forge_margin (bool) – Whether to enforce the grid margin.
yscale (float) – Y scale for the specific ternary diagram.
tfm – Log transform to use for the grid creation.

Returns:

bins (numpy.ndarray) – Bin centres along each of the ternary axes ((samples, 3))
binedges (numpy.ndarray) – Position of bin edges.
centregrid (list of numpy.ndarray) – Meshgrid of bin centres.
edgegrid (list of numpy.ndarray) – Meshgrid of bin edges.

pyrolite.util.plot.helpers

matplotlib helper functions for commong drawing tasks.

pyrolite.util.plot.helpers.alphalabel_subplots(ax, fmt='{}', xy=(0.03, 0.95), ha='left', va='top', **kwargs)[source]

Add alphabetical labels to a successive series of subplots with a specified format.

Parameters:

ax (list | numpy.ndarray | numpy.flatiter) – Axes to label, in desired order.
fmt (str) – Format string to use. To add e.g. parentheses, you could specify "({})".
xy (tuple) – Position of the labels in axes coordinates.
ha (str) – Horizontal alignment of the labels ({"left", "right"}).
va (str) – Vertical alignment of the labels ({"top", "bottom"}).

pyrolite.util.plot.helpers.get_centroid(poly)[source]

Centroid of a closed polygon using the Shoelace formula.

Parameters:: poly (matplotlib.patches.Polygon) – Polygon to obtain the centroid of.
Returns:: cx, cy – Centroid coordinates.
Return type:: tuple

pyrolite.util.plot.helpers.get_visual_center(poly, vertical_exaggeration=1)[source]

Visual center of a closed polygon.

Parameters:

poly (matplotlib.patches.Polygon) – Polygon for which to obtain the visual center.
vertical_exaggeration (float) – Apparent vertical exaggeration of the plot (pixels per unit in y direction divided by pixels per unit in the x direction).

Returns:

cx, cy – Centroid coordinates.

Return type:

tuple

pyrolite.util.plot.helpers.rect_from_centre(x, y, dx=0, dy=0, **kwargs)[source]: Takes an xy point, and creates a rectangular patch centred about it.

pyrolite.util.plot.helpers.draw_vector(v0, v1, ax=None, **kwargs)[source]

Plots an arrow represnting the direction and magnitue of a principal component on a biaxial plot.

Modified after Jake VanderPlas’ Python Data Science Handbook https://jakevdp.github.io/PythonDataScienceHandbook/ 05.09-principal-component-analysis.html

Todo

Update for ternary plots.

pyrolite.util.plot.helpers.vector_to_line(mu: array, vector: array, variance: float, spans: int = 4, expand: int = 10)[source]: Creates an array of points representing a line along a vector - typically for principal component analysis. Modified after Jake VanderPlas’ Python Data Science Handbook https://jakevdp.github.io/PythonDataScienceHandbook/ 05.09-principal-component-analysis.html

pyrolite.util.plot.helpers.plot_stdev_ellipses(comp, nstds=4, scale=100, resolution=1000, transform=None, ax=None, **kwargs)[source]

Plot covariance ellipses at a number of standard deviations from the mean.

Parameters:

comp (numpy.ndarray) – Composition to use.
nstds (int) – Number of standard deviations from the mean for which to plot the ellipses.
scale (float) – Scale applying to all x-y data points. For intergration with python-ternary.
transform (callable) – Function for transformation of data prior to plotting (to either 2D or 3D).
ax (matplotlib.axes.Axes) – Axes to plot on.

Returns:

ax

Return type:

matplotlib.axes.Axes

pyrolite.util.plot.helpers.plot_pca_vectors(comp, nstds=2, scale=100.0, transform=None, ax=None, colors=None, linestyles=None, **kwargs)[source]

Plot vectors corresponding to principal components and their magnitudes.

Parameters:

comp (numpy.ndarray) – Composition to use.
nstds (int) – Multiplier for magnitude of individual principal component vectors.
scale (float) – Scale applying to all x-y data points. For intergration with python-ternary.
transform (callable) – Function for transformation of data prior to plotting (to either 2D or 3D).
ax (matplotlib.axes.Axes) – Axes to plot on.

Returns:

ax

Return type:

matplotlib.axes.Axes

Todo

Minor reimplementation of the sklearn PCA to avoid dependency.

https://en.wikipedia.org/wiki/Principal_component_analysis

pyrolite.util.plot.helpers.plot_2dhull(data, ax=None, splines=False, s=0, **plotkwargs)[source]: Plots a 2D convex hull around an array of xy data points.

pyrolite.util.plot.helpers.plot_cooccurence(arr, ax=None, normalize=True, log=False, colorbar=False, **kwargs)[source]

Plot the co-occurence frequency matrix for a given input.

Parameters:

ax (matplotlib.axes.Axes, None) – The subplot to draw on.
normalize (bool) – Whether to normalize the cooccurence to compare disparate variables.
log (bool) – Whether to take the log of the cooccurence.
colorbar (bool) – Whether to append a colorbar.

Returns:

Axes on which the cooccurence plot is added.

Return type:

matplotlib.axes.Axes

pyrolite.util.plot.helpers.nan_scatter(xdata, ydata, ax=None, axes_width=0.2, **kwargs)[source]

Scatter plot with additional marginal axes to plot data for which data is partially missing. Additional keyword arguments are passed to matplotlib.

Parameters:

xdata (numpy.ndarray) – X data
ydata (class:numpy.ndarray | pd.Series) – Y data
ax (matplotlib.axes.Axes) – Axes on which to plot.
axes_width (float) – Width of the marginal axes.

Returns:

Axes on which the nan_scatter is plotted.

Return type:

matplotlib.axes.Axes

pyrolite.util.plot.helpers.init_spherical_octant(angle_indicated=30, labels=None, view_init=(25, 55), fontsize=10, **kwargs)[source]

Initalize a figure with a 3D octant of a unit sphere, appropriately labeled with regard to angles corresponding to the handling of the respective compositional data transformation function (sphere()).

Parameters:

angle_indicated (float) – Angle relative to axes for indicating the relative positioning, optional.
labels (list) – Optional specification of data/axes labels. This will be used for labelling of both the axes and optionally-added arcs specifying which angles are represented.

Returns:

ax – Initialized 3D axis.

Return type:

matplotlib.axes.Axes3D

pyrolite.util.plot.interpolation

Line interpolation for matplotlib lines and paths.

pyrolite.util.plot.interpolation.interpolate_path(path, resolution=100, periodic=False, aspath=True, closefirst=False, **kwargs)[source]

Obtain the interpolation of an existing path at a given resolution. Keyword arguments are forwarded to scipy.interpolate.splprep().

Parameters:

path (matplotlib.path.Path) – Path to interpolate.
resolution :class:`int` – Resolution at which to obtain the new path. The verticies of the new path will have shape (resolution, 2).
periodic (bool) – Whether to use a periodic spline.
periodic (bool) – Whether to return a matplotlib.path.Path, or simply a tuple of x-y arrays.
closefirst (bool) – Whether to first close the path by appending the first point again.

Returns:

Interpolated Path object, if aspath is True, else a tuple of x-y arrays.

Return type:

matplotlib.path.Path | tuple

pyrolite.util.plot.interpolation.interpolated_patch_path(patch, resolution=100, **kwargs)[source]

Obtain the periodic interpolation of the existing path of a patch at a given resolution.

Parameters:

patch (matplotlib.patches.Patch) – Patch to obtain the original path from.
resolution :class:`int` – Resolution at which to obtain the new path. The verticies of the new path will have shape (resolution, 2).

Returns:

Interpolated Path object.

Return type:

matplotlib.path.Path

pyrolite.util.plot.interpolation.get_contour_paths(src, resolution=100, minsize=3, filter=True)[source]

Extract the paths of contours from a contour plot.

Parameters:

ax (matplotlib.axes.Axes | matplotlib.contour.QuadContourSet) – Axes to extract contours from.
resolution (int) – Resolution of interpolated splines to return.
filter (bool) – Whether to filter out paths which have no length.

Returns:

contourspaths (list (list)) – List of lists, each represnting one line collection (a single contour). In the case where this contour is multimodal, there will be multiple paths for each contour.
contournames (list) – List of names for contours, where they have been labelled, and there are no other text artists on the figure.
contourstyles (list) – List of styles for contours.

pyrolite.util.plot.legend

Functions for creating and modifying legend entries for matplotlib.

Todo

Functions for working with and modifying legend entries.

ax.lines + ax.patches + ax.collections + ax.containers, handle ax.parasites

pyrolite.util.plot.legend.proxy_rect(**kwargs)[source]

Generates a legend proxy for a filled region.

Return type:: matplotlib.patches.Rectangle

pyrolite.util.plot.legend.proxy_line(**kwargs)[source]

Generates a legend proxy for a line region.

Return type:: matplotlib.lines.Line2D

pyrolite.util.plot.legend.modify_legend_handles(ax, **kwargs)[source]

Modify the handles of a legend based for a single axis.

Parameters:

ax (matplotlib.axes.Axes) – Axis for which to obtain modifed legend handles.

Returns:

handles (list) – Handles to be passed to a legend call.
labels (list) – Labels to be passed to a legend call.

pyrolite.util.plot.style

Functions for automated plot styling and argument handling.

ivar DEFAULT_CONT_COLORMAP:: Default continuous colormap.
vartype DEFAULT_CONT_COLORMAP:: matplotlib.colors.ScalarMappable
ivar DEFAULT_DISC_COLORMAP:: Default discrete colormap.
vartype DEFAULT_DISC_COLORMAP:: matplotlib.colors.ScalarMappable

pyrolite.util.plot.style.linekwargs(kwargs)[source]

Get a subset of keyword arguments to pass to a matplotlib line-plot call.

Parameters:: kwargs (dict) – Dictionary of keyword arguments to subset.
Return type:: dict

pyrolite.util.plot.style.scatterkwargs(kwargs)[source]

Get a subset of keyword arguments to pass to a matplotlib scatter call.

Parameters:: kwargs (dict) – Dictionary of keyword arguments to subset.
Return type:: dict

pyrolite.util.plot.style.patchkwargs(kwargs)[source]

pyrolite.util.plot.style.marker_cycle(markers=['D', 's', 'o', '+', '*'])[source]

Cycle through a set of markers.

Parameters:: markers (list) – List of markers to provide to matplotlib.

pyrolite.util.plot.style.mappable_from_values(values, cmap=<matplotlib.colors.ListedColormap object>, norm=None, **kwargs)[source]

Create a scalar mappable object from an array of values.

Return type:: matplotlib.cm.ScalarMappable

pyrolite.util.plot.style.ternary_color(tlr, alpha=1.0, colors=([1, 0, 0], [0, 1, 0], [0, 0, 1]), coefficients=(1, 1, 1))[source]

Color a set of points by their ternary combinations of three specified colors.

Parameters:

tlr (numpy.ndarray)
alpha (float) – Alpha coefficient for the colors; to be applied multiplicatively with any existing alpha value (for RGBA colors specified).
colors (tuple) – Set of colours corresponding to the top, left and right verticies, respectively.
coefficients (tuple) – Coefficients for the ternary data to adjust the centre.

Returns:

Color array for the ternary points.

Return type:

numpy.ndarray

pyrolite.util.plot.style.color_ternary_polygons_by_centroid(ax=None, patches=None, alpha=1.0, colors=([1, 0, 0], [0, 1, 0], [0, 0, 1]), coefficients=(1, 1, 1))[source]

Color a set of polygons within a ternary diagram by their centroid colors.

Parameters:

ax (matplotlib.axes.Axes) – Ternary axes to check for patches, if patches is not supplied.
patches (list) – List of ternary-hosted patches to apply color to.
alpha (float) – Alpha coefficient for the colors; to be applied multiplicatively with any existing alpha value (for RGBA colors specified).
colors (tuple) – Set of colours corresponding to the top, left and right verticies, respectively.
coefficients (tuple) – Coefficients for the ternary data to adjust the centre.

Returns:

patches – List of patches, with updated facecolors.

Return type:

list

pyrolite.util.plot.transform

Transformation utilites for matplotlib.

pyrolite.util.plot.transform.affine_transform(mtx=array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]))[source]

Construct a function which will perform a 2D affine transform based on a 3x3 affine matrix.

Parameters:: mtx (numpy.ndarray)

pyrolite.util.plot.transform.tlr_to_xy(tlr)[source]

Transform a ternary coordinate system (top-left-right) to an xy-cartesian coordinate system.

Parameters:: tlr (numpy.ndarray) – Array of shape (n, 3) in the t-l-r coordinate system.
Returns:: xy – Array of shape (n, 2) in the x-y coordinate system.
Return type:: numpy.ndarray

pyrolite.util.plot.transform.xy_to_tlr(xy)[source]

Parameters:: xy (numpy.ndarray) – Array of shape (n, 2) in the x-y coordinate system.
Returns:: tlr – Array of shape (n, 3) in the t-l-r coordinate system.
Return type:: numpy.ndarray

pyrolite.util.plot.transform.ABC_to_xy(ABC, xscale=1.0, yscale=1.0)[source]

Convert ternary compositional coordiantes to x-y coordinates for visualisation within a triangle.

Parameters:

ABC (numpy.ndarray) – Ternary array (samples, 3).
xscale (float) – Scale for x-axis.
yscale (float) – Scale for y-axis.

Returns:

Array of x-y coordinates (samples, 2)

Return type:

numpy.ndarray

pyrolite.util.plot.transform.xy_to_ABC(xy, xscale=1.0, yscale=1.0)[source]

Convert x-y coordinates within a triangle to compositional ternary coordinates.

Parameters:

xy (numpy.ndarray) – XY array (samples, 2).
xscale (float) – Scale for x-axis.
yscale (float) – Scale for y-axis.

Returns:

Array of ternary coordinates (samples, 3)

Return type:

numpy.ndarray