WrightTools.artists module

Artists.

class WrightTools.artists.Axes(fig, rect, facecolor=None, frameon=True, sharex=None, sharey=None, label='', xscale=None, yscale=None, **kwargs)[source]

Bases: matplotlib.axes._axes.Axes

Axes.

add_sideplot(along, pad=0, height=0.75, ymin=0, ymax=1.1)[source]

Add a side axis.

Parameters:
  • along ({'x', 'y'}) – Axis to add along.
  • pad (float (optional)) – Side axis pad. Default is 0.
  • height (float (optional)) – Side axis height. Default is 0.
contour(*args, **kwargs)[source]

Plot contours.

Parameters:
  • data (2D WrightTools.data.Data object) – Data to plot.
  • channel (int or string (optional)) – Channel index or name. Default is 0.
  • dynamic_range (boolean (optional)) – Force plotting of all contours, overloading for major extent. Only applies to signed data. Default is False.
  • autolabel ({'none', 'both', 'x', 'y'} (optional)) – Parameterize application of labels directly from data object. Default is none.
  • xlabel (string (optional)) – xlabel. Default is None.
  • ylabel (string (optional)) – ylabel. Default is None.
  • **kwargs

    matplotlib.axes.Axes.contour optional keyword arguments.

Returns:

Return type:

matplotlib.contour.QuadContourSet

contourf(*args, **kwargs)[source]

Plot contours.

Parameters:
  • data (2D WrightTools.data.Data object) – Data to plot.
  • channel (int or string (optional)) – Channel index or name. Default is 0.
  • dynamic_range (boolean (optional)) – Force plotting of all contours, overloading for major extent. Only applies to signed data. Default is False.
  • autolabel ({'none', 'both', 'x', 'y'} (optional)) – Parameterize application of labels directly from data object. Default is none.
  • xlabel (string (optional)) – xlabel. Default is None.
  • ylabel (string (optional)) – ylabel. Default is None.
  • **kwargs

    matplotlib.axes.Axes.contourf optional keyword arguments.

Returns:

Return type:

matplotlib.contour.QuadContourSet

is_sideplot = False
legend(*args, **kwargs)[source]

Add a legend.

Parameters:
  • *args – matplotlib legend args.
  • *kwargs – matplotlib legend kwargs.
Returns:

Return type:

legend

pcolor(*args, **kwargs)[source]

Create a pseudocolor plot of a 2-D array.

Uses pcolor_helper to ensure that color boundaries are drawn bisecting point positions, when possible.

Parameters:
  • data (2D WrightTools.data.Data object) – Data to plot.
  • channel (int or string (optional)) – Channel index or name. Default is 0.
  • dynamic_range (boolean (optional)) – Force plotting of all contours, overloading for major extent. Only applies to signed data. Default is False.
  • autolabel ({'none', 'both', 'x', 'y'} (optional)) – Parameterize application of labels directly from data object. Default is none.
  • xlabel (string (optional)) – xlabel. Default is None.
  • ylabel (string (optional)) – ylabel. Default is None.
  • **kwargs

    matplotlib.axes.Axes.pcolor optional keyword arguments.

Returns:

Return type:

matplotlib.collections.PolyCollection

pcolormesh(*args, **kwargs)[source]

Create a pseudocolor plot of a 2-D array.

Uses pcolor_helper to ensure that color boundaries are drawn bisecting point positions, when possible. Quicker than pcolor

Parameters:
  • data (2D WrightTools.data.Data object) – Data to plot.
  • channel (int or string (optional)) – Channel index or name. Default is 0.
  • dynamic_range (boolean (optional)) – Force plotting of all contours, overloading for major extent. Only applies to signed data. Default is False.
  • autolabel ({'none', 'both', 'x', 'y'} (optional)) – Parameterize application of labels directly from data object. Default is none.
  • xlabel (string (optional)) – xlabel. Default is None.
  • ylabel (string (optional)) – ylabel. Default is None.
  • **kwargs

    matplotlib.axes.Axes.pcolormesh optional keyword arguments.

Returns:

Return type:

matplotlib.collections.QuadMesh

plot(*args, **kwargs)[source]

Plot lines and/or markers.

Parameters:
  • data (1D WrightTools.data.Data object) – Data to plot.
  • channel (int or string (optional)) – Channel index or name. Default is 0.
  • dynamic_range (boolean (optional)) – Force plotting of all contours, overloading for major extent. Only applies to signed data. Default is False.
  • autolabel ({'none', 'both', 'x', 'y'} (optional)) – Parameterize application of labels directly from data object. Default is none.
  • xlabel (string (optional)) – xlabel. Default is None.
  • ylabel (string (optional)) – ylabel. Default is None.
  • **kwargs

    matplotlib.axes.Axes.plot optional keyword arguments.

Returns:

list of matplotlib.lines.line2D objects

Return type:

list

transposed = False
class WrightTools.artists.Figure(figsize=None, dpi=None, facecolor=None, edgecolor=None, linewidth=0.0, frameon=None, subplotpars=None, tight_layout=None, constrained_layout=None)[source]

Bases: matplotlib.figure.Figure

Figure.

add_subplot(*args, **kwargs)[source]

Add a subplot to the figure.

Parameters:
  • *args
  • **kwargs
Returns:

Return type:

WrightTools.artists.Axes object

class WrightTools.artists.GridSpec(nrows, ncols, figure=None, left=None, bottom=None, right=None, top=None, wspace=None, hspace=None, width_ratios=None, height_ratios=None)[source]

Bases: matplotlib.gridspec.GridSpec

GridSpec.

WrightTools.artists.add_sideplot(ax, along, pad=0.0, *, grid=True, zero_line=True, arrs_to_bin=None, normalize_bin=True, ymin=0, ymax=1.1, height=0.75, c='C0')[source]

Add a sideplot to an axis. Sideplots share their corresponding axis.

Parameters:
  • ax (matplotlib AxesSubplot object) – The axis to add a sideplot along.
  • along ({'x', 'y'}) – The dimension to add a sideplot along.
  • pad (number (optional)) – Distance between axis and sideplot. Default is 0.
  • grid (bool (optional)) – Toggle for plotting grid on sideplot. Default is True.
  • zero_line (bool (optional)) – Toggle for plotting black line at zero signal. Default is True.
  • arrs_to_bin (list [xi, yi, zi] (optional)) – Bins are plotted if arrays are supplied. Default is None.
  • normalize_bin (bool (optional)) – Normalize bin by max value. Default is True.
  • ymin (number (optional)) – Bin minimum extent. Default is 0.
  • ymax (number (optional)) – Bin maximum extent. Default is 1.1
  • c (string (optional)) – Line color. Default is C0.
Returns:

AxesSubplot object

Return type:

axCorr

WrightTools.artists.apply_rcparams(kind='fast')[source]

Quickly apply rcparams for given purposes.

Parameters:kind ({'default', 'fast', 'publication'} (optional)) – Settings to use. Default is ‘fast’.
WrightTools.artists.corner_text(text, distance=0.075, *, ax=None, corner='UL', factor=200, bbox=True, fontsize=18, background_alpha=1, edgecolor=None)[source]

Place some text in the corner of the figure.

Parameters:
  • text (str) – The text to use.
  • distance (number (optional)) – Distance from the corner. Default is 0.05.
  • ax (axis (optional)) – The axis object to label. If None, uses current axis. Default is None.
  • corner ({'UL', 'LL', 'UR', 'LR'} (optional)) – The corner to label. Upper left, Lower left etc. Default is UL.
  • factor (number (optional)) – Scaling factor. Default is 200.
  • bbox (boolean (optional)) – Toggle bounding box. Default is True.
  • fontsize (number (optional)) – Text fontsize. If None, uses the matplotlib default. Default is 18.
  • background_alpha (number (optional)) – Opacity of background bounding box. Default is 1.
  • edgecolor (string (optional)) – Frame edgecolor. Default is None (inherits from legend.edgecolor rcparam).
Returns:

The matplotlib text object.

Return type:

text

WrightTools.artists.create_figure(*, width='single', nrows=1, cols=[1], margin=1.0, hspace=0.25, wspace=0.25, cbar_width=0.25, aspects=[], default_aspect=1)[source]

Re-parameterization of matplotlib figure creation tools, exposing convenient variables.

Figures are defined primarily by their width. Height is defined by the aspect ratios of the subplots contained within. hspace, wspace, and cbar_width are defined in inches, making it easier to make consistent plots. Margins are enforced to be equal around the entire plot, starting from the edges of the subplots.

Parameters:
  • width ({'single', 'double', 'dissertation'} or float (optional)) – The total width of the generated figure. Can be given in inches directly, or can be specified using keys. Default is ‘single’ (6.5 inches).
  • nrows (int (optional)) – The number of subplot rows in the figure. Default is 1.
  • cols (list (optional)) – A list of numbers, defining the number and width-ratios of the figure columns. May also contain the special string ‘cbar’, defining a column as a colorbar-containing column. Default is [1].
  • margin (float (optional)) – Margin in inches. Margin is applied evenly around the figure, starting from the subplot boundaries (so that ticks and labels appear in the margin). Default is 1.
  • hspace (float (optional)) – The ‘height space’ (space seperating two subplots vertically), in inches. Default is 0.25.
  • wspace (float (optional)) – The ‘width space’ (space seperating two subplots horizontally), in inches. Default is 0.25.
  • cbar_width (float (optional)) – The width of the colorbar in inches. Default is 0.25.
  • aspects (list of lists (optional)) – Define the aspect ratio of individual subplots. List of lists, each sub-ist having the format [[row, col], aspect]. The figure will expand vertically to acomidate the defined aspect ratio. Aspects are V/H so aspects larger than 1 will be taller than wide and vice-versa for aspects smaller than 1. You may only define the aspect for one subplot in each row. If no aspect is defined for a particular row, the leftmost subplot will have an aspect of default_aspect. Default is [].
Returns:

(matplotlib.figure.Figure, matplotlib.gridspec.GridSpec). GridSpec contains SubplotSpec objects that can have axes placed into them. The SubplotSpec objects can be accessed through indexing: [row, col]. Slicing works, for example cax = plt.subplot(gs[:, -1]). See matplotlib gridspec documentation for more information.

Return type:

tuple

Notes

To ensure the margins work as expected, save the fig with the same margins (pad_inches) as specified in this function. Common savefig call: plt.savefig(plt.savefig(output_path, dpi=300, transparent=True, pad_inches=1))

See also

wt.artists.plot_margins()
Plot lines to visualize the figure edges, margins, and centers. For debug and design purposes.
wt.artists.subplots_adjust()
Enforce margins for figure generated elsewhere.
WrightTools.artists.diagonal_line(xi=None, yi=None, *, ax=None, c=None, ls=None, lw=None, zorder=3)[source]

Plot a diagonal line.

Parameters:
  • xi (1D array-like (optional)) – The x axis points. If None, taken from axis limits. Default is None.
  • yi (1D array-like) – The y axis points. If None, taken from axis limits. Default is None.
  • ax (axis (optional)) – Axis to plot on. If none is supplied, the current axis is used.
  • c (string (optional)) – Line color. Default derives from rcParams grid color.
  • ls (string (optional)) – Line style. Default derives from rcParams linestyle.
  • lw (float (optional)) – Line width. Default derives from rcParams linewidth.
  • zorder (number (optional)) – Matplotlib zorder. Default is 3.
Returns:

The plotted line.

Return type:

matplotlib.lines.Line2D object

WrightTools.artists.get_color_cycle(n, cmap='rainbow', rotations=3)[source]

Get a list of RGBA colors following a colormap.

Useful for plotting lots of elements, keeping the color of each unique.

Parameters:
  • n (integer) – The number of colors to return.
  • cmap (string (optional)) – The colormap to use in the cycle. Default is rainbow.
  • rotations (integer (optional)) – The number of times to repeat the colormap over the cycle. Default is 3.
Returns:

List of RGBA lists.

Return type:

list

WrightTools.artists.get_scaled_bounds(ax, position, *, distance=0.1, factor=200)[source]

Get scaled bounds.

Parameters:
  • ax (Axes object) – Axes object.
  • position ({'UL', 'LL', 'UR', 'LR'}) – Position.
  • distance (number (optional)) – Distance. Default is 0.1.
  • factor (number (optional)) – Factor. Default is 200.
Returns:

Return type:

([h_scaled, v_scaled], [va, ha])

WrightTools.artists.grayify_cmap(cmap)[source]

Return a grayscale version of the colormap.

Source

WrightTools.artists.interact2D(data, xaxis=0, yaxis=1, channel=0, local=False, verbose=True)[source]

Interactive 2D plot of the dataset. Side plots show x and y projections of the slice (shaded gray). Left clicks on the main axes draw 1D slices on side plots at the coordinates selected. Right clicks remove the 1D slices. For 3+ dimensional data, sliders below the main axes are used to change which slice is viewed.

Parameters:
  • data (WrightTools.Data object) – Data to plot.
  • xaxis (string, integer, or data.Axis object (optional)) – Expression or index of x axis. Default is 0.
  • yaxis (string, integer, or data.Axis object (optional)) – Expression or index of y axis. Default is 1.
  • channel (string, integer, or data.Channel object (optional)) – Name or index of channel to plot. Default is 0.
  • local (boolean (optional)) – Toggle plotting locally. Default is False.
  • verbose (boolean (optional)) – Toggle talkback. Default is True.
WrightTools.artists.pcolor_helper(xi, yi, zi=None)[source]

Prepare a set of arrays for plotting using pcolor.

The return values are suitable for feeding directly into matplotlib.pcolor such that the pixels are properly centered.

Parameters:
  • xi (1D or 2D array-like) – Array of X-coordinates.
  • yi (1D or 2D array-like) – Array of Y-coordinates.
  • zi (2D array (optional, deprecated)) – If zi is not None, it is returned unchanged in the output.
Returns:

  • X (2D ndarray) – X dimension for pcolor
  • Y (2D ndarray) – Y dimension for pcolor
  • zi (2D ndarray) – if zi parameter is not None, returns zi parameter unchanged

WrightTools.artists.plot_colorbar(cax=None, cmap='default', ticks=None, clim=None, vlim=None, label=None, tick_fontsize=14, label_fontsize=18, decimals=None, orientation='vertical', ticklocation='auto', extend='neither', extendfrac=None, extendrect=False)[source]

Easily add a colormap to an axis.

Parameters:
  • cax (matplotlib axis (optional)) – The axis to plot the colorbar on. Finds the current axis if none is given.
  • cmap (string or LinearSegmentedColormap (optional)) – The colormap to fill the colorbar with. Strings map as keys to the WrightTools colormaps dictionary. Default is default.
  • ticks (1D array-like (optional)) – Ticks. Default is None.
  • clim (two element list (optional)) – The true limits of the colorbar, in the same units as ticks. If None, streaches the colorbar over the limits of ticks. Default is None.
  • vlim (two element list-like (optional)) – The limits of the displayed colorbar, in the same units as ticks. If None, displays over clim. Default is None.
  • label (str (optional)) – Label. Default is None.
  • tick_fontsize (number (optional)) – Fontsize. Default is 14.
  • label_fontsize (number (optional)) – Label fontsize. Default is 18.
  • decimals (integer (optional)) – Number of decimals to appear in tick labels. Default is None (best guess).
  • orientation ({'vertical', 'horizontal'} (optional)) – Colorbar orientation. Default is vertical.
  • ticklocation ({'auto', 'left', 'right', 'top', 'bottom'} (optional)) – Tick location. Default is auto.
  • extend ({‘neither’, ‘both’, ‘min’, ‘max’} (optional)) – If not ‘neither’, make pointed end(s) for out-of- range values. These are set for a given colormap using the colormap set_under and set_over methods.
  • extendfrac ({None, ‘auto’, length, lengths} (optional)) – If set to None, both the minimum and maximum triangular colorbar extensions have a length of 5% of the interior colorbar length (this is the default setting). If set to ‘auto’, makes the triangular colorbar extensions the same lengths as the interior boxes (when spacing is set to ‘uniform’) or the same lengths as the respective adjacent interior boxes (when spacing is set to ‘proportional’). If a scalar, indicates the length of both the minimum and maximum triangular colorbar extensions as a fraction of the interior colorbar length. A two-element sequence of fractions may also be given, indicating the lengths of the minimum and maximum colorbar extensions respectively as a fraction of the interior colorbar length.
  • extendrect (bool (optional)) – If False the minimum and maximum colorbar extensions will be triangular (the default). If True the extensions will be rectangular.
Returns:

The created colorbar.

Return type:

matplotlib.colorbar.ColorbarBase object

WrightTools.artists.plot_colormap_components(cmap)[source]

Plot the components of a given colormap.

WrightTools.artists.plot_gridlines(ax=None, c='grey', lw=1, diagonal=False, zorder=2, makegrid=True)[source]

Plot dotted gridlines onto an axis.

Parameters:
  • ax (matplotlib AxesSubplot object (optional)) – Axis to add gridlines to. If None, uses current axis. Default is None.
  • c (matplotlib color argument (optional)) – Gridline color. Default is grey.
  • lw (number (optional)) – Gridline linewidth. Default is 1.
  • diagonal (boolean (optional)) – Toggle inclusion of diagonal gridline. Default is False.
  • zorder (number (optional)) – zorder of plotted grid. Default is 2.
WrightTools.artists.plot_margins(*, fig=None, inches=1.0, centers=True, edges=True)[source]

Add lines onto a figure indicating the margins, centers, and edges.

Useful for ensuring your figure design scripts work as intended, and for laying out figures.

Parameters:
  • fig (matplotlib.figure.Figure object (optional)) – The figure to plot onto. If None, gets current figure. Default is None.
  • inches (float (optional)) – The size of the figure margin, in inches. Default is 1.
  • centers (bool (optional)) – Toggle for plotting lines indicating the figure center. Default is True.
  • edges (bool (optional)) – Toggle for plotting lines indicating the figure edges. Default is True.
WrightTools.artists.quick1D(data, axis=0, at={}, channel=0, *, local=False, autosave=False, save_directory=None, fname=None, verbose=True)[source]

Quickly plot 1D slice(s) of data.

Parameters:
  • data (WrightTools.Data object) – Data to plot.
  • axis (string or integer (optional)) – Expression or index of axis. Default is 0.
  • at (dictionary (optional)) – Dictionary of parameters in non-plotted dimension(s). If not provided, plots will be made at each coordinate.
  • channel (string or integer (optional)) – Name or index of channel to plot. Default is 0.
  • local (boolean (optional)) – Toggle plotting locally. Default is False.
  • autosave (boolean (optional)) – Toggle autosave. Default is False.
  • save_directory (string (optional)) – Location to save image(s). Default is None (auto-generated).
  • fname (string (optional)) – File name. If None, data name is used. Default is None.
  • verbose (boolean (optional)) – Toggle talkback. Default is True.
Returns:

List of saved image files (if any).

Return type:

list of strings

WrightTools.artists.quick2D(data, xaxis=0, yaxis=1, at={}, channel=0, *, contours=0, pixelated=True, dynamic_range=False, local=False, contours_local=True, autosave=False, save_directory=None, fname=None, verbose=True)[source]

Quickly plot 2D slice(s) of data.

Parameters:
  • data (WrightTools.Data object.) – Data to plot.
  • xaxis (string or integer (optional)) – Expression or index of horizontal axis. Default is 0.
  • yaxis (string or integer (optional)) – Expression or index of vertical axis. Default is 1.
  • at (dictionary (optional)) – Dictionary of parameters in non-plotted dimension(s). If not provided, plots will be made at each coordinate.
  • channel (string or integer (optional)) – Name or index of channel to plot. Default is 0.
  • contours (integer (optional)) – The number of black contour lines to add to the plot. Default is 0.
  • pixelated (boolean (optional)) – Toggle between pcolor and contourf (deulaney) plotting backends. Default is True (pcolor).
  • dynamic_range (boolean (optional)) – Force the colorbar to use all of its colors. Only changes behavior for signed channels. Default is False.
  • local (boolean (optional)) – Toggle plotting locally. Default is False.
  • contours_local (boolean (optional)) – Toggle plotting black contour lines locally. Default is True.
  • autosave (boolean (optional)) – Toggle autosave. Default is False.
  • save_directory (string (optional)) – Location to save image(s). Default is None (auto-generated).
  • fname (string (optional)) – File name. If None, data name is used. Default is None.
  • verbose (boolean (optional)) – Toggle talkback. Default is True.
Returns:

List of saved image files (if any).

Return type:

list of strings

WrightTools.artists.savefig(path, fig=None, close=True, *, dpi=300)[source]

Save a figure.

Parameters:
  • path (str) – Path to save figure at.
  • fig (matplotlib.figure.Figure object (optional)) – The figure to plot onto. If None, gets current figure. Default is None.
  • close (bool (optional)) – Toggle closing of figure after saving. Default is True.
Returns:

The full path where the figure was saved.

Return type:

str

WrightTools.artists.set_ax_labels(ax=None, xlabel=None, ylabel=None, xticks=None, yticks=None, label_fontsize=18)[source]

Set all axis labels properties easily.

Parameters:
  • ax (matplotlib AxesSubplot object (optional)) – Axis to set. If None, uses current axis. Default is None.
  • xlabel (None or string (optional)) – x axis label. Default is None.
  • ylabel (None or string (optional)) – y axis label. Default is None.
  • xticks (None or False or list of numbers) – xticks. If False, ticks are hidden. Default is None.
  • yticks (None or False or list of numbers) – yticks. If False, ticks are hidden. Default is None.
  • label_fontsize (number) – Fontsize of label. Default is 18.

See also

set_fig_labels()

WrightTools.artists.set_ax_spines(ax=None, *, c='k', lw=3, zorder=10)[source]

Easily set the properties of all four axis spines.

Parameters:
  • ax (matplotlib AxesSubplot object (optional)) – Axis to set. If None, uses current axis. Default is None.
  • c (any matplotlib color argument (optional)) – Spine color. Default is k.
  • lw (number (optional)) – Spine linewidth. Default is 3.
  • zorder (number (optional)) – Spine zorder. Default is 10.
WrightTools.artists.set_fig_labels(fig=None, xlabel=None, ylabel=None, xticks=None, yticks=None, title=None, label_fontsize=18, title_fontsize=20)[source]

Set all axis labels of a figure simultaniously.

Only plots ticks and labels for edge axes.

Parameters:
  • fig (matplotlib.figure.Figure object (optional)) – Figure to set labels of. If None, uses current figure. Default is None.
  • xlabel (None or string (optional)) – x axis label. Default is None.
  • ylabel (None or string (optional)) – y axis label. Default is None.
  • xticks (None or False or list of numbers (optional)) – xticks. If False, ticks are hidden. Default is None.
  • yticks (None or False or list of numbers (optional)) – yticks. If False, ticks are hidden. Default is None.
  • title (None or string (optional)) – Title of figure. Default is None.
  • label_fontsize (number) – Fontsize of label. Default is 18.
  • title_fontsize (number) – Fontsize of title. Default is 20.

See also

set_ax_labels()

WrightTools.artists.stitch_to_animation(images, outpath=None, *, duration=0.5, palettesize=256, verbose=True)[source]

Stitch a series of images into an animation.

Currently supports animated gifs, other formats coming as needed.

Parameters:
  • images (list of strings) – Filepaths to the images to stitch together, in order of apperence.
  • outpath (string (optional)) – Path of output, including extension. If None, bases output path on path of first path in images. Default is None.
  • duration (number or list of numbers (optional)) – Duration of (each) frame in seconds. Default is 0.5.
  • palettesize (int (optional)) – The number of colors in the resulting animation. Input is rounded to the nearest power of 2. Default is 1024.
  • verbose (bool (optional)) – Toggle talkback. Default is True.
WrightTools.artists.subplots_adjust(fig=None, inches=1)[source]

Enforce margin to be equal around figure, starting at subplots.

Note

You probably should be using wt.artists.create_figure instead.

See also

wt.artists.plot_margins()
Visualize margins, for debugging / layout.
wt.artists.create_figure()
Convinience method for creating well-behaved figures.