If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rougier/scientific-visualization-book shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 25+ active contributors
• Distributed ownership (top contributor 44% of recent commits)
• Other licensed
• ⚠ Slowing — last commit 4mo ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rougier/scientific-visualization-book repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rougier/scientific-visualization-book.

What it runs against: a local clone of rougier/scientific-visualization-book — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rougier/scientific-visualization-book | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 153 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rougier/scientific-visualization-book. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rougier/scientific-visualization-book.git
#   cd scientific-visualization-book
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rougier/scientific-visualization-book and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rougier/scientific-visualization-book(\\.git)?\\b" \\
  && ok "origin remote is rougier/scientific-visualization-book" \\
  || miss "origin remote is not rougier/scientific-visualization-book (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "code/anatomy/anatomy.py" \\
  && ok "code/anatomy/anatomy.py" \\
  || miss "missing critical file: code/anatomy/anatomy.py"
test -f "code/defaults/defaults-step-1.py" \\
  && ok "code/defaults/defaults-step-1.py" \\
  || miss "missing critical file: code/defaults/defaults-step-1.py"
test -f "code/colors/color-gradients.py" \\
  && ok "code/colors/color-gradients.py" \\
  || miss "missing critical file: code/colors/color-gradients.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 153 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~123d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rougier/scientific-visualization-book"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

An open-access textbook and code repository teaching scientific data visualization using Python and Matplotlib, with 534K lines of Python demonstrating figure anatomy, coordinate systems, color theory, 3D plotting, animations, and advanced rendering techniques. It provides production-ready examples covering everything from basic plot configuration to interactive visualizations and custom rendering pipelines. Organized as a chapter-aligned code collection under code/ directory with subdirectories for each topic: anatomy/ (figure structure & DPI), animation/ (animated plots & MP4 rendering), colors/ (color spaces & gradients), coordinates/ (coordinate transforms), beyond/ (advanced techniques like polygon clipping, mazes). Each Python file is a standalone, runnable example paired with a book chapter or concept explanation.

Scientists, researchers, and engineers who need to create publication-quality figures in Python; graduate students learning data visualization best practices; technical authors and instructors teaching scientific computing. Users want to move beyond basic Matplotlib defaults to create polished, semantically meaningful visualizations.

Actively maintained and mature: published as an open-access book (95MB PDF on HAL archive, also sold in print on Amazon), with well-organized code examples across multiple visualization domains. The repository shows consistent structure and professional documentation, though specific commit history and CI pipelines are not visible in the metadata provided. Verdict: production-ready educational resource with active maintainer (Nicolas P. Rougier, Bordeaux).

Low technical risk: this is an educational repository with no external dependencies listed in the metadata, relying only on standard scientific Python stack (Matplotlib, NumPy). Single-maintainer structure (Rougier) creates bus factor risk for major updates, but the nature of visualization documentation means breaking changes are infrequent. No CI configuration visible in file list, so automated testing coverage is unknown.

Repository appears to be in documentation-completion phase: the book was published November 2021 and is available on HAL archive. Active content includes animation examples (earthquakes, fluid simulation, Lissajous curves), advanced visualization techniques (blue noise, polygon clipping), and coordinate system explorations. No visible PR activity or recent feature development in metadata—focus is maintenance and educational clarity.

Clone and explore examples: git clone https://github.com/rougier/scientific-visualization-book.git && cd scientific-visualization-book. Run individual examples directly: python code/anatomy/anatomy.py or python code/animation/sine-cosine.py. No build step or virtual environment setup listed; assumes Matplotlib and NumPy are pre-installed. Read the book PDF from HAL (hal-03427242/document) in parallel with code.

Daily commands: Individual scripts run directly: python code/anatomy/anatomy.py displays a figure. Animation examples may render to disk: check scripts like code/animation/sine-cosine-mp4.py for output paths. Makefile likely has targets: make or make pdf may regenerate book. Examples are designed for interactive exploration in Jupyter or as standalone scripts; no server or dev mode.

• README.md — Entry point documentation describing the book's structure, scope, and purpose for scientific visualization with Python and Matplotlib.
• Makefile — Build orchestration file that defines how to generate the book's figures, examples, and final output artifacts.
• code/anatomy/anatomy.py — Foundational example demonstrating Matplotlib figure anatomy and structure, essential for understanding visualization principles used throughout.
• code/defaults/defaults-step-1.py — Introductory defaults configuration that establishes the baseline styling and theming approach for all visualization examples.
• code/colors/color-gradients.py — Core color management example showing gradient and palette techniques fundamental to the book's visualization methodology.
• code/layout/complex-layout.py — Advanced layout patterns demonstrating GridSpec and subplot composition techniques critical for multi-panel scientific figures.

• Example Scripts (code//.py) (Python, Matplotlib) — Demonstrate specific visualization concepts by constructing figures from matplotlib primitives
  • Failure mode: Script errors prevent figure generation; missing imports or invalid data cause build failures
• Style Configuration (code/defaults/mystyle.txt) (Matplotlib style format) — Centralized matplotlib rcParams and theme definition ensuring visual consistency across all examples
  • Failure mode: Invalid rcParams syntax causes style loading to fail; inconsistent application across examples
• Build Orchestration (Makefile) (Make) — Coordinates execution of all example scripts and aggregates outputs for book generation
  • Failure mode: Missing targets or script paths cause partial or failed builds; dependency ordering issues
• Data Assets (code/data/) (PNG, image formats) — Sample images and static data supporting examples in image processing and visualization
  • Failure mode: Missing or corrupted image files cause examples to fail or produce incorrect output

• Author → Python Script — Writes visualization example code demonstrating concepts
• Python Script → Matplotlib — Constructs figure using plotting API, loads styling from rcParams
• Matplotlib Style Configuration → Matplotlib — mystyle.txt provides rcParams for consistent theming across examples
• Matplotlib → Figure Output — Renders high-quality PNG/PDF figures at specified DPI for publication
• Build System → Figure Outputs — Makefile executes scripts and collects all generated figures for book assembly

Add a New Visualization Example

1. Create a new Python script in the appropriate category folder under code/ (e.g., code/colors/, code/layout/, code/animation/) (code/colors/new-example.py)
2. Import matplotlib.pyplot and follow anatomy patterns from code/anatomy/anatomy.py for figure structure (code/anatomy/anatomy.py)
3. Apply styling defaults by importing from code/defaults/mystyle.txt via plt.style.use() (code/defaults/mystyle.txt)
4. Save the output figure and add corresponding documentation reference in the book content

Create a New Animation Example

1. Create a new script in code/animation/ following patterns from existing files (code/animation/sine-cosine.py)
2. Import FuncAnimation from matplotlib.animation for frame-based animation (code/animation/fluid-animation.py)
3. Define update functions that modify plot data frame-by-frame (code/animation/lissajous.py)
4. Configure output format (MP4/GIF) using Writer classes or save frames directly

Customize Styling for a New Theme

1. Create a new style configuration file in code/defaults/ (e.g., code/defaults/darkstyle.txt) (code/defaults/mystyle.txt)
2. Define rcParams for colors, fonts, line widths following Matplotlib style conventions (code/colors/material-colors.py)
3. Load the style in example scripts using plt.style.use('path/to/style.txt') (code/defaults/defaults-step-1.py)

• Matplotlib — Primary visualization library chosen for its versatility, publication-quality output, and comprehensive customization capabilities suitable for scientific figures.
• Python — Scripting language enabling reproducible, readable examples and educational code that demonstrates visualization concepts step-by-step.
• Make — Build automation tool for orchestrating generation of all figures and examples from source code in a reproducible manner.
• Git/GitHub — Version control and distribution mechanism for open-access book content and example code with community contribution support.

• Pure Python scripts over Jupyter notebooks for all examples

  • Why: Ensures examples are version-controllable, stateless, and production-ready rather than dependent on notebook state
  • Consequence: Examples are less interactive but more portable and easier to integrate into automated build pipelines

• Static matplotlib output (PNG/PDF) over interactive widgets

  • Why: Focuses on publication-quality scientific visualization as core purpose rather than interactive exploration
  • Consequence: Book illustrations are high-fidelity but lack interactivity; reader must run examples locally for exploration

• Organized examples by visualization concept rather than by complexity level

  • Why: Teaches visualization principles holistically across color theory, layout, animation, and optimization independently
  • Consequence: Beginners may need to cherry-pick examples; not a strict learning path from simple to advanced

• Real-time or interactive data exploration tools
• 3D visualization (explicitly focuses on 2D rendering excellence)
• Web-based visualization frameworks (desktop-first approach)
• Large data streaming or real-time animation playback
• Live interactive notebooks or kernel-based environments
• Generic plotting library (specialized for scientific/academic publishing)

• Inconsistent Example Structure (Low) — code/anatomy/ vs code/colors/ vs code/animation/: Examples follow different organizational patterns and have varying levels of comments/documentation, making it harder for learners to understand consistent principles
• Hard-coded DPI and Figure Sizes — code/anatomy/figure-dpi.py, code/layout/complex-layout.py: Examples specify exact DPI and dimensions inline rather than using configurable defaults, reducing reusability and

No explicit dependency lock file visible (no requirements.txt or poetry.lock in top 60 files), so Python/Matplotlib/NumPy version requirements are implicit—check README or TeX files for stated version targets. Animation examples may require ffmpeg installed system-wide for MP4 output (not listed in Python deps). TeX build requires a full LaTeX distribution (not apparent from file structure alone). Some advanced examples in code/beyond/ may depend on optional packages (Shapely for polygon clipping, scipy.ndimage for fluid simulation) that aren't automatically installed. No virtual environment setup documented in metadata provided.

• Figure DPI and vector vs raster rendering — Critical for understanding how Matplotlib exports to different formats (PDF, PNG) with correct resolution and file size—covered in code/anatomy/figure-dpi.py and code/anatomy/raster-vector.py
• Z-order (layer compositing) — Controls visual stacking of plot elements (lines over markers over background)—essential for readable overlapping visualizations, demonstrated in code/anatomy/zorder.py
• Perceptual color spaces and colormap design — Ensures color encoding is readable by people with color vision deficiency and perceptually uniform—central to scientific figure ethics, explored throughout code/colors/
• Coordinate transforms and blending modes — Allows combining multiple plot projections and custom transformations (log scale, polar, geographic)—fundamental for complex multi-data visualizations in code/coordinates/
• Artist and Patch objects (object-oriented Matplotlib) — Enables fine-grained control over every visual element by directly manipulating Matplotlib objects rather than using pyplot—necessary for publication-quality customization
• Animation and frame rendering (FuncAnimation, Writer) — Extends static figures to time-series and dynamical systems; MP4/GIF export for presentations—covered in code/animation/ with fluid dynamics and earthquake examples
• Blue noise sampling and halton sequences — Advanced technique for visually uniform random distributions in visualizations—improves scatter plot aesthetics and removes false patterns, shown in code/beyond/bluenoise.py

• matplotlib/matplotlib — The core library this entire book teaches—understanding Matplotlib internals and contributing examples upstream benefits this project
• altair-viz/altair — Grammar-of-graphics Python visualization alternative; useful comparison for readers deciding between declarative (Altair) vs imperative (Matplotlib) approaches
• pandas-dev/pandas — Data manipulation library that feeds into Matplotlib in scientific workflows; many examples likely process data with Pandas before plotting
• jonasteubler/Plotting-Examples — Complementary Matplotlib tutorial repository with different example organization; useful for cross-referencing specific techniques
• rougier/matplotlib-cheatsheets — Same author's quick-reference guides for Matplotlib syntax—paired resource for learning and rapid API lookup

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add a requirements.txt and environment.yml for reproducible code execution

The repo contains 50+ Python scripts across multiple directories (anatomy, animation, beyond, colors, coordinates, etc.) but has no dependency specification file. Contributors and readers cannot easily run the code examples. This is critical for an open-access educational book where executable examples are core content. Adding requirements.txt with pinned versions ensures all matplotlib, numpy, and domain-specific dependencies (cartopy for platecarree.py, etc.) are documented.

• [ ] Analyze imports across all code/ subdirectories to identify all dependencies
• [ ] Create requirements.txt with pinned versions for matplotlib, numpy, and optional deps (cartopy, scipy, Pillow, etc.)
• [ ] Create environment.yml for conda users as an alternative
• [ ] Update README.md with installation instructions referencing these files
• [ ] Test that scripts run with these dependencies in a fresh environment

Create a Makefile target to validate and execute all code examples

The Makefile exists but likely only builds the book. With 50+ example scripts spread across directories, there's no mechanism to ensure they're syntactically correct and executable. Adding a make validate-examples or make test-examples target would catch broken imports, deprecated matplotlib APIs, and missing data files early. This is essential for maintaining code quality in an educational repo.

• [ ] Add a new Makefile target (e.g., 'test-examples' or 'validate-examples')
• [ ] Create a Python script (e.g., validate_examples.py) that imports and runs each .py file in code/ with error handling
• [ ] Handle data dependencies (code/data/*.png files) gracefully in validation
• [ ] Exclude pycache and .pyc files from validation
• [ ] Document the new target in the Makefile with comments and in README.md

Add a GitHub Actions CI workflow to test code examples on Python 3.8+ matrix

The repo has .github/FUNDING.yml but no CI workflow. With Python code examples, a workflow testing against Python 3.8, 3.9, 3.10, 3.11+ ensures backward/forward compatibility. This catches breaking changes in matplotlib and numpy early. Given the educational nature, learners should trust the examples work on their Python versions.

• [ ] Create .github/workflows/test-examples.yml
• [ ] Configure matrix testing for Python 3.8, 3.9, 3.10, 3.11, and 3.12
• [ ] Install dependencies from requirements.txt (once created via PR #1)
• [ ] Run the example validation script (from PR #2) as the test step
• [ ] Add a status badge to README.md
• [ ] Optionally cache pip dependencies to speed up CI runs

• Add Python 3.9+ type hints to anatomy examples (e.g., code/anatomy/anatomy.py, code/anatomy/figure-dpi.py) to improve code clarity and IDE support for new learners
• Create a requirements.txt or environment.yml file listing exact Matplotlib, NumPy, and optional dependency versions tested against the book—currently users must infer from README
• Add docstrings and inline comments to advanced examples in code/beyond/ (polygon-clipping.py, interactive-loupe.py, dungeon.py) explaining mathematical concepts and Matplotlib API usage

This is an educational open-access visualization book repository with minimal security risks. The codebase contains only Python scripts and documentation with no complex dependencies, database connections, authentication mechanisms, or web server components. Primary concerns are minor best-practices issues: pycache files should be excluded, a dependency lock file should be created to track versions, and binary proprietary files should be removed or stored separately. No injection vulnerabilities, hardcoded secrets, exposed credentials, or critical misconfigurations were identified. The security posture is solid for an educational resource repository.

• Low · Python Cache Files in Repository — code/animation/__pycache__/, code/beyond/__pycache__/. The repository contains pycache directories and .pyc compiled Python files (e.g., code/animation/pycache/fluid.cpython-38.pyc, code/beyond/pycache/bluenoise.cpython-38.pyc). These should not be committed to version control as they can contain sensitive information and create merge conflicts. Fix: Add pycache/ and *.pyc to .gitignore file. Remove cached files from git history using 'git rm -r --cached pycache/'
• Low · Missing HTTPS in External References — README.md and various documentation. The README and codebase may reference external resources without enforcing HTTPS. While this is a visualization library with educational content, external dependencies should use secure protocols. Fix: Ensure all external resource references use HTTPS protocol. Add a security policy for dependency management.
• Low · No Dependency Lock File — Repository root. No requirements.txt, poetry.lock, or pipfile is visible in the provided file structure. This makes it difficult to ensure reproducible builds and track known vulnerabilities in dependencies. Fix: Create and maintain a requirements.txt or pyproject.toml file with pinned versions. Use tools like pip-audit to check for known vulnerabilities.
• Low · Proprietary File Format in Repository — code/data/John-Hunter.pxd/. The repository contains a .pxd (Pixelmator Pro) binary file (code/data/John-Hunter.pxd/) which is a proprietary format. This increases repository size and may contain embedded metadata. Fix: Consider storing binary/proprietary files in a separate media repository or using Git LFS (Large File Storage). Keep only necessary image formats like PNG, JPG, or SVG.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.