Utility Functions#

Shared plotting and validation helpers.

Plot Dispatch#

plotez.backend.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

plotez.backend.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.

Validation#

plotez.backend.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 | None) – 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 | None) – 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 (list[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:
Return type:

tuple[NDArray, NDArray, NDArray | None, NDArray | None]

plotez.backend.validate_1d(*arrays, names)[source]#

Verify that every supplied array is exactly 1-D.

Parameters:

  • *arrays (NDArray) – Arrays to check (already converted with np.asarray).

  • names (list[str]) – Human-readable name for each array, used in the error message.

Raises:

ShapeError – If any array has ndim != 1.

Return type:

None

plotez.backend.validate_equal_length(*arrays, names)[source]#

Verify that all supplied arrays share the same length.

Scalar (0-d) arrays are skipped — they broadcast freely and do not need a length check.

Parameters:

  • *arrays (NDArray) – Arrays to check (already converted with np.asarray).

  • names (list[str]) – Human-readable name for each array, used in the error message.

Raises:

DataLengthError – If the arrays do not all have the same length.

Return type:

None

plotez.backend.errorbar_validation(x, y, x_err, y_err)[source]#

Validate the input arrays for error bars to ensure compatibility with the provided data arrays.

Parameters:

  • x (NDArray) – The array of x-coordinate data.

  • y (NDArray) – The array of y-coordinate data.

  • x_err (ArrayLike | None) –

    The error values associated with the x-coordinate data. Can represent either symmetric or asymmetric errors.

    • If symmetric, it should be a 1D array.

    • If asymmetric, it should be a 2D array with shape (2, N).

    • Can also be None, in which case no validation is performed for x-error.

  • y_err (ArrayLike | None) –

    The error values associated with the y-coordinate data. Can represent either symmetric or asymmetric errors.

    • If symmetric, it should be a 1D array.

    • If asymmetric, it should be a 2D array with shape (2, N).

    • Can also be None, in which case no validation is performed for y-error.

Returns:

A tuple containing the validated x_err and y_err arrays, respectively. If no validation is performed for a specific error array (i.e., it is None), it is returned as None.

Return type:

tuple[NDArray | None, NDArray | None]

Raises:

  • ShapeError – Raised if the shape of x_err or y_err does not conform to valid symmetric or asymmetric error formats.

  • DataLengthError – Raised if the length of the x_err or y_err array does not match the length of x or y data array.

plotez.backend.errorband_validation(x, y, y_lower, y_upper)[source]#

Validate the input parameters for an error band visualization process.

Parameters:

  • x (NDArray) – Primary data on the x-axis to be validated.

  • y (NDArray) – Primary data on the y-axis to be validated.

  • y_lower (ArrayLike | None) – Optional lower-bound data for the error band, validated if provided.

  • y_upper (ArrayLike | None) – Optional upper-bound data for the error band, validated if provided.

Returns:

A tuple containing the validated x_err and y_err arrays, respectively. If no validation is performed for a specific error array (i.e., it is None), it is returned as None.

Return type:

tuple[NDArray | None, NDArray | None]

plotez.backend.error_offset_validation(y, y_lower, y_upper)[source]#

Validate and processes the lower and upper error offset arrays relative to a target array.

Parameters:

  • y (NDArray) – The target array against which the error offsets are validated.

  • y_lower (ArrayLike | None) – The lower error offsets. Can be None. If provided, it is validated for dimensionality and length.

  • y_upper (ArrayLike | None) – The upper error offsets. Can be None. If provided, it is validated for dimensionality and length.

Returns:

A tuple containing the validated x_lower and y_lower arrays, respectively. If no validation is performed for a specific error array (i.e., it is None), it is returned as None.

Return type:

tuple[NDArray | None, NDArray | None]