ampworks.plotutils#

A module designed to enhance plotting with the matplotlib library. Functions and classes include routines to simplify color scheme management, formatting axis ticks, fonts, and more, making it easier to create polished and consistent visualizations.

Classes#

ColorMap

Map values to RGBA colors.

Functions#

add_text(ax, xloc, yloc, text[, ha, va])

Add text to ax at a given location.

colors_from_data(data[, cmap])

Map an array of values to colors using a normalized colormap.

colors_from_size(size[, cmap])

Generate a list of evenly spaced colors from a colormap.

focused_limits(y[, factor, margin])

Compute limits by ignoring outliers.

format_ticks(ax[, xdiv, ydiv, xdir, ydir, top, right])

Formats axis ticks.

minor_ticks(ax[, xdiv, ydiv])

Adds minor ticks.

tick_direction(ax[, xdir, ydir, top, right])

Controls tick directions.

Package Contents#

class ampworks.plotutils.ColorMap(cmap='jet', norm=(0, 1))[source]#

Map values to RGBA colors.

A wrapper around matplotlib’s colormaps to provide convenient access to generate normalized color sequences.

Parameters:

  • cmap (str, optional) – Name of the matplotlib colormap, by default ‘jet’.

  • norm (tuple[float], optional) – 2-tuple of (min, max) values used for normalization.

Raises:

  • ValueError – ‘norm’ must be length 2.

  • ValueError – ‘norm[0]’ must be strictly less than ‘norm[1]’.

get_color(scalar)[source]#

Map a scalar value to an RGBA color tuple.

Parameters:

scalar (float) – Value to map. Must lie within the normalization range.

Returns:

color (tuple[float]) – The corresponding RGBA color.

Raises:

ValueError – ‘scalar’ is not in bounds set by ‘norm’.

ampworks.plotutils.add_text(ax, xloc, yloc, text, ha='left', va='center')[source]#

Add text to ax at a given location.

Parameters:

  • ax (Axes) – An axis instance from a matplotlib figure.

  • xloc (float) – Relative location (0-1) for text in x-direction.

  • yloc (float) – Relative location (0-1) for text in y-direction.

  • text (str) – Text string to add to figure.

  • ha (str, optional) – Horizontal alignment relative to (xloc, yloc). Must be in {‘left’, ‘center’, ‘right’}. By default ‘left’.

  • va (str, optional) – Vertical alignment relative to (xloc, yloc). Must be in {‘baseline’, ‘bottom’, ‘center’, ‘center_baseline’, ‘top’}. By default ‘center’.

ampworks.plotutils.colors_from_data(data, cmap='jet')[source]#

Map an array of values to colors using a normalized colormap.

Parameters:

  • data (ndarray) – Input numeric array.

  • cmap (str, optional) – Name of the matplotlib colormap, by default ‘jet’.

Returns:

colors (ndarray) – Array of RGBA color tuples with the same shape as ‘data’.

ampworks.plotutils.colors_from_size(size, cmap='jet')[source]#

Generate a list of evenly spaced colors from a colormap.

Parameters:

  • size (int) – Number of colors to generate.

  • cmap (str, optional) – Name of the matplotlib colormap, by default ‘jet’.

Returns:

colors (list) – List of RGBA color tuples.

ampworks.plotutils.focused_limits(y, factor=2.5, margin=0.05)[source]#

Compute limits by ignoring outliers.

This function determines the interquartile range (IQR) of data and uses that to determine outliers. Suggested limits are then provided based on data that falls within some factor of the IQR. While the first input is named ‘y’, this function is equally valid for suggesting ‘x’ limits.

Parameters:

  • y (ArrayLike) – Input data values.

  • factor (float, optional) – Multiplier for the IQR. Defaults to 2.5. Any values outside the range [Q1 - factor*IQR, Q3 + factor*IQR] are considered outliers.

  • margin (float, optional) – Fractional padding to add to the final limits, relative to the data range after clipping. Default is 0.05 (5%).

Returns:

ymin, ymax (float) – Suggested axis limits for plotting.

ampworks.plotutils.format_ticks(ax, xdiv=None, ydiv=None, xdir='in', ydir='in', top=True, right=True)[source]#

Formats axis ticks.

Specifically, applies both minor_ticks() and tick_direction() from one convenient function, instead of calling them separately.

Parameters:

  • ax (Axes) – An axis instance from a matplotlib figure.

  • xdiv (int, optional) – Divisions between x major ticks. Defaults to None (auto locate).

  • ydiv (int, optional) – Divisions between y major ticks. Defaults to None (auto locate).

  • xdir ({'in', 'out', 'inout'}, optional) – Places x ticks inward, outward, or both. By default ‘in’.

  • ydir ({'in', 'out', 'inout'}, optional) – Places y ticks inward, outward, or both. By default ‘in’.

  • top (bool, optional) – Mirror the x ticks along the top of Axis, by default True.

  • right (bool, optional) – Mirror the y ticks along the top of Axis, by default True.

ampworks.plotutils.minor_ticks(ax, xdiv=None, ydiv=None)[source]#

Adds minor ticks.

Parameters:

  • ax (Axes) – An axis instance from a matplotlib figure.

  • xdiv (int, optional) – Divisions between x major ticks. Defaults to None (auto locate).

  • ydiv (int, optional) – Divisions between y major ticks. Defaults to None (auto locate).

Notes

This function ignores axes with logarithmic scaling.

ampworks.plotutils.tick_direction(ax, xdir='in', ydir='in', top=True, right=True)[source]#

Controls tick directions.

Parameters:

  • ax (Axes) – An axis instance from a matplotlib figure.

  • xdir ({'in', 'out', 'inout'}, optional) – Places x ticks inward, outward, or both. By default ‘in’.

  • ydir ({'in', 'out', 'inout'}, optional) – Places y ticks inward, outward, or both. By default ‘in’.

  • top (bool, optional) – Mirror the x ticks along the top of Axis, by default True.

  • right (bool, optional) – Mirror the y ticks along the top of Axis, by default True.