Graph Utils

Helper functions for styling graphs.

add_regression_line(ax, regression_type='linear', color='red', linestyle='--', text_position=0.6, show_equation=True, show_r2=True, **kwargs)

Add a regression line with configurable algorithm to a matplotlib plot.

This function examines the data in a matplotlib Axes object and adds a regression line to it. It supports line plots, scatter plots, and bar charts (both vertical and horizontal), and can handle both numeric and datetime x-axis values.

For bar charts, the function automatically detects orientation using matplotlib's BarContainer API and extracts appropriate x,y coordinates from bar positions and heights.

Note: If an axes contains multiple plot types (e.g., both lines and bars), the function processes them in priority order: lines first, then bars, then scatter plots. Only the first available plot type will be used for regression analysis.

Parameters:

Name	Type	Description	Default
ax	Axes	The matplotlib axes object containing the plot (line, scatter, or bar).	required
regression_type	Literal['linear', 'power', 'logarithmic', 'exponential']	Regression algorithm to use. Supported values: - "linear": y = mx + b (default, OLS regression) - "power": y = ax^b (elasticity analysis, log-log transformation) - "logarithmic": y = a*ln(x) + b (diminishing returns analysis) - "exponential": y = ae^(bx) (growth/decay patterns) Defaults to "linear".	'linear'
color	str	Color of the regression line. Defaults to "red".	'red'
linestyle	str	Style of the regression line. Defaults to "--".	'--'
text_position	float	Relative position (0-1) for the equation text. Defaults to 0.6.	0.6
show_equation	bool	Whether to display the equation on the plot. Defaults to True.	True
show_r2	bool	Whether to display the R² value on the plot. Defaults to True.	True
kwargs	Any	Additional keyword arguments to pass to the plot function.	{}

Returns:

Name	Type	Description
Axes	Axes	The matplotlib axes with the regression line added.

Raises:

Type	Description
ValueError	If the plot contains no visible lines, scatter points, or bar patches, or if regression_type is not supported.

Examples:

Basic linear regression (backward compatible):

>>> ax = data.plot.scatter(x='price', y='demand')
>>> gu.add_regression_line(ax)

Power law regression for price elasticity:

>>> gu.add_regression_line(ax, regression_type="power")

Bar chart with regression line:

>>> ax = df.plot.bar(x='category', y='sales')
>>> gu.add_regression_line(ax, regression_type="linear")

Source code in openretailscience/plots/styles/graph_utils.py

def add_regression_line(
    ax: Axes,
    regression_type: Literal["linear", "power", "logarithmic", "exponential"] = "linear",
    color: str = "red",
    linestyle: str = "--",
    text_position: float = 0.6,
    show_equation: bool = True,
    show_r2: bool = True,
    **kwargs: Any,  # noqa: ANN401 - forwarded to matplotlib's ax.plot()
) -> Axes:
    """Add a regression line with configurable algorithm to a matplotlib plot.

    This function examines the data in a matplotlib Axes object and adds a
    regression line to it. It supports line plots, scatter plots, and bar charts
    (both vertical and horizontal), and can handle both numeric and datetime x-axis values.

    For bar charts, the function automatically detects orientation using matplotlib's
    BarContainer API and extracts appropriate x,y coordinates from bar positions and heights.

    Note: If an axes contains multiple plot types (e.g., both lines and bars), the function
    processes them in priority order: lines first, then bars, then scatter plots. Only the
    first available plot type will be used for regression analysis.

    Args:
        ax (Axes): The matplotlib axes object containing the plot (line, scatter, or bar).
        regression_type (Literal["linear", "power", "logarithmic", "exponential"], optional):
            Regression algorithm to use. Supported values:
            - "linear": y = mx + b (default, OLS regression)
            - "power": y = ax^b (elasticity analysis, log-log transformation)
            - "logarithmic": y = a*ln(x) + b (diminishing returns analysis)
            - "exponential": y = ae^(bx) (growth/decay patterns)
            Defaults to "linear".
        color (str, optional): Color of the regression line. Defaults to "red".
        linestyle (str, optional): Style of the regression line. Defaults to "--".
        text_position (float, optional): Relative position (0-1) for the equation text. Defaults to 0.6.
        show_equation (bool, optional): Whether to display the equation on the plot. Defaults to True.
        show_r2 (bool, optional): Whether to display the R² value on the plot. Defaults to True.
        kwargs: Additional keyword arguments to pass to the plot function.

    Returns:
        Axes: The matplotlib axes with the regression line added.

    Raises:
        ValueError: If the plot contains no visible lines, scatter points, or bar patches, or if
            regression_type is not supported.

    Examples:
        Basic linear regression (backward compatible):
        >>> ax = data.plot.scatter(x='price', y='demand')
        >>> gu.add_regression_line(ax)

        Power law regression for price elasticity:
        >>> gu.add_regression_line(ax, regression_type="power")

        Bar chart with regression line:
        >>> ax = df.plot.bar(x='category', y='sales')
        >>> gu.add_regression_line(ax, regression_type="linear")
    """
    # Validate regression type
    supported_types = ["linear", "power", "logarithmic", "exponential"]
    if regression_type not in supported_types:
        error_msg = f"Unsupported regression_type '{regression_type}'. Supported types: {supported_types}"
        raise ValueError(error_msg)

    # Extract data from the plot
    x_data, y_data = _extract_plot_data(ax)

    # Convert to numeric data and validate
    x_numeric, y_numeric = _prepare_numeric_data(x_data, y_data)

    # Apply algorithm-specific data validation
    _validate_regression_data(x_numeric, y_numeric, regression_type)

    # Perform regression calculation
    param1, param2, r_squared = _perform_regression_calculation(regression_type, x_numeric, y_numeric)

    # Generate regression line points
    x_min, x_max = ax.get_xlim()
    data_size = len(x_numeric)
    x_line, y_line = _generate_regression_line(regression_type, param1, param2, x_min, x_max, data_size)

    if len(x_line) == 0:
        warnings.warn(
            f"Regression line for '{regression_type}' produced no finite values in the visible range. "
            "Consider adjusting axis limits or using a different regression type.",
            UserWarning,
            stacklevel=2,
        )
        return ax

    # Plot the regression line
    ax.plot(x_line, y_line, color=color, linestyle=linestyle, **kwargs)

    # Add equation and R² text if either is requested
    if show_equation or show_r2:
        _add_equation_text(ax, param1, param2, r_squared, color, text_position, show_equation, show_r2, regression_type)

    return ax

add_source_text(ax, source_text, font_size=None, vertical_padding=2, is_venn_diagram=False)

Add source text to the bottom left corner of a graph using styling helpers.

Parameters:

Name	Type	Description	Default
ax	Axes	The graph to add the source text to.	required
source_text	str	The source text.	required
font_size	float	The font size of the source text. If None, uses styling context default.	None
vertical_padding	float	The padding in ems below the x-axis label. Defaults to 2.	2
is_venn_diagram	bool	Flag to indicate if the diagram is a Venn diagram. If True, x_norm and y_norm will be set to fixed values. Defaults to False.	False

Returns:

Name	Type	Description
Text	Text	The source text.

Source code in openretailscience/plots/styles/graph_utils.py

def add_source_text(
    ax: Axes,
    source_text: str,
    font_size: float | None = None,
    vertical_padding: float = 2,
    is_venn_diagram: bool = False,
) -> Text:
    """Add source text to the bottom left corner of a graph using styling helpers.

    Args:
        ax (Axes): The graph to add the source text to.
        source_text (str): The source text.
        font_size (float, optional): The font size of the source text. If None, uses styling context default.
        vertical_padding (float, optional): The padding in ems below the x-axis label. Defaults to 2.
        is_venn_diagram (bool, optional): Flag to indicate if the diagram is a Venn diagram.
            If True, `x_norm` and `y_norm` will be set to fixed values. Defaults to False.

    Returns:
        Text: The source text.
    """
    plot_styler = PlotStyler()

    return plot_styler.apply_source_text(
        ax=ax,
        text=source_text,
        font_size=font_size,
        vertical_padding=vertical_padding,
        is_venn_diagram=is_venn_diagram,
    )

apply_hatches(ax, num_segments)

Apply hatch patterns to patches in a plot, such as bars, histograms, or area plots.

This function divides the patches in the given Axes object into the specified number of segments and applies a different hatch pattern to each segment.

Parameters:

Name	Type	Description	Default
ax	Axes	The matplotlib Axes object containing the plot with patches (bars, histograms, etc.).	required
num_segments	int	The number of segments to divide the patches into, with each segment receiving a different hatch pattern.	required

Returns:

Name	Type	Description
Axes	Axes	The modified Axes object with hatches applied to the patches.

Source code in openretailscience/plots/styles/graph_utils.py

def apply_hatches(ax: Axes, num_segments: int) -> Axes:
    """Apply hatch patterns to patches in a plot, such as bars, histograms, or area plots.

    This function divides the patches in the given Axes object into the specified
    number of segments and applies a different hatch pattern to each segment.

    Args:
        ax (Axes): The matplotlib Axes object containing the plot with patches (bars, histograms, etc.).
        num_segments (int): The number of segments to divide the patches into, with each
            segment receiving a different hatch pattern.

    Returns:
        Axes: The modified Axes object with hatches applied to the patches.
    """
    available_hatches = _hatches_gen()
    patch_groups = np.array_split(ax.patches, num_segments)
    for patch_group in patch_groups:
        hatch = next(available_hatches)
        for patch in patch_group:
            patch.set_hatch(hatch)

    legend = ax.get_legend()
    if legend:
        existing_hatches = [patch.get_hatch() for patch in ax.patches if patch.get_hatch() is not None]
        unique_hatches = [hatch for idx, hatch in enumerate(existing_hatches) if hatch not in existing_hatches[:idx]]
        for legend_patch, hatch in zip(legend.get_patches(), cycle(unique_hatches)):
            legend_patch.set_hatch(hatch)

    return ax

get_decimals(ylim, tick_values, max_decimals=10)

Helper function for the human_format function that determines the number of decimals to use for the y-axis.

Parameters:

Name	Type	Description	Default
ylim	tuple[float, float]	The y-axis limits.	required
tick_values	list[float]	The y-axis tick values.	required
max_decimals	int	The maximum number of decimals to use. Defaults to 10.	10

Returns:

Name	Type	Description
int	int	The number of decimals to use.

Source code in openretailscience/plots/styles/graph_utils.py

def get_decimals(ylim: tuple[float, float], tick_values: list[float], max_decimals: int = 10) -> int:
    """Helper function for the `human_format` function that determines the number of decimals to use for the y-axis.

    Args:
        ylim (tuple[float, float]): The y-axis limits.
        tick_values (list[float]): The y-axis tick values.
        max_decimals (int, optional): The maximum number of decimals to use. Defaults to 10.

    Returns:
        int: The number of decimals to use.
    """
    decimals = 0
    while decimals < max_decimals:
        tick_labels = [human_format(t, 0, decimals=decimals) for t in tick_values if t >= ylim[0] and t <= ylim[1]]
        # Ensure no duplicate labels
        if len(tick_labels) == len(set(tick_labels)):
            break
        decimals += 1
    return decimals

human_format(num, pos=None, decimals=0, prefix='')

Format a number in a human-readable format for Matplotlib, discarding trailing zeros.

Parameters:

Name	Type	Description	Default
num	float	The number to format.	required
pos	int	The position. Defaults to None. Only used for Matplotlib compatibility.	None
decimals	int	The number of decimals. Defaults to 0.	0
prefix	str	The prefix of the returned string, eg '$'. Defaults to "".	''

Returns:

Name	Type	Description
str	str	The formatted number, with trailing zeros removed.

Source code in openretailscience/plots/styles/graph_utils.py

def human_format(
    num: float,
    pos: int | None = None,  # noqa: ARG001 (pos is only used for Matplotlib compatibility)
    decimals: int = 0,
    prefix: str = "",
) -> str:
    """Format a number in a human-readable format for Matplotlib, discarding trailing zeros.

    Args:
        num (float): The number to format.
        pos (int, optional): The position. Defaults to None. Only used for Matplotlib compatibility.
        decimals (int, optional): The number of decimals. Defaults to 0.
        prefix (str, optional): The prefix of the returned string, eg '$'. Defaults to "".

    Returns:
        str: The formatted number, with trailing zeros removed.
    """
    # The minimum difference between two numbers to receive a different suffix
    minimum_magnitude_difference = 1000.0
    magnitude = 0

    # Keep dividing by 1000 until the number is small enough
    while abs(num) >= minimum_magnitude_difference:
        magnitude += 1
        num /= minimum_magnitude_difference

    # Check if the number rounds to exactly 1000 at the current magnitude
    if round(abs(num), decimals) == minimum_magnitude_difference:
        num /= minimum_magnitude_difference
        magnitude += 1

    # If magnitude exceeds the predefined suffixes, continue with multiples of "P"
    if magnitude < len(_MAGNITUDE_SUFFIXES):
        suffix = _MAGNITUDE_SUFFIXES[magnitude]
    else:
        # Calculate how many times beyond "P" we've gone and append that to "P"
        extra_magnitude = magnitude - (len(_MAGNITUDE_SUFFIXES) - 1)
        suffix = f"{1000**extra_magnitude}P"

    # Format the number and remove trailing zeros
    formatted_num = f"{prefix}%.{decimals}f" % num
    formatted_num = formatted_num.rstrip("0").rstrip(".") if "." in formatted_num else formatted_num

    return f"{formatted_num}{suffix}"

not_none(value1, value2)

Helper function that returns the first value that is not None.

Parameters:

Name	Type	Description	Default
value1	Any	The first value.	required
value2	Any	The second value.	required

Returns:

Type	Description
Any	The first value that is not None.

Source code in openretailscience/plots/styles/graph_utils.py

def not_none(value1: Any, value2: Any) -> Any:  # noqa: ANN401
    """Helper function that returns the first value that is not None.

    Args:
        value1: The first value.
        value2: The second value.

    Returns:
        The first value that is not None.
    """
    if value1 is None:
        return value2
    return value1

set_axis_percent(fmt_axis, xmax=1, decimals=None, symbol='%')

Format an axis to display values as percentages.

This function configures a matplotlib axis to display its tick labels as percentages using matplotlib's PercentFormatter.

Parameters:

Name	Type	Description	Default
fmt_axis	YAxis | XAxis	The axis to format (either ax.yaxis or ax.xaxis).	required
xmax	float	The value that represents 100%. Defaults to 1.	1
decimals	int | None	Number of decimal places to include. If None, automatically selects based on data range. Defaults to None.	None
symbol	str | None	The symbol to use for percentage. If None, no symbol is displayed. Defaults to "%".	'%'

Returns:

Name	Type	Description
None	None	The function modifies the axis formatter in place.

Example

import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot([0, 0.25, 0.5, 0.75, 1.0], [0, 0.3, 0.5, 0.7, 1.0])
# Format y-axis as percentage
set_axis_percent(ax.yaxis)
# Format x-axis as percentage with 1 decimal place
set_axis_percent(ax.xaxis, decimals=1)

Source code in openretailscience/plots/styles/graph_utils.py

def set_axis_percent(
    fmt_axis: YAxis | XAxis,
    xmax: float = 1,
    decimals: int | None = None,
    symbol: str | None = "%",
) -> None:
    """Format an axis to display values as percentages.

    This function configures a matplotlib axis to display its tick labels as percentages
    using matplotlib's PercentFormatter.

    Args:
        fmt_axis (YAxis | XAxis): The axis to format (either ax.yaxis or ax.xaxis).
        xmax (float, optional): The value that represents 100%. Defaults to 1.
        decimals (int | None, optional): Number of decimal places to include. If None,
            automatically selects based on data range. Defaults to None.
        symbol (str | None, optional): The symbol to use for percentage. If None,
            no symbol is displayed. Defaults to "%".

    Returns:
        None: The function modifies the axis formatter in place.

    Example:
        ```python
        import matplotlib.pyplot as plt
        fig, ax = plt.subplots()
        ax.plot([0, 0.25, 0.5, 0.75, 1.0], [0, 0.3, 0.5, 0.7, 1.0])
        # Format y-axis as percentage
        set_axis_percent(ax.yaxis)
        # Format x-axis as percentage with 1 decimal place
        set_axis_percent(ax.xaxis, decimals=1)
        ```
    """
    return fmt_axis.set_major_formatter(mtick.PercentFormatter(xmax=xmax, decimals=decimals, symbol=symbol))

standard_graph_styles(ax, title=None, x_label=None, y_label=None, title_pad=None, x_label_pad=None, y_label_pad=None, legend_title=None, move_legend_outside=False, show_legend=True)

Apply standard styles to a Matplotlib graph using styling helpers.

Parameters:

Name	Type	Description	Default
ax	Axes	The graph to apply the styles to.	required
title	str	The title of the graph. Defaults to None.	None
x_label	str	The x-axis label. Defaults to None.	None
y_label	str	The y-axis label. Defaults to None.	None
title_pad	int	The padding above the title. Defaults to styling context default.	None
x_label_pad	int	The padding below the x-axis label. Defaults to styling context default.	None
y_label_pad	int	The padding to the left of the y-axis label. Defaults to styling context default.	None
legend_title	str	The title of the legend. If None, no legend title is applied. Defaults to None.	None
move_legend_outside	bool	Whether to move the legend outside the plot. Defaults to False.	False
show_legend	bool	Whether to display the legend or not.	True

Returns:

Name	Type	Description
Axes	Axes	The graph with the styles applied.

Source code in openretailscience/plots/styles/graph_utils.py

def standard_graph_styles(
    ax: Axes,
    title: str | None = None,
    x_label: str | None = None,
    y_label: str | None = None,
    title_pad: int | None = None,
    x_label_pad: int | None = None,
    y_label_pad: int | None = None,
    legend_title: str | None = None,
    move_legend_outside: bool = False,
    show_legend: bool = True,
) -> Axes:
    """Apply standard styles to a Matplotlib graph using styling helpers.

    Args:
        ax (Axes): The graph to apply the styles to.
        title (str, optional): The title of the graph. Defaults to None.
        x_label (str, optional): The x-axis label. Defaults to None.
        y_label (str, optional): The y-axis label. Defaults to None.
        title_pad (int, optional): The padding above the title. Defaults to styling context default.
        x_label_pad (int, optional): The padding below the x-axis label. Defaults to styling context default.
        y_label_pad (int, optional): The padding to the left of the y-axis label. Defaults to styling context default.
        legend_title (str, optional): The title of the legend. If None, no legend title is applied. Defaults to None.
        move_legend_outside (bool, optional): Whether to move the legend outside the plot. Defaults to False.
        show_legend (bool): Whether to display the legend or not.

    Returns:
        Axes: The graph with the styles applied.
    """
    plot_styler = PlotStyler()

    # Apply base plot styling
    plot_styler.apply_base_styling(ax)

    # Apply text styling
    if title is not None:
        plot_styler.apply_title(ax, title, title_pad)

    if x_label is not None:
        plot_styler.apply_label(ax, x_label, "x", x_label_pad)

    if y_label is not None:
        plot_styler.apply_label(ax, y_label, "y", y_label_pad)

    # Apply tick styling
    plot_styler.apply_ticks(ax)

    # Apply legend styling if needed
    if show_legend and (ax.get_legend() is not None or legend_title is not None or move_legend_outside):
        plot_styler.apply_legend(ax, legend_title, move_legend_outside)

    return ax

standard_tick_styles(ax)

Apply standard tick styles using styling helpers.

Parameters:

Name	Type	Description	Default
ax	Axes	The graph to apply the styles to.	required

Returns:

Name	Type	Description
Axes	Axes	The graph with the styles applied.

Source code in openretailscience/plots/styles/graph_utils.py

def standard_tick_styles(ax: Axes) -> Axes:
    """Apply standard tick styles using styling helpers.

    Args:
        ax (Axes): The graph to apply the styles to.

    Returns:
        Axes: The graph with the styles applied.
    """
    plot_styler = PlotStyler()
    plot_styler.apply_ticks(ax)
    return ax

truncate_to_x_digits(num_str, digits)

Truncate a human-formatted number to the first num_digits significant digits.

Parameters:

Name	Type	Description	Default
num_str	str	The formatted number (e.g., '999.999K').	required
digits	int	The number of digits to keep.	required

Returns:

Name	Type	Description
str	str	The truncated formatted number (e.g., '999.9K').

Source code in openretailscience/plots/styles/graph_utils.py

def truncate_to_x_digits(num_str: str, digits: int) -> str:
    """Truncate a human-formatted number to the first `num_digits` significant digits.

    Args:
        num_str (str): The formatted number (e.g., '999.999K').
        digits (int): The number of digits to keep.

    Returns:
        str: The truncated formatted number (e.g., '999.9K').
    """
    # Split the number part and the suffix (e.g., "999.999K" -> "999.999" and "K")
    suffix = ""
    for s in _MAGNITUDE_SUFFIXES:
        if num_str.endswith(s) and s != "":
            suffix = s
            num_str = num_str[: -len(s)]  # Remove the suffix for now
            break

    # Handle negative numbers
    is_negative = num_str.startswith("-")
    if is_negative:
        num_str = num_str[1:]  # Remove the negative sign for now

    # Handle zero case explicitly
    if float(num_str) == 0:
        return f"0{suffix}"

    # Handle small numbers explicitly to avoid scientific notation
    scientific_notation_threshold = 1e-4
    if abs(float(num_str)) < scientific_notation_threshold:
        return f"{float(num_str):.{digits}f}".rstrip("0").rstrip(".")

    digits_before_decimal = len(num_str.split(".")[0])
    # Calculate how many digits to keep after the decimal
    digits_to_keep_after_decimal = digits - digits_before_decimal

    # Ensure truncation without rounding
    if digits_to_keep_after_decimal > 0:
        factor = 10**digits_to_keep_after_decimal
        truncated_num = str(int(float(num_str) * factor) / factor)
    else:
        factor = 10**digits
        truncated_num = str(int(float(num_str) * factor) / factor)

    # Reapply the negative sign if needed
    if is_negative:
        truncated_num = f"-{truncated_num}"

    # Remove unnecessary trailing zeros and decimal point
    truncated_num = truncated_num.rstrip("0").rstrip(".")

    return f"{truncated_num}{suffix}"