Plotting Functions#

Public functions for line, scatter, error, histogram, file, dual-axis, and multi-panel plotting.

Single-Axis Plots#

plotez.plot_xy(x_data, y_data, x_label='X', y_label='Y', data_label='XY Data', plot_title='XY Plot', 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) – The label for the x-axis.

  • y_label (str) – The label for the y-axis.

  • plot_title (str) – The title for the plot.

  • data_label (str) – Data label for the plot to put in the legend.

  • is_scatter (bool) – If True, creates a scatter plot. Otherwise, creates a line plot. Defaults 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:

The axis object of the plot.

Return type:

Axes

Raises:

  • ShapeError – If x_data or y_data is not one-dimensional.

  • DataLengthError – If x_data and y_data have different lengths.

plotez.plot_errorbar(x_data, y_data, x_err=None, y_err=None, x_label='X', y_label='Y', plot_title='XY ErrorBar', data_label='X vs. Y', 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) – The label for the x-axis.

  • y_label (str) – The label for the y-axis.

  • plot_title (str) – The title of the plot.

  • data_label (str) – The label for the data points, which will appear in the plot legend. If None, the legend is not displayed.

  • 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 Matplotlib Axes on which the plot was drawn.

Return type:

Axes

Raises:

  • ShapeError – If x/y data is not one-dimensional or an asymmetric error array is not shaped (2, N).

  • DataLengthError – If x/y data or an error array has an incompatible length.

plotez.plot_errorband(x_data, y_data, y_lower=None, y_upper=None, x_label='X', y_label='Y', plot_title='XY ErrorBand', data_label='X vs. Y', line=True, band_config=None, line_config=None, axis=None, figure_kwargs=None)[source]#

Plot a line graph with a shaded error band representing uncertainty.

Parameters:

  • x_data (ArrayLike) – The independent variable values to plot.

  • y_data (ArrayLike) – The central values to plot.

  • y_lower (float | ArrayLike | None) – The lower bound of the error band. If None, it is inferred as a symmetric reflection of y_upper through y_data. At least one of y_lower or y_upper must be provided.

  • y_upper (float | ArrayLike | None) – The upper bound of the error band. If None, it is inferred as a symmetric reflection of y_lower through y_data. At least one of y_lower or y_upper must be provided.

  • x_label (str) – The label for the x-axis.

  • y_label (str) – The label for the y-axis.

  • plot_title (str) – The title of the plot.

  • data_label (str) – The label for the data series, used in the legend. If line=True, the label is attached to the line. If line=False, it is attached to the band.

  • line (bool) – Whether to draw a line through the central values over the error band.

  • band_config (ErrorBandConfig | None) – Configuration for the error band styling. If None, defaults are used.

  • line_config (LinePlotConfig | dict | None) – Configuration for the line styling. If None, defaults are used.

  • axis (Axes | None) – Pre-existing Matplotlib axes to draw on. If provided, figure_kwargs is ignored.

  • figure_kwargs (dict | None) – Keyword arguments passed to plt.subplots when creating a new figure. Ignored if axis is provided.

Returns:

The Matplotlib Axes on which the plot was drawn.

Return type:

Axes

Raises:

  • ConfigurationError – If both y_lower and y_upper are None.

  • ShapeError – If data or an array-valued bound is not one-dimensional.

  • DataLengthError – If data and array-valued bounds do not have matching lengths.

plotez.plot_errorband_relative(x_data, y_data, y_lower=None, y_upper=None, x_label='X', y_label='Y', plot_title='XY ErrorBand', data_label='X vs. Y', line=True, band_config=None, line_config=None, axis=None, figure_kwargs=None)[source]#

Plot a line graph with a shaded error band using relative (offset) errors.

A convenience wrapper around plot_errorband() where y_lower and y_upper are interpreted as offsets from y_data rather than absolute bounds. Internally, the absolute bounds are computed as y_data - y_lower and y_data + y_upper before passing to plot_errorband().

Parameters:

  • x_data (ArrayLike) – The independent variable values to plot.

  • y_data (ArrayLike) – The central values to plot.

  • y_lower (float | ArrayLike | None) – The downward offset from y_data defining the lower band edge. If None, it is inferred as equal to y_upper, implying a symmetric band. At least one of y_lower or y_upper must be provided.

  • y_upper (float | ArrayLike | None) – The upward offset from y_data defining the upper band edge. If None, it is inferred as equal to y_lower, implying a symmetric band. At least one of y_lower or y_upper must be provided.

  • x_label (str) – The label for the x-axis.

  • y_label (str) – The label for the y-axis.

  • plot_title (str) – The title of the plot.

  • data_label (str) – The label for the data series, used in the legend. If line=True, the label is attached to the line. If line=False, it is attached to the band.

  • line (bool) – Whether to draw a line through the central values over the error band.

  • band_config (ErrorBandConfig | None) – Configuration for the error band styling. If None, defaults are used.

  • line_config (LinePlotConfig | dict | None) – Configuration for the line styling. If None, defaults are used.

  • axis (Axes | None) – Pre-existing Matplotlib axes to draw on. If provided, figure_kwargs is ignored.

  • figure_kwargs (dict | None) – Keyword arguments passed to plt.subplots when creating a new figure. Ignored if axis is provided.

Returns:

The Matplotlib Axes on which the plot was drawn.

Return type:

Axes

Raises:

See also

plot_errorband

The absolute-bounds version of this function.

plotez.plot_hist(x_data, x_label='X', y_label='Counts', plot_title='Histogram', data_label=None, hist_config=None, axis=None, figure_kwargs=None)[source]#

Plot a histogram of the data.

Parameters:

  • x_data (ArrayLike) – Array or sequence of data points to be histogrammed.

  • x_label (str) – Label for the x-axis.

  • y_label (str) – Label for the y-axis.

  • plot_title (str) – Title for the plot.

  • data_label (str | None) – Label(s) for the data series. This is used in plot’s legend generation.

  • hist_config (HistogramConfig | dict | None) – Configuration object for histogram styling. If None, default configurations are used.

  • axis (Axes | None) – An existing matplotlib axis object on which to plot. If None, a new figure and axis are created.

  • figure_kwargs (dict | None) – Keyword arguments for creating the figure and axis when axis is not provided. Ignored if axis is provided.

Returns:

The Matplotlib Axes on which the histogram was drawn.

Return type:

Axes

Raises:

ShapeError – If x_data is not one-dimensional.

plotez.plot_density(x_data, x_label='X', y_label='Density', plot_title='Density Plot', data_label=None, hist_config=None, axis=None, figure_kwargs=None)[source]#

Plot a density histogram based on the given data and configuration.

Parameters:

  • x_data (ArrayLike) – The data array used for generating the density plot.

  • x_label (str) – The label for the x-axis. Default is “X”.

  • y_label (str) – The label for the y-axis. Default is “Density”.

  • plot_title (str) – The title of the density plot. Default is “Density Plot”.

  • data_label (str | None) – The optional label for the dataset being visualized. Default is None.

  • hist_config (HistogramConfig | dict | None) – The histogram configuration, either as an instance of HistogramConfig, a dictionary, or None. If provided, it is used to configure the histogram and ensures that density=True is set. Default is None.

  • axis (Axes | None) – The Matplotlib Axes object on which to draw the plot. If None, a new set of axes is created. Default is None.

  • figure_kwargs (dict | None) – Optional keyword arguments passed when creating a new Matplotlib figure. These arguments are ignored if an existing axis is provided. Default is None.

Returns:

The Matplotlib Axes on which the density plot was drawn.

Return type:

Axes

plotez.plot_two_column_file(file_name, delimiter=',', skip_header=False, x_label='X', y_label='Y', data_label='XY Data', plot_title='XY Plot', 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) – The label for the x-axis.

  • y_label (str) – The label for the y-axis.

  • data_label (str) – Data label for the plot to put in the legend. Defaults to ‘X vs Y’.

  • plot_title (str) – The title for the plot.

  • 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:

The axes object of the plot.

Return type:

Axes

Raises:

Dual-Axis Plots#

plotez.plot_xyy(x_data, y1_data, y2_data, x_label='X', y1_label='Y$_1$', y2_label='Y$_2$', data_labels=None, plot_title='XYY Plot', 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) – The label for the x-axis.

  • y1_label (str) – The label for the first y-axis.

  • y2_label (str) – The label for the second y-axis.

  • plot_title (str) – The title for the plot.

  • data_labels (list[str] | tuple[str, ...] | None) – The labels for the two datasets. Default is (r”X vs. Y$_1$”, r”X vs. Y$_2$”).

  • 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.

Return type:

tuple[Axes, Axes]

Raises:

  • ShapeError – If any data array is not one-dimensional.

  • DataLengthError – If x_data, y1_data, and y2_data have different lengths.

plotez.plot_xxy(x1_data, x2_data, y_data, y_label='Y', x1_label='X$_1$', x2_label='X$_2$', data_labels=None, plot_title='', 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) – The label for the first x-axis.

  • x2_label (str) – The label for the second x-axis.

  • y_label (str) – The label for the y-axis.

  • plot_title (str) – The title for the plot.

  • data_labels (list[str] | tuple[str, ...] | None) – The labels for the two datasets. Default is (r”Y vs. X$_1$”, r”Y vs. X$_2$”).

  • is_scatter (bool) – Whether to create a scatter plot (True) or a line plot (False). Defaults 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 x-axis plot.

Return type:

tuple[Axes, Axes]

Raises:

  • ShapeError – If any data array is not one-dimensional.

  • DataLengthError – If x1_data, x2_data, and y_data have different lengths.

plotez.plot_with_dual_axes(x1_data, y1_data, x2_data=None, y2_data=None, x1y1_label='X$_1$ vs. Y$_1$', x1y2_label='X$_1$ vs. Y$_2$', x2y1_label='X$_2$ vs. Y$_1$', use_twin_x=False, axis_labels=None, plot_title='DualAxesPlot', 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) – Label for the plot of X1 vs. Y1.

  • x1y2_label (str) – Label for the plot of X1 vs. Y2 (when using dual Y-axes).

  • x2y1_label (str) – Label for the plot of X2 vs. Y1 (when using dual X-axes).

  • use_twin_x (bool) – If True, creates a dual y-axis plot. If False, creates a dual x-axis plot. Default is False.

  • axis_labels (list[str] | tuple[str, ...] | None) – List or tuple of axis labels in the form [x_label, y_label1, y_label2]. Defaults to [“X”, r”Y$_1$”, r”Y$_2$”] when not provided.

  • plot_title (str) – Title of the 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

Multi-Panel Plots#

plotez.two_subplots(x_data, y_data, x_labels=None, y_labels=None, data_labels=None, plot_title='TwoSubPlots', subplot_titles=None, orientation='h', 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[ArrayLike]) – List containing x-axis data arrays for each subplot.

  • y_data (ArrayLike | list[ArrayLike]) – List containing y-axis data arrays for each subplot.

  • x_labels (list[str] | tuple[str, ...] | None) – List or tuple of labels for the x-axes in each subplot. Defaults to [r”X$_1$”, r”X$_2$”].

  • y_labels (list[str] | tuple[str, ...] | None) – List or tuple of labels for the y-axes in each subplot. Defaults to [r”Y$_1$”, r”Y$_2$”].

  • data_labels (list[str] | tuple[str, ...] | None) – List or tuple of labels for the data series in each subplot. Defaults to [r”X$_1$ vs. Y$_1$”, r”X$_2$ vs. Y$_2$”].

  • plot_title (str) – Title of the plot.

  • subplot_titles (list[str] | tuple[str, ...] | None) – List or tuple of titles for the individual subplots, if required.

  • orientation (str) – Orientation of the subplots, either ‘h’ for horizontal or ‘v’ for vertical.

  • 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 shaped (n_rows, n_cols) array of Matplotlib Axes objects.

Return type:

NDArray

Raises:

  • DataError – If fewer x- or y-datasets are supplied than the requested grid requires.

  • OrientationError – If orientation is not ‘h’ or ‘v’.

plotez.n_plotter(x_data, y_data, n_rows, n_cols, x_labels=None, y_labels=None, data_labels=None, plot_title=None, subplot_titles=None, 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[ArrayLike]) – List of x-axis data arrays for each subplot.

  • y_data (ArrayLike | list[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 (list[str] | tuple[str, ...] | None) – List or tuple of labels for the x-axes of each subplot.

  • y_labels (list[str] | tuple[str, ...] | None) – List or tuple of labels for the y-axes of each subplot.

  • data_labels (list[str] | tuple[str, ...] | None) – List or tuple of labels for the data series in each subplot.

  • plot_title (str | None) – Title of the plot.

  • subplot_titles (list[str] | tuple[str, ...] | None) – List or tuple of titles for the individual subplots, if required.

  • 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 shaped (n_rows, n_cols) array of Matplotlib Axes objects.

Return type:

NDArray

Raises:

DataError – If fewer x- or y-datasets are supplied than the requested grid requires.