djrhails-graphs 0.1.0__tar.gz

djrhails_graphs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Hails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

djrhails_graphs-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: djrhails-graphs
+Version: 0.1.0
+Summary: Economist-style chart theme for matplotlib/seaborn
+Author-email: Daniel Hails <graphs@hails.info>
+Project-URL: Homepage, https://github.com/DJRHails/graphs
+Project-URL: Bug Tracker, https://github.com/DJRHails/graphs/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# graphs
+
+Economist-style chart theme for matplotlib and seaborn — global theme, title-stack
+finaliser, direct line labels, CI bands, horizontal bars, and dumbbell charts.
+Uses IBM Plex Sans typography and a curated 8-colour palette.
+
+Version: 0.1.0
+
+## Install
+
+```bash
+pip install djrhails-graphs
+```
+
+PyPI distribution is `djrhails-graphs` because the bare name `graphs` is taken.
+The import package is `graphs`.
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+ax.plot(x, y, label="Series A")
+label_lines(ax)
+finalize(
+    ax,
+    title="Bold chart title",
+    descriptor="Country, metric, unit",
+    source="Source: Organisation",
+)
+```
+
+See `examples/` for runnable scripts:
+
+- `line_chart.py` — multi-series line with CI bands + direct labels
+- `faceted_chart.py` — three-panel faceted layout with panel labels
+- `bar_chart.py` — horizontal bar with max-value highlight
+- `dumbbell_chart.py` — before/after comparison with legend
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `set_theme()` | Apply global rcParams (figure, axes, ticks, fonts, palette) |
+| `finalize(ax, title, descriptor, source, *, y_axis_right, title_x, y_start, autoscale_y)` | Title stack, red rule, source line, y-axis tidy-up |
+| `label_lines(ax, ...)` | Direct end-of-line labels with collision avoidance |
+| `smart_legend(ax, ...)` | Pick the emptiest corner of the axes |
+| `ci_fill(ax, x, y_lo, y_hi, *, color)` | Confidence-interval band |
+| `bar_h(ax, categories, values, *, highlight_max)` | Horizontal bar chart |
+| `dumbbell(ax, categories, start, end, ...)` | Dot-and-line before/after chart |
+| `panel_label(ax, label)` | Bold panel sub-heading for facets |
+
+### Palette
+
+```python
+from graphs import colors, C_BG, C_RED, C_SPINE, C_GRID, C_LABEL, C_TEXT, C_CI
+```
+
+Sequence `colors` (red primary, blue, teal, green, yellow, mauve, slate, coral).
+
+### Typography
+
+IBM Plex Sans is loaded automatically. If already registered in matplotlib's
+font manager, no download occurs. Otherwise TTFs are fetched from
+`github.com/IBM/plex` on first use and cached inside the installed package.
+
+Fallback chain: IBM Plex Sans → Verdana → Arial → DejaVu Sans.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

djrhails_graphs-0.1.0/README.md

@@ -0,0 +1,77 @@
+# graphs
+
+Economist-style chart theme for matplotlib and seaborn — global theme, title-stack
+finaliser, direct line labels, CI bands, horizontal bars, and dumbbell charts.
+Uses IBM Plex Sans typography and a curated 8-colour palette.
+
+Version: 0.1.0
+
+## Install
+
+```bash
+pip install djrhails-graphs
+```
+
+PyPI distribution is `djrhails-graphs` because the bare name `graphs` is taken.
+The import package is `graphs`.
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+ax.plot(x, y, label="Series A")
+label_lines(ax)
+finalize(
+    ax,
+    title="Bold chart title",
+    descriptor="Country, metric, unit",
+    source="Source: Organisation",
+)
+```
+
+See `examples/` for runnable scripts:
+
+- `line_chart.py` — multi-series line with CI bands + direct labels
+- `faceted_chart.py` — three-panel faceted layout with panel labels
+- `bar_chart.py` — horizontal bar with max-value highlight
+- `dumbbell_chart.py` — before/after comparison with legend
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `set_theme()` | Apply global rcParams (figure, axes, ticks, fonts, palette) |
+| `finalize(ax, title, descriptor, source, *, y_axis_right, title_x, y_start, autoscale_y)` | Title stack, red rule, source line, y-axis tidy-up |
+| `label_lines(ax, ...)` | Direct end-of-line labels with collision avoidance |
+| `smart_legend(ax, ...)` | Pick the emptiest corner of the axes |
+| `ci_fill(ax, x, y_lo, y_hi, *, color)` | Confidence-interval band |
+| `bar_h(ax, categories, values, *, highlight_max)` | Horizontal bar chart |
+| `dumbbell(ax, categories, start, end, ...)` | Dot-and-line before/after chart |
+| `panel_label(ax, label)` | Bold panel sub-heading for facets |
+
+### Palette
+
+```python
+from graphs import colors, C_BG, C_RED, C_SPINE, C_GRID, C_LABEL, C_TEXT, C_CI
+```
+
+Sequence `colors` (red primary, blue, teal, green, yellow, mauve, slate, coral).
+
+### Typography
+
+IBM Plex Sans is loaded automatically. If already registered in matplotlib's
+font manager, no download occurs. Otherwise TTFs are fetched from
+`github.com/IBM/plex` on first use and cached inside the installed package.
+
+Fallback chain: IBM Plex Sans → Verdana → Arial → DejaVu Sans.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

djrhails_graphs-0.1.0/djrhails_graphs.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: djrhails-graphs
+Version: 0.1.0
+Summary: Economist-style chart theme for matplotlib/seaborn
+Author-email: Daniel Hails <graphs@hails.info>
+Project-URL: Homepage, https://github.com/DJRHails/graphs
+Project-URL: Bug Tracker, https://github.com/DJRHails/graphs/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# graphs
+
+Economist-style chart theme for matplotlib and seaborn — global theme, title-stack
+finaliser, direct line labels, CI bands, horizontal bars, and dumbbell charts.
+Uses IBM Plex Sans typography and a curated 8-colour palette.
+
+Version: 0.1.0
+
+## Install
+
+```bash
+pip install djrhails-graphs
+```
+
+PyPI distribution is `djrhails-graphs` because the bare name `graphs` is taken.
+The import package is `graphs`.
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+ax.plot(x, y, label="Series A")
+label_lines(ax)
+finalize(
+    ax,
+    title="Bold chart title",
+    descriptor="Country, metric, unit",
+    source="Source: Organisation",
+)
+```
+
+See `examples/` for runnable scripts:
+
+- `line_chart.py` — multi-series line with CI bands + direct labels
+- `faceted_chart.py` — three-panel faceted layout with panel labels
+- `bar_chart.py` — horizontal bar with max-value highlight
+- `dumbbell_chart.py` — before/after comparison with legend
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `set_theme()` | Apply global rcParams (figure, axes, ticks, fonts, palette) |
+| `finalize(ax, title, descriptor, source, *, y_axis_right, title_x, y_start, autoscale_y)` | Title stack, red rule, source line, y-axis tidy-up |
+| `label_lines(ax, ...)` | Direct end-of-line labels with collision avoidance |
+| `smart_legend(ax, ...)` | Pick the emptiest corner of the axes |
+| `ci_fill(ax, x, y_lo, y_hi, *, color)` | Confidence-interval band |
+| `bar_h(ax, categories, values, *, highlight_max)` | Horizontal bar chart |
+| `dumbbell(ax, categories, start, end, ...)` | Dot-and-line before/after chart |
+| `panel_label(ax, label)` | Bold panel sub-heading for facets |
+
+### Palette
+
+```python
+from graphs import colors, C_BG, C_RED, C_SPINE, C_GRID, C_LABEL, C_TEXT, C_CI
+```
+
+Sequence `colors` (red primary, blue, teal, green, yellow, mauve, slate, coral).
+
+### Typography
+
+IBM Plex Sans is loaded automatically. If already registered in matplotlib's
+font manager, no download occurs. Otherwise TTFs are fetched from
+`github.com/IBM/plex` on first use and cached inside the installed package.
+
+Fallback chain: IBM Plex Sans → Verdana → Arial → DejaVu Sans.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

djrhails_graphs-0.1.0/djrhails_graphs.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+requirements.txt
+djrhails_graphs.egg-info/PKG-INFO
+djrhails_graphs.egg-info/SOURCES.txt
+djrhails_graphs.egg-info/dependency_links.txt
+djrhails_graphs.egg-info/requires.txt
+djrhails_graphs.egg-info/top_level.txt
+examples/bar_chart.py
+examples/dumbbell_chart.py
+examples/faceted_chart.py
+examples/line_chart.py
+graphs/__init__.py
+graphs/_charts.py
+graphs/_finalize.py
+graphs/_fonts.py
+graphs/_labels.py
+graphs/_legend.py
+graphs/_palette.py
+graphs/_theme.py

djrhails_graphs-0.1.0/djrhails_graphs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

djrhails_graphs-0.1.0/djrhails_graphs.egg-info/requires.txt

@@ -0,0 +1,2 @@
+matplotlib>=3.7
+numpy>=1.24

djrhails_graphs-0.1.0/djrhails_graphs.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+examples
+graphs

djrhails_graphs-0.1.0/examples/bar_chart.py

@@ -0,0 +1,38 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib"]
+# ///
+"""Horizontal bar chart — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+
+from graphs import bar_h, finalize, set_theme
+
+set_theme()
+
+categories = ["Germany", "France", "Italy", "Spain", "Poland", "Sweden"]
+values = [3.7, 2.4, 1.8, 2.1, 4.2, 3.1]
+
+fig, ax = plt.subplots(figsize=(7, 4))
+fig.subplots_adjust(top=0.62, bottom=0.10, left=0.14, right=0.90)
+
+bar_h(ax, categories, values)
+
+finalize(
+    ax,
+    title="Eastern promise",
+    descriptor="GDP growth rate, %, 2023",
+    source="Source: Eurostat",
+    y_axis_right=False,
+    title_x=0.02,
+)
+
+out = Path(__file__).resolve().parent / "economist_bar.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved bar chart")

djrhails_graphs-0.1.0/examples/dumbbell_chart.py

@@ -0,0 +1,72 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib"]
+# ///
+"""Dumbbell chart — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+
+from graphs import dumbbell, finalize, set_theme
+
+set_theme()
+
+countries = [
+    "United States",
+    "China",
+    "Germany",
+    "Japan",
+    "India",
+    "Brazil",
+]
+gdp_2000 = [10.25, 1.21, 1.95, 4.72, 0.47, 0.65]
+gdp_2020 = [20.93, 14.72, 3.84, 5.06, 2.62, 1.44]
+
+fig, ax = plt.subplots(figsize=(8, 4.5))
+fig.subplots_adjust(top=0.62, bottom=0.12, left=0.18, right=0.88)
+
+dumbbell(
+    ax,
+    countries,
+    gdp_2000,
+    gdp_2020,
+    label_start="2000",
+    label_end="2020",
+)
+ax.set_xlim(-0.5, 24)
+ax.xaxis.set_major_formatter(
+    ticker.FuncFormatter(lambda v, _: f"${v:.0f}tn")
+)
+
+finalize(
+    ax,
+    title="The great divergence",
+    descriptor="GDP in current US dollars, selected economies",
+    source="Source: World Bank",
+    y_axis_right=False,
+    title_x=0.02,
+)
+
+bbox = ax.get_position()
+fig.legend(
+    handles=ax._dumbbell_handles,
+    labels=["2000", "2020"],
+    loc="upper right",
+    bbox_to_anchor=(bbox.x1, bbox.y1 + 0.005),
+    bbox_transform=fig.transFigure,
+    frameon=False,
+    fontsize=8.5,
+    ncol=2,
+    handletextpad=0.4,
+    columnspacing=1.0,
+)
+
+out = Path(__file__).resolve().parent / "economist_dumbbell.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved dumbbell chart")

djrhails_graphs-0.1.0/examples/faceted_chart.py

@@ -0,0 +1,86 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib", "numpy"]
+# ///
+"""Faceted line chart with panel labels — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+import numpy as np
+
+from graphs import (
+    C_BG,
+    C_LABEL,
+    C_RED,
+    C_SPINE,
+    ci_fill,
+    finalize,
+    panel_label,
+    set_theme,
+)
+
+set_theme()
+
+np.random.seed(7)
+x = np.linspace(-6, 10, 80)
+panels = {
+    "Economic": np.where(
+        x < 0, x * 0.01, np.cumsum(np.random.randn(80) * 0.015)
+    ),
+    "Violent": np.cumsum(np.random.randn(80) * 0.008),
+    "Sexual": np.cumsum(np.random.randn(80) * 0.006),
+}
+
+fig, axes = plt.subplots(1, 3, figsize=(10, 5.5), sharey=False)
+fig.subplots_adjust(
+    top=0.72, bottom=0.16, left=0.04, right=0.97, wspace=0.35
+)
+
+for ax, (panel_name, y) in zip(axes, panels.items()):
+    ci = np.abs(np.random.randn(len(x))) * 0.025 + 0.01
+    ci_fill(ax, x, y - ci, y + ci)
+    ax.plot(x, y, color=C_RED, linewidth=2)
+    ax.axhline(0, color=C_SPINE, linewidth=0.8, zorder=3)
+    ax.scatter([0], [0], color=C_SPINE, s=40, zorder=5)
+
+    ax.yaxis.set_label_position("right")
+    ax.yaxis.tick_right()
+    ax.spines["right"].set_visible(True)
+    ax.spines["right"].set_color(C_BG)
+    ax.spines["bottom"].set_color(C_SPINE)
+    ax.spines[["top", "left"]].set_visible(False)
+    ax.yaxis.set_tick_params(pad=-2, labelsize=8.5)
+    ax.set_ylim(-0.22, 0.22)
+    ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.1f"))
+    ax.set_xlabel(
+        "Years since cancer diagnosis (1980-2018)",
+        fontsize=8,
+        color=C_LABEL,
+    )
+    panel_label(ax, panel_name)
+
+finalize(
+    axes[0],
+    title=(
+        "Denmark, criminal-conviction rate since\n"
+        "cancer diagnosis, by type of offense"
+    ),
+    descriptor="Percentage-point change from baseline",
+    source=(
+        'Source: "Breaking bad", '
+        "American Economics Journal, 2026"
+    ),
+    y_axis_right=False,
+    title_x=0.04,
+    y_start=0.075,
+)
+
+out = Path(__file__).resolve().parent / "economist_facet.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved facet chart")

djrhails_graphs-0.1.0/examples/line_chart.py

@@ -0,0 +1,50 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib", "numpy"]
+# ///
+"""Line chart with CI bands and direct labels — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+import numpy as np
+
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+np.random.seed(42)
+years = np.arange(2000, 2024)
+data = {
+    "United States": np.cumsum(np.random.randn(24) * 1.5) + 100,
+    "China": np.cumsum(np.random.randn(24) * 2.0) + 100,
+    "Germany": np.cumsum(np.random.randn(24) * 1.0) + 100,
+}
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+for col, y in data.items():
+    ci = np.abs(np.random.randn(len(years))) * 2.5 + 0.5
+    ci_fill(ax, years, y - ci, y + ci)
+    ax.plot(years, y, label=col)
+
+label_lines(ax, stroke=True, min_sep_pct=6.0)
+ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.0f"))
+
+finalize(
+    ax,
+    title="GDP across major economies",
+    descriptor="Index, 2000=100",
+    source="Sources: IMF; World Bank",
+    y_axis_right=True,
+)
+
+out = Path(__file__).resolve().parent / "economist_line.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved line chart")

djrhails_graphs-0.1.0/graphs/__init__.py

@@ -0,0 +1,52 @@
+"""graphs — Economist-style chart theme for matplotlib/seaborn.
+
+Usage::
+
+    from graphs import set_theme, finalize, colors
+    set_theme()
+
+    fig, ax = plt.subplots()
+    fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+    ax.plot(...)
+    finalize(ax, title="Bold headline", descriptor="Country, metric, unit",
+             source="Source: Organisation")
+"""
+
+from graphs._charts import bar_h, ci_fill, dumbbell
+from graphs._finalize import finalize, panel_label
+from graphs._fonts import _get_font as get_font
+from graphs._labels import label_lines
+from graphs._legend import smart_legend
+from graphs._palette import (
+    C_BG,
+    C_CI,
+    C_GRID,
+    C_LABEL,
+    C_RED,
+    C_SPINE,
+    C_TEXT,
+    colors,
+)
+from graphs._theme import set_theme
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "bar_h",
+    "ci_fill",
+    "colors",
+    "C_BG",
+    "C_CI",
+    "C_GRID",
+    "C_LABEL",
+    "C_RED",
+    "C_SPINE",
+    "C_TEXT",
+    "dumbbell",
+    "finalize",
+    "get_font",
+    "label_lines",
+    "panel_label",
+    "set_theme",
+    "smart_legend",
+]