API Reference

This page contains the API reference for PlotEZ.

Main Plotting Functions

PlotEZ - Mundane plotting made easy.

This module provides simplified plotting functions for common visualization tasks.

n_plotter(x_data, y_data, n_rows, n_cols, x_labels=None, y_labels=None, data_labels=None, plot_title=None, subplot_title=None, auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None)[source]

Plot multiple subplots in a grid with optional customization for each subplot.

Parameters:

x_data (ArrayLike) – List of x-axis data arrays for each subplot.
y_data (ArrayLike) – List of y-axis data arrays for each subplot.
n_rows (int) – Number of rows in the subplot grid.
n_cols (int) – Number of columns in the subplot grid.
x_labels (str | Sequence[str] | None) – List of labels for the x-axes of each subplot.
y_labels (str | Sequence[str] | None) – List of labels for the y-axes of each subplot.
data_labels (str | Sequence[str] | None) – List of labels for the data series in each subplot.
plot_title (str | None) – Title of the plot.
subplot_title (str | Sequence[str] | None) – Titles for the subplots, if required.
auto_label (bool) – Automatically assigns labels to subplots if True. If True, it overwrites user-provided labels. Defaults to False.
is_scatter (bool) – If True, plots data as scatter plots; otherwise, plots as line plots.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axes. Passed directly to plt.subplots.

Returns:

A tuple of (figure, axes_array) containing the matplotlib Figure and flattened array of Axes.

Return type:

tuple[Figure, Axes]

plot_errorband(x_data, y_data, y_lower=None, y_upper=None, x_label=None, y_label=None, plot_title=None, data_label=None, auto_label=False, line=True, band_config=None, line_config=None, axis=None, figure_kwargs=None)[source]

Plot a line with an error band around it using the provided data and configurations.

Parameters:

x_data (ArrayLike) – Array or sequence containing x-coordinates for the plot.
y_data (ArrayLike) – Array or sequence containing y-coordinates for the plot.
y_lower (float | ArrayLike | None) – Array of absolute y-values for the lower band edge. NOT error offsets - use y_data - error if needed.
y_upper (float | ArrayLike | None) – Array of absolute y-values for the upper band edge. NOT error offsets - use y_data + error if needed.
x_label (str | None) – Label for the x-axis. If None, no label will be displayed unless auto-labeling is enabled.
y_label (str | None) – Label for the y-axis. If None, no label will be displayed unless auto-labeling is enabled.
plot_title (str | None) – Title for the plot. If None, no title will be displayed unless auto-labeling is enabled.
data_label (str | None) – Label for the data series. This is used in legend generation if auto_label is enabled.
auto_label (bool) – If set to True, default labels for axis and title are applied, and a legend is generated. Defaults to False.
line (bool, optional) – If set to True, a central line is plotted on the graph. Defaults to True.
band_config (ErrorBandConfig | None) – Configuration object defining the style of the error band. If None, the default styling is applied.
line_config (LinePlotConfig | dict | None) – Configuration object defining the style of the central line. If None, the default styling is applied.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – An existing matplotlib axis object on which to plot. If None, a new figure and axis are created.

Returns:

A matplotlib Axes object containing the plot.

Return type:

Axes

plot_errorbar(x_data, y_data, x_err=None, y_err=None, x_label=None, y_label=None, plot_title=None, data_label=None, auto_label=False, errorbar_config=None, axis=None, figure_kwargs=None)[source]

Plot an error bar graph with optional error ranges, labels, and configurations.

Parameters:

x_data (ArrayLike) – The x-coordinates of the data points.
y_data (ArrayLike) – The y-coordinates of the data points.
x_err (float | ArrayLike | None) – Error margins for x-coordinates. Can be: - Scalar: symmetric error for all points - 1D array (N,): symmetric errors, one per point - 2D array (2, N): asymmetric [lower_errors, upper_errors]
y_err (float | ArrayLike | None) – Error margins for y-coordinates. Can be: - Scalar: symmetric error for all points - 1D array (N,): symmetric errors, one per point - 2D array (2, N): asymmetric [lower_errors, upper_errors]
x_label (str | None) – The label for the x-axis. If None and auto_label argument is set to True, a default label “X” is used.
y_label (str | None) – The label for the y-axis. If None and auto_label argument is set to True, a default label “Y” is used.
plot_title (str | None) – The title of the plot. If None and auto_label argument is set to True, the default title “Error Bar Plot” is used.
data_label (str | None) – The label for the data points, which will appear in the plot legend. If None, the legend is not displayed.
auto_label (bool) – If True, automatically assigns default labels for the axes and title if no labels or title are provided.
errorbar_config (ErrorPlotConfig | None) – Custom configurations for the error bars. If None, default configurations are used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – A matplotlib Axes object on which the plot will be rendered. If None, a new subplot is created using figure_kwargs.

Returns:

The Axes object containing the error bar plot.

Return type:

Axes

plot_two_column_file(file_name, delimiter=',', skip_header=False, x_label=None, y_label=None, data_label=None, plot_title=None, auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None, axis=None)[source]

Read a two-column file (x, y) and plot the data.

Parameters:

file_name (str) – The path to the file to be plotted. The file should contain two columns (x and y data).
delimiter (str) – The delimiter used in the file (default is ‘,’).
skip_header (bool) – If True, skips the first row in the given data file, otherwise does nothing. Default is False.
x_label (str | None) – The label for the x-axis.
y_label (str | None) – The label for the y-axis.
data_label (str | None) – Data label for the plot to put in the legend. Defaults to ‘X vs Y’.
plot_title (str | None) – The title for the plot.
auto_label (bool) – If True, automatically sets the x-axis label, y-axis label, and plot title. Default is False.
is_scatter (bool) – If True, creates a scatter plot. Otherwise, creates a line plot. Default is False.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – The axis object to draw the plots on. If not passed, a new axis object will be created internally.

Returns:

A tuple of (primary_axis, secondary_axis) if a dual-axis plot is created, otherwise a single Axes.

Return type:

tuple[Axes, Axes] or Axes

Raises:

ValueError – If the file does not contain exactly two columns.

plot_with_dual_axes(x1_data, y1_data, x2_data=None, y2_data=None, x1y1_label=None, x1y2_label=None, x2y1_label=None, use_twin_x=False, auto_label=False, axis_labels=None, plot_title=None, is_scatter=False, plot_config=None, figure_kwargs=None, axis=None)[source]

Plot the data with options for dual axes (x or y) or single axis.

Parameters:

x1_data (ArrayLike) – Data for the primary x-axis.
y1_data (ArrayLike) – Data for the primary y-axis.
x2_data (ArrayLike | None) – Data for the secondary x-axis (used for dual x-axis plots).
y2_data (ArrayLike | None) – Data for the secondary y-axis (used for dual y-axis plots).
x1y1_label (str | None) – Label for the plot of X1 vs. Y1. If None, and auto_label is True, defaults to ‘X1 vs Y1’.
x1y2_label (str | None) – Label for the plot of X1 vs. Y2 (when using dual Y-axes). If None, and auto_label is True, defaults to ‘X1 vs Y2’.
x2y1_label (str | None) – Label for the plot of X2 vs. Y1 (when using dual X-axes). If None, and auto_label is True, defaults to ‘X2 vs Y1’.
use_twin_x (bool) – If True, creates a dual y-axis plot. If False, creates a dual x-axis plot. Default is False.
auto_label (bool) – If True, automatically assigns labels if none are provided. Default is False.
axis_labels (list[str] | str | None) – List of axis labels in the form [x_label, y_label1, y_label2]. If None, and auto_label is True, defaults to [‘X’, ‘Y1’, ‘Y2’] or [‘X1’, ‘Y’, ‘X2’].
plot_title (str | None) – Title of the plot. If None, and auto_label is True, defaults to ‘Plot’.
is_scatter (bool) – If True, creates scatter plot; otherwise, line plot. Default is False.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – The axis object to draw the plots on. If not passed, a new axis object will be created internally.

Returns:

A tuple of (primary_axis, secondary_axis) when dual axes are used, otherwise a single Axes.

Return type:

tuple[Axes, Axes] or Axes

plot_xxy(x1_data, x2_data, y_data, y_label=None, x1_label=None, x2_label=None, plot_title=None, data_labels=(None, None), auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None, axis=None)[source]

Plot two sets of x-data (x1_data and x2_data) against the same y-data (y_data) on the same plot.

Parameters:

x1_data (ArrayLike) – The first set of x-axis data to be plotted against y_data.
x2_data (ArrayLike) – The second set of x-axis data to be plotted against y_data.
y_data (ArrayLike) – The y-axis data for both plots.
x1_label (str | None) – The label for the first x-axis.
x2_label (str | None) – The label for the second x-axis.
y_label (str | None) – The label for the y-axis.
plot_title (str | None) – The title for the plot.
data_labels (Sequence[str | None]) – The labels for the two datasets. Default is (None, None).
auto_label (bool) – Whether to automatically label the plot. Default is False.
is_scatter (bool) – Whether to create a scatter plot (True) or a line plot (False). Default is False.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – A Matplotlib axis to plot on. If None, a new axis is created. Default is None.

Returns:

A tuple of (primary_axis, secondary_axis) for the dual y-axis plot, or a single Axes.

Return type:

tuple[Axes, Axes] or Axes

plot_xy(x_data, y_data, x_label=None, y_label=None, plot_title=None, data_label=None, auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None, axis=None)[source]

Plot the x_data against y_data with customizable options.

Parameters:

x_data (ArrayLike) – The data for the x-axis.
y_data (ArrayLike) – The data for the y-axis.
x_label (str | None) – The label for the x-axis.
y_label (str | None) – The label for the y-axis.
plot_title (str | None) – The title for the plot.
data_label (str | None) – Data label for the plot to put in the legend. Defaults to ‘X vs Y’.
auto_label (bool) – If True, automatically sets x and y-axis labels and the plot title. Default is False.
is_scatter (bool) – If True, creates a scatter plot. Otherwise, creates a line plot. Default is False.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – The axis object to draw the plots on. If not passed, a new axis object will be created internally.

Returns:

A tuple of (primary_axis, secondary_axis) if a dual-axis plot is created, otherwise a single Axes.

Return type:

tuple[Axes, Axes] or Axes

plot_xyy(x_data, y1_data, y2_data, x_label=None, y1_label=None, y2_label=None, plot_title=None, data_labels=(None, None), auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None, axis=None)[source]

Plot two sets of y-data (y1_data and y2_data) against the same x-data (x_data) on the same plot.

Parameters:

x_data (ArrayLike) – The x-axis data for both plots.
y1_data (ArrayLike) – The first set of y-axis data to be plotted against x_data.
y2_data (ArrayLike) – The second set of y-axis data to be plotted against x_data.
x_label (str | None) – The label for the x-axis.
y1_label (str | None) – The label for the first y-axis.
y2_label (str | None) – The label for the second y-axis.
plot_title (str | None) – The title for the plot.
data_labels (Sequence[str | None]) – The labels for the two datasets. Default is (None, None).
auto_label (bool) – Whether to automatically label the plot. Default is False.
is_scatter (bool) – Whether to create a scatter plot (True) or a line plot (False). Default is False.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.
axis (Axes | None) – A Matplotlib axis to plot on. If None, a new axis is created. Default is None.

Returns:

A tuple of (primary_axis, secondary_axis) for the dual y-axis plot, or a single Axes.

Return type:

tuple[Axes, Axes] or Axes

two_subplots(x_data, y_data, x_labels=None, y_labels=None, data_labels=None, plot_title=None, subplot_title=None, orientation='h', auto_label=False, is_scatter=False, plot_config=None, figure_kwargs=None)[source]

Create two subplots arranged horizontally or vertically, with optional customization.

Parameters:

x_data (ArrayLike) – List containing x-axis data arrays for each subplot.
y_data (ArrayLike) – List containing y-axis data arrays for each subplot.
x_labels (list[str] | str | None) – List of labels for the x-axes in each subplot.
y_labels (list[str] | str | None) – List of labels for the y-axes in each subplot.
data_labels (list[str] | str | None) – List of labels for the data series in each subplot.
plot_title (str | None) – Title of the plot.
subplot_title (list[str] | str | None) – Titles for the subplots, if required.
orientation (str) – Orientation of the subplots, either 'h' for horizontal or 'v' for vertical.
auto_label (bool) – Automatically assigns labels to subplots if True.
is_scatter (bool) – If True, plots data as scatter plots; otherwise, plots as line plots.
plot_config (LinePlotConfig | ScatterPlotConfig | None) – Configuration object for line or scatter styling. If None, a default LinePlotConfig is used.
figure_kwargs (dict | None) – Keyword arguments for creating the figure and axes. Passed directly to plt.subplots.

Returns:

A tuple of (figure, axes_array) containing the matplotlib Figure and flattened array of Axes.

Return type:

tuple[Figure, Axes]

Raises:

OrientationError – If orientation is not 'h' or 'v'.

Utility Classes

Parameter Classes

class LinePlotConfig(color=None, linewidth=None, linestyle=None, alpha=None, marker=None, markersize=None, markerfacecolor=None, markeredgecolor=None, markeredgewidth=None, _extra=<factory>)[source]

Bases: object

Configuration class for line plots.

Parameters:

color (str | Sequence[str] | None)
linewidth (float | Sequence[float] | None)
linestyle (str | Sequence[str] | None)
alpha (float | Sequence[float] | None)
marker (str | Sequence[str] | None)
markersize (float | Sequence[float] | None)
markerfacecolor (str | Sequence[str] | None)
markeredgecolor (str | Sequence[str] | None)
markeredgewidth (float | Sequence[float] | None)
_extra (dict[str, Any])

__repr__()[source]: Pretty repr showing both explicit and extra params.

get_dict()[source]

Get all parameters as dict for matplotlib.

Return type:: dict[str, Any]

classmethod populate(dictionary)[source]

Create a LinePlotConfig instance from a dictionary, using a mapping for shorthand keys.

Parameters:: dictionary (dict[str, Any])
Return type:: LinePlotConfig

alpha: float | Sequence[float] | None = None

color: str | Sequence[str] | None = None

linestyle: str | Sequence[str] | None = None

linewidth: float | Sequence[float] | None = None

marker: str | Sequence[str] | None = None

markeredgecolor: str | Sequence[str] | None = None

markeredgewidth: float | Sequence[float] | None = None

markerfacecolor: str | Sequence[str] | None = None

markersize: float | Sequence[float] | None = None

class ErrorPlotConfig(color=None, linewidth=None, linestyle=None, alpha=None, ecolor=None, elinewidth=None, marker=None, markersize=None, markerfacecolor=None, markeredgecolor=None, capsize=None, capthick=None, errorevery=None, _extra=<factory>)[source]

Bases: object

Configuration class for error bar plots.

Parameters:

color (str | None)
linewidth (float | None)
linestyle (str | None)
alpha (float | None)
ecolor (str | None)
elinewidth (float | None)
marker (str | None)
markersize (float | None)
markerfacecolor (str | None)
markeredgecolor (str | None)
capsize (float | None)
capthick (float | None)
errorevery (int | tuple | None)
_extra (dict[str, Any])

__repr__()[source]: Pretty repr showing both explicit and extra params.

get_dict()[source]

Get all parameters as dict for matplotlib.

Return type:: dict[str, Any]

classmethod populate(dictionary)[source]

Create an ErrorPlotConfig instance from a dictionary, using a mapping for shorthand keys.

Parameters:: dictionary (dict[str, Any])
Return type:: ErrorPlotConfig

alpha: float | None = None

capsize: float | None = None

capthick: float | None = None

color: str | None = None

ecolor: str | None = None

elinewidth: float | None = None

errorevery: int | tuple | None = None

linestyle: str | None = None

linewidth: float | None = None

marker: str | None = None

markeredgecolor: str | None = None

markerfacecolor: str | None = None

markersize: float | None = None

class ErrorBandConfig(color=None, alpha=0.25, linewidth=None, edgecolor=None, linestyle=None, hatch=None, interpolate=None, step=None, _extra=<factory>)[source]

Bases: object

Configuration class for error bands (shaded fill regions).

Parameters:

color (str | None)
alpha (float)
linewidth (float | None)
edgecolor (str | None)
linestyle (str | None)
hatch (str | Literal['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'] | None)
interpolate (bool | None)
step (str | Literal['pre', 'post', 'mid'] | None)
_extra (dict[str, Any])

__repr__()[source]: Return a string representation of the ErrorBandConfig instance.

get_dict()[source]

Get all parameters as dict for matplotlib.

Return type:: dict[str, Any]

classmethod populate(dictionary)[source]

Create an ErrorBandConfig instance from a dictionary, using a mapping for shorthand keys.

Parameters:: dictionary (dict[str, Any])
Return type:: ErrorBandConfig

alpha: float = 0.25

color: str | None = None

edgecolor: str | None = None

hatch: str | Literal['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'] | None = None

interpolate: bool | None = None

linestyle: str | None = None

linewidth: float | None = None

step: str | Literal['pre', 'post', 'mid'] | None = None

class ScatterPlotConfig(color=None, s=None, alpha=None, marker=None, cmap=None, edgecolors=None, facecolors=None, _extra=<factory>)[source]

Bases: object

Configuration class for scatter plots.

Parameters:

color (str | None)
s (float | None)
alpha (float | None)
marker (str | None)
cmap (str | None)
edgecolors (str | None)
facecolors (str | None)
_extra (dict[str, Any])

__repr__()[source]: Pretty repr showing both explicit and extra params.

get_dict()[source]

Get all parameters as dict for matplotlib.

Return type:: dict[str, Any]

classmethod populate(dictionary)[source]

Create a ScatterPlotConfig instance from a dictionary, using a mapping for shorthand keys.

Parameters:: dictionary (dict[str, Any])
Return type:: ScatterPlotConfig

alpha: float | None = None

cmap: str | None = None

color: str | None = None

edgecolors: str | None = None

facecolors: str | None = None

marker: str | None = None

s: float | None = None

Utility Functions

plot_or_scatter(axes, scatter)[source]

Return the plot or scatter method based on the specified plot type.

Parameters:

axes – The matplotlib axis on which to apply the plot or scatter method.
scatter (bool) – If True, returns the scatter method; otherwise, returns the plot method.

Returns:

The matplotlib plotting method (axes.scatter if scatter is True, otherwise axes.plot).

Return type:

function

split_dictionary(plot_instance)[source]

Split a config instance’s parameters into two separate instances.

Parameters:: plot_instance (LSE) – An instance with parameters stored as lists or tuples. Each parameter should be a list or tuple containing exactly two values, corresponding to settings for the two resulting instances.
Returns:: Two instances of the same type as plot_instance, with parameters split based on the values in plot_instance. The first instance (instance1) and second instance (instance2) will have their attributes set according to the first and second elements, respectively, from each list or tuple in plot_instance.
Return type:: Tuple
Raises:: ValueError – If any parameter in plot_instance is not a list or tuple with exactly two elements.

Notes

The parameters with only one element are broadcast to both instances rather than raising an error.

dual_axes_data_validation(x1_data, x2_data, y1_data, y2_data, use_twin_x, axis_labels)[source]

Validate the data and parameters for dual-axes plotting.

Parameters:

x1_data (ArrayLike) – Data for the primary x-axis.
x2_data (ArrayLike) – Data for the secondary x-axis (used in dual x-axis plots). Should be None if use_twin_x is True.
y1_data (ArrayLike) – Data for the primary y-axis.
y2_data (ArrayLike) – Data for the secondary y-axis (used in dual y-axis plots). Should be None if use_twin_x is False.
use_twin_x (bool) – If True, a dual y-axis plot is expected; otherwise, a dual x-axis plot is expected.
axis_labels (Sequence[str] | None) – List of axis labels. Must have exactly three elements: - Label for the x-axis of the primary plot. - Label for the y-axis of the primary plot. - Label for the secondary axis (x or y).

Raises:

AxisLabelError – If axis_labels does not have exactly three elements.
EmptyDataError – If x1_data or y1_data is empty.
TwinXDataError – If x2_data is provided when use_twin_x is True.
TwinYDataError – If y2_data is provided when use_twin_x is False.

Return type:

None

dual_axes_label_management(x1y1_label=None, x1y2_label=None, x2y1_label=None, auto_label=False, axis_labels=None, plot_title=None, use_twin_x=True)[source]

Manage labels and titles for dual-axes plots.

Parameters:

x1y1_label (str, optional) – Label for the primary plot (X1 vs. Y1). Ignored if auto_label=True.
x1y2_label (str, optional) – Label for the secondary Y-axis plot (X1 vs. Y2), used if use_twin_x is True. Ignored if auto_label=True.
x2y1_label (str, optional) – Label for the secondary X-axis plot (X2 vs. Y1), used if use_twin_x is False. Ignored if auto_label=True.
auto_label (bool, default False) – If True, overwrites all provided labels with automatic defaults. When True, all label parameters are ignored.
axis_labels (Sequence[str], optional) – Axis labels as [x_label, y1_label, y2_or_x2_label]. Ignored if auto_label=True. - Dual Y-axis: [primary x, primary y, secondary y] - Dual X-axis: [primary x, primary y, secondary x]
plot_title (str, optional) – Plot title. Ignored if auto_label=True.
use_twin_x (bool, default True) – If True, dual Y-axis plot. If False, dual X-axis plot.

Returns:

(x1y1_label, x1y2_label, x2y1_label, plot_title, axis_labels)

Return type:

tuple[str, str, str, str, list[str]]

Notes

When auto_label=True, all user-provided labels are replaced with:

Dual Y-axis defaults: axis_labels=[‘X’, ‘Y₁’, ‘Y₂’], x1y1_label=’X₁ vs. Y₁’, x1y2_label=’X₁ vs. Y₂’
Dual X-axis defaults: axis_labels=[‘X₁’, ‘Y’, ‘X₂’], x1y1_label=’Y vs. X₁’, x2y1_label=’Y vs. X₂’
plot_title=’Plot’

When auto_label=False, missing labels are replaced with empty strings.

Convenience / Wrapper Functions

These factory functions provide a concise, keyword-driven way to build config objects without importing the dataclass names directly. All are available at the top-level plotez namespace.

Each function also has a short alias that can be used interchangeably:

Long-form function	Short alias
`line_plot_configuration`	`lpc`
`error_plot_configuration`	`epc`
`error_band_configuration`	`ebc`
scatter_plot_configuration``\| ``spc

line_plot_configuration(c=None, lw=None, ls=None, alpha=None, marker=None, ms=None, mfc=None, mec=None, mew=None, **kwargs)[source]

Create a configuration object for line plots.

Parameters:

c (str | Sequence[str] | None) – Line color.
lw (float | Sequence[float] | None) – Line width.
ls (str | Sequence[str] | None) – Line style (e.g., ‘-’, ‘–’, ‘-.’, ‘:’).
alpha (float | Sequence[float] | None) – Transparency level (0.0 to 1.0).
marker (str | Sequence[str] | None) – Marker style (e.g., ‘o’, ‘s’, ‘^’).
ms (float | Sequence[float] | None) – Marker size.
mfc (str | Sequence[str] | None) – Marker face color.
mec (str | Sequence[str] | None) – Marker edge color.
mew (float | Sequence[float] | None) – Marker edge width.
**kwargs – Additional keyword arguments passed to the underlying plot function.

Returns:

Configuration object for line plots.

Return type:

LinePlotConfig

error_plot_configuration(c=None, lw=None, ls=None, alpha=None, ecolor=None, elinewidth=None, marker=None, ms=None, mfc=None, mec=None, capsize=None, capthick=None, errorevery=None, **kwargs)[source]

Create a configuration object for error bar plots.

Parameters:

c (str | None) – Line color.
lw (float | None) – Line width.
ls (str | None) – Line style (e.g., ‘-’, ‘–’, ‘-.’, ‘:’).
alpha (float | None) – Transparency level (0.0 to 1.0).
ecolor (str | None) – Error bar color.
elinewidth (float | None) – Error bar line width.
marker (str | None) – Marker style (e.g., ‘o’, ‘s’, ‘^’).
ms (float | None) – Marker size.
mfc (str | None) – Marker face color.
mec (str | None) – Marker edge color.
capsize (float | None) – Length of the error bar caps in points.
capthick (float | None) – Thickness of error bar caps.
errorevery (int | tuple | None) – Draw error bars on a subset of data points.
**kwargs – Additional keyword arguments passed to the underlying errorbar function.

Returns:

Configuration object for error bar plots.

Return type:

ErrorPlotConfig

error_band_configuration(c=None, alpha=0.25, lw=None, ec=None, ls=None, hatch=None, interpolate=None, step=None, **kwargs)[source]

Create a configuration object for error bands.

Parameters:

c (str | None) – Fill color for the error band.
alpha (float) – Transparency level (0.0 to 1.0).
lw (float | None) – Edge line width.
ec (str | None) – Edge color.
ls (str | None) – Edge line style (e.g., ‘-’, ‘–’, ‘-.’, ‘:’).
hatch (str | Literal['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*'] | None) – Hatching pattern (e.g., ‘/’, ‘|’, ‘-’, ‘+’, ‘x’).
interpolate (bool | None) – Whether to interpolate the error band.
step (str | Literal['pre', 'post', 'mid'] | None) – Step mode for the band (e.g., ‘pre’, ‘post’, ‘mid’).
**kwargs – Additional keyword arguments passed to the underlying fill function.

Returns:

Configuration object for error bands.

Return type:

ErrorBandConfig

scatter_plot_configuration(c=None, s=None, alpha=None, marker=None, cmap=None, ec=None, fc=None, **kwargs)[source]

Create a configuration object for scatter plots.

Parameters:

c (color or array-like, optional) – Marker color(s).
s (float or array-like, optional) – Marker size(s) in points squared.
alpha (float, optional) – Transparency level (0.0 to 1.0).
marker (str, optional) – Marker style (e.g., ‘o’, ‘s’, ‘^’).
cmap (str or Colormap, optional) – Colormap name or object.
ec (color or array-like, optional) – Edge color(s).
fc (color or array-like, optional) – Face color(s).
**kwargs (dict, optional) – Additional keyword arguments passed to the underlying scatter function.

Returns:

Configuration object for scatter plots.

Return type:

ScatterPlotConfig

Shorthand Key Reference

All populate() class methods and wrapper functions accept shorthand aliases in place of full matplotlib parameter names. The tables below list every recognised alias.

Line / Error-bar parameters

Alias	Full parameter name
`ls`	`linestyle`
`lw`	`linewidth`
`c`	`color`
`ms`	`markersize`
`mec`	`markeredgecolor`
`mfc`	`markerfacecolor`
`mew`	`markeredgewidth`

Error-bar-only parameters

The ErrorPlotConfig / epc wrapper also accepts all line aliases above, plus:

Alias	Full parameter name
`ecolor`	`ecolor`
`elinewidth`	`elinewidth`
`capsize`	`capsize`
`capthick`	`capthick`

Scatter parameters

Alias	Full parameter name
`c`	`color`
`s`	`size`
`ec`	`edgecolors`
`fc`	`facecolors`

Error Handling

PlotEZ Error Handling.

Custom exceptions for plotting operations.

exception AxisLabelError[source]

Bases: ConfigurationError

Raised when the axis_labels sequence does not contain exactly three elements.

Notes

Dual-axes functions require labels for three axes: primary x, primary y, and the secondary axis (either x or y).

exception ColumnCountError[source]

Bases: DataError

Raised when a data file does not contain exactly two columns.

Notes

plot_two_column_file expects files with exactly one x-column and one y-column. Any other column count triggers this error.

exception ConfigurationError[source]

Bases: PlotError

Base class for plot configuration and parameter errors.

Notes

Inherit from this class for errors that arise from incorrect or conflicting plot configuration options rather than from the data itself.

exception DataError[source]

Bases: PlotError

Base class for data-related plotting errors.

Notes

Inherit from this class for any error that stems from invalid, malformed, or incompatible input data arrays or files.

exception EmptyDataError[source]

Bases: DataError

Raised when required primary x or y data is empty.

Notes

At least one data point must be present in the primary x and y arrays before a plot can be constructed.

exception LabelConflictWarning[source]

Bases: UserWarning

Issued when auto_label=True overrides user-provided labels.

Notes

When auto_label is enabled it silently replaces any explicitly supplied axis labels, data labels, or plot titles with auto-generated defaults. This warning is raised to make that substitution visible to the caller. Use warnings.filterwarnings to suppress or escalate it as needed.

exception OrientationError[source]

Bases: PlotError

Raised when an invalid or unexpected orientation is used in a plot.

Notes

This error occurs when the orientation parameter for a plot is set incorrectly or does not match the expected format.

exception PlotError[source]

Bases: Exception

Base class for exceptions related to plotting operations.

Notes

This serves as the parent class for all plotting-related errors. Specific exceptions related to plot configuration or data issues should inherit from this class.

exception ShapeError[source]

Bases: DataError

Raised when an array has an unexpected or incompatible shape.

Notes

Typically raised when an error array intended for asymmetric error bars does not satisfy the required (2, N) shape contract.

exception TwinXDataError[source]

Bases: ConfigurationError

Raised when x2_data is supplied for a dual-Y-axis (use_twin_x=True) plot.

Notes

A dual-Y-axis plot shares the x-axis between both datasets; providing a separate x2_data is therefore contradictory and not permitted.

exception TwinYDataError[source]

Bases: ConfigurationError

Raised when y2_data is supplied for a dual-X-axis (use_twin_x=False) plot.

Notes

A dual-X-axis plot shares the y-axis between both datasets; providing a separate y2_data is therefore contradictory and not permitted.