fluxplot 0.1.0__py3-none-any.whl

fluxplot/fits.py

@@ -0,0 +1,240 @@
+"""``fp.regression`` and ``fp.kde``: fitted curves drawn as addressable series with the fit recorded.
+
+A regression is three parts of one series — the points (``<series>.point.k``), the fit line
+(``<series>.fit``) and its confidence band (``<series>.band``) — and a ``regression`` payload in
+the manifest: the coefficients, R², the p-value, n and the confidence level, so a caption or a
+consumer can state the fit exactly as drawn. A KDE is a line (and optionally its fill) with the
+evaluation grid and density recorded, so it can be re-drawn without the raw values.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+import numpy as np
+
+from . import data as _data
+from . import tagger as _tagger
+from .descriptors import Mark
+
+__all__ = ["regression", "kde", "RegressionResult", "KdeResult", "lowess", "REGRESSION_KINDS"]
+
+REGRESSION_KINDS = ("linear", "poly", "lowess")
+_BOOT_SEED = 0
+
+
+@dataclass
+class RegressionResult:
+    ax: Any
+    #: the fit ``Line2D``, the band ``PolyCollection`` (or ``None``) and the points (or ``None``)
+    line: Any
+    band: Any
+    points: Any
+    #: the evaluation grid and the fitted curve with its confidence bounds
+    grid: np.ndarray = field(repr=False, default=None)
+    fit: np.ndarray = field(repr=False, default=None)
+    lower: np.ndarray = field(repr=False, default=None)
+    upper: np.ndarray = field(repr=False, default=None)
+    #: ``{kind, degree, coefficients, r2, p, n, ci, …}`` as the manifest records it
+    stats: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class KdeResult:
+    ax: Any
+    line: Any
+    area: Any
+    grid: np.ndarray = field(repr=False, default=None)
+    density: np.ndarray = field(repr=False, default=None)
+    stats: Dict[str, Any] = field(default_factory=dict)
+
+
+def _clean_xy(x, y, who):
+    x = np.asarray(x, dtype=float).ravel()
+    y = np.asarray(y, dtype=float).ravel()
+    if x.size != y.size:
+        raise ValueError(f"{who}: x and y have different lengths ({x.size} vs {y.size})")
+    ok = np.isfinite(x) & np.isfinite(y)
+    if ok.sum() < 3:
+        raise ValueError(f"{who} needs at least 3 finite (x, y) pairs, got {int(ok.sum())}")
+    return x[ok], y[ok]
+
+
+def lowess(x, y, grid, frac=2 / 3, it=3):
+    """Cleveland's (1979) locally weighted regression: at each grid point a linear fit weighted by
+    the tricube of distance to the nearest ``frac`` of the data, with ``it`` robustifying
+    iterations that down-weight large residuals (bisquare). Returns the smooth on ``grid``."""
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    grid = np.asarray(grid, dtype=float)
+    n = x.size
+    k = max(int(np.ceil(frac * n)), 2)
+    robust = np.ones(n)
+
+    def fit_at(x0, weights_extra):
+        d = np.abs(x - x0)
+        h = np.sort(d)[min(k, n) - 1] or 1e-12
+        w = np.clip(1 - (d / h) ** 3, 0, 1) ** 3 * weights_extra
+        sw = w.sum()
+        if sw <= 0:
+            return np.nan
+        xm = (w * x).sum() / sw
+        ym = (w * y).sum() / sw
+        var = (w * (x - xm) ** 2).sum()
+        slope = (w * (x - xm) * (y - ym)).sum() / var if var > 0 else 0.0
+        return ym + slope * (x0 - xm)
+
+    for _ in range(max(it, 0)):
+        fitted = np.array([fit_at(xi, robust) for xi in x])
+        resid = y - fitted
+        s = np.median(np.abs(resid)) or 1e-12
+        robust = np.clip(1 - (resid / (6 * s)) ** 2, 0, 1) ** 2
+    return np.array([fit_at(g, robust) for g in grid])
+
+
+def _poly_ci(x, y, grid, degree, ci):
+    """Polynomial least squares with the confidence band of the mean response."""
+    from scipy import stats as _sp
+    n = x.size
+    dof = n - (degree + 1)
+    if dof < 1:
+        raise ValueError(f"regression: degree {degree} needs more than {degree + 1} points (n={n})")
+    coef, cov = np.polyfit(x, y, degree, cov=True)
+    fit_grid = np.polyval(coef, grid)
+    fitted = np.polyval(coef, x)
+    design = np.vander(grid, degree + 1)  # highest power first, as polyfit's coefficients
+    se = np.sqrt(np.einsum("ij,jk,ik->i", design, cov, design))
+    t = _sp.t.ppf(0.5 + ci / 2, dof)
+    ss_res = float(((y - fitted) ** 2).sum())
+    ss_tot = float(((y - y.mean()) ** 2).sum())
+    r2 = 1 - ss_res / ss_tot if ss_tot > 0 else float("nan")
+    if degree == 1:
+        p = float(_sp.linregress(x, y).pvalue)
+    else:
+        f = ((ss_tot - ss_res) / degree) / (ss_res / dof) if ss_res > 0 else float("inf")
+        p = float(_sp.f.sf(f, degree, dof))
+    return coef, fit_grid, fit_grid - t * se, fit_grid + t * se, r2, p, dof
+
+
+def regression(ax, x, y, *, series, kind="linear", ci=0.95, degree=1, frac=2 / 3, points=True, n_grid=100,
+               n_boot=200, label=None, color=None, band_kw=None, point_kw=None, **line_kw) -> RegressionResult:
+    """Fit ``y ~ x`` and draw the fit line, its confidence band and (by default) the points as one
+    series, recording the fit in the manifest.
+
+    Parameters
+    ----------
+    kind
+        ``"linear"`` (a straight line), ``"poly"`` (a polynomial of ``degree``) or ``"lowess"``
+        (Cleveland's locally weighted regression with span ``frac``).
+    ci
+        The confidence level of the band: for linear / poly the t-interval of the mean response;
+        for lowess a seeded percentile bootstrap of the smooth (``n_boot`` resamples).
+    points
+        Draw the observations as ``<series>.point.k`` too.
+    color
+        The series colour (line, band and points); default the cycle's next colour.
+    band_kw, point_kw, **line_kw
+        Extra keywords for the band (``fill_between``), the points (``scatter``) and the fit line.
+
+    Returns
+    -------
+    RegressionResult
+        With ``stats = {kind, degree, coefficients, r2, p, n, ci, frac?}`` (``coefficients`` in
+        ``numpy.polyfit`` order, highest power first; ``None`` for lowess, whose ``p`` is ``None``).
+    """
+    from .api import _series_color, band as _band, scatter as _scatter
+    if kind not in REGRESSION_KINDS:
+        raise ValueError(f"regression: kind must be one of {REGRESSION_KINDS}, got {kind!r}")
+    if not 0 < ci < 1:
+        raise ValueError(f"regression: ci must lie in (0, 1), got {ci!r}")
+    xs, ys = _clean_xy(x, y, "regression")
+    grid = np.linspace(xs.min(), xs.max(), int(n_grid))
+    deg = 1 if kind == "linear" else int(degree)
+    if kind in ("linear", "poly"):
+        coef, fit, lo, hi, r2, p, dof = _poly_ci(xs, ys, grid, deg, ci)
+        stats = {"kind": kind, "degree": deg, "coefficients": [float(c) for c in coef], "r2": float(r2), "p": p,
+                 "n": int(xs.size), "ci": float(ci), "dof": int(dof)}
+    else:
+        fit = lowess(xs, ys, grid, frac=frac)
+        rng = np.random.default_rng(_BOOT_SEED)
+        draws = []
+        for _ in range(int(n_boot)):
+            idx = rng.integers(0, xs.size, xs.size)
+            draws.append(lowess(xs[idx], ys[idx], grid, frac=frac))
+        draws = np.array(draws)
+        lo, hi = np.nanpercentile(draws, [50 * (1 - ci), 50 * (1 + ci)], axis=0)
+        fitted = np.interp(xs, grid, fit)
+        ss_res = float(((ys - fitted) ** 2).sum())
+        ss_tot = float(((ys - ys.mean()) ** 2).sum())
+        stats = {"kind": "lowess", "degree": None, "coefficients": None,
+                 "r2": 1 - ss_res / ss_tot if ss_tot > 0 else float("nan"), "p": None, "n": int(xs.size),
+                 "ci": float(ci), "frac": float(frac), "bootstrap": int(n_boot)}
+
+    kw = dict(line_kw)
+    if color is not None:
+        kw["color"] = color
+    _series_color(series, kw)
+    the_color = kw.get("color")
+    reg = _tagger.registry_for(ax.figure)
+    # the fit is registered first, so the series is a "regression" (its first mark names its kind);
+    # drawn first too, it still sits above the points (a line's zorder beats a collection's)
+    (ln,) = ax.plot(grid, fit, label=label, **kw)
+    if the_color is None:
+        the_color = ln.get_color()
+    payload = {**stats, "grid": _data.values(grid), "fit": _data.values(fit)}
+    reg.add(Mark(role="line", series=series, name="fit", kind="regression", x=_data.values(grid), y=_data.values(fit),
+                 label=label, artists=[ln], data={"regression": payload}))
+    pts = None
+    if points:
+        pkw = dict(point_kw or {})
+        pkw.setdefault("s", 14)
+        pkw.setdefault("alpha", 0.6)
+        pkw.setdefault("color", the_color)
+        pts = _scatter(ax, xs, ys, series=series, **pkw)
+    bkw = dict(band_kw or {})
+    bkw.setdefault("color", the_color)
+    band = _band(ax, grid, lo, hi, series=series, what=f"{ci:.0%} CI", **bkw)
+    return RegressionResult(ax=ax, line=ln, band=band, points=pts, grid=grid, fit=fit, lower=np.asarray(lo),
+                            upper=np.asarray(hi), stats=stats)
+
+
+def kde(ax, values, *, series, bw="scott", fill=False, n_grid=200, cut=3.0, label=None, color=None,
+        fill_kw=None, **line_kw) -> KdeResult:
+    """A Gaussian kernel density estimate drawn as a line (``<series>.line``; ``fill=True`` adds
+    ``<series>.fill``), recording the grid, the density and the bandwidth in the manifest.
+
+    ``bw`` is scipy's ``bw_method`` (``"scott"``, ``"silverman"``, a number or a callable);
+    the grid runs ``cut`` bandwidths past the data on either side.
+    """
+    from scipy import stats as _sp
+    from .api import _series_color
+    v = np.asarray(values, dtype=float).ravel()
+    v = v[np.isfinite(v)]
+    if v.size < 2:
+        raise ValueError(f"kde needs at least 2 finite values, got {v.size}")
+    if v.std(ddof=1) == 0:
+        raise ValueError("kde: the values have zero variance")
+    estimator = _sp.gaussian_kde(v, bw_method=bw)
+    bandwidth = float(estimator.factor * v.std(ddof=1))
+    grid = np.linspace(v.min() - cut * bandwidth, v.max() + cut * bandwidth, int(n_grid))
+    density = estimator(grid)
+    kw = dict(line_kw)
+    if color is not None:
+        kw["color"] = color
+    _series_color(series, kw)
+    (ln,) = ax.plot(grid, density, label=label, **kw)
+    reg = _tagger.registry_for(ax.figure)
+    payload = {"grid": _data.values(grid), "density": _data.values(density), "bandwidth": bandwidth,
+               "method": bw if isinstance(bw, str) else ("callable" if callable(bw) else float(bw)), "n": int(v.size)}
+    reg.add(Mark(role="line", series=series, kind="kde", live_data=True, x=None, y=None, label=label, artists=[ln],
+                 data={"kde": payload}))
+    area = None
+    if fill:
+        fkw = dict(fill_kw or {})
+        fkw.setdefault("alpha", 0.25)
+        fkw.setdefault("linewidth", 0)
+        fkw.setdefault("color", ln.get_color())
+        area = ax.fill_between(grid, 0.0, density, **fkw)
+        reg.add(Mark(role="area", series=series, name="fill", kind="kde", artists=[area],
+                     data={"band": {"x": _data.values(grid), "y1": _data.values(density), "y2": [0.0] * int(n_grid)}}))
+    return KdeResult(ax=ax, line=ln, area=area, grid=grid, density=density, stats=payload)

fluxplot/glb.py

@@ -0,0 +1,84 @@
+"""Deterministic numpy-only binary glTF 2.0 writer (scene3d contract 0.1.0)."""
+from __future__ import annotations
+import json
+import struct
+import numpy as np
+from matplotlib.colors import to_rgba
+from .version import __version__
+
+
+def linear_rgb(rgb):
+    rgb=np.asarray(rgb,dtype=float)
+    return np.where(rgb<=.04045,rgb/12.92,((rgb+.055)/1.055)**2.4)
+
+
+def vertex_normals(vertices, faces):
+    out=np.zeros_like(vertices,dtype=np.float64)
+    # Convert before subtraction/cross products: finite float32 coordinates can
+    # overflow float32 area products while their float64 products remain finite.
+    t=np.asarray(vertices,dtype=np.float64)[faces]
+    area=np.cross(t[:,1]-t[:,0],t[:,2]-t[:,0])
+    for i in range(3): np.add.at(out,faces[:,i],area)
+    size=np.linalg.norm(out,axis=1)
+    out[size==0]=(0,1,0)
+    return (out/np.linalg.norm(out,axis=1,keepdims=True)).astype('<f4')
+
+
+def _finite32(a, name):
+    with np.errstate(over='ignore'): a=np.asarray(a,dtype='<f4')
+    if not np.isfinite(a).all(): raise ValueError(f'{name} cannot be represented by finite float32 values')
+    return a
+
+
+def write_glb(scene):
+    """Serialize one GLB. No timestamps, external resources, textures, or vertex welding."""
+    if not scene.parts: raise ValueError('cannot save an empty Scene3D; add a mesh first with fp.mesh3d(sc, ...)')
+    scene._resolve_pending_view(strict=True)
+    binary=bytearray()
+    doc=dict(asset={'version':'2.0','generator':f'fluxplot {__version__}'},buffers=[{}],bufferViews=[],accessors=[],meshes=[],nodes=[],materials=[],scenes=[{'nodes':list(range(len(scene.parts)))}],scene=0)
+    def accessor(a, kind, component, *, bounds=False, normalized=False, target=None, stride=None):
+        a=np.ascontiguousarray(a); binary.extend(b'\0'*(-len(binary)%4))
+        view={'buffer':0,'byteOffset':len(binary),'byteLength':a.nbytes}
+        if target is not None: view['target']=target
+        if stride is not None: view['byteStride']=stride
+        doc['bufferViews'].append(view); binary.extend(a.tobytes())
+        entry={'bufferView':len(doc['bufferViews'])-1,'componentType':component,'count':len(a),'type':kind}
+        if bounds: entry.update(min=a.min(axis=0).tolist(),max=a.max(axis=0).tolist())
+        if normalized: entry['normalized']=True
+        doc['accessors'].append(entry)
+        return len(doc['accessors'])-1
+    rotation=scene.to_world[:3,:3]
+    for part in scene.parts:
+        v=_finite32(part.vertices@rotation.T,'positions')
+        f=part.faces.astype('<u2' if part.faces.max()<65536 else '<u4')
+        n=vertex_normals(v,f)
+        attrs={'POSITION':accessor(v,'VEC3',5126,bounds=True,target=34962),'NORMAL':accessor(n,'VEC3',5126,target=34962)}
+        if part.values is not None:
+            valid=np.isfinite(part.values)
+            value=_finite32(np.where(valid,part.values,0),'values')
+            attrs['_VALUE']=accessor(value,'SCALAR',5126,target=34962)
+            if not valid.all(): attrs['_VALID']=accessor(np.column_stack([valid,np.zeros((len(valid),3),dtype='u1')]).astype('u1'),'SCALAR',5121,target=34962,stride=4)
+        if part.colors is not None:
+            rgba=np.asarray(part.colors,dtype=float).copy(); rgba[:,:3]=linear_rgb(rgba[:,:3])
+            attrs['COLOR_0']=accessor(np.rint(np.clip(rgba,0,1)*255).astype('u1'),'VEC4',5121,normalized=True,target=34962)
+        rgba=to_rgba(part.color); base=[*linear_rgb(rgba[:3]).tolist(),rgba[3]]
+        # Vertex colors already carry the complete map; white avoids tinting them twice.
+        # The part colour's alpha (fp.surface3d(alpha=...)) still applies as opacity.
+        if part.colors is not None: base=[1,1,1,rgba[3] if rgba[3]<1 else 1]
+        material={'name':part.id,'pbrMetallicRoughness':{'baseColorFactor':base,'metallicFactor':0,'roughnessFactor':.6},'doubleSided':True}
+        if rgba[3]<1 or (part.colors is not None and (part.colors[:,3]<1).any()): material['alphaMode']='BLEND'
+        doc['materials'].append(material)
+        prim={'attributes':attrs,'indices':accessor(f.ravel(),'SCALAR',5123 if f.dtype.itemsize==2 else 5125,target=34963),'material':len(doc['materials'])-1,'mode':4}
+        mesh={'name':part.id,'primitives':[prim]}
+        if part.states:
+            prim['targets']=[]
+            for name,target in part.states.items():
+                world=_finite32(target@rotation.T,'shape positions')
+                prim['targets'].append({'POSITION':accessor(_finite32(world-v,'shape deltas'),'VEC3',5126,bounds=True,target=34962),'NORMAL':accessor(vertex_normals(world,f)-n,'VEC3',5126,target=34962)})
+            mesh['extras']={'targetNames':list(part.states)}
+            mesh['weights']=[scene._view.get('states',{}).get(name,0) for name in part.states]
+        doc['meshes'].append(mesh); doc['nodes'].append({'name':part.id,'mesh':len(doc['meshes'])-1})
+    doc['buffers'][0]['byteLength']=len(binary)
+    js=json.dumps(doc,sort_keys=True,separators=(',',':'),allow_nan=False).encode('utf8')
+    js+=b' '*(-len(js)%4); binary.extend(b'\0'*(-len(binary)%4))
+    return struct.pack('<4sII',b'glTF',2,28+len(js)+len(binary))+struct.pack('<I4s',len(js),b'JSON')+js+struct.pack('<I4s',len(binary),b'BIN\0')+binary

fluxplot/ids.py

@@ -0,0 +1,173 @@
+"""Deterministic semantic IDs — the public, long-lived join key (spec §7, open Q6).
+
+An id is a dotted path of `[a-z0-9-]` segments; the dot is the only separator and the index is
+0-based:
+
+    control.line   control.point.3   axis.x.title   axis.x.tick.2   legend   annotation.peak
+
+matplotlib's own ids use ``_`` + hex hashes (``line2d_7``, ``p3dcf139bf4``) and never contain dots,
+so this namespace is provably disjoint from anything matplotlib autogenerates.
+"""
+from __future__ import annotations
+
+import re
+
+# Structural roots that stand alone at the head of an id (not series-scoped).
+STRUCTURAL_ROOTS = frozenset(
+    {
+        "figure",
+        "panel",
+        "plot-area",
+        "axis",
+        "legend",
+        "colorbar",
+        "title",
+        "background",
+        "annotation",
+        "reference-line",
+        "highlight-region",
+        "significance-bracket",
+        "label",
+    }
+)
+
+_SLUG_DROP = re.compile(r"[^a-z0-9-]+")
+_SLUG_DASHES = re.compile(r"-+")
+_SEGMENT_RE = re.compile(r"^[a-z0-9-]+$")
+
+# Characters that are spelled out rather than dropped: Greek letters (α → alpha), the micro sign,
+# degrees, percent and the common maths signs scientific names carry.
+TRANSLITERATE = {
+    "α": "alpha", "β": "beta", "γ": "gamma", "δ": "delta", "ε": "epsilon", "ζ": "zeta", "η": "eta",
+    "θ": "theta", "ι": "iota", "κ": "kappa", "λ": "lambda", "μ": "mu", "ν": "nu", "ξ": "xi",
+    "ο": "omicron", "π": "pi", "ρ": "rho", "σ": "sigma", "ς": "sigma", "τ": "tau", "υ": "upsilon",
+    "φ": "phi", "χ": "chi", "ψ": "psi", "ω": "omega", "ϵ": "epsilon", "ϑ": "theta", "ϕ": "phi",
+    "µ": "mu", "°": "deg", "%": "pct", "‰": "permille", "±": "pm", "×": "x", "∞": "inf",
+    "→": "to", "←": "from", "≤": "le", "≥": "ge", "≠": "ne", "−": "-", "–": "-", "—": "-", "‑": "-",
+    "&": "and", "+": "plus",
+}
+# Punctuation whose loss never confuses two names: sentence marks and quotes.
+_SOFT_DROP = set(".,;:!?'\u2019\"`")
+_HASH_LEN = 6
+
+
+def _fold(name: str) -> str:
+    """Lowercase, accents stripped, superscripts/subscripts and Greek spelled out."""
+    import unicodedata
+    out = []
+    for ch in unicodedata.normalize("NFKD", name):
+        if unicodedata.category(ch) == "Mn":  # a combining accent
+            continue
+        low = ch.lower()
+        out.append(TRANSLITERATE.get(low, low))
+    return "".join(out)
+
+
+def _slug_parts(name: object):
+    raw = str(name).strip()
+    folded = _fold(raw).replace("_", "-").replace(" ", "-")
+    dropped = [ch for ch in set(_SLUG_DROP.findall(folded.replace("-", ""))) for ch in ch]
+    lossy = any(ch not in _SOFT_DROP and not ch.isspace() for ch in dropped)
+    s = _SLUG_DROP.sub("-", folded)
+    s = _SLUG_DASHES.sub("-", s).strip("-")
+    return raw, s, lossy
+
+
+def slugify(name: object) -> str:
+    """Turn an arbitrary series/category name into a stable id segment.
+
+    Deterministic: accents folded, Greek letters / ``µ`` / ``°`` / ``%`` and super- or subscript
+    digits spelled out (``α`` → ``alpha``, ``CO₂`` → ``co2``), lowercase, spaces/underscores to
+    ``-``, other characters dropped, repeated ``-`` collapsed and trimmed. When dropping
+    characters lost information that could make two names collide (brackets, slashes, symbols —
+    ``IL-6 (pg/mL)`` vs ``IL-6 [pg/mL]``), or when nothing legible is left, a 6-hex-digit hash of
+    the original name is appended, so distinct names give distinct, stable ids. Empty input falls
+    back to ``series``.
+    """
+    raw, s, lossy = _slug_parts(name)
+    if raw and (not s or s == "series" or lossy):
+        import hashlib
+        s = (s or "series") + "-" + hashlib.sha1(raw.encode("utf-8")).hexdigest()[:_HASH_LEN]
+    return s or "series"
+
+
+def legacy_slugify(name: object) -> str:
+    """The pre-0.3.2 slug (lowercase, ``_``/space → ``-``, everything else dropped): what an
+    older manifest called the same series, for ``idAliases``."""
+    s = str(name).strip().lower().replace("_", "-").replace(" ", "-")
+    s = _SLUG_DROP.sub("-", s)
+    s = _SLUG_DASHES.sub("-", s).strip("-")
+    return s or "series"
+
+
+def is_valid_segment(seg: str) -> bool:
+    return bool(_SEGMENT_RE.match(seg))
+
+
+def join(*segments: object) -> str:
+    """Compose an id from segments, validating each is a legal segment."""
+    parts = []
+    for seg in segments:
+        if seg is None:
+            continue
+        seg = str(seg)
+        if not is_valid_segment(seg):
+            raise ValueError(f"invalid id segment: {seg!r}")
+        parts.append(seg)
+    if not parts:
+        raise ValueError("an id needs at least one segment")
+    return ".".join(parts)
+
+
+def series_root(series: object) -> str:
+    """Slug for a series, disambiguated from structural roots.
+
+    A series literally named "legend" becomes ``legend-series`` so structural roots stay unambiguous.
+    """
+    slug = slugify(series)
+    return f"{slug}-series" if slug in STRUCTURAL_ROOTS else slug
+
+
+def series_id(series: object, role: str | None = None, index: int | None = None) -> str:
+    """``control`` → ``control``; +role → ``control.line``; +index → ``control.point.3``."""
+    segs: list[object] = [series_root(series)]
+    if role is not None:
+        segs.append(role)
+    if index is not None:
+        segs.append(int(index))
+    return join(*segs)
+
+
+def axis_id(which: str, part: str | None = None, index: int | None = None) -> str:
+    """``axis.x``, ``axis.x.title``, ``axis.x.tick.2`` (which ∈ x, y, x2, y2)."""
+    segs: list[object] = ["axis", which]
+    if part is not None:
+        segs.append(part)
+    if index is not None:
+        segs.append(int(index))
+    return join(*segs)
+
+
+class IdAllocator:
+    """Per-plot id allocation with deterministic collision handling.
+
+    Same inputs → same ids. If a candidate id is already taken, later ones get a deterministic
+    ``-2``, ``-3``, … suffix on the final segment (by insertion order).
+    """
+
+    def __init__(self) -> None:
+        self._seen: set[str] = set()
+
+    def take(self, candidate: str) -> str:
+        if candidate not in self._seen:
+            self._seen.add(candidate)
+            return candidate
+        head, _, tail = candidate.rpartition(".")
+        i = 2
+        while True:
+            suffixed = f"{tail}-{i}"
+            new = f"{head}.{suffixed}" if head else suffixed
+            if new not in self._seen:
+                self._seen.add(new)
+                return new
+            i += 1