# mwaskom/seaborn architecture

> Architecture diagram of the GitHub repository mwaskom/seaborn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mwaskom/seaborn
- Repository: https://github.com/mwaskom/seaborn

## Overview

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: [`seaborn/_core/plot.py`](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/plot.py) (Plot core), [`seaborn/_stats/__init__.py`](https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/__init__.py) (Stats), [`doc/conf.py`](https://github.com/mwaskom/seaborn/blob/master/doc/conf.py) (Docs build), [`ci/check_gallery.py`](https://github.com/mwaskom/seaborn/blob/master/ci/check_gallery.py) (CI tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Modern core"]
  node_objects["Objects API<br/>public plotting API<br/>[objects.py]"]
  node_core_plot["Plot core<br/>pipeline engine<br/>[plot.py]"]
  node_core_data["Data model<br/>data handling<br/>[data.py]"]
  node_core_groupby["Grouping<br/>aggregation boundary<br/>[groupby.py]"]
  node_core_scales["Scales<br/>mapping/scaling<br/>[scales.py]"]
  node_core_rules["Plot rules<br/>plot semantics<br/>[rules.py]"]
  node_marks["Marks<br/>visual primitives<br/>[__init__.py]"]
  node_stats["Stats<br/>stat transforms<br/>[__init__.py]"]
  node_stats_density["Density<br/>stat transform<br/>[density.py]"]
  node_stats_regression["Regression<br/>stat transform<br/>[regression.py]"]
end

subgraph group_legacy["Legacy API"]
  node_legacy_api["Legacy API<br/>function plotting"]
  node_relational["Relational<br/>legacy plots<br/>[relational.py]"]
  node_distributions["Distributions<br/>legacy plots<br/>[distributions.py]"]
  node_categorical["Categorical<br/>legacy plots<br/>[categorical.py]"]
  node_regression["Regression<br/>legacy plots<br/>[regression.py]"]
  node_axisgrid["Axis grids<br/>multi-axes layouts<br/>[axisgrid.py]"]
end

subgraph group_style["Style system"]
  node_palettes["Palettes<br/>color system<br/>[palettes.py]"]
  node_rcmod["Theme setup<br/>style config<br/>[rcmod.py]"]
  node_colors["Color data<br/>named colors<br/>[__init__.py]"]
end

subgraph group_docs["Docs and examples"]
  node_docs_build["Docs build<br/>documentation pipeline<br/>[conf.py]"]
  node_examples["Examples<br/>gallery sources"]
end

subgraph group_quality["Verification"]
  node_tests["Test suite<br/>verification"]
  node_ci["CI tools<br/>automation<br/>[check_gallery.py]"]
end

node_objects -->|"composes"| node_core_plot
node_core_plot -->|"ingests"| node_core_data
node_core_plot -->|"groups"| node_core_groupby
node_core_plot -->|"applies"| node_core_rules
node_core_plot -->|"maps"| node_core_scales
node_core_plot -->|"renders with"| node_marks
node_core_plot -->|"transforms"| node_stats
node_stats -->|"includes"| node_stats_density
node_stats -->|"includes"| node_stats_regression
node_legacy_api -->|"routes to"| node_core_plot
node_relational -->|"uses core"| node_core_plot
node_distributions -->|"uses"| node_stats_density
node_categorical -->|"uses"| node_stats
node_regression -->|"uses"| node_stats_regression
node_axisgrid -->|"extends"| node_legacy_api
node_palettes -.->|"feeds defaults"| node_rcmod
node_colors -->|"supports"| node_palettes
node_docs_build -->|"documents"| node_objects
node_docs_build -->|"documents"| node_legacy_api
node_examples -->|"demonstrates"| node_relational
node_examples -->|"demonstrates"| node_distributions
node_examples -->|"demonstrates"| node_categorical
node_tests -->|"verifies"| node_core_plot
node_tests -->|"verifies"| node_marks
node_tests -->|"verifies"| node_stats
node_tests -->|"verifies"| node_legacy_api
node_ci -->|"checks"| node_examples
node_ci -->|"builds"| node_docs_build

click node_objects "https://github.com/mwaskom/seaborn/blob/master/seaborn/objects.py"
click node_core_plot "https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/plot.py"
click node_core_data "https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/data.py"
click node_core_groupby "https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/groupby.py"
click node_core_scales "https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/scales.py"
click node_core_rules "https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/rules.py"
click node_marks "https://github.com/mwaskom/seaborn/blob/master/seaborn/_marks/__init__.py"
click node_stats "https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/__init__.py"
click node_stats_density "https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/density.py"
click node_stats_regression "https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/regression.py"
click node_relational "https://github.com/mwaskom/seaborn/blob/master/seaborn/relational.py"
click node_distributions "https://github.com/mwaskom/seaborn/blob/master/seaborn/distributions.py"
click node_categorical "https://github.com/mwaskom/seaborn/blob/master/seaborn/categorical.py"
click node_regression "https://github.com/mwaskom/seaborn/blob/master/seaborn/regression.py"
click node_axisgrid "https://github.com/mwaskom/seaborn/blob/master/seaborn/axisgrid.py"
click node_palettes "https://github.com/mwaskom/seaborn/blob/master/seaborn/palettes.py"
click node_rcmod "https://github.com/mwaskom/seaborn/blob/master/seaborn/rcmod.py"
click node_colors "https://github.com/mwaskom/seaborn/blob/master/seaborn/colors/__init__.py"
click node_docs_build "https://github.com/mwaskom/seaborn/blob/master/doc/conf.py"
click node_ci "https://github.com/mwaskom/seaborn/blob/master/ci/check_gallery.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_objects,node_core_plot,node_core_data,node_core_groupby,node_core_scales,node_core_rules,node_marks,node_stats,node_stats_density,node_stats_regression toneBlue
class node_legacy_api,node_relational,node_distributions,node_categorical,node_regression,node_axisgrid toneAmber
class node_palettes,node_rcmod,node_colors toneMint
class node_docs_build,node_examples toneRose
class node_tests,node_ci toneIndigo
```

## Components

### Modern core

Objects-based plotting pipeline and its internal layers.

- [Objects API](https://github.com/mwaskom/seaborn/blob/master/seaborn/objects.py): public plotting API · High-level composition interface for building plots from data, stats, marks, and scales. · `seaborn/objects.py`
- [Plot core](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/plot.py): pipeline engine · Data ingestion, grouping, rules, and subplot orchestration for the objects system. · `seaborn/_core/plot.py`
- [Data model](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/data.py): data handling · Normalizes inputs and manages tabular data access for plotting. · `seaborn/_core/data.py`
- [Grouping](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/groupby.py): aggregation boundary · Group construction and split-apply logic used throughout the plotting pipeline. · `seaborn/_core/groupby.py`
- [Scales](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/scales.py): mapping/scaling · Coordinate and semantic scales that map data values into plot space. · `seaborn/_core/scales.py`
- [Plot rules](https://github.com/mwaskom/seaborn/blob/master/seaborn/_core/rules.py): plot semantics · Declarative rules that coordinate how variables, properties, and transforms interact. · `seaborn/_core/rules.py`
- [Marks](https://github.com/mwaskom/seaborn/blob/master/seaborn/_marks/__init__.py): visual primitives · Renderable geometry such as bars, dots, lines, areas, and text. · `seaborn/_marks/__init__.py`
- [Stats](https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/__init__.py): stat transforms · Derived-value computations used by the objects pipeline. · `seaborn/_stats/__init__.py`
- [Density](https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/density.py): stat transform · KDE and related distribution estimation utilities. · `seaborn/_stats/density.py`
- [Regression](https://github.com/mwaskom/seaborn/blob/master/seaborn/_stats/regression.py): stat transform · 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**: function plotting · Classic seaborn modules that expose function-based plot constructors and figure-level helpers.
- [Relational](https://github.com/mwaskom/seaborn/blob/master/seaborn/relational.py): legacy plots · Scatter and line plotting functions for relationship visualizations. · `seaborn/relational.py`
- [Distributions](https://github.com/mwaskom/seaborn/blob/master/seaborn/distributions.py): legacy plots · Histogram, KDE, ECDF, and distribution-oriented plotting APIs. · `seaborn/distributions.py`
- [Categorical](https://github.com/mwaskom/seaborn/blob/master/seaborn/categorical.py): legacy plots · Category-aware plots such as bar, box, violin, strip, and swarm. · `seaborn/categorical.py`
- [Regression](https://github.com/mwaskom/seaborn/blob/master/seaborn/regression.py): legacy plots · Regression and residual plotting functions built on statistical summaries. · `seaborn/regression.py`
- [Axis grids](https://github.com/mwaskom/seaborn/blob/master/seaborn/axisgrid.py): multi-axes layouts · Facet and grid layout helpers for multi-panel compositions. · `seaborn/axisgrid.py`

### Style system

Color palettes, themes, and matplotlib style configuration.

- [Palettes](https://github.com/mwaskom/seaborn/blob/master/seaborn/palettes.py): color system · Discrete and continuous palette definitions and helpers. · `seaborn/palettes.py`
- [Theme setup](https://github.com/mwaskom/seaborn/blob/master/seaborn/rcmod.py): style config · Matplotlib rcParam and theme configuration for seaborn defaults. · `seaborn/rcmod.py`
- [Color data](https://github.com/mwaskom/seaborn/blob/master/seaborn/colors/__init__.py): named colors · Color tables and package-level color resources. · `seaborn/colors/__init__.py`

### Docs and examples

Executable examples and documentation pipeline.

- [Docs build](https://github.com/mwaskom/seaborn/blob/master/doc/conf.py): documentation pipeline · Sphinx configuration and notebook-driven documentation generation. · `doc/conf.py`
- **Examples**: gallery sources · Executable gallery scripts used to demonstrate and validate plotting patterns.

### Verification

Tests, CI, and release-support tooling.

- **Test suite**: verification · Package-level tests that mirror the major implementation areas.
- [CI tools](https://github.com/mwaskom/seaborn/blob/master/ci/check_gallery.py): automation · Gallery checks, dataset caching, and workflow support for reproducible validation. · `ci/check_gallery.py`

## Connections

- 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.
