gsplot.style.legend#

Functions

legend(ax, *args, **kwargs)

Adds a legend to the specified axis.

legend_axes(*args, **kwargs)

Adds legends to all axes in the current Matplotlib figure.

legend_get_handlers(ax)

Retrieves the legend handles, labels, and associated handlers for the specified axis.

legend_handlers(ax[, handles, labels, handlers])

Adds a legend with custom handles, labels, and handlers to the specified axis.

legend_reverse(ax[, handles, labels, handlers])

Adds a legend to the specified axis with reversed order of handles and labels.
legend(ax, *args, **kwargs)[source]#

Adds a legend to the specified axis.

Parameters:

  • ax (matplotlib.axes.Axes) – The target axis for the legend.

  • *args (Any) – Additional positional arguments for the legend.

  • **kwargs (Any) – Additional keyword arguments for the legend.

Notes

This function utilizes the ParamsGetter to retrieve bound parameters and the CreateClassParams class to handle the merging of default, configuration, and passed parameters.

Returns:

The created legend object.

Return type:

matplotlib.legend.Legend

Examples

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> import gsplot as gs
>>> x = np.linspace(0, 10, 100)
>>> plt.plot(x, np.sin(x), label="Sine")
>>> plt.plot(x, np.cos(x), label="Cosine")
>>> gs.legend(plt.gcf()[0])  # Adds legend to the first axis
>>> plt.show()
legend_axes(*args, **kwargs)[source]#

Adds legends to all axes in the current Matplotlib figure.

Parameters:

  • *args (Any) – Additional positional arguments for legends.

  • **kwargs (Any) – Additional keyword arguments for legends.

Notes

This function utilizes the ParamsGetter to retrieve bound parameters and the CreateClassParams class to handle the merging of default, configuration, and passed parameters.

Returns:

A list of legend objects created for each axis.

Return type:

list[matplotlib.legend.Legend]

Examples

>>> import matplotlib.pyplot as plt
>>> fig, axes = plt.subplots(2, 1)
>>> import gsplot as gs
>>> axes[0].plot([1, 2, 3], [4, 5, 6], label="Line 1")
>>> axes[1].plot([1, 2, 3], [6, 5, 4], label="Line 2")
>>> gs.legend_axes()  # Adds legends to all axes
>>> plt.show()
legend_get_handlers(ax)[source]#

Retrieves the legend handles, labels, and associated handlers for the specified axis.

Parameters:

ax (Axes) – The target axis for retrieving the legend handlers. Can be an axis index or an Axes object.

Returns:

  • handles: The list of legend handles.

  • labels: The list of legend labels.

  • handlers: A dictionary mapping handles to their legend handlers.

Return type:

tuple

Examples

>>> import matplotlib.pyplot as plt
>>> import gsplot as gs
>>> fig, ax = plt.subplots()
>>> ax.plot([0, 1], [0, 1], label="Line A")
>>> ax.plot([1, 0], [0, 1], label="Line B")
>>> handles, labels, handlers = gs.legend_get_handlers(ax)
>>> print("Handles:", handles)
>>> print("Labels:", labels)
>>> print("Handlers:", handlers)
legend_handlers(ax, handles=None, labels=None, handlers=None, *args, **kwargs)[source]#

Adds a legend with custom handles, labels, and handlers to the specified axis.

Parameters:

  • ax (Axes) – The target axis for the legend. Can be an axis index or an Axes object.

  • handles (list[Any], optional) – A list of custom handles for the legend.

  • labels (list[str], optional) – A list of custom labels for the legend.

  • handlers (dict, optional) – A dictionary of custom legend handlers.

  • *args (Any) – Additional positional arguments for the legend.

  • **kwargs (Any) – Additional keyword arguments for the legend.

Notes

This function utilizes the ParamsGetter to retrieve bound parameters and the CreateClassParams class to handle the merging of default, configuration, and passed parameters.

Returns:

The created legend object with the provided custom handlers.

Return type:

matplotlib.legend.Legend

Examples

>>> import matplotlib.pyplot as plt
>>> from matplotlib.lines import Line2D
>>> import gsplot as gs
>>> fig, ax = plt.subplots()
>>> ax.plot([0, 1], [0, 1], label="Line A")
>>> custom_handle = [Line2D([0], [0], color="r", lw=2)]
>>> gs.legend_handlers(ax, handles=custom_handle, labels=["Custom Line"])
>>> plt.show()
legend_reverse(ax, handles=None, labels=None, handlers=None, *args, **kwargs)[source]#

Adds a legend to the specified axis with reversed order of handles and labels.

Parameters:

  • ax (Axes) – The target axis for the legend. Can be an axis index or an Axes object.

  • handles (list[Any], optional) – A list of custom handles for the legend.

  • labels (list[str], optional) – A list of custom labels for the legend.

  • handlers (dict, optional) – A dictionary of custom legend handlers.

  • *args (Any) – Additional positional arguments for the legend.

  • **kwargs (Any) – Additional keyword arguments for the legend.

Notes

This function utilizes the ParamsGetter to retrieve bound parameters and the CreateClassParams class to handle the merging of default, configuration, and passed parameters.

Returns:

The created legend object with reversed order.

Return type:

matplotlib.legend.Legend

Examples

>>> import matplotlib.pyplot as plt
>>> x = [1, 2, 3]
>>> y1 = [4, 5, 6]
>>> y2 = [6, 5, 4]
>>> plt.plot(x, y1, label="Line 1")
>>> plt.plot(x, y2, label="Line 2")
>>> legend_reverse(plt.gca()[0])  # Reverses the legend order
>>> plt.show()