eofigs 0.1.0__py3-none-any.whl

eofigs/__init__.py

@@ -0,0 +1,52 @@
+"""Analysis-aware, publication-ready figures for Earth observation research.
+
+eofigs is under development towards its first release (v0.1). Available now: journal
+styles, figure sizes in millimetres, panel labels, export and figure checks, the variable
+library, print-size raster handling, trend statistics, manuscript figure sets, built-in
+palettes, colour-blind previews, study area maps, trend maps, event composites and accuracy
+scatters.
+"""
+
+from eofigs import palettes
+from eofigs.accuracy import accuracy_scatter
+from eofigs.check import CheckReport, CheckResult, check_figure, cvd_preview
+from eofigs.events import event_composite
+from eofigs.export import save_figure
+from eofigs.figures import FigureSet, figure_set
+from eofigs.maps import add_inset, add_north_arrow, add_scale_bar, study_area_map
+from eofigs.raster import fit_raster
+from eofigs.stats import trend
+from eofigs.styling import label_panels, new_figure, set_style, style, tidy_axes
+from eofigs.trends import trend_map
+from eofigs.variables import Variable, register_variable, variable
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CheckReport",
+    "CheckResult",
+    "FigureSet",
+    "Variable",
+    "__version__",
+    "accuracy_scatter",
+    "add_inset",
+    "add_north_arrow",
+    "add_scale_bar",
+    "check_figure",
+    "cvd_preview",
+    "event_composite",
+    "figure_set",
+    "fit_raster",
+    "label_panels",
+    "new_figure",
+    "palettes",
+    "register_variable",
+    "save_figure",
+    "set_style",
+    "study_area_map",
+    "style",
+    "tidy_axes",
+    "trend",
+    "trend_map",
+    "variable",
+]

eofigs/_colour.py

@@ -0,0 +1,258 @@
+"""Colour science helpers: CIELAB, CIEDE2000, colour-vision simulation, colour-map classes."""
+
+from __future__ import annotations
+
+import numpy as np
+from matplotlib.colors import Colormap
+
+# Okabe & Ito (2008) categorical colours, black last.
+OKABE_ITO = (
+    "#E69F00",
+    "#56B4E9",
+    "#009E73",
+    "#F0E442",
+    "#0072B2",
+    "#D55E00",
+    "#CC79A7",
+    "#000000",
+)
+TEXT_COLOUR = "#1A1A1A"
+SECONDARY_COLOUR = "#4D4D4D"
+GRID_COLOUR = "#E0E0E0"
+NO_DATA_COLOUR = "#BDBDBD"
+
+# Machado, Oliveira & Fernandes (2009), severity 1.0, applied to linear sRGB.
+CVD_MATRICES = {
+    "protan": np.array(
+        [
+            [0.152286, 1.052583, -0.204868],
+            [0.114503, 0.786281, 0.099216],
+            [-0.003882, -0.048116, 1.051998],
+        ]
+    ),
+    "deutan": np.array(
+        [
+            [0.367322, 0.860646, -0.227968],
+            [0.280085, 0.672501, 0.047413],
+            [-0.011820, 0.042940, 0.968881],
+        ]
+    ),
+    "tritan": np.array(
+        [
+            [1.255528, -0.076749, -0.178779],
+            [-0.078411, 0.930809, 0.147602],
+            [0.004733, 0.691367, 0.303900],
+        ]
+    ),
+}
+
+_SRGB_TO_XYZ = np.array(
+    [
+        [0.4124564, 0.3575761, 0.1804375],
+        [0.2126729, 0.7151522, 0.0721750],
+        [0.0193339, 0.1191920, 0.9503041],
+    ]
+)
+_D65 = np.array([0.95047, 1.0, 1.08883])
+
+# Colour-map classes. Names are compared without a "cmc." or "eofigs." prefix and without "_r".
+CMAP_BANNED = frozenset(
+    {
+        "jet",
+        "rainbow",
+        "hsv",
+        "nipy_spectral",
+        "turbo",
+        "gist_rainbow",
+        "gist_ncar",
+        "flag",
+        "prism",
+    }
+)
+CMAP_SEQUENTIAL = frozenset(
+    {
+        # cmcrameri
+        "acton", "bamako", "batlow", "batlowK", "batlowW", "bilbao", "buda", "davos", "devon",
+        "glasgow", "grayC", "hawaii", "imola", "lajolla", "lapaz", "lipari", "navia", "nuuk",
+        "oslo", "tokyo", "turku",
+        # matplotlib perceptually uniform and single-hue sequential
+        "viridis", "plasma", "inferno", "magma", "cividis", "Greys", "Purples", "Blues",
+        "Greens", "Oranges", "Reds", "YlOrBr", "YlOrRd", "OrRd", "PuRd", "RdPu", "BuPu", "GnBu",
+        "PuBu", "YlGnBu", "PuBuGn", "BuGn", "YlGn", "gray", "binary", "bone",
+        # eofigs
+        "slate",
+    }
+)  # fmt: skip
+CMAP_DIVERGING = frozenset(
+    {
+        # cmcrameri
+        "bam", "berlin", "broc", "cork", "lisbon", "managua", "roma", "tofino", "vanimo", "vik",
+        # matplotlib
+        "PiYG", "PRGn", "BrBG", "PuOr", "RdGy", "RdBu", "RdYlBu", "RdYlGn", "Spectral",
+        "coolwarm", "bwr", "seismic",
+        # eofigs
+        "terra_slate",
+    }
+)  # fmt: skip
+CMAP_MULTI_SEQUENTIAL = frozenset({"bukavu", "fes", "oleron"})
+CMAP_CYCLIC = frozenset({"bamO", "brocO", "corkO", "romaO", "vikO", "twilight", "twilight_shifted"})
+CMAP_CATEGORICAL = frozenset(
+    {
+        "tab10", "tab20", "tab20b", "tab20c", "Set1", "Set2", "Set3", "Paired", "Accent",
+        "Dark2", "Pastel1", "Pastel2",
+    }
+)  # fmt: skip
+
+
+def to_linear(rgb: np.ndarray) -> np.ndarray:
+    """Convert sRGB values in [0, 1] to linear RGB."""
+    rgb = np.asarray(rgb, dtype=float)
+    return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def to_srgb(lin: np.ndarray) -> np.ndarray:
+    """Convert linear RGB to sRGB values in [0, 1]."""
+    lin = np.clip(lin, 0.0, 1.0)
+    return np.where(lin <= 0.0031308, lin * 12.92, 1.055 * lin ** (1 / 2.4) - 0.055)
+
+
+def simulate_cvd(rgb: np.ndarray, kind: str) -> np.ndarray:
+    """Simulate protan, deutan or tritan vision (Machado et al. 2009, full severity)."""
+    return to_srgb(to_linear(rgb) @ CVD_MATRICES[kind].T)
+
+
+def to_lab(rgb: np.ndarray) -> np.ndarray:
+    """Convert sRGB values in [0, 1] (last axis = channels) to CIELAB (D65)."""
+    xyz = to_linear(rgb) @ _SRGB_TO_XYZ.T / _D65
+    f = np.where(xyz > 216 / 24389, np.cbrt(xyz), (24389 / 27 * xyz + 16) / 116)
+    lightness = 116 * f[..., 1] - 16
+    a = 500 * (f[..., 0] - f[..., 1])
+    b = 200 * (f[..., 1] - f[..., 2])
+    return np.stack([lightness, a, b], axis=-1)
+
+
+def delta_e2000(lab1: np.ndarray, lab2: np.ndarray) -> float:
+    """CIEDE2000 colour difference between two CIELAB colours."""
+    l1, a1, b1 = (float(v) for v in lab1)
+    l2, a2, b2 = (float(v) for v in lab2)
+    c1, c2 = np.hypot(a1, b1), np.hypot(a2, b2)
+    c_mean = (c1 + c2) / 2
+    g = 0.5 * (1 - np.sqrt(c_mean**7 / (c_mean**7 + 25**7)))
+    a1p, a2p = (1 + g) * a1, (1 + g) * a2
+    c1p, c2p = np.hypot(a1p, b1), np.hypot(a2p, b2)
+    h1p = np.degrees(np.arctan2(b1, a1p)) % 360
+    h2p = np.degrees(np.arctan2(b2, a2p)) % 360
+    dlp, dcp = l2 - l1, c2p - c1p
+    if c1p * c2p == 0:
+        dh = 0.0
+    else:
+        dh = h2p - h1p
+        if dh > 180:
+            dh -= 360
+        elif dh < -180:
+            dh += 360
+    dhp = 2 * np.sqrt(c1p * c2p) * np.sin(np.radians(dh / 2))
+    lp_mean, cp_mean = (l1 + l2) / 2, (c1p + c2p) / 2
+    if c1p * c2p == 0:
+        hp_mean = h1p + h2p
+    elif abs(h1p - h2p) <= 180:
+        hp_mean = (h1p + h2p) / 2
+    elif h1p + h2p < 360:
+        hp_mean = (h1p + h2p + 360) / 2
+    else:
+        hp_mean = (h1p + h2p - 360) / 2
+    t = (
+        1
+        - 0.17 * np.cos(np.radians(hp_mean - 30))
+        + 0.24 * np.cos(np.radians(2 * hp_mean))
+        + 0.32 * np.cos(np.radians(3 * hp_mean + 6))
+        - 0.20 * np.cos(np.radians(4 * hp_mean - 63))
+    )
+    d_theta = 30 * np.exp(-(((hp_mean - 275) / 25) ** 2))
+    r_c = 2 * np.sqrt(cp_mean**7 / (cp_mean**7 + 25**7))
+    s_l = 1 + 0.015 * (lp_mean - 50) ** 2 / np.sqrt(20 + (lp_mean - 50) ** 2)
+    s_c = 1 + 0.045 * cp_mean
+    s_h = 1 + 0.015 * cp_mean * t
+    r_t = -np.sin(np.radians(2 * d_theta)) * r_c
+    return float(
+        np.sqrt(
+            (dlp / s_l) ** 2 + (dcp / s_c) ** 2 + (dhp / s_h) ** 2 + r_t * (dcp / s_c) * (dhp / s_h)
+        )
+    )
+
+
+def base_cmap_name(cmap: Colormap) -> str:
+    """Return a colour map's name without a ``cmc.``/``eofigs.`` prefix or ``_r`` suffix."""
+    name = cmap.name
+    for prefix in ("cmc.", "eofigs."):
+        if name.startswith(prefix):
+            name = name[len(prefix) :]
+    if name.endswith("_r"):
+        name = name[:-2]
+    return name
+
+
+def cmap_lightness(cmap: Colormap, n: int = 256) -> np.ndarray:
+    """CIELAB lightness L* sampled evenly along a colour map."""
+    rgb = cmap(np.linspace(0, 1, n))[:, :3]
+    return to_lab(rgb)[:, 0]
+
+
+def is_monotonic(values: np.ndarray, tol: float = 1.0) -> bool:
+    """Test whether values only increase or only decrease.
+
+    Small reversals are allowed: the values may fall back by at most ``tol`` below their
+    running maximum (increasing) or rise by at most ``tol`` above their running minimum
+    (decreasing), which absorbs rounding in sampled colour maps.
+    """
+    values = np.asarray(values, dtype=float)
+    increasing = np.max(np.maximum.accumulate(values) - values) <= tol
+    decreasing = np.max(values - np.minimum.accumulate(values)) <= tol
+    return bool(increasing or decreasing)
+
+
+def classify_cmap(cmap: Colormap) -> str:
+    """Classify a colour map by how its lightness should behave.
+
+    Returns ``"banned"``, ``"sequential"``, ``"diverging"``, ``"multi-sequential"``,
+    ``"cyclic"``, ``"categorical"`` or ``"unknown"``. Known cmcrameri and matplotlib
+    names are classified from fixed lists. Other maps are
+    classified from their lightness profile; maps that fit no class are returned as
+    ``"unknown"``.
+    """
+    name = base_cmap_name(cmap)
+    if name in CMAP_BANNED:
+        return "banned"
+    for kind, names in (
+        ("sequential", CMAP_SEQUENTIAL),
+        ("diverging", CMAP_DIVERGING),
+        ("multi-sequential", CMAP_MULTI_SEQUENTIAL),
+        ("cyclic", CMAP_CYCLIC),
+        ("categorical", CMAP_CATEGORICAL),
+    ):
+        if name in names:
+            return kind
+    if name.endswith("S") and name[:-1] in CMAP_SEQUENTIAL | {"batlowK", "batlowW"}:
+        return "categorical"
+    lightness = cmap_lightness(cmap)
+    if is_monotonic(lightness):
+        return "sequential"
+    if diverging_ok(lightness):
+        return "diverging"
+    return "unknown"
+
+
+def diverging_ok(lightness: np.ndarray, tol: float = 1.0) -> bool:
+    """Test whether lightness is monotonic on each side of its extreme value near the centre."""
+    n = lightness.size
+    mid = slice(n // 4, 3 * n // 4)
+    centre = lightness[mid]
+    ends = (lightness[0] + lightness[-1]) / 2
+    k = n // 4 + int(np.argmax(centre) if centre.mean() >= ends else np.argmin(centre))
+    return is_monotonic(lightness[: k + 1], tol) and is_monotonic(lightness[k:], tol)
+
+
+def multi_sequential_ok(lightness: np.ndarray, tol: float = 1.0) -> bool:
+    """Test whether each half of a two-part colour map has monotonic lightness."""
+    half = lightness.size // 2
+    return is_monotonic(lightness[:half], tol) and is_monotonic(lightness[half:], tol)

eofigs/_countries.py

@@ -0,0 +1,157 @@
+"""Country outlines for locator insets: bundled default and optional Natural Earth worldviews."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from importlib import resources
+from pathlib import Path
+
+NE_VERSION = "5.1.2"
+
+#: Natural Earth worldviews (point-of-view country layers), by lower-case code. ``iso`` and
+#: ``tlc`` are Natural Earth's ISO-based and "Top Level Country" variants.
+WORLDVIEWS = (
+    "arg", "bdg", "bra", "chn", "deu", "egy", "esp", "fra", "gbr", "grc", "idn", "ind",
+    "iso", "isr", "ita", "jpn", "kor", "mar", "nep", "nld", "pak", "pol", "prt", "pse",
+    "rus", "sau", "swe", "tlc", "tur", "twn", "ukr", "usa", "vnm",
+)  # fmt: skip
+
+#: sha256 of each worldview file at NE_VERSION (docs/scripts/worldview_checksums.py).
+WORLDVIEW_SHA256: dict[str, str] = {
+    "arg": "357fbb518e4288d32734087c91ac9f27d630068f7f60552d225ff64a6c04ed12",
+    "bdg": "38dc28eea054c58cd828ca846cd08bd31007451b5c3591df0d73483d24380ed7",
+    "bra": "131c5102ecf8f87f8462bb2bb50d114e3d80c3076ad61bc29122ace3fb97186d",
+    "chn": "16e7589083527d01208b9f645fc8643c767170258e9d13b59d37bc5a1f6a8758",
+    "deu": "125fc4b1f425926b8bd22dce23af6f9f873543c2fe330915ccbe0aa7fa21ff82",
+    "egy": "11a59f8d01367bfe49e1e65a04349dc670a4341ba9465683b10e70f34576f5ef",
+    "esp": "cc953fbb5ee827ca39d49940491fe48b3979a7ca4b10649c36d66948ad3ea7a0",
+    "fra": "e5537c00e42ef027db1be55f3cadaf97441a8edea7435c3731c742175267d48c",
+    "gbr": "23e586f7225a4a83b20178b78b8b8209b14bc6c385b09add44e3a2e50ac6dac3",
+    "grc": "dfb2253a2ee995a4f2a4ea9ae90c6b915080d85144be7a37971be33ca7096592",
+    "idn": "358d61ae12a92f9d42bb2193877030b4bff1193ff967ce0f0d9edb51b60acfea",
+    "ind": "36a54ee97a509325e98eb44fd91bc7e53b0c5139cf10039918042bbd64102192",
+    "iso": "9a097f5c5fe0cd2e0f1f120a507f9f8e421c6ff7e20a2e4c8621311081b55453",
+    "isr": "36c2af239f9a04d2d104e893ce82ca52fea7dafbceac91a09be5b9c0569ecf68",
+    "ita": "76f28332474ffdd7717fc67dcd8f0b2086eb8405c71fa47bf857ff42642a9615",
+    "jpn": "d9dde4daa1b51fef2ee76b7e7ab86eb0f5deffc6bacb64dd9cacdd6cec6e880c",
+    "kor": "4d7d99017cc81e5825295e781c21361c3f3b86b702d515302770924cf0c4cbf8",
+    "mar": "9956aa888e35c4ca8d8d10a918469b3695316cfc6528d41d48bbfbeff19f3d4b",
+    "nep": "4755295da115a74668886f37db1b8a6b631a28e5c30a5cf7e47d799565a6d365",
+    "nld": "19f257724022f2c694e80f52c7e3263da75ec0f0f0c7a39ae22bd5672a492375",
+    "pak": "cb6730734f7ffd64a087ec8cd801291ddf4507611c9902bd800362f2813a653b",
+    "pol": "eef38fb79a91f9d26e1645f761dfafe9550ec217c73ac443f824581d42f5f197",
+    "prt": "b1ca5db9522ba7d249b62fec5bab48afed74b42fbbcc79743a9722b7d8dcc35b",
+    "pse": "8a69cbfe9402ac5bbd6e24e81cce6950137e0d7524023df9f5cfbd467bfdc976",
+    "rus": "8309218a2d9b0b2a7f218a03fa05825a7757390ccec4d793e6e8e6a6015dd04d",
+    "sau": "36191159ec58c7beaca1e2508cef84155b9dccba143d621ee336b60b81e786c0",
+    "swe": "6ff518e3d0079108fc12996a72352d30c86b251431ec506b6573a1eebd9d6bc6",
+    "tlc": "07b9ea4ffe9daa6b5280dc3c3343d176db5c05c77e4975918501356ca2080ce4",
+    "tur": "2019fd24f5ac8dc68b90a2f26e236e5e1f5bd97b75e7e88520c3f20ac22e7fde",
+    "twn": "5a3a14498c8fed258452de9e207d5e226b6fd279a43ff191897674708c219e9b",
+    "ukr": "6fcdaed26c8d551018fbd3b97185df863a4f15f489e602fceae1dee90d6a5ae8",
+    "usa": "4dd67d07246421372a3ea069d0b58b8ae28fe42c6a787a18411025b68f614d03",
+    "vnm": "09e8e8d4fa210d8d8b5d8d0c988bf3e2ff37beda138ac97af2b044b7859ef7a2",
+}
+
+#: Simplification tolerance in degrees for downloaded worldviews (inset scale).
+SIMPLIFY_DEG = 0.02
+
+
+def worldview_url(code: str) -> str:
+    """URL of one worldview file (1:10m admin-0 countries) at the pinned version."""
+    return (
+        f"https://naciscdn.org/naturalearth/{NE_VERSION}/10m/cultural/"
+        f"ne_10m_admin_0_countries_{code}.zip"
+    )
+
+
+def cache_dir() -> Path:
+    """Folder for downloaded data (``EOFIGS_CACHE`` overrides the platform default)."""
+    if os.environ.get("EOFIGS_CACHE"):
+        return Path(os.environ["EOFIGS_CACHE"])
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+        return base / "eofigs" / "Cache"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "eofigs"
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "eofigs"
+
+
+def _normalise(worldview: str) -> str:
+    code = str(worldview).strip().lower()
+    if code not in WORLDVIEWS:
+        raise ValueError(
+            f"Unknown worldview {worldview!r}. Natural Earth provides: "
+            f"{', '.join(c.upper() for c in WORLDVIEWS)}; or pass worldview=None for the "
+            "default (de facto) boundaries."
+        )
+    return code
+
+
+def countries(worldview: str | None = None):
+    """Country outlines (EPSG:4326) with ``code`` and ``name`` columns.
+
+    ``None`` returns the bundled Natural Earth 1:110m layer (de facto boundaries). A
+    worldview code such as ``"PAK"`` or ``"IND"`` returns that country's point of view,
+    downloaded once from Natural Earth (version pinned, checksum verified), simplified
+    to inset scale and cached.
+    """
+    import geopandas as gpd
+
+    if worldview is None:
+        path = resources.files("eofigs").joinpath("data/ne_110m_countries.geojson")
+        with resources.as_file(path) as local:
+            return gpd.read_file(local)
+    code = _normalise(worldview)
+    cached = cache_dir() / f"ne_{NE_VERSION}_countries_{code}.geojson"
+    if not cached.exists():
+        _build_worldview(code, cached)
+    return gpd.read_file(cached)
+
+
+def _download(url: str, target: Path) -> None:
+    try:
+        with urllib.request.urlopen(url, timeout=60) as response, target.open("wb") as fh:  # noqa: S310
+            while chunk := response.read(1 << 20):
+                fh.write(chunk)
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise RuntimeError(
+            f"Could not download the Natural Earth worldview file {url} ({exc}). eofigs "
+            "needs the internet once for each worldview; after that it is cached in "
+            f"{cache_dir()}. Offline, use worldview=None (bundled default boundaries) or "
+            "pass your own boundaries as a GeoDataFrame (countries=...)."
+        ) from exc
+
+
+def _build_worldview(code: str, cached: Path) -> None:
+    import geopandas as gpd
+
+    expected = WORLDVIEW_SHA256.get(code)
+    if expected is None:
+        raise RuntimeError(f"No checksum is recorded for worldview {code.upper()!r}.")
+    cached.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory() as tmp:
+        archive = Path(tmp) / f"{code}.zip"
+        _download(worldview_url(code), archive)
+        digest = hashlib.sha256(archive.read_bytes()).hexdigest()
+        if digest != expected:
+            raise RuntimeError(
+                f"The downloaded worldview file for {code.upper()} does not match its "
+                f"checksum (got {digest[:12]}..., expected {expected[:12]}...); it was not "
+                "used. Try again later."
+            )
+        data = gpd.read_file(f"zip://{archive.as_posix()}")
+    data = data.to_crs("EPSG:4326")
+    out = gpd.GeoDataFrame(
+        {"code": data["ADM0_A3"], "name": data["NAME_EN"]},
+        geometry=data.geometry.simplify(SIMPLIFY_DEG, preserve_topology=True),
+        crs="EPSG:4326",
+    )
+    partial = cached.with_suffix(".part")
+    out.to_file(partial, driver="GeoJSON")
+    partial.replace(cached)

eofigs/_presets.py

@@ -0,0 +1,147 @@
+"""Journal presets loaded from the bundled ``data/journals.json``."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+
+MM_PER_INCH = 25.4
+
+
+@dataclass(frozen=True)
+class Journal:
+    """Figure requirements of one publisher, read from ``journals.json``."""
+
+    key: str
+    name: str
+    widths_mm: dict[str, float]
+    max_height_mm: float
+    min_font_pt: float
+    base_font_pt: float
+    font_family: str
+    fonts: tuple[str, ...]
+    dpi: dict[str, int]
+    export_dpi: int
+    formats: tuple[str, ...]
+    source_url: str
+    checked: str
+    eofigs_defaults: tuple[str, ...]
+    notes: str
+
+    @property
+    def max_width_mm(self) -> float:
+        """Largest named width (full page or text width)."""
+        return max(self.widths_mm.values())
+
+    def required_dpi(self, art: str = "combination") -> int:
+        """Resolution the publisher asks for one artwork type.
+
+        Parameters
+        ----------
+        art : {"combination", "line", "halftone"}
+            ``"line"`` for line art (plots and drawings), ``"halftone"`` for photographs
+            and continuous-tone images, ``"combination"`` for figures that mix both.
+        """
+        return int(self.dpi[check_art(art)])
+
+    def export_dpi_for(self, art: str = "combination") -> int:
+        """Default raster resolution: the export resolution or the requirement, if higher."""
+        return max(self.export_dpi, self.required_dpi(art))
+
+
+@lru_cache(maxsize=1)
+def _load() -> dict:
+    text = resources.files("eofigs").joinpath("data/journals.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+ART_TYPES = ("combination", "line", "halftone")
+
+
+def check_art(art: str) -> str:
+    """Validate an artwork type name.
+
+    Raises
+    ------
+    ValueError
+        If ``art`` is not ``"combination"``, ``"line"`` or ``"halftone"``.
+    """
+    if art not in ART_TYPES:
+        raise ValueError(f"art must be one of {ART_TYPES} (got {art!r}).")
+    return art
+
+
+def journal_keys() -> list[str]:
+    """Names of all bundled journal presets."""
+    return sorted(_load()["journals"])
+
+
+def get_journal(name: str | Journal) -> Journal:
+    """Return the preset for ``name`` (case-insensitive; aliases such as ``"tandf"`` accepted).
+
+    Raises
+    ------
+    ValueError
+        If no preset has that name. The message lists the available presets.
+    """
+    if isinstance(name, Journal):
+        return name
+    data = _load()
+    key = str(name).strip().lower()
+    key = data["aliases"].get(key, key)
+    if key not in data["journals"]:
+        raise ValueError(
+            f"Unknown journal {name!r}. Available presets: {', '.join(journal_keys())}. "
+            "Use 'custom' for a generic preset."
+        )
+    entry = data["journals"][key]
+    return Journal(
+        key=key,
+        name=entry["name"],
+        widths_mm={k: float(v) for k, v in entry["widths_mm"].items()},
+        max_height_mm=float(entry["max_height_mm"]),
+        min_font_pt=float(entry["min_font_pt"]),
+        base_font_pt=float(entry["base_font_pt"]),
+        font_family=entry["font_family"],
+        fonts=tuple(entry["fonts"]),
+        dpi={k: int(v) for k, v in entry["dpi"].items()},
+        export_dpi=int(entry["export_dpi"]),
+        formats=tuple(entry["formats"]),
+        source_url=entry["source_url"],
+        checked=entry["checked"],
+        eofigs_defaults=tuple(entry["eofigs_defaults"]),
+        notes=entry["notes"],
+    )
+
+
+def resolve_width(width: str | float, journal: Journal) -> float:
+    """Convert a named width (``"single"``, ``"double"``, ...) or a number in mm to mm.
+
+    Raises
+    ------
+    ValueError
+        For an unknown width name, a non-positive width, or a width larger than the
+        journal's full text width.
+    """
+    if isinstance(width, str):
+        if width not in journal.widths_mm:
+            raise ValueError(
+                f"Unknown width {width!r} for {journal.name}. "
+                f"Use one of {sorted(journal.widths_mm)} or a number in mm."
+            )
+        return journal.widths_mm[width]
+    width_mm = float(width)
+    if width_mm <= 0:
+        raise ValueError(f"width must be positive (got {width_mm} mm).")
+    if width_mm > journal.max_width_mm + 0.5:
+        raise ValueError(
+            f"width {width_mm:g} mm is wider than {journal.name}'s full width "
+            f"({journal.max_width_mm:g} mm). Use width='{_widest(journal)}' or a smaller number."
+        )
+    return width_mm
+
+
+def _widest(journal: Journal) -> str:
+    return max(journal.widths_mm, key=journal.widths_mm.get)