Home / matplotlib / references/api_reference.md

references/api_reference.md

Matplotlib API Reference

This document provides a quick reference for the most commonly used matplotlib classes and methods.

Core Classes

Figure

The top-level container for all plot elements.

Creation:

fig = plt.figure(figsize=(10, 6), dpi=100, facecolor='white')
fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(10, 6))
fig, axes = plt.subplots(2, 2, figsize=(12, 10))

Key Methods: - fig.add_subplot(nrows, ncols, index) - Add a subplot - fig.add_axes([left, bottom, width, height]) - Add axes at specific position - fig.savefig(filename, dpi=300, bbox_inches='tight') - Save figure - fig.tight_layout() - Adjust spacing to prevent overlaps - fig.suptitle(title) - Set figure title - fig.legend() - Create figure-level legend - fig.colorbar(mappable) - Add colorbar to figure - plt.close(fig) - Close figure to free memory

Key Attributes: - fig.axes - List of all axes in the figure - fig.dpi - Resolution in dots per inch - fig.figsize - Figure dimensions in inches (width, height)

Axes

The actual plotting area where data is visualized.

Creation:

fig, ax = plt.subplots()  # Single axes
ax = fig.add_subplot(111)  # Alternative method

Plotting Methods:

Line plots: - ax.plot(x, y, **kwargs) - Line plot - ax.step(x, y, where='pre'/'mid'/'post') - Step plot - ax.errorbar(x, y, yerr, xerr) - Error bars

Scatter plots: - ax.scatter(x, y, s=size, c=color, marker='o', alpha=0.5) - Scatter plot

Bar charts: - ax.bar(x, height, width=0.8, align='center') - Vertical bar chart - ax.barh(y, width) - Horizontal bar chart

Statistical plots: - ax.hist(data, bins=10, density=False) - Histogram - ax.boxplot(data, labels=None) - Box plot - ax.violinplot(data) - Violin plot

2D plots: - ax.imshow(array, cmap='viridis', aspect='auto') - Display image/matrix - ax.contour(X, Y, Z, levels=10) - Contour lines - ax.contourf(X, Y, Z, levels=10) - Filled contours - ax.pcolormesh(X, Y, Z) - Pseudocolor plot

Filling: - ax.fill_between(x, y1, y2, alpha=0.3) - Fill between curves - ax.fill_betweenx(y, x1, x2) - Fill between vertical curves

Text and annotations: - ax.text(x, y, text, fontsize=12) - Add text - ax.annotate(text, xy=(x, y), xytext=(x2, y2), arrowprops={}) - Annotate with arrow

Customization Methods:

Labels and titles: - ax.set_xlabel(label, fontsize=12) - Set x-axis label - ax.set_ylabel(label, fontsize=12) - Set y-axis label - ax.set_title(title, fontsize=14) - Set axes title

Limits and scales: - ax.set_xlim(left, right) - Set x-axis limits - ax.set_ylim(bottom, top) - Set y-axis limits - ax.set_xscale('linear'/'log'/'symlog') - Set x-axis scale - ax.set_yscale('linear'/'log'/'symlog') - Set y-axis scale

Ticks: - ax.set_xticks(positions) - Set x-tick positions - ax.set_xticklabels(labels) - Set x-tick labels - ax.tick_params(axis='both', labelsize=10) - Customize tick appearance

Grid and spines: - ax.grid(True, alpha=0.3, linestyle='--') - Add grid - ax.spines['top'].set_visible(False) - Hide top spine - ax.spines['right'].set_visible(False) - Hide right spine

Legend: - ax.legend(loc='best', fontsize=10, frameon=True) - Add legend - ax.legend(handles, labels) - Custom legend

Aspect and layout: - ax.set_aspect('equal'/'auto'/ratio) - Set aspect ratio - ax.invert_xaxis() - Invert x-axis - ax.invert_yaxis() - Invert y-axis

pyplot Module

High-level interface for quick plotting.

Figure creation: - plt.figure() - Create new figure - plt.subplots() - Create figure and axes - plt.subplot() - Add subplot to current figure

Plotting (uses current axes): - plt.plot() - Line plot - plt.scatter() - Scatter plot - plt.bar() - Bar chart - plt.hist() - Histogram - (All axes methods available)

Display and save: - plt.show() - Display figure - plt.savefig() - Save figure - plt.close() - Close figure

Style: - plt.style.use(style_name) - Apply style sheet - plt.style.available - List available styles

State management: - plt.gca() - Get current axes - plt.gcf() - Get current figure - plt.sca(ax) - Set current axes - plt.clf() - Clear current figure - plt.cla() - Clear current axes

Line and Marker Styles

Line Styles

  • '-' or 'solid' - Solid line
  • '--' or 'dashed' - Dashed line
  • '-.' or 'dashdot' - Dash-dot line
  • ':' or 'dotted' - Dotted line
  • '' or ' ' or 'None' - No line

Marker Styles

  • '.' - Point marker
  • 'o' - Circle marker
  • 'v', '^', '<', '>' - Triangle markers
  • 's' - Square marker
  • 'p' - Pentagon marker
  • '*' - Star marker
  • 'h', 'H' - Hexagon markers
  • '+' - Plus marker
  • 'x' - X marker
  • 'D', 'd' - Diamond markers

Color Specifications

Single character shortcuts: - 'b' - Blue - 'g' - Green - 'r' - Red - 'c' - Cyan - 'm' - Magenta - 'y' - Yellow - 'k' - Black - 'w' - White

Named colors: - 'steelblue', 'coral', 'teal', etc. - See full list: https://matplotlib.org/stable/gallery/color/named_colors.html

Other formats: - Hex: '#FF5733' - RGB tuple: (0.1, 0.2, 0.3) - RGBA tuple: (0.1, 0.2, 0.3, 0.5)

Common Parameters

Plot Function Parameters

ax.plot(x, y,
    color='blue',           # Line color
    linewidth=2,            # Line width
    linestyle='--',         # Line style
    marker='o',             # Marker style
    markersize=8,           # Marker size
    markerfacecolor='red',  # Marker fill color
    markeredgecolor='black',# Marker edge color
    markeredgewidth=1,      # Marker edge width
    alpha=0.7,              # Transparency (0-1)
    label='data',           # Legend label
    zorder=2,               # Drawing order
    rasterized=True         # Rasterize for smaller file size
)

Scatter Function Parameters

ax.scatter(x, y,
    s=50,                   # Size (scalar or array)
    c='blue',               # Color (scalar, array, or sequence)
    marker='o',             # Marker style
    cmap='viridis',         # Colormap (if c is numeric)
    alpha=0.5,              # Transparency
    edgecolors='black',     # Edge color
    linewidths=1,           # Edge width
    vmin=0, vmax=1,         # Color scale limits
    label='data'            # Legend label
)

Text Parameters

ax.text(x, y, text,
    fontsize=12,            # Font size
    fontweight='normal',    # 'normal', 'bold', 'heavy', 'light'
    fontstyle='normal',     # 'normal', 'italic', 'oblique'
    fontfamily='sans-serif',# Font family
    color='black',          # Text color
    alpha=1.0,              # Transparency
    ha='center',            # Horizontal alignment: 'left', 'center', 'right'
    va='center',            # Vertical alignment: 'top', 'center', 'bottom', 'baseline'
    rotation=0,             # Rotation angle in degrees
    bbox=dict(              # Background box
        facecolor='white',
        edgecolor='black',
        boxstyle='round'
    )
)

rcParams Configuration

Common rcParams settings for global customization:

# Font settings
plt.rcParams['font.family'] = 'sans-serif'
plt.rcParams['font.sans-serif'] = ['Arial', 'Helvetica']
plt.rcParams['font.size'] = 12

# Figure settings
plt.rcParams['figure.figsize'] = (10, 6)
plt.rcParams['figure.dpi'] = 100
plt.rcParams['figure.facecolor'] = 'white'
plt.rcParams['savefig.dpi'] = 300
plt.rcParams['savefig.bbox'] = 'tight'

# Axes settings
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['axes.titlesize'] = 16
plt.rcParams['axes.grid'] = True
plt.rcParams['axes.grid.alpha'] = 0.3

# Line settings
plt.rcParams['lines.linewidth'] = 2
plt.rcParams['lines.markersize'] = 8

# Tick settings
plt.rcParams['xtick.labelsize'] = 10
plt.rcParams['ytick.labelsize'] = 10
plt.rcParams['xtick.direction'] = 'in'  # 'in', 'out', 'inout'
plt.rcParams['ytick.direction'] = 'in'

# Legend settings
plt.rcParams['legend.fontsize'] = 12
plt.rcParams['legend.frameon'] = True
plt.rcParams['legend.framealpha'] = 0.8

# Grid settings
plt.rcParams['grid.alpha'] = 0.3
plt.rcParams['grid.linestyle'] = '--'

GridSpec for Complex Layouts

from matplotlib.gridspec import GridSpec

fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig, hspace=0.3, wspace=0.3)

# Span multiple cells
ax1 = fig.add_subplot(gs[0, :])      # Top row, all columns
ax2 = fig.add_subplot(gs[1:, 0])     # Bottom two rows, first column
ax3 = fig.add_subplot(gs[1, 1:])     # Middle row, last two columns
ax4 = fig.add_subplot(gs[2, 1])      # Bottom row, middle column
ax5 = fig.add_subplot(gs[2, 2])      # Bottom row, right column

3D Plotting

from mpl_toolkits.mplot3d import Axes3D

fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')

# Plot types
ax.plot(x, y, z)                    # 3D line
ax.scatter(x, y, z)                 # 3D scatter
ax.plot_surface(X, Y, Z)            # 3D surface
ax.plot_wireframe(X, Y, Z)          # 3D wireframe
ax.contour(X, Y, Z)                 # 3D contour
ax.bar3d(x, y, z, dx, dy, dz)       # 3D bar

# Customization
ax.set_xlabel('X')
ax.set_ylabel('Y')
ax.set_zlabel('Z')
ax.view_init(elev=30, azim=45)      # Set viewing angle

Animation

from matplotlib.animation import FuncAnimation

fig, ax = plt.subplots()
line, = ax.plot([], [])

def init():
    ax.set_xlim(0, 2*np.pi)
    ax.set_ylim(-1, 1)
    return line,

def update(frame):
    x = np.linspace(0, 2*np.pi, 100)
    y = np.sin(x + frame/10)
    line.set_data(x, y)
    return line,

anim = FuncAnimation(fig, update, init_func=init,
                     frames=100, interval=50, blit=True)

# Save animation
anim.save('animation.gif', writer='pillow', fps=20)
anim.save('animation.mp4', writer='ffmpeg', fps=20)

Image Operations

# Read and display image
img = plt.imread('image.png')
ax.imshow(img)

# Display matrix as image
ax.imshow(matrix, cmap='viridis', aspect='auto',
          interpolation='nearest', origin='lower')

# Colorbar
cbar = plt.colorbar(im, ax=ax)
cbar.set_label('Values')

# Image extent (set coordinates)
ax.imshow(img, extent=[x_min, x_max, y_min, y_max])

Event Handling

# Mouse click event
def on_click(event):
    if event.inaxes:
        print(f'Clicked at x={event.xdata:.2f}, y={event.ydata:.2f}')

fig.canvas.mpl_connect('button_press_event', on_click)

# Key press event
def on_key(event):
    print(f'Key pressed: {event.key}')

fig.canvas.mpl_connect('key_press_event', on_key)

Useful Utilities

# Get current axis limits
xlims = ax.get_xlim()
ylims = ax.get_ylim()

# Set equal aspect ratio
ax.set_aspect('equal', adjustable='box')

# Share axes between subplots
fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)

# Twin axes (two y-axes)
ax2 = ax1.twinx()

# Remove tick labels
ax.set_xticklabels([])
ax.set_yticklabels([])

# Scientific notation
ax.ticklabel_format(style='scientific', axis='y', scilimits=(0,0))

# Date formatting
import matplotlib.dates as mdates
ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
ax.xaxis.set_major_locator(mdates.DayLocator(interval=7))
← Back to matplotlib