matplotlib

matplotlib Best Practices

Matplotlib is the bedrock of Python data visualization. Adhering to these guidelines ensures your plots are not just visually appealing, but also robust, performant, and easily integrated into production AI/ML and data science pipelines.

1. Code Organization & Structure

1.1 Standard Imports

Always use the conventional aliases. This improves readability and consistency across projects.

❌ BAD:

import numpy
import matplotlib.pyplot
import matplotlib

✅ GOOD:

import numpy as np
import matplotlib.pyplot as plt
import matplotlib as mpl

1.2 Object-Oriented API First

Prioritize the object-oriented API (Figure and Axes objects) over pyplot's stateful interface. This leads to more explicit, reproducible, and testable code, especially in functions or classes.

❌ BAD (Stateful pyplot):

plt.plot([1, 2, 3], [4, 5, 6])
plt.title("My Plot")
plt.xlabel("X-axis")
plt.ylabel("Y-axis")
plt.show() # Blocks execution

✅ GOOD (Object-Oriented):

from typing import List
import matplotlib.figure as mpl_figure
import matplotlib.axes as mpl_axes

def create_my_plot(data_x: List[float], data_y: List[float], title: str, x_label: str, y_label: str) -> mpl_figure.Figure:
    fig, ax = plt.subplots(figsize=(8, 6))
    ax.plot(data_x, data_y)
    ax.set_title(title)
    ax.set_xlabel(x_label)
    ax.set_ylabel(y_label)
    return fig

# Usage in a script or notebook
if __name__ == "__main__":
    x = [1, 2, 3]
    y = [4, 5, 6]
    my_figure = create_my_plot(x, y, "My Plot", "X-axis", "Y-axis")
    my_figure.savefig("my_plot.png") # Non-blocking save
    # If interactive display is needed, use:
    # plt.show()

1.3 Consistent Variable Naming

Use the standard variable names for Figure and Axes objects.

❌ BAD:

my_figure_object, my_axis_object = plt.subplots()

✅ GOOD:

fig, ax = plt.subplots()
# For multiple axes
fig, axs = plt.subplots(2, 2)

1.4 rcParams Access