Turn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 250,000+ scientists worldwide. 177 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.
Matplotlib API Reference
Targets Matplotlib 3.11.2. Examples are fragments requiring imports and correctly shaped named data. See the official API and 3.11 changes.
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 subplotfig.add_axes([left, bottom, width, height])- Add axes at specific positionfig.savefig(filename, dpi=300, bbox_inches='tight')- Save figurefig.tight_layout()- Adjust spacing to prevent overlapsfig.suptitle(title)- Set figure titlefig.legend()- Create figure-level legendfig.colorbar(mappable, ax=ax)- Add colorbar to figureplt.close(fig)- Close figure to free memory
Key Attributes:
fig.axes- List of all axes in the figurefig.dpi- Resolution in dots per inchfig.get_size_inches()- Figure dimensions in inches (width, height); usefig.set_size_inches(width, height)to change them
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 plotax.step(x, y, where='pre'/'mid'/'post')- Step plotax.errorbar(x, y, yerr=yerr, xerr=xerr)- Nonnegative error sizes: scalar,(N,), or(2, N)for lower/upper sizes
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 chartax.barh(y, width)- Horizontal bar chart
Statistical plots:
ax.hist(data, bins=10, density=False)- Histogramax.boxplot(data, tick_labels=None, orientation='vertical')- Box plotax.violinplot(data)- Violin plot
2D plots:
ax.imshow(array, cmap='viridis', aspect='auto')- Display image/matrixax.contour(X, Y, Z, levels=10)- Contour linesax.contourf(X, Y, Z, levels=10)- Filled contoursax.pcolormesh(X, Y, Z)- Pseudocolor plot
Filling:
ax.fill_between(x, y1, y2, alpha=0.3)- Fill between curvesax.fill_betweenx(y, x1, x2)- Fill between vertical curves
Text and annotations:
ax.text(x, y, text, fontsize=12)- Add textax.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 labelax.set_ylabel(label, fontsize=12)- Set y-axis labelax.set_title(title, fontsize=14)- Set axes title
Limits and scales:
ax.set_xlim(left, right)- Set x-axis limitsax.set_ylim(bottom, top)- Set y-axis limitsax.set_xscale('linear'/'log'/'symlog')- Set x-axis scaleax.set_yscale('linear'/'log'/'symlog')- Set y-axis scale
Ticks:
ax.set_xticks(positions)- Set x-tick positionsax.set_xticks(positions, labels)- Set x-tick positions and labels togetherax.tick_params(axis='both', labelsize=10)- Customize tick appearance
Grid and spines:
ax.grid(True, alpha=0.3, linestyle='--')- Add gridax.spines['top'].set_visible(False)- Hide top spineax.spines['right'].set_visible(False)- Hide right spine
Legend:
ax.legend(loc='best', fontsize=10, frameon=True)- Add legendax.legend(handles, labels)- Custom legend
Aspect and layout:
ax.set_aspect('equal'/'auto'/ratio)- Set aspect ratioax.invert_xaxis()- Invert x-axisax.invert_yaxis()- Invert y-axis
pyplot Module
High-level interface for quick plotting.
Figure creation:
plt.figure()- Create new figureplt.subplots()- Create figure and axesplt.subplot()- Add subplot to current figure
Plotting (uses current axes):
plt.plot()- Line plotplt.scatter()- Scatter plotplt.bar()- Bar chartplt.hist()- Histogram- Many plotting methods have pyplot wrappers; Axes setters are not all exposed with the same name (for example,
plt.xlabelwrapsax.set_xlabel).
Display and save:
plt.show()- Display figureplt.savefig()- Save figureplt.close()- Close figure
Style:
plt.style.use(style_name)- Apply style sheetplt.style.available- List available styles
State management:
plt.gca()- Get current axesplt.gcf()- Get current figureplt.sca(ax)- Set current axesplt.clf()- Clear current figureplt.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, # Marker area in points squared
c=values, # Numeric array, one value per point
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', 'DejaVu Sans']
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['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
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=fig.canvas.supports_blit)
# Keep anim alive. Pillow handles GIF; MP4 needs an external FFmpeg executable.
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
im = 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.tick_params(labelbottom=False, labelleft=False)
# Scientific notation
ax.ticklabel_format(style='scientific', axis='y', scilimits=(0,0))
# Requires ScalarFormatter (normally a linear numeric axis), not a log/date formatter.
# 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))