flowmpl

Matplotlib design system and flow diagram renderer for analytical publications.

Built for research notebooks that combine data visualization with process flow diagrams — the kind of work where you need both a consistent visual language across charts and clean auto-routed arrows between labeled boxes.

Install

pip install flowmpl           # core: matplotlib + numpy only
pip install flowmpl[charts]   # + pandas (annotated_series, stacked_bar, etc.)
pip install flowmpl[maps]     # + geopandas + requests (us_scatter_map)
pip install flowmpl[all]      # everything

Quick Start

from flowmpl import COLORS, FONTS, flow_diagram

fig = flow_diagram(
    nodes={
        "a": ("Announce", 1.0, 1.0, COLORS["accent"],    "#ffffff"),
        "b": ("Permit",   3.0, 1.0, COLORS["neutral"],   COLORS["text_dark"]),
        "c": ("Build",    5.0, 1.0, COLORS["positive"],  "#ffffff"),
    },
    edges=[
        {"src": "a", "dst": "b", "label": "12–18 mo"},
        {"src": "b", "dst": "c", "label": "24–36 mo"},
    ],
    title="From announcement to operation",
)
fig.savefig("pipeline.png", dpi=150, bbox_inches="tight")

Design System

flowmpl ships a complete design system extracted from a production research project:

Chart Functions

All functions return matplotlib.Figure objects.

from flowmpl import (
    annotated_series,       # time series with annotations + fill
    multi_panel,            # multi-subplot from a single DataFrame
    stacked_bar,            # stacked bar for categorical breakdowns
    waterfall_chart,        # cost allocation / flow breakdowns
    horizontal_bar_ranking, # ranked horizontal bars with highlights
)

Helpers

from flowmpl import (
    focus_colors,    # SWD gray+accent pattern: focus items colored, rest gray
    legend_below,    # place legend below axes (works with bbox_inches='tight')
    annotate_point,  # annotate a data point with arrow + text
    reference_line,  # labeled horizontal or vertical reference line
    chart_title,     # subtle left-aligned insight title (for standalone PNGs)
)

focus_colors() example

colors = focus_colors(
    ["MSFT", "AMZN", "GOOGL", "META"],
    focus="AMZN",
    color_map=COMPANY_COLORS,
)
# → ['#c0c0c0', '#ff9900', '#c0c0c0', '#c0c0c0']

Flow Diagram

flow_diagram() renders labeled boxes connected by auto-routed arrows. It handles:

• Auto-routing: chooses straight or elbow connections based on source/destination geometry
• Face overrides: explicit exit/entry keys bypass the heuristic for complex layouts
• Auto-spacing: adjusts vertical spacing to prevent label overlap
• Face spreading: distributes multiple edges from the same face to avoid overlaps

Node format

nodes = {
    "key": (label, cx, cy, fill_color, text_color),
}

• cx, cy: center coordinates in abstract units (the renderer scales to fit)
• Sizes auto-scaled; override with node_width / node_height params

Edge format

edges = [
    {"src": "a", "dst": "b"},                           # basic
    {"src": "a", "dst": "b", "label": "2 years"},       # with label
    {"src": "a", "dst": "b", "dashed": True},           # dashed line
    {"src": "a", "dst": "b", "color": "#888"},          # custom color
    {"src": "a", "dst": "b", "exit": "top",   "entry": "left"},  # face override
    {"src": "a", "dst": "b", "exit": "bottom", "entry": "left"}, # force exit face
]

Routing heuristic

The auto-router uses the vector between node centers:

Use explicit exit/entry overrides when the heuristic produces overlapping arrows from the same face (e.g., a root node with multiple connections at different angles).

T-layout example (face overrides)

fig = flow_diagram(
    nodes={
        "r": ("Root",   1.0, 1.5, COLORS["accent"],   "#ffffff"),
        "a": ("Top",    4.5, 3.0, COLORS["positive"], "#ffffff"),
        "m": ("Middle", 4.5, 1.5, COLORS["neutral"],  COLORS["text_dark"]),
        "b": ("Bottom", 4.5, 0.0, CONTEXT,            COLORS["text_dark"]),
    },
    edges=[
        {"src": "r", "dst": "a", "exit": "top",    "entry": "left"},
        {"src": "r", "dst": "m"},                           # straight, no override needed
        {"src": "r", "dst": "b", "exit": "bottom", "entry": "left"},
    ],
    title="Three destinations from one source",
)

Without the face overrides, all three arrows would exit from r's right face and overlap. With exit="top" and exit="bottom", each arrow leaves from a different face.

Map

from flowmpl import us_scatter_map
import matplotlib.patches as mpatches

fig = us_scatter_map(
    lats=[37.7, 40.7, 41.8],
    lons=[-122.4, -74.0, -87.6],
    colors=["#e74c3c", "#3498db", "#2ecc71"],
    sizes=[100, 150, 80],
    title="Three cities",
    legend_handles=[
        mpatches.Patch(color="#e74c3c", label="San Francisco"),
        mpatches.Patch(color="#3498db", label="New York"),
        mpatches.Patch(color="#2ecc71", label="Chicago"),
    ],
)

State boundary shapefiles are downloaded from the US Census Bureau on first use and cached in the package directory.

License

MIT