API Reference

This page documents the plotfair API. All public classes, functions, and objects are documented with their docstrings.

plotfair 

The main package exports commonly used objects and functions for convenience.

faiirplot Beautiful color and plotting utilities for matplotlib and plotly.

Main modules: - colors: Color swatches, palettes, and utilities - presets: Default plotting settings - colormaps: Colormap creation utilities - plt_y: Matplotlib-like Plotly wrapper - interplot_presets: interplot presets and patches

class plotfair.Iplt(*args, **kwargs)

Bases: object

Convenient interface class wrapping interplot Plot object.

Provides familiar plotting methods similar to matplotlib’s pyplot, supporting both interactive and non-interactive modes.

new(*args, **kwargs): Create a new plot, closing previous if non-interactive.

static parse_format_string(fmt)

Parse matplotlib-style format strings.

Format strings can specify color, marker, and line style.

Parameters:

fmt (str) – Format string (e.g., ‘ro-’, ‘b–’, ‘g^:’).

Returns:

{‘color’: str or None, ‘marker’: str or None,: ’linestyle’: str or None}

Return type:

dict

Examples

>>> parse_format_string('ro-')
{'color': 'red', 'marker': 'circle', 'linestyle': 'solid'}
>>> parse_format_string('b--')
{'color': 'blue', 'marker': None, 'linestyle': 'dashed'}
>>> parse_format_string('g^')
{'color': 'green', 'marker': 'triangle-up', 'linestyle': None}

plot(*args, **kwargs)

Plot data with optional formatting.

Supports calls like: - plot(y): y vs. index - plot(x, y): x vs. y - plot(x, y, fmt): with format string controlling marker and line style

Optional kwargs: color, linestyle, marker, alpha, label, etc.

class plotfair.Plty

Bases: object

A Plotly-based Matplotlib-like interface for creating interactive plots.

This class provides methods similar to Matplotlib’s pyplot interface, enabling users to create line plots, histograms, set axis limits, labels, titles, and switch between linear and log-log scales, all using Plotly’s interactive plotting capabilities.

hist(data, bins=50, **kwargs)

Plot histograms similar to plt.hist.

Data can be a list, numpy array, or a dictionary of {label: values}. Bins can be an integer or an array of bin edges. Supports density=True for normalized histograms.

linear(): Set both x and y axes to linear scale.

loglog(): Set both x and y axes to logarithmic scale.

plot(*args, **kwargs)

Plot lines and/or markers. Usage mimics plt.plot.

Supports: - plot(y) - plot(x, y) - plot(x, y, fmt) Optional keyword arguments include color, linestyle, marker, alpha, label, etc.

save_to_clipboard(): Saves figure to clipboard but uses script from https://alecjacobson.com/weblog/3816.html but can probably also use https://github.com/jcsalterego/pngpaste/

show(): Display the figure and reset the figure object.

show_()

title(text): Set the figure title.

xlabel(text): Set the x-axis label.

xlim(xmin=None, xmax=None): Set the limits of the x-axis.

ylabel(text): Set the y-axis label.

ylim(ymin=None, ymax=None): Set the limits of the y-axis.

plotfair.floats_to_rgbstring(color_float): Convert a float tuple to an RGB string for use by plotly form (0.0, 0.0, 0.0) to “rgb(0, 0, 0)

plotfair.hex_to_rgb(hex_code): Convert a hex color code to an RGB tuple with values 0-1.

plotfair.paintkit_to_colorway(paintkit): Convert a PaintKit to a Plotly-compatible colorway list.

plotfair.show_colormap(cmap, name=None, height=0.5): Display a colormap as a horizontal gradient bar.

Colors 

Color swatches, palettes, and colormap utilities.

class plotfair.colors.ColorSwatch(name, hex_code, tags=None)

Bases: object

A single color with metadata including name, hex code, and tags.

has_tag(tag): Check if this swatch has a specific tag.

class plotfair.colors.PaintKit(colors)

Bases: object

A collection of ColorSwatches with filtering and visualization methods.

display_paintkit(color_tags=None, saturation_tags=None, label='hex'): Display a grid of swatches by color and saturation tags.

filter(*, tags=None, any_tags=None)

Filter colors by tags.

Parameters:

tags – Set of tags that must ALL be present.
any_tags – Set of tags where at least ONE must be present.

Returns:

A new PaintKit with matching colors.

get_named(*names): Get swatches by their exact names.

ordered_swatches(tag_list)

Get swatches in a specific order by tag, one per tag.

Parameters:: tag_list – List of tags defining the desired order.
Returns:: A new PaintKit with one swatch per tag in order.

to_cmap(colors=None, name='custom_cmap'): Convert to a matplotlib ListedColormap.

to_cycler(colors=None): Convert to a matplotlib color cycler for axes.prop_cycle.

plotfair.colors.floats_to_rgbstring(color_float): Convert a float tuple to an RGB string for use by plotly form (0.0, 0.0, 0.0) to “rgb(0, 0, 0)

plotfair.colors.hex_to_rgb(hex_code): Convert a hex color code to an RGB tuple with values 0-1.

plotfair.colors.paintkit_to_colorway(paintkit): Convert a PaintKit to a Plotly-compatible colorway list.

plotfair.colors.perceptual_colormap_nonuniform(colors, positions=None, n=256, space='CAM02-UCS')

Create a perceptually uniform colormap with optional custom positions.

Parameters:

colors – List of colors (hex, names, or RGB tuples).
positions – Optional list of positions [0.0, …, 1.0] for each color.
n – Number of steps in the output colormap.
space – Perceptual color space for interpolation.

Returns:

A matplotlib ListedColormap.

plotfair.colors.read_colors_from_csv(filename)

Load ColorSwatches from a CSV file.

Parameters:: filename – Path to CSV with ‘name’, ‘hex_code’, and ‘tags’ columns. Tags should be semicolon-separated.
Returns:: List of ColorSwatch objects.

plotfair.colors.show_colormap(cmap, name=None, height=0.5): Display a colormap as a horizontal gradient bar.

plotfair.colors.srgb_gradient_colormap(colors, positions=None, n=256, name='srgb_colormap')

Create a gradient colormap using sRGB interpolation.

Parameters:

colors – List of colors (hex, names, or RGB tuples).
positions – Optional list of positions [0.0, …, 1.0] for each color.
n – Number of steps in the output colormap.
name – Name for the colormap.

Returns:

A matplotlib LinearSegmentedColormap.

Colormaps 

Colormap creation utilities for perceptual and sRGB gradients.

PridePy.colormaps Colormap creation utilities for perceptual and sRGB gradients.

This module provides functions to create colormaps that are perceptually uniform or linear in sRGB space. It supports generating colormaps with anchor colors placed at nonuniform positions and visualizing colormaps.

plotfair.colormaps.log_cmap(cmap, x, *, x_array=None, vmin=None, vmax=None)

Exactly one of:

x_array
(vmin and vmax)

must be provided.

plotfair.colormaps.perceptual_colormap_nonuniform(colors, positions=None, n=256, space='CAM02-UCS')

Generate a perceptually uniform colormap between fixed color anchors at nonuniform positions.

Parameters:

colors (list) – List of color specifications (e.g., color names or RGB tuples).
positions (list or None) – Optional list of floats in [0, 1] specifying the relative positions of the anchor colors. Must start with 0.0 and end with 1.0 if provided. If None, colors are assumed to be evenly spaced.
n (int) – Number of points in the output colormap.
space (str) – The color space in which to perform interpolation (default is “CAM02-UCS”).

Returns:

A matplotlib ListedColormap object representing: the perceptually uniform colormap.

Return type:

ListedColormap

plotfair.colormaps.show_colormap(cmap, name=None, height=0.5)

Display a horizontal gradient of the given colormap.

Parameters:

cmap (Colormap) – A matplotlib colormap instance to display.
name (str or None) – Optional title to display above the colormap.
height (float) – Height of the displayed gradient figure in inches.

Behavior:: Opens a matplotlib window showing the colormap gradient.

plotfair.colormaps.srgb_gradient_colormap(colors, positions=None, n=256, name='srgb_colormap')

Create a linear sRGB gradient colormap from anchor colors.

Parameters:

colors (list) – List of color specifications (e.g., color names or RGB tuples).
positions (list or None) – Optional list of floats in [0, 1] specifying the relative positions of the anchor colors. Must start with 0.0 and end with 1.0 if provided. If None, colors are assumed to be evenly spaced.
n (int) – Number of points in the output colormap.
name (str) – Name of the resulting colormap.

Returns:

A matplotlib LinearSegmentedColormap object: representing the sRGB gradient colormap.

Return type:

LinearSegmentedColormap

Presets 

Default matplotlib and seaborn plotting settings.

plotfair.presets

This module defines default plotting settings for matplotlib and seaborn to ensure consistent and visually appealing figures across the project. It updates matplotlib’s rcParams with preferred defaults, applies a seaborn style, and monkey-patches matplotlib.pyplot.savefig with a wrapper that saves figures to a specified folder by default. #TODO: Create Style with https://matplotlib.org/stable/users/explain/customizing.html

plotfair.presets.savefig_with_folder(self, fname, *args, folder=None, **kwargs)

Save a matplotlib figure to a file, ensuring the output directory exists.

Parameters:

fname (str) – The filename for the saved figure. If not an absolute path, it will be saved inside the specified folder.
*args – Additional positional arguments passed to plt.savefig.
folder (str) – The folder to save the figure in (default: “figs”).
**kwargs – Additional keyword arguments passed to plt.savefig.

Behavior:

If SAVE_FIGS is True, creates the folder if it doesn’t exist and saves the figure.
If fname is not an absolute path, prepends the folder to the filename.
If SAVE_FIGS is False, prints a message and does not save.

Plotly Wrapper (plt_y)

Matplotlib-like interface for Plotly.

This module provides a Matplotlib-like plotting interface using Plotly as the backend. It defines the Plty class which mimics familiar Matplotlib plotting functions such as plot, hist, setting axis limits, titles, labels, and supports log-log scaling. The module also includes predefined Plotly templates and themes for consistent styling.

class plotfair.plt_y.Plty

Bases: object

A Plotly-based Matplotlib-like interface for creating interactive plots.

This class provides methods similar to Matplotlib’s pyplot interface, enabling users to create line plots, histograms, set axis limits, labels, titles, and switch between linear and log-log scales, all using Plotly’s interactive plotting capabilities.

hist(data, bins=50, **kwargs)

Plot histograms similar to plt.hist.

Data can be a list, numpy array, or a dictionary of {label: values}. Bins can be an integer or an array of bin edges. Supports density=True for normalized histograms.

linear(): Set both x and y axes to linear scale.

loglog(): Set both x and y axes to logarithmic scale.

plot(*args, **kwargs)

Plot lines and/or markers. Usage mimics plt.plot.

Supports: - plot(y) - plot(x, y) - plot(x, y, fmt) Optional keyword arguments include color, linestyle, marker, alpha, label, etc.

save_to_clipboard(): Saves figure to clipboard but uses script from https://alecjacobson.com/weblog/3816.html but can probably also use https://github.com/jcsalterego/pngpaste/

show(): Display the figure and reset the figure object.

show_()

title(text): Set the figure title.

xlabel(text): Set the x-axis label.

xlim(xmin=None, xmax=None): Set the limits of the x-axis.

ylabel(text): Set the y-axis label.

ylim(ymin=None, ymax=None): Set the limits of the y-axis.

Interplot Presets 

Presets and utilities for the interplot library.

Presets and utilities for interplot plotting library.

This module configures default styles, behaviors, and helper classes for interplot (iplot) plots. It customizes matplotlib and plotly plot appearances, provides enhanced show and save methods, and defines a convenient plotting interface via the Iplt class.

class plotfair.interplot_presets.Iplt(*args, **kwargs)

Bases: object

Convenient interface class wrapping interplot Plot object.

Provides familiar plotting methods similar to matplotlib’s pyplot, supporting both interactive and non-interactive modes.

new(*args, **kwargs): Create a new plot, closing previous if non-interactive.

static parse_format_string(fmt)

Parse matplotlib-style format strings.

Format strings can specify color, marker, and line style.

Parameters:

fmt (str) – Format string (e.g., ‘ro-’, ‘b–’, ‘g^:’).

Returns:

{‘color’: str or None, ‘marker’: str or None,: ’linestyle’: str or None}

Return type:

dict

Examples

>>> parse_format_string('ro-')
{'color': 'red', 'marker': 'circle', 'linestyle': 'solid'}
>>> parse_format_string('b--')
{'color': 'blue', 'marker': None, 'linestyle': 'dashed'}
>>> parse_format_string('g^')
{'color': 'green', 'marker': 'triangle-up', 'linestyle': None}

plot(*args, **kwargs)

Plot data with optional formatting.

Supports calls like: - plot(y): y vs. index - plot(x, y): x vs. y - plot(x, y, fmt): with format string controlling marker and line style

Optional kwargs: color, linestyle, marker, alpha, label, etc.

plotfair.interplot_presets.my_mpl_style(fig, ax)

Apply custom matplotlib style to figures and axes.

Parameters:

fig – Matplotlib figure object.
ax – Axes array (2D even for 1x1).

Returns:

Tuple of (fig, ax) with style applied.

plotfair.interplot_presets.rebuild_blank(self): Clear plot by rebuilding with default parameters.

plotfair.interplot_presets.save_with_folder(self, path, *args, folder='figs', **kwargs)

Save plot to a specified folder, creating it if necessary.

Parameters:

self – Plot instance.
path – Filename or boolean for default naming.
folder – Folder to save figures into.
*args – Additional positional arguments.
**kwargs – Additional keyword arguments.

Returns:

Result of original save method.

plotfair.interplot_presets.show_and_close(self): Enhanced show method that closes plot if not interactive.

Apple Color Palette 

macOS color palette generator.

API Reference

plotfair

Colors

Colormaps

Presets

Plotly Wrapper (plt_y)

Interplot Presets

Apple Color Palette

plotfair 

Colors 

Colormaps 

Presets 

Interplot Presets 

Apple Color Palette 