Data Visualization Best Practices
Expert guidance for creating publication-quality scientific visualizations, avoiding common pitfalls, and optimizing figure clarity.
When to Use This Skill
- Creating figures for scientific publications
- Debugging misleading or distorted visualizations
- Optimizing figure layouts and element sizes
- Choosing appropriate plot types for data characteristics
- Ensuring statistical annotations fit properly
- Generating images for sharing with Claude or other AI tools
Supporting Files
This skill is organized into focused reference files. Load them as needed:
- pitfalls-and-troubleshooting.md - Log-scale distortion, coordinate transform bugs, outlier handling philosophy, axis range optimization, float year labels
- chart-recipes.md - Code recipes for temporal trends, boxplots, scatter plots, category proportions, stacked area charts, sample size legends, the dual-approach for outlier handling in publication figures
- color-palettes.md - Okabe-Ito palette, Paul Tol palette, sequential/diverging schemes, colorblind-safe implementation in matplotlib/seaborn
- claude-image-constraints.md - Claude API 8000px limit, safe figure size presets, resize helpers, Jupyter notebook oversized image fixes
- figure-descriptions.md - Templates for writing publication-quality figure descriptions with proper statistical reporting
- itol-reference.md - iTOL dataset formats (DATASET_STYLE, DATASET_BINARY, DATASET_COLORSTRIP), species name synchronization, troubleshooting
- journal-requirements.md - Journal-specific figure specs (Nature, Science, Cell, PLOS, ACS, IEEE, Elsevier, BMC): dimensions, DPI, formats, panel labeling, file naming
Assets (importable in notebooks/scripts)
assets/publication.mplstyle - General publication style: plt.style.use('path/to/publication.mplstyle')assets/nature.mplstyle - Nature journal style (89mm single column, 7pt fonts, 600 DPI)assets/presentation.mplstyle - Larger fonts/lines for posters and slidesassets/color_palettes.py - Importable palette definitions (Okabe-Ito, Wong, Paul Tol), apply_palette() helper, DNA base colors
Scripts (helper utilities)
scripts/figure_export.py - save_publication_figure(), save_for_journal(), check_figure_size() - export in multiple formats with journal-specific DPI/format settingsscripts/style_presets.py - apply_publication_style(), configure_for_journal(), set_color_palette() - one-command journal configuration
Core Principles
1. Always Check Log-Scale Plots
KDE-based plots (violin, ridge) on log axes produce distorted shapes. Use boxplots or log-transform data first, then plot on linear axes. See pitfalls-and-troubleshooting.md for details.
2. Show All Data First, Filter Later
Default to showing ALL data points in initial visualizations (showfliers=True). Outliers may be biologically meaningful. Only filter after review with domain expert, and always document exclusions.
3. Use Colorblind-Safe Palettes
Use Okabe-Ito palette (recommended by Nature) for categorical data. Combine color with marker shapes for redundancy. Never use red-green combinations. See color-palettes.md for hex codes and implementation.
4. Respect Claude's Image Size Limit
Images shared with Claude must not exceed 8000 pixels in either dimension. Use safe figure size presets and the save_figure() helper. See claude-image-constraints.md.
5. Position Annotations Carefully
Use pure data coordinates or ax.transAxes (0-1 range) for text positioning. Never mix coordinate systems (e.g., ax.get_xaxis_transform() with data-scale y-values). See pitfalls-and-troubleshooting.md.
Chart Selection Quick Guide
| Data Type |
Recommended Chart |
When to Use |
| Distribution comparison |
Boxplot |
Large datasets, log scales, multiple groups |
| Distribution shape |
Histogram |
Always works on log scales, shows true frequency |
| Temporal trends (few points) |
Scatter + regression |
< 50 points per timepoint, continuous time |
| Temporal trends (many points) |
Boxplots by year |
Overlapping points, discrete timepoints |
| Category proportions over time |
Stacked area + stacked bar (dual panel) |
Showing both relative and absolute trends |
| Categorical comparison |
Bar chart, violin (linear scale only) |
Group means or distributions |
| Phylogenetic annotation |
iTOL datasets |
Tree visualization with metadata |
Publication Figure Checklist
Before Creating
During Creation
After Creation
For Temporal Analyses
Quick Reference: Safe Figure Sizes (300 DPI)
FIG_SIZES = {
'single_column': (3.5, 4), # 1050x1200 px
'double_column': (7, 5), # 2100x1500 px
'full_page': (7, 9), # 2100x2700 px
'poster': (20, 15), # 6000x4500 px
'max_claude': (26, 26), # 7800x7800 px
}
Quick Reference: Okabe-Ito Colors (3 Categories)
colors = {
'Category_A': '#0072B2', # Blue
'Category_B': '#E69F00', # Orange
'Category_C': '#CC79A7' # Reddish Purple
}
Best Practices Summary
- Always check log-scale plots - Verify KDE-based plots against histograms
- Test element sizes - Regenerate with different sizes for optimal clarity
- Explicit axis limits - Don't rely on auto-limits when annotations are added
- Consistent styling - Use seaborn context and style for publication consistency
- High DPI - Save at 300 DPI minimum (
dpi=300, bbox_inches='tight')
- Optimize axis ranges - Zoom to data range when distributions are compressed
- Check image dimensions - Verify size before sharing with Claude (max 7999x7999)
- Set size constraints - Use safe figure sizes when generating images programmatically
- Temporal trends with outliers - Create both cleaned (publication) and full (verification) versions
- Include sample sizes - Always show n= in legends for comparative figures
References
1---2name: data-visualization3description: Best practices for creating clear, accurate scientific visualizations with matplotlib, seaborn, and other Python plotting libraries. Covers common pitfalls, optimization techniques, publication-quality figure generation, and Claude API image size constraints.4---5
6# Data Visualization Best Practices
7
8Expert guidance for creating publication-quality scientific visualizations, avoiding common pitfalls, and optimizing figure clarity.
9
10## When to Use This Skill
11
12- Creating figures for scientific publications
13- Debugging misleading or distorted visualizations
14- Optimizing figure layouts and element sizes
15- Choosing appropriate plot types for data characteristics
16- Ensuring statistical annotations fit properly
17- Generating images for sharing with Claude or other AI tools
18
19## Supporting Files
20
21This skill is organized into focused reference files. Load them as needed:
22
23- **[pitfalls-and-troubleshooting.md](pitfalls-and-troubleshooting.md)** - Log-scale distortion, coordinate transform bugs, outlier handling philosophy, axis range optimization, float year labels
24- **[chart-recipes.md](chart-recipes.md)** - Code recipes for temporal trends, boxplots, scatter plots, category proportions, stacked area charts, sample size legends, the dual-approach for outlier handling in publication figures
25- **[color-palettes.md](color-palettes.md)** - Okabe-Ito palette, Paul Tol palette, sequential/diverging schemes, colorblind-safe implementation in matplotlib/seaborn
26- **[claude-image-constraints.md](claude-image-constraints.md)** - Claude API 8000px limit, safe figure size presets, resize helpers, Jupyter notebook oversized image fixes
27- **[figure-descriptions.md](figure-descriptions.md)** - Templates for writing publication-quality figure descriptions with proper statistical reporting
28- **[itol-reference.md](itol-reference.md)** - iTOL dataset formats (DATASET_STYLE, DATASET_BINARY, DATASET_COLORSTRIP), species name synchronization, troubleshooting
29- **[journal-requirements.md](journal-requirements.md)** - Journal-specific figure specs (Nature, Science, Cell, PLOS, ACS, IEEE, Elsevier, BMC): dimensions, DPI, formats, panel labeling, file naming
30
31## Assets (importable in notebooks/scripts)
32
33- **`assets/publication.mplstyle`** - General publication style: `plt.style.use('path/to/publication.mplstyle')`
34- **`assets/nature.mplstyle`** - Nature journal style (89mm single column, 7pt fonts, 600 DPI)
35- **`assets/presentation.mplstyle`** - Larger fonts/lines for posters and slides
36- **`assets/color_palettes.py`** - Importable palette definitions (Okabe-Ito, Wong, Paul Tol), `apply_palette()` helper, DNA base colors
37
38## Scripts (helper utilities)
39
40- **`scripts/figure_export.py`** - `save_publication_figure()`, `save_for_journal()`, `check_figure_size()` - export in multiple formats with journal-specific DPI/format settings
41- **`scripts/style_presets.py`** - `apply_publication_style()`, `configure_for_journal()`, `set_color_palette()` - one-command journal configuration
42
43## Core Principles
44
45### 1. Always Check Log-Scale Plots
46
47KDE-based plots (violin, ridge) on log axes produce distorted shapes. Use boxplots or log-transform data first, then plot on linear axes. See [pitfalls-and-troubleshooting.md](pitfalls-and-troubleshooting.md) for details.
48
49### 2. Show All Data First, Filter Later
50
51Default to showing ALL data points in initial visualizations (`showfliers=True`). Outliers may be biologically meaningful. Only filter after review with domain expert, and always document exclusions.
52
53### 3. Use Colorblind-Safe Palettes
54
55Use Okabe-Ito palette (recommended by Nature) for categorical data. Combine color with marker shapes for redundancy. Never use red-green combinations. See [color-palettes.md](color-palettes.md) for hex codes and implementation.
56
57### 4. Respect Claude's Image Size Limit
58
59Images shared with Claude must not exceed **8000 pixels** in either dimension. Use safe figure size presets and the `save_figure()` helper. See [claude-image-constraints.md](claude-image-constraints.md).
60
61### 5. Position Annotations Carefully
62
63Use pure data coordinates or `ax.transAxes` (0-1 range) for text positioning. Never mix coordinate systems (e.g., `ax.get_xaxis_transform()` with data-scale y-values). See [pitfalls-and-troubleshooting.md](pitfalls-and-troubleshooting.md).
64
65## Chart Selection Quick Guide
66
67| Data Type | Recommended Chart | When to Use |
68|-----------|------------------|-------------|
69| Distribution comparison | Boxplot | Large datasets, log scales, multiple groups |
70| Distribution shape | Histogram | Always works on log scales, shows true frequency |
71| Temporal trends (few points) | Scatter + regression | < 50 points per timepoint, continuous time |
72| Temporal trends (many points) | Boxplots by year | Overlapping points, discrete timepoints |
73| Category proportions over time | Stacked area + stacked bar (dual panel) | Showing both relative and absolute trends |
74| Categorical comparison | Bar chart, violin (linear scale only) | Group means or distributions |
75| Phylogenetic annotation | iTOL datasets | Tree visualization with metadata |
76
77## Publication Figure Checklist
78
79### Before Creating
80
81- [ ] Choose colorblind-safe palette (Okabe-Ito recommended)
82- [ ] Plan figure dimensions within Claude's 8000px limit
83- [ ] Decide on panel layout (side-by-side vs stacked)
84
85### During Creation
86
87- [ ] Include sample sizes in legends: `Category (n=123)`
88- [ ] Use integer year labels: `ax.xaxis.set_major_locator(plt.MaxNLocator(integer=True))`
89- [ ] Set explicit axis limits when adding annotations
90- [ ] Reduce element sizes for dense data (s=25, alpha=0.5)
91- [ ] Use `bbox_inches='tight'` when saving
92
93### After Creation
94
95- [ ] Verify image dimensions (max 7999x7999 for Claude)
96- [ ] Check annotations are within plot bounds
97- [ ] Test colorblind accessibility
98- [ ] Save at 300 DPI minimum for publication
99
100### For Temporal Analyses
101
102- [ ] Create both all-data and cleaned versions
103- [ ] Calculate statistics on FULL dataset (not cleaned)
104- [ ] Document outlier removal method and retention rate
105- [ ] Use clear file naming: `figure.png` vs `figure_clean.png`
106
107## Quick Reference: Safe Figure Sizes (300 DPI)
108
109```python
110FIG_SIZES = {
111 'single_column': (3.5, 4), # 1050x1200 px
112 'double_column': (7, 5), # 2100x1500 px
113 'full_page': (7, 9), # 2100x2700 px
114 'poster': (20, 15), # 6000x4500 px
115 'max_claude': (26, 26), # 7800x7800 px
116}
117```
118
119## Quick Reference: Okabe-Ito Colors (3 Categories)
120
121```python
122colors = {
123 'Category_A': '#0072B2', # Blue
124 'Category_B': '#E69F00', # Orange
125 'Category_C': '#CC79A7' # Reddish Purple
126}
127```
128
129## Best Practices Summary
130
1311. **Always check log-scale plots** - Verify KDE-based plots against histograms
1322. **Test element sizes** - Regenerate with different sizes for optimal clarity
1333. **Explicit axis limits** - Don't rely on auto-limits when annotations are added
1344. **Consistent styling** - Use seaborn context and style for publication consistency
1355. **High DPI** - Save at 300 DPI minimum (`dpi=300, bbox_inches='tight'`)
1366. **Optimize axis ranges** - Zoom to data range when distributions are compressed
1377. **Check image dimensions** - Verify size before sharing with Claude (max 7999x7999)
1388. **Set size constraints** - Use safe figure sizes when generating images programmatically
1399. **Temporal trends with outliers** - Create both cleaned (publication) and full (verification) versions
14010. **Include sample sizes** - Always show n= in legends for comparative figures
141
142## References
143
144- Matplotlib documentation: https://matplotlib.org/
145- Seaborn visualization: https://seaborn.pydata.org/
146- iTOL documentation: https://itol.embl.de/help.cgi
147- Okabe-Ito palette: https://jfly.uni-koeln.de/color/
148- ColorBrewer: https://colorbrewer2.org
delphine-l