Matplotlib

Source: https://github.com/aipoch/medical-research-skills

Matplotlib

When to Use

• Use this skill when you need a low-level plotting library for comprehensive customization. use when fine-grained control over every plot element is needed, creating new types of charts, or integrating into specific scientific workflows. can export to png/pdf/svg for publication. for quick statistical charts, use seaborn; for interactive charts, use plotly; for journal-style, publication-ready multi-panel charts, use scientific-visualization in a reproducible workflow.
• Use this skill when a data analytics task needs a packaged method instead of ad-hoc freeform output.
• Use this skill when the user expects a concrete deliverable, validation step, or file-based result.
• Use this skill when scripts/plot_template.py is the most direct path to complete the request.
• Use this skill when you need the matplotlib package behavior rather than a generic answer.

Key Features

• Scope-focused workflow aligned to: A low-level plotting library for comprehensive customization. Use when fine-grained control over every plot element is needed, creating new types of charts, or integrating into specific scientific workflows. Can export to PNG/PDF/SVG for publication. For quick statistical charts, use seaborn; for interactive charts, use plotly; for journal-style, publication-ready multi-panel charts, use scientific-visualization.
• Packaged executable path(s): scripts/plot_template.py plus 1 additional script(s).
• Reference material available in references/ for task-specific guidance.
• Structured execution path designed to keep outputs consistent and reviewable.

Dependencies

• Python: 3.10+. Repository baseline for current packaged skills.
• Third-party packages: not explicitly version-pinned in this skill package. Add pinned versions if this skill needs stricter environment control.

Example Usage

cd "20260316/scientific-skills/Data Analytics/matplotlib"
python -m py_compile scripts/plot_template.py
python scripts/plot_template.py --help

Example run plan:

1. Confirm the user input, output path, and any required config values.
2. Edit the in-file CONFIG block or documented parameters if the script uses fixed settings.
3. Run python scripts/plot_template.py with the validated inputs.
4. Review the generated output and return the final artifact with any assumptions called out.

Implementation Details

See ## Overview above for related details.

• Execution model: validate the request, choose the packaged workflow, and produce a bounded deliverable.
• Input controls: confirm the source files, scope limits, output format, and acceptance criteria before running any script.
• Primary implementation surface: scripts/plot_template.py with additional helper scripts under scripts/.
• Reference guidance: references/ contains supporting rules, prompts, or checklists.
• Parameters to clarify first: input path, output path, scope filters, thresholds, and any domain-specific constraints.
• Output discipline: keep results reproducible, identify assumptions explicitly, and avoid undocumented side effects.

Overview

Matplotlib is Python's fundamental visualization library for creating static, animated, and interactive plots. This skill provides guidance on using matplotlib effectively, covering both the pyplot interface (MATLAB-style) and the Object-Oriented interface (Figure/Axes), along with best practices for creating publication-quality visualizations.

When to Use This Skill

Use this skill in the following scenarios:

• Creating any type of plot or chart (line, scatter, bar, histogram, heatmap, contour, etc.)
• Generating scientific or statistical visualizations
• Customizing plot appearance (colors, styles, labels, legends)
• Creating multi-panel plots with subplots
• Exporting visualizations to various formats (PNG, PDF, SVG, etc.)
• Building interactive plots or animations
• Handling 3D visualizations
• Integrating plots into Jupyter Notebooks or GUI applications

Core Concepts

Matplotlib Hierarchy

Matplotlib uses an object hierarchy:

1. Figure - Top-level container for all plot elements
2. Axes - The actual plotting area where data is displayed (a Figure can contain multiple Axes)
3. Artist - Everything visible on the plot (lines, text, ticks, etc.)
4. Axis - The axis objects that handle ticks and labels (x-axis, y-axis)

Two Interfaces

1. pyplot Interface (Implicit, MATLAB-style)

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()

• Convenient for quick, simple plots
• Automatically maintains state
• Suitable for interactive work and simple scripts

2. Object-Oriented Interface (Explicit)

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()

• Recommended for most use cases
• More explicit control over Figure and Axes
• Better for complex plots with multiple subplots
• Easier to maintain and debug

Common Workflows

1. Basic Plot Creation

Single plot workflow:

import matplotlib.pyplot as plt
import numpy as np

# Create figure and axes (OO interface - recommended)
fig, ax = plt.subplots(figsize=(10, 6))

# Generate and plot data
x = np.linspace(0, 2*np.pi, 100)
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')

# Customize
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Trigonometric Functions')
ax.legend()
ax.grid(True, alpha=0.3)

# Save and/or display
plt.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()

2. Multiple Subplots

Creating subplot layouts:

# Method 1: Regular grid
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
axes[0, 0].plot(x, y1)
axes[0, 1].scatter(x, y2)
axes[1, 0].bar(categories, values)
axes[1, 1].hist(data, bins=30)

# Method 2: Mosaic layout (more flexible)
fig, axes = plt.subplot_mosaic([['left', 'right_top'],
                                 ['left', 'right_bottom']],
                                figsize=(10, 8))
axes['left'].plot(x, y)
axes['right_top'].scatter(x, y)
axes['right_bottom'].hist(data)

# Method 3: GridSpec (maximum control)
from matplotlib.gridspec import GridSpec
fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig)
ax1 = fig.add_subplot(gs[0, :])  # First row, all columns
ax2 = fig.add_subplot(gs[1:, 0])  # Bottom two rows, first column
ax3 = fig.add_subplot(gs[1:, 1:])  # Bottom two rows, last two columns

3. Plot Types and Use Cases

Line plots - Time series, continuous data, trends

ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')

Scatter plots - Relationships between variables, correlations

ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')

Bar charts - Category comparisons

ax.bar(categories, values, color='steelblue', edgecolor='black')

# Horizontal bar chart:
ax.barh(categories, values)

Histograms - Distribution

ax.hist(data, bins=30, edgecolor='black', alpha=0.7)

Heatmaps - Matrix data, correlations

im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)

Contour plots - 3D data on 2D plane

contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)

Box plots - Statistical distributions

ax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])

Violin plots - Distribution density

ax.violinplot([data1, data2, data3], positions=[1, 2, 3])

For complete plot type examples and variants, see references/plot_types.md.

4. Styling and Customization

Color specification methods:

• Named colors: 'red', 'blue', 'steelblue'
• Hex codes: '#FF5733'
• RGB tuples: (0.1, 0.2, 0.3)
• Colormaps: cmap='viridis', cmap='plasma', cmap='coolwarm'

Using style sheets:

plt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style

# Available: 'ggplot', 'bmh', 'fivethirtyeight', etc.
print(plt.style.available)  # List all available styles

Customizing with rcParams:

plt.rcParams['font.size'] = 12
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['axes.titlesize'] = 16
plt.rcParams['xtick.labelsize'] = 10
plt.rcParams['ytick.labelsize'] = 10
plt.rcParams['legend.fontsize'] = 12
plt.rcParams['figure.titlesize'] = 18

Text and annotations:

ax.text(x, y, 'annotation', fontsize=12, ha='center')
ax.annotate('important point', y), xytext=(x+1, y+1),
            arrowprops xy=(x,=dict(arrowstyle='->', color='red'))

For detailed styling options and colormap guidance, see references/styling_guide.md.

5. Saving Plots

Exporting to various formats:

# High-resolution PNG for presentations/papers
plt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

# Vector formats for publication (scalable)
plt.savefig('figure.pdf', bbox_inches='tight')
plt.savefig('figure.svg', bbox_inches='tight')

# Transparent background
plt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

Important parameters:

• dpi: Resolution (300 for print, 150 for web, 72 for screen)
• bbox_inches='tight': Remove extra white margins
• facecolor='white': Ensure white background (useful for dark themes)
• transparent=True: Transparent background