How mwaskom/seaborn works
1. What this repository is
Seaborn is a Python statistical visualization library. Its core job is to turn tabular data into plots by sitting on top of matplotlib, with pandas/numpy handling data structures and computation. The repository is organized around both a modern “objects” plotting system and older, function-based plotting APIs.
2. Primary runtime boundary: user code → matplotlib
The package’s outputs are matplotlib figures/axes and artists, not a custom rendering engine. That means seaborn’s architecture is mostly an analysis-and-plot-construction layer: it prepares data, computes statistics, chooses visual encodings, and delegates final drawing to matplotlib.
3. Modern plotting subsystem: seaborn/_core, _marks, _stats
The newer architecture lives in three closely related packages:
- seaborn._core handles data ingestion, grouping, plotting rules, scales, subplots, and property mapping.
- seaborn._stats computes derived values such as aggregation, counting, density, ordering, and regression summaries.
- seaborn._marks defines visual primitives such as bars, dots, lines, areas, and text.
Data flows through these layers from raw input to statistical transformation to visual mark placement.
4. Objects interface
seaborn/objects.py exposes the higher-level objects API built on those internals. This is the most explicit composition layer in the repo: plots are assembled from data, transforms, stats, scales, and marks rather than from one-off plotting functions. This subsystem is the clearest place to draw the “pipeline” architecture.
5. Legacy high-level plotting modules
The classic seaborn API is still present in modules like relational.py, distributions.py, categorical.py, regression.py, matrix.py, axisgrid.py, and miscplot.py. These modules provide domain-specific plotting functions such as scatter, line, histogram, KDE, categorical plots, regression plots, heatmaps, and multi-axes grid layouts. Many of these functions wrap the newer core logic or compose matplotlib directly.
6. Data handling and statistical computation
The repository depends heavily on pandas and numpy for data normalization, grouping, and vectorized calculations. Optional scipy and statsmodels support higher-end statistics such as density estimation and regression. This creates a boundary where basic plotting works with the core dependencies, while advanced stats are conditionally available.
7. Color, theme, and style subsystem
Modules like palettes.py, cm.py, rcmod.py, and seaborn/colors/ define color palettes, colormap behavior, and global style/theme settings. These are cross-cutting concerns rather than plot-specific logic: they affect how plots look regardless of the plot type, and they often influence defaults used by both legacy and objects APIs.
8. Utility and compatibility layer
utils.py, _compat.py, and algorithms.py provide shared helpers, compatibility shims, and common algorithms used across plotting and stats code. seaborn/external/ vendors small third-party utilities needed for portability, which isolates the rest of the package from direct dependency churn.
9. Documentation architecture
The doc/ tree is a substantial subsystem, not just static prose. It uses Sphinx plus custom extensions under doc/sphinxext/, tutorial notebooks under doc/_tutorial/, docstring notebooks under doc/_docstrings/, and gallery-generation tooling. The docs pipeline turns executable examples into API docs, tutorials, and the online gallery.
10. Example gallery as executable architecture
examples/ contains the canonical usage examples that feed the documentation gallery. These scripts are important because they are part of the public surface: they demonstrate plot composition patterns, and they are validated by CI tooling to ensure examples remain runnable and visually consistent.
11. Testing mirrors the package structure
tests/ is organized to reflect the main implementation areas: _core, _marks, _stats, plus top-level tests for legacy modules and utilities. This gives a strong signal that the repo’s architecture is layered around the modern core system, with separate validation for plotting APIs, statistical transforms, and supporting helpers.
12. Build, CI, and release support
The repo includes pyproject.toml, setup.cfg, Makefile, pre-commit config, and GitHub Actions workflows for linting, testing, docs checks, and gallery validation. CI helpers in ci/ cache datasets and support example/gallery checks, showing that reproducible docs and visual regressions are part of the engineering workflow.
13. Overall data flow to diagram
A useful architecture diagram would show: user data enters either the legacy function API or the objects API; data is normalized/grouped in _core; optional statistical computation happens in _stats; visual encodings are defined by _marks and styling/palette modules; matplotlib renders the final output; examples/tests/docs exercise and verify the whole stack.
Main entry points: plot.py Plot core · __init__.py Stats · conf.py Docs build · check_gallery.py CI tools
Components 23
Modern core
Objects-based plotting pipeline and its internal layers.
- Objects API · High-level composition interface for building plots from data, stats, marks, and scales.
seaborn/objects.py - Plot core · Data ingestion, grouping, rules, and subplot orchestration for the objects system.
seaborn/_core/plot.py - Data model · Normalizes inputs and manages tabular data access for plotting.
seaborn/_core/data.py - Grouping · Group construction and split-apply logic used throughout the plotting pipeline.
seaborn/_core/groupby.py - Scales · Coordinate and semantic scales that map data values into plot space.
seaborn/_core/scales.py - Plot rules · Declarative rules that coordinate how variables, properties, and transforms interact.
seaborn/_core/rules.py - Marks · Renderable geometry such as bars, dots, lines, areas, and text.
seaborn/_marks/__init__.py - Stats · Derived-value computations used by the objects pipeline.
seaborn/_stats/__init__.py - Density · KDE and related distribution estimation utilities.
seaborn/_stats/density.py - Regression · Linear and model-based summaries for fitted trend visualization.
seaborn/_stats/regression.py
Legacy API
Function-based plotting modules and figure-level helpers.
- Legacy API · Classic seaborn modules that expose function-based plot constructors and figure-level helpers.
- Relational · Scatter and line plotting functions for relationship visualizations.
seaborn/relational.py - Distributions · Histogram, KDE, ECDF, and distribution-oriented plotting APIs.
seaborn/distributions.py - Categorical · Category-aware plots such as bar, box, violin, strip, and swarm.
seaborn/categorical.py - Regression · Regression and residual plotting functions built on statistical summaries.
seaborn/regression.py - Axis grids · Facet and grid layout helpers for multi-panel compositions.
seaborn/axisgrid.py
Style system
Color palettes, themes, and matplotlib style configuration.
- Palettes · Discrete and continuous palette definitions and helpers.
seaborn/palettes.py - Theme setup · Matplotlib rcParam and theme configuration for seaborn defaults.
seaborn/rcmod.py - Color data · Color tables and package-level color resources.
seaborn/colors/__init__.py
Docs and examples
Executable examples and documentation pipeline.
- Docs build · Sphinx configuration and notebook-driven documentation generation.
doc/conf.py - Examples · Executable gallery scripts used to demonstrate and validate plotting patterns.
Verification
Tests, CI, and release-support tooling.
- Test suite · Package-level tests that mirror the major implementation areas.
- CI tools · Gallery checks, dataset caching, and workflow support for reproducible validation.
ci/check_gallery.py
Connections 28
- Objects API → Plot core: composes · Objects API builds plots through the core pipeline.
- Plot core → Data model: ingests · Core plot normalizes and reads tabular inputs.
- Plot core → Grouping: groups · Data is split and organized for plot construction.
- Plot core → Plot rules: applies · Rules coordinate variable semantics and transformations.
- Plot core → Scales: maps · Scales convert data values into visual coordinates.
- Plot core → Marks: renders with · Plot pipeline delegates drawing to visual marks.
- Plot core → Stats: transforms · Optional statistics derive aggregated or fitted values.
- Stats → Density: includes · Density estimation is one major stat family.
- Stats → Regression: includes · Regression summaries are another major stat family.
- Legacy API → Plot core: routes to · The modern core is the shared composition engine behind newer plotting flows.
- Relational → Plot core: uses core · Modern relational plots share the new core machinery.
- Distributions → Density: uses · Distribution plots rely on density and count transforms.
- Categorical → Stats: uses · Categorical plots depend on summary and ordering transforms.
- Regression → Regression: uses · Regression plots rely on fitted-model summaries.
- Axis grids → Legacy API: extends · Grid helpers provide multi-panel figure-level composition.
- Palettes → Theme setup: feeds defaults · Palette choices interact with global styling and theme defaults.
- Color data → Palettes: supports · Named color resources back palette construction.
- Docs build → Objects API: documents · Sphinx docs and notebooks describe the objects interface.
- Docs build → Legacy API: documents · API docs and tutorials cover the classic plotting modules.
- Examples → Relational: demonstrates · Gallery scripts exercise public plotting APIs.
- Examples → Distributions: demonstrates · Examples cover distribution and density plots.
- Examples → Categorical: demonstrates · Examples cover categorical plot patterns.
- Test suite → Plot core: verifies · Core pipeline behavior is directly tested.
- Test suite → Marks: verifies · Mark primitives have dedicated validation coverage.
- Test suite → Stats: verifies · Stat transforms are covered by dedicated tests.
- Test suite → Legacy API: verifies · Legacy plotting modules have module-level tests.
- CI tools → Examples: checks · CI validates gallery examples and generated outputs.
- CI tools → Docs build: builds · Automation supports reproducible documentation builds.