gleplot 6.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
gleplot/series.py ADDED
@@ -0,0 +1,1609 @@
1
+ """Typed series classes for :class:`gleplot.axes.Axes`.
2
+
3
+ Every drawable an axes owns -- lines, scatters, bars, fills, error bars,
4
+ external-file references, text annotations, heatmaps, contours, reference
5
+ lines and shaded spans -- used to be an anonymous ``dict`` in one of eleven
6
+ parallel lists on ``Axes``, with three hand-synchronised tables kept
7
+ alongside them (``Axes._SERIES_ATTRS`` for the list order,
8
+ ``Axes._ARRAY_KEYS`` for which keys hold ndarrays, and
9
+ ``Axes._default_column_names`` for the sidecar header row a legacy project
10
+ has to regenerate). Nothing tied a key name to the table entries that
11
+ described it, so adding a field meant remembering three unrelated places.
12
+
13
+ This module collapses that triple into one class per series kind. Each class
14
+ declares its fields as plain class-level annotations; the metaclass hook
15
+ turns those annotations into :attr:`Series.FIELDS`, and the class also owns
16
+ its :attr:`Series.ARRAY_FIELDS` and its
17
+ :meth:`Series.default_column_names` implementation. The registry
18
+ :data:`SERIES_CLASSES` maps the ``Axes`` list attribute onto its class and
19
+ fixes the serialization/emission order.
20
+
21
+ Wire compatibility
22
+ ------------------
23
+
24
+ The classes are ``dict`` **subclasses** that hold *all* of their state as
25
+ their own items and none as instance attributes. That is deliberate and is
26
+ what keeps this refactor behaviour-preserving:
27
+
28
+ * ``Axes.to_dict()`` output is unchanged -- ``_to_jsonable`` already turns
29
+ any mapping into a plain ``dict``, and construction inserts fields in the
30
+ declared order, so the serialized shape (and therefore the ``.gle`` and
31
+ ``.dat`` bytes the writer produces) is byte-for-byte what it was.
32
+ * The writer, the recognizer and applications built on gleplot address
33
+ series by key
34
+ (``series["color"]``, ``series.get("label")``, ``"zorder" in series``);
35
+ every one of those call sites keeps working untouched.
36
+ * Optional fields stay *absent* rather than becoming ``None``. ``zorder``
37
+ and ``_draw_seq`` are only meaningful when set, and ``sorted_zorder_
38
+ drawables`` distinguishes the two cases, so ``__init__`` stores only the
39
+ fields it is actually given.
40
+ * Having no instance ``__dict__`` state means ``copy``/``deepcopy``/pickle
41
+ round-trip a series without any custom protocol support.
42
+
43
+ On top of that the declared fields are readable as attributes
44
+ (``series.color`` is ``series["color"]``), which is what gives static type
45
+ checking something to work with.
46
+
47
+ Where the numbers come from: ``data_source``
48
+ --------------------------------------------
49
+
50
+ Every kind that owns bulk data declares a ``data_source`` field holding a
51
+ :class:`gleplot.sources.DataSource`. It follows the same
52
+ "absent means the historical behaviour" rule as ``zorder``: a series with no
53
+ ``data_source`` key is an :class:`~gleplot.sources.InlineData` series whose
54
+ arrays live in its own ``ARRAY_FIELDS``, which is exactly what the scripting
55
+ API produces and exactly the shape every pre-existing project has. A series
56
+ whose ``data_source`` is a :class:`~gleplot.sources.ColumnRef` /
57
+ :class:`~gleplot.sources.GridRef` instead carries ``None`` in those array
58
+ fields until the write-time resolution pass fills them in from a
59
+ :class:`~gleplot.sources.DataProvider` (see ``gleplot.writer.resolve_figure``).
60
+
61
+ The field is spelled ``data_source``, not ``source``: ``HeatmapSeries`` and
62
+ ``ContourSeries`` have had a ``source`` field since long before this
63
+ abstraction existed (it holds ``'grid'`` or ``'points'``, i.e. which *grid
64
+ mode* the series uses), and those two kinds are precisely the ones that need
65
+ a ``GridRef``. Renaming the older field would have changed the serialized
66
+ shape of every heatmap and contour ever saved for no gain.
67
+
68
+ Whether it is drawn at all: ``visible``
69
+ ---------------------------------------
70
+
71
+ Every *drawable* kind declares a ``visible`` field (GLEstudio SPEC 14.6).
72
+ It follows the same "absent means the historical behaviour" rule as
73
+ ``zorder`` and ``data_source``: a series with no ``visible`` key is drawn,
74
+ so no existing project changes shape, and :func:`is_visible` is the single
75
+ reader of the field. Only ``visible = False`` hides.
76
+
77
+ Hidden means hidden *everywhere the figure is rendered*: the writer skips
78
+ the series' entire emission -- its ``.dat`` sidecar, its display command and
79
+ its ``key "..."`` legend entry -- and it is excluded from auto-limit
80
+ computation, so limits may re-fit when a series is hidden (explicit limits
81
+ are of course untouched). The one place it is NOT skipped is the model,
82
+ which keeps the arrays, the label and the reserved data-file name so that
83
+ un-hiding restores byte-identical output.
84
+
85
+ ``TextAnnotation`` deliberately has no ``visible``: SPEC 7.5 lists texts as
86
+ their own branch of the structure tree, beside series rather than among
87
+ them, and G11 is per-*series* visibility.
88
+
89
+ Hidden is orthogonal to *dangling* (SPEC 3.2, ``DanglingSourceRef``):
90
+ "hidden because asked" and "skipped because broken" are different states
91
+ and neither is ever reported as the other.
92
+
93
+ How the curve is drawn: ``smooth_mode`` / ``svg_smooth``
94
+ --------------------------------------------------------
95
+
96
+ :class:`LineSeries` declares two independent smoothing fields (GLEstudio
97
+ SPEC 14.7), mirroring the two independent clauses of GLE's ``dn`` grammar
98
+ (``graph.tex``: ``dn smooth | smoothm`` and ``dn svg_smooth [m]``):
99
+
100
+ * ``smooth_mode`` -- ``'none'``, ``'smooth'`` or ``'smoothm'``. GLE's
101
+ ``smooth`` fits a piecewise cubic *as a function of x*
102
+ (``fitbez(data, multi=false)``); ``smoothm`` is the multi-valued variant
103
+ (``multi=true``) for curves with more than one y per x -- a hysteresis
104
+ loop, a closed contour. It is deliberately **not** a boolean: collapsing
105
+ ``smoothm`` into ``smooth`` would silently redraw such a curve as a
106
+ function of x.
107
+ * ``svg_smooth`` -- the iteration count of GLE's 7-point Savitzky-Golay
108
+ filter (``savgol.cpp``), an integer >= 1; absent means off.
109
+
110
+ Both follow the "absent means the historical behaviour" rule ``visible``
111
+ and ``zorder`` follow. An absent ``smooth_mode`` defers to the figure-wide
112
+ :attr:`gleplot.config.GLEGraphConfig.smooth_curves`, which is exactly what
113
+ every project written before this field did; a *present* one wins for that
114
+ series, including ``'none'`` on a figure whose default is smoothed. The two
115
+ fields are orthogonal: a series may carry either, both or neither, and the
116
+ writer emits ``svg_smooth m`` **before** the mode token because that is the
117
+ only order in which GLE keeps both (``graph2.cpp``'s ``SVG_SMOOTH`` branch
118
+ clears ``smooth``/``smoothm``, while ``SMOOTH`` leaves ``svg_smooth``
119
+ alone). :func:`smooth_mode` and :func:`svg_smooth_iterations` are the
120
+ single readers.
121
+
122
+ The scope is ``LineSeries`` only (SPEC 14.7). Error bars and file-reference
123
+ series still take the figure-wide flag: GLE would accept the qualifier on
124
+ them, but v1.1 models it only where the semantics are documented.
125
+ """
126
+
127
+ import re
128
+ import sys
129
+ from typing import Any, Dict, List, Mapping, Optional, Tuple, Type
130
+
131
+ import numpy as np
132
+
133
+ from .sources import DataSource, source_from_dict
134
+
135
+ __all__ = [
136
+ "Series",
137
+ "LineSeries",
138
+ "ScatterSeries",
139
+ "BarSeries",
140
+ "HistSeries",
141
+ "FunctionSeries",
142
+ "FitSeries",
143
+ "FillSeries",
144
+ "ErrorbarSeries",
145
+ "FileSeries",
146
+ "TextAnnotation",
147
+ "HeatmapSeries",
148
+ "ContourSeries",
149
+ "RefLine",
150
+ "Span",
151
+ "Rug",
152
+ "DerivedSeries",
153
+ "PlacedImage",
154
+ "SERIES_CLASSES",
155
+ "SERIES_ATTRS",
156
+ "SMOOTH_MODES",
157
+ "is_visible",
158
+ "normalize_smooth_mode",
159
+ "normalize_svg_smooth",
160
+ "sanitize_column_name",
161
+ "smooth_mode",
162
+ "svg_smooth_iterations",
163
+ "sorted_zorder_drawables",
164
+ ]
165
+
166
+
167
+ def is_visible(series: Mapping[str, Any]) -> bool:
168
+ """Whether ``series`` should be drawn (GLEstudio SPEC 14.6).
169
+
170
+ The single reader of the ``visible`` field, so the "absent means drawn"
171
+ rule lives in exactly one place. A value of ``None`` also reads as drawn:
172
+ an unset or malformed flag must never make a series disappear silently
173
+ (SPEC 8.1.4 -- no silent drops), and showing something the user did not
174
+ ask to hide is the recoverable direction of that error.
175
+
176
+ Kinds that declare no ``visible`` field (``TextAnnotation``) are always
177
+ drawn, which is what the default already says.
178
+ """
179
+ flag = series.get("visible", True)
180
+ return True if flag is None else bool(flag)
181
+
182
+
183
+ #: The three values ``smooth_mode`` may take (GLEstudio SPEC 14.7), spelled
184
+ #: exactly as GLE spells the corresponding ``dn`` keyword so the writer can
185
+ #: emit the token verbatim. ``'none'`` is the explicit "do not smooth this
186
+ #: series", which is NOT the same as the field being absent -- see
187
+ #: :func:`normalize_smooth_mode`.
188
+ SMOOTH_MODES: Tuple[str, ...] = ("none", "smooth", "smoothm")
189
+
190
+
191
+ def normalize_smooth_mode(value: Any) -> Optional[str]:
192
+ """Coerce a stored ``smooth_mode`` to a member of :data:`SMOOTH_MODES`.
193
+
194
+ Returns ``None`` for "not declared", which the writer reads as *defer to
195
+ the figure-wide* ``GLEGraphConfig.smooth_curves``. That is the only
196
+ reading under which every project written before this field keeps its
197
+ exact bytes, so absent has to stay distinguishable from ``'none'``.
198
+
199
+ A value that is neither absent nor a known mode (a stale string, a
200
+ boolean from a caller that assumed a flag) also reads as ``None``: an
201
+ unrecognized mode must never be *guessed* into a smoothing that
202
+ reinterpolates the data, and deferring to the figure default is the same
203
+ recoverable direction :func:`is_visible` takes.
204
+ """
205
+ if value is None:
206
+ return None
207
+ text = str(value).strip().lower()
208
+ return text if text in SMOOTH_MODES else None
209
+
210
+
211
+ def normalize_svg_smooth(value: Any) -> Optional[int]:
212
+ """Coerce a stored ``svg_smooth`` to an iteration count, or ``None``.
213
+
214
+ ``None`` means the filter is off. Iterations are integers >= 1: GLE runs
215
+ the 7-point Savitzky-Golay pass ``m`` times (``graph2.cpp``, which itself
216
+ coerces a parsed ``0`` up to ``1`` -- "if they say svg_smooth they want it
217
+ at least once"). A non-numeric or sub-1 stored value is off rather than
218
+ an error, for the same reason as :func:`normalize_smooth_mode`: the
219
+ recoverable direction is drawing the data.
220
+ """
221
+ if value is None or isinstance(value, bool):
222
+ return None
223
+ try:
224
+ count = int(value)
225
+ except (TypeError, ValueError):
226
+ return None
227
+ return count if count >= 1 else None
228
+
229
+
230
+ def smooth_mode(series: Mapping[str, Any]) -> Optional[str]:
231
+ """The declared smooth mode of ``series``, or ``None`` if it defers.
232
+
233
+ The single reader of the field; see :func:`normalize_smooth_mode` for
234
+ what the two "nothing here" cases mean. Kinds that declare no
235
+ ``smooth_mode`` (everything but :class:`LineSeries`, SPEC 14.7) always
236
+ defer, which is what returning ``None`` for a missing key already says.
237
+ """
238
+ return normalize_smooth_mode(series.get("smooth_mode"))
239
+
240
+
241
+ def svg_smooth_iterations(series: Mapping[str, Any]) -> Optional[int]:
242
+ """Savitzky-Golay iterations for ``series``, or ``None`` when off.
243
+
244
+ The single reader of the field. Independent of :func:`smooth_mode`:
245
+ GLE's two clauses are independent and so are these two fields.
246
+ """
247
+ return normalize_svg_smooth(series.get("svg_smooth"))
248
+
249
+
250
+ # -- sidecar column-name helpers ---------------------------------------------
251
+ #
252
+ # These live here rather than in axes.py because they encode series *schema*
253
+ # knowledge: which columns a kind writes to its ``.dat`` sidecar and in what
254
+ # order. ``gleplot.axes`` re-exports them, so the historical import path
255
+ # (``from gleplot.axes import sanitize_column_name``) still works.
256
+
257
+
258
+ def _looks_numeric(token: str) -> bool:
259
+ """True if ``token`` would parse as a float (int/float/exponent form).
260
+
261
+ GLE's own header auto-detection (see ``graph.cpp: auto_has_header`` /
262
+ ``isFloatMiss``) treats the first row of a data file as a header ONLY
263
+ if *every* cell in that row fails float conversion; a single numeric-
264
+ looking header token would make GLE read the whole header row as data
265
+ instead. Column names must never satisfy this check.
266
+ """
267
+ try:
268
+ float(token)
269
+ return True
270
+ except ValueError:
271
+ return False
272
+
273
+
274
+ def sanitize_column_name(name: object, fallback: str = "col") -> str:
275
+ """Sanitize an arbitrary label into a safe GLE data-file column header token.
276
+
277
+ Rules (documented here as the single source of truth for the sanitizer):
278
+
279
+ 1. Keep only ``[A-Za-z0-9_]`` characters; every other character
280
+ (whitespace, punctuation, unicode, ...) becomes a single ``_``.
281
+ 2. Lowercase the result.
282
+ 3. Collapse consecutive underscores to one and strip leading/trailing
283
+ underscores.
284
+ 4. If the result is empty, fall back to ``fallback``.
285
+ 5. If the result would itself parse as a number (e.g. a label of
286
+ ``"2024"``), prefix it with ``fallback + "_"`` so it can never be
287
+ mistaken for a data value -- GLE's header auto-detection requires
288
+ *every* first-row token to be non-numeric, and a purely numeric
289
+ column name would silently defeat the header row for the whole
290
+ file (see :func:`_looks_numeric`).
291
+ 6. The result never contains whitespace (guaranteed by step 1), since
292
+ header tokens are whitespace/space-separated on the header line.
293
+
294
+ Uniqueness across a file's column names is NOT handled here (a single
295
+ label sanitizes deterministically); see :func:`_unique_column_names`
296
+ for de-duplication via ``_2``, ``_3``, ... suffixes.
297
+ """
298
+ text = re.sub(r"[^A-Za-z0-9_]+", "_", str(name).strip().lower())
299
+ text = re.sub(r"_+", "_", text).strip("_")
300
+ if not text:
301
+ text = fallback
302
+ if _looks_numeric(text):
303
+ text = f"{fallback}_{text}"
304
+ return text
305
+
306
+
307
+ def _unique_column_names(names: List[str]) -> List[str]:
308
+ """De-duplicate column name tokens with stable ``_2``, ``_3``, ... suffixes.
309
+
310
+ The first occurrence of a name is kept as-is; subsequent occurrences of
311
+ the same (already-sanitized) name are suffixed with ``_2``, ``_3``, etc.
312
+ (matching ``_reserve_data_filename``'s collision convention). This
313
+ keeps sanitize_column_name pure/stateless while still guaranteeing
314
+ uniqueness within one sidecar's header row.
315
+ """
316
+ seen: dict = {}
317
+ result = []
318
+ for name in names:
319
+ if name not in seen:
320
+ seen[name] = 1
321
+ result.append(name)
322
+ else:
323
+ seen[name] += 1
324
+ candidate = f"{name}_{seen[name]}"
325
+ while candidate in seen:
326
+ seen[name] += 1
327
+ candidate = f"{name}_{seen[name]}"
328
+ seen[candidate] = 1
329
+ result.append(candidate)
330
+ return result
331
+
332
+
333
+ def _build_column_names(
334
+ x_name: str, y_names: List[str], label: Optional[str]
335
+ ) -> List[str]:
336
+ """Build a sidecar header row: one name for x, then one per y-like column.
337
+
338
+ Parameters
339
+ ----------
340
+ x_name : str
341
+ Base name for the x column (conventionally ``'x'``).
342
+ y_names : list of str
343
+ Base (pre-uniqueness) names for the remaining columns in file order,
344
+ e.g. ``['y']`` for a plain line, ``['y', 'err']`` for a symmetric
345
+ errorbar, ``['upper', 'lower']`` for a fill, ``['height']`` for a
346
+ bar chart. When ``label`` is given, the FIRST entry of ``y_names``
347
+ (the primary data column) is derived from the sanitized label
348
+ instead of its own base name; the rest keep their stable suffixes.
349
+ label : str, optional
350
+ Series label (e.g. the ``label=`` argument to ``plot``/``errorbar``/
351
+ ...). When present, sanitized and used as the primary data column's
352
+ name in place of its generic base name (e.g. ``'y'``). When absent
353
+ (``None`` or empty), the generic base name is kept as-is.
354
+
355
+ Returns
356
+ -------
357
+ list of str
358
+ ``[x_name] + y_names`` with the primary column optionally renamed
359
+ from ``label``, then de-duplicated for uniqueness within the file.
360
+ """
361
+ names = [x_name]
362
+ for i, base in enumerate(y_names):
363
+ if i == 0 and label:
364
+ names.append(sanitize_column_name(label, fallback=base))
365
+ else:
366
+ names.append(base)
367
+ return _unique_column_names(names)
368
+
369
+
370
+ def _build_errorbar_column_names(
371
+ label: Optional[str],
372
+ yerr_up: Any,
373
+ yerr_down: Any,
374
+ xerr_left: Any,
375
+ xerr_right: Any,
376
+ ) -> List[str]:
377
+ """Build the sidecar header row for an errorbar series.
378
+
379
+ Mirrors :meth:`gleplot.writer.GLEWriter.add_errorbar_series`'s column-building
380
+ order exactly (x, y, then vertical error column(s), then horizontal
381
+ error column(s)), so the header row lines up 1:1 with the data columns
382
+ the writer actually emits:
383
+
384
+ - symmetric y error (``yerr_up == yerr_down``, both given) -> one
385
+ ``'err'`` column
386
+ - asymmetric -> ``'err_up'`` and/or ``'err_down'`` columns, in that order
387
+ - symmetric x error (``xerr_left == xerr_right``, both given) -> one
388
+ ``'xerr'`` column
389
+ - asymmetric -> ``'xerr_left'`` and/or ``'xerr_right'`` columns
390
+
391
+ The primary y column is named from ``label`` when given (else ``'y'``);
392
+ error columns always keep their stable suffix names (never derived from
393
+ the label) since GLE never auto-keys off an error dataset's column name
394
+ directly relevant here -- only the uniqueness pass can rename them.
395
+ """
396
+ y_names = ["y"]
397
+
398
+ has_yerr = yerr_up is not None or yerr_down is not None
399
+ has_xerr = xerr_left is not None or xerr_right is not None
400
+ yerr_symmetric = (
401
+ has_yerr
402
+ and yerr_up is not None
403
+ and yerr_down is not None
404
+ and np.array_equal(yerr_up, yerr_down)
405
+ )
406
+ xerr_symmetric = (
407
+ has_xerr
408
+ and xerr_left is not None
409
+ and xerr_right is not None
410
+ and np.array_equal(xerr_left, xerr_right)
411
+ )
412
+
413
+ if has_yerr:
414
+ if yerr_symmetric:
415
+ y_names.append("err")
416
+ else:
417
+ if yerr_up is not None:
418
+ y_names.append("err_up")
419
+ if yerr_down is not None:
420
+ y_names.append("err_down")
421
+
422
+ if has_xerr:
423
+ if xerr_symmetric:
424
+ y_names.append("xerr")
425
+ else:
426
+ if xerr_left is not None:
427
+ y_names.append("xerr_left")
428
+ if xerr_right is not None:
429
+ y_names.append("xerr_right")
430
+
431
+ return _build_column_names("x", y_names, label)
432
+
433
+
434
+ # -- the base class -----------------------------------------------------------
435
+
436
+
437
+ def _own_annotations(cls: type) -> Mapping[str, Any]:
438
+ """Names annotated in ``cls``'s own body, in declaration order.
439
+
440
+ Python 3.14 evaluates annotations lazily (PEP 649): a class body no
441
+ longer stores ``__annotations__`` in its namespace, so reading
442
+ ``vars(cls)`` finds nothing there. Only the names matter here, so ask for
443
+ forward references rather than forcing every annotation to resolve while
444
+ the class is still being created.
445
+ """
446
+ if sys.version_info >= (3, 14):
447
+ import annotationlib
448
+
449
+ if "__annotate_func__" not in vars(cls) and "__annotations__" not in vars(cls):
450
+ return {}
451
+ return annotationlib.get_annotations(
452
+ cls, format=annotationlib.Format.FORWARDREF
453
+ )
454
+ own: Mapping[str, Any] = vars(cls).get("__annotations__", {})
455
+ return own
456
+
457
+
458
+ class Series(Dict[str, Any]):
459
+ """Base class for every typed series: a ``dict`` that knows its schema.
460
+
461
+ Subclasses declare their fields as bare class-level annotations, in the
462
+ order they are serialized::
463
+
464
+ class MySeries(Series):
465
+ ATTR = "mine"
466
+ ARRAY_FIELDS = ("x",)
467
+
468
+ x: np.ndarray
469
+ label: Optional[str]
470
+
471
+ A class-level annotation that also has a *value* (every ``ClassVar``
472
+ below does) is configuration, not a field, and is skipped.
473
+
474
+ Only the fields actually passed to :meth:`__init__` are stored, so
475
+ "absent" and "present but ``None``" stay distinguishable -- ``zorder``
476
+ relies on that. Unknown keyword arguments are rejected: that is the
477
+ check which now enforces what the hand-synced tables used to.
478
+ """
479
+
480
+ #: The ``Axes`` list attribute this kind lives in (``"lines"``, ...).
481
+ ATTR: str = ""
482
+
483
+ #: Draw-order kind name for the cross-kind z-ordering in
484
+ #: ``sorted_zorder_drawables``; ``None`` for kinds that are
485
+ #: not part of that ordering (fills, texts, heatmaps, contours, ...).
486
+ KIND: Optional[str] = None
487
+
488
+ #: Default ``zorder`` when the caller omitted one. Matches the
489
+ #: pre-zorder GLE emission stack: bars, then lines, scatters, errorbars
490
+ #: (later ``dN`` commands draw on top in GLE).
491
+ ZORDER_DEFAULT: Optional[float] = None
492
+
493
+ #: Stable tie-break rank for legacy series that predate ``_draw_seq``.
494
+ KIND_RANK: Optional[int] = None
495
+
496
+ #: Fields holding numeric arrays, restored as float ndarrays by
497
+ #: ``Axes.from_dict``. Everything else is a JSON scalar/string/None.
498
+ ARRAY_FIELDS: Tuple[str, ...] = ()
499
+
500
+ #: Declared field names in serialization order. Derived from the class
501
+ #: annotations by :meth:`__init_subclass__`; never written by hand.
502
+ FIELDS: Tuple[str, ...] = ()
503
+
504
+ def __init_subclass__(cls, **kwargs: Any) -> None:
505
+ super().__init_subclass__(**kwargs)
506
+ fields: List[str] = []
507
+ for base in reversed(cls.__mro__):
508
+ for name in _own_annotations(base):
509
+ # A class-level annotation carrying a value is configuration
510
+ # (ATTR, ARRAY_FIELDS, ...), not a data field.
511
+ if name in vars(base) or name.startswith("__"):
512
+ continue
513
+ if name not in fields:
514
+ fields.append(name)
515
+ cls.FIELDS = tuple(fields)
516
+
517
+ def __init__(self, **kwargs: Any) -> None:
518
+ unknown = [key for key in kwargs if key not in self.FIELDS]
519
+ if unknown:
520
+ raise TypeError(
521
+ f"{type(self).__name__} got unknown field(s) "
522
+ f"{sorted(unknown)!r}. Declare them on the class (that is the "
523
+ "single place a series kind's schema lives) or fix the caller."
524
+ )
525
+ super().__init__((name, kwargs[name]) for name in self.FIELDS if name in kwargs)
526
+
527
+ @classmethod
528
+ def _restore(cls, payload: Dict[str, Any]) -> "Series":
529
+ """Rebuild a series from a :meth:`Axes.to_dict` payload.
530
+
531
+ Lenient where :meth:`__init__` is strict: keys the class does not
532
+ declare are preserved verbatim (after the declared ones) so a project
533
+ written by a newer gleplot still round-trips through an older one,
534
+ which is the forward-compatibility promise ``Axes.from_dict`` makes.
535
+ """
536
+ obj = cls(**{k: v for k, v in payload.items() if k in cls.FIELDS})
537
+ for key, value in payload.items():
538
+ if key not in cls.FIELDS:
539
+ obj[key] = value
540
+ # A serialized source is a plain mapping; rebuild it as its class so
541
+ # ``source_of(series)`` hands back something with behaviour. An
542
+ # unrecognized ``kind`` survives verbatim (see source_from_dict).
543
+ if obj.get("data_source") is not None:
544
+ obj["data_source"] = source_from_dict(obj["data_source"])
545
+ return obj
546
+
547
+ def copy(self) -> "Series":
548
+ """A shallow copy of the same class (``dict.copy`` returns a ``dict``)."""
549
+ return self._restore(self)
550
+
551
+ def default_column_names(self) -> Optional[List[str]]:
552
+ """Regenerate ``column_names`` for a series that has none stored.
553
+
554
+ Projects saved before Track E3 (named sidecar column headers) have no
555
+ ``'column_names'`` key on their series at all, and a hand-written
556
+ ``.dat`` recovered by the recognizer may have no header row to
557
+ recover names from. Rather than leaving it absent -- which would
558
+ produce a headerless sidecar on the next save, a silent format
559
+ regression -- each kind recomputes the same default names its
560
+ plotting method would have produced for equivalent arguments.
561
+
562
+ Returns ``None`` for kinds that generate no sidecar of their own
563
+ (file references, texts, heatmaps, contours): there is nothing to
564
+ name.
565
+ """
566
+ return None
567
+
568
+ def __getattr__(self, name: str) -> Any:
569
+ # Only reached when normal attribute lookup fails, so methods and
570
+ # class attributes are never shadowed by same-named items.
571
+ try:
572
+ return self[name]
573
+ except KeyError:
574
+ raise AttributeError(
575
+ f"{type(self).__name__!r} has no attribute {name!r}"
576
+ ) from None
577
+
578
+ def __setattr__(self, name: str, value: Any) -> None:
579
+ if name in self.FIELDS:
580
+ self[name] = value
581
+ else:
582
+ super().__setattr__(name, value)
583
+
584
+ def __delattr__(self, name: str) -> None:
585
+ if name in self.FIELDS:
586
+ try:
587
+ del self[name]
588
+ except KeyError:
589
+ raise AttributeError(
590
+ f"{type(self).__name__!r} has no attribute {name!r}"
591
+ ) from None
592
+ else:
593
+ super().__delattr__(name)
594
+
595
+ def __repr__(self) -> str:
596
+ return f"{type(self).__name__}({dict.__repr__(self)})"
597
+
598
+
599
+ # -- data series --------------------------------------------------------------
600
+
601
+
602
+ class _XYSeries(Series):
603
+ """Shared schema of the two series ``Axes.plot`` produces.
604
+
605
+ ``plot()`` builds one dict and files it under ``lines`` or ``scatters``
606
+ depending on whether a marker was requested without a line, so the two
607
+ kinds have identical fields and differ only in where they live and how
608
+ they z-order.
609
+ """
610
+
611
+ ARRAY_FIELDS = ("x", "y")
612
+
613
+ type: str
614
+ x: np.ndarray
615
+ y: np.ndarray
616
+ #: ``None`` is a recovered ``dN`` line that set no colour: the writer
617
+ #: writes none, and GLE draws in the current colour.
618
+ color: Optional[str]
619
+ marker: Optional[str]
620
+ markersize: float
621
+ linestyle: str
622
+ #: ``None`` is a recovered ``dN`` line that drew a line but set no
623
+ #: ``lwidth``: the writer writes none (GLE's current line width).
624
+ linewidth: Optional[float]
625
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
626
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
627
+ _lwidth_verbatim: bool
628
+ #: GLE's ``nomiss qualifier: draw the line through a missing value
629
+ #: instead of leaving a gap (GLE default: gap). Only meaningful when a
630
+ #: line is drawn, but preserved verbatim on scatter-only series too so a
631
+ #: hand-written file that sets it never loses the setting on re-save.
632
+ nomiss: bool
633
+ label: Optional[str]
634
+ yaxis: str
635
+ #: ``'x2'`` binds the series to the top scale. Absent means the
636
+ #: primary x axis, so a series stored before this field existed is
637
+ #: unchanged.
638
+ xaxis: str
639
+ offset: float
640
+ data_file: Optional[str]
641
+ column_names: Optional[List[str]]
642
+ #: Where the numbers come from; absent means InlineData (this
643
+ #: series' own array fields). See :mod:`gleplot.sources`.
644
+ data_source: Optional[DataSource]
645
+ #: Display-command order within the axes; absent on pre-zorder projects.
646
+ _draw_seq: int
647
+ #: Set by ``open_gle`` when a raw line kept in the block reads one of
648
+ #: this series' datasets: role -> its name in the file, which the writer
649
+ #: renames in those lines to the name it writes that dataset under. The
650
+ #: roles are ``data`` (the series' own dataset), ``offset`` (its
651
+ #: ``let dK = dJ+off`` alias), ``hist`` (a histogram's binned dataset),
652
+ #: ``from`` (a stacked bar's baseline), ``second`` and ``second_offset``
653
+ #: (a fill's second curve and its alias), and ``yerr``, ``yerr_up``,
654
+ #: ``yerr_down``, ``xerr``, ``xerr_left``, ``xerr_right`` (an error
655
+ #: bar's error datasets).
656
+ _gle_names: Dict[str, str]
657
+ #: Only present when the caller asked for an explicit draw order.
658
+ zorder: float
659
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
660
+ visible: bool
661
+ #: GLE ``mdist``: markers every this many cm along the curve instead of
662
+ #: one per point. Absent: a marker on every point (or the figure's
663
+ #: ``GLEMarkerConfig.mdist`` on a marked line).
664
+ mdist: float
665
+ #: GLE ``deresolve``: draw one point in every N. Absent: every point.
666
+ deresolve: int
667
+ #: GLE ``deresolve N average``: each window of N points is drawn as its
668
+ #: mean. Only present together with ``deresolve``.
669
+ deresolve_average: bool
670
+ #: GLE's per-dataset range, in data coordinates: the series is drawn as
671
+ #: if its axes ran over it, and nothing outside it is drawn. Absent:
672
+ #: that edge is the limit of the axis the series is drawn against.
673
+ xmin: float
674
+ xmax: float
675
+ ymin: float
676
+ ymax: float
677
+
678
+ def default_column_names(self) -> Optional[List[str]]:
679
+ return _build_column_names("x", ["y"], self.get("label"))
680
+
681
+
682
+ class LineSeries(_XYSeries):
683
+ """A line (optionally marker-decorated) dataset -- ``Axes.plot``.
684
+
685
+ The one kind that carries the smoothing fields (SPEC 14.7); see the
686
+ module docstring for why they are two independent fields and why the
687
+ mode is not a boolean.
688
+ """
689
+
690
+ ATTR = "lines"
691
+ KIND = "line"
692
+ ZORDER_DEFAULT = 3.0
693
+ KIND_RANK = 1
694
+
695
+ #: ``'none'`` / ``'smooth'`` / ``'smoothm'``; absent (the default) defers
696
+ #: to the figure-wide ``GLEGraphConfig.smooth_curves``. See
697
+ #: :func:`smooth_mode`.
698
+ smooth_mode: str
699
+ #: Savitzky-Golay iterations (int >= 1); absent (the default) means off.
700
+ #: Independent of ``smooth_mode``. See :func:`svg_smooth_iterations`.
701
+ svg_smooth: int
702
+ #: GLE ``dn line`` mode (``steps``, ``fsteps``, ``hist``, ``bar``,
703
+ #: ``impulses``). Absent means a plain polyline, so a series that never
704
+ #: asked for one keeps the historical dict shape and the writer emits a
705
+ #: bare ``line``. See :data:`gleplot.parser.tables.LINE_MODES`.
706
+ line_mode: str
707
+ #: The non-finite rows are gaps: the writer writes them as GLE missing
708
+ #: values (``*``), which break the line, so each run of points is its
709
+ #: own polyline (``Axes.plot`` / ``step`` with NaN, ``Axes.hlines`` /
710
+ #: ``Axes.vlines``). Absent: NaN is written ``nan``, which GLE drops,
711
+ #: joining the neighbours. A line read from a data provider gets it at
712
+ #: write time, on the resolved copy only.
713
+ gaps: bool
714
+
715
+
716
+ class ScatterSeries(_XYSeries):
717
+ """A marker-only dataset -- ``Axes.scatter`` / ``plot(linestyle='none')``."""
718
+
719
+ ATTR = "scatters"
720
+ KIND = "scatter"
721
+ ZORDER_DEFAULT = 4.0
722
+ KIND_RANK = 2
723
+
724
+ #: GLE ``mdata``: each point's marker size as a multiple of
725
+ #: ``markersize``, one per point. Absent: every marker at ``markersize``.
726
+ mdata: np.ndarray
727
+ #: ``scatter(c=...)``: one value per point, coloured through ``cmap``
728
+ #: from ``vmin`` (its first colour) to ``vmax`` (its last). Absent: every
729
+ #: point in ``color``. ``cmap``, ``vmin`` and ``vmax`` are present
730
+ #: exactly when this is.
731
+ cdata: np.ndarray
732
+ cmap: str
733
+ vmin: float
734
+ vmax: float
735
+ #: Colorbar declaration dict of a colour-mapped scatter, as on
736
+ #: :attr:`HeatmapSeries.colorbar`, with ``zmin``/``zmax`` its ``vmin``
737
+ #: and ``vmax``. Absent: no colorbar. See :meth:`gleplot.Figure.colorbar`.
738
+ colorbar: Dict[str, Any]
739
+
740
+ def default_column_names(self) -> Optional[List[str]]:
741
+ if "mdata" in self:
742
+ return _build_column_names("x", ["y", "mdata"], self.get("label"))
743
+ if "cdata" in self:
744
+ return _build_column_names("x", ["y", "c"], self.get("label"))
745
+ return super().default_column_names()
746
+
747
+
748
+ class BarSeries(Series):
749
+ """A bar chart -- ``Axes.bar``."""
750
+
751
+ ATTR = "bars"
752
+ KIND = "bar"
753
+ ZORDER_DEFAULT = 2.0
754
+ KIND_RANK = 0
755
+ ARRAY_FIELDS = ("x", "height")
756
+
757
+ x: np.ndarray
758
+ height: np.ndarray
759
+ #: Face colour of each bar in this dataset. One GLE dataset has one
760
+ #: fill: a call that asks for a different colour per bar becomes one
761
+ #: series per bar, and a grouped ``bar d1,d2 fill c1,c2`` is several
762
+ #: series that share :attr:`group`. A single series whose ``fill`` list
763
+ #: is longer than one dataset keeps the extra tokens in
764
+ #: :attr:`fill_list` (GLE stores them and draws the first). With a
765
+ #: :attr:`pattern`, GLE's ``fill`` is the hatch ink, so this is too.
766
+ colors: Optional[List[str]]
767
+ #: GLE fill pattern (``bar ... pattern SHADE``: ``SHADE``, ``RSHADE``
768
+ #: or ``GRID``, optionally numbered 1-5), matplotlib's ``hatch``.
769
+ #: Absent: a solid fill. The pattern also reaches the legend swatch.
770
+ pattern: Optional[str]
771
+ #: Colour under the hatch (``bar ... background``), matplotlib's face
772
+ #: colour when :attr:`pattern` is set. Absent: GLE's white.
773
+ background: Optional[str]
774
+ #: Authored ``fill`` tokens when they are not just :attr:`colors`' first
775
+ #: entry. The writer emits this list verbatim. Absent on an API series.
776
+ fill_list: Optional[List[str]]
777
+ #: Stroke colour (GLE ``color``). Absent: the writer emits no ``color``
778
+ #: keyword, and GLE strokes in black. ``"none"`` is matplotlib's missing
779
+ #: edge. GLE strokes every bar, so the writer emits a hairline in the
780
+ #: colour under the edge: ``color <fill> lwidth 0``, or the
781
+ #: :attr:`background` of a hatched bar.
782
+ edgecolor: Optional[str]
783
+ #: Authored ``color`` list when a command names more than one edge.
784
+ #: Emitted verbatim. Absent when :attr:`edgecolor` is the whole story.
785
+ edge_list: Optional[List[str]]
786
+ #: Edge width in points. Absent: nothing is written, and GLE keeps the
787
+ #: line width already in force. ``0`` is written, and GLE draws it as
788
+ #: its thinnest line.
789
+ linewidth: Optional[float]
790
+ #: Edge linestyle. Absent: GLE's solid default, and no ``lstyle`` token.
791
+ #: ``'-'`` is stored only when a script or a caller named the style, so
792
+ #: a hand-written ``lstyle 1`` is not dropped.
793
+ linestyle: Optional[str]
794
+ #: A ``lstyle`` token that is not one of the four matplotlib styles
795
+ #: (a comma list, or a number the style map does not know). Re-emitted
796
+ #: as written. Absent when :attr:`linestyle` carries it.
797
+ lstyle: Optional[str]
798
+ #: True emits ``horiz`` (matplotlib ``barh``). Absent is vertical, so a
799
+ #: plain bar keeps the historical dict shape.
800
+ horiz: bool
801
+ #: Baseline of each bar (matplotlib ``bottom``, or ``left`` on
802
+ #: ``barh``). Absent draws from 0 and the y column is the height.
803
+ #: Present: ``bar dTo from dFrom``. The to-dataset's y is :attr:`top`
804
+ #: when a script was recovered, otherwise ``bottom + height``.
805
+ bottom: Optional[np.ndarray]
806
+ #: Exact to-dataset y recovered from a ``from`` command. The writer
807
+ #: prefers it so the sidecar stays the bytes that were read.
808
+ top: Optional[np.ndarray]
809
+ #: Series that share this id were one ``bar d1,d2,...`` command and are
810
+ #: written as one. Absent on an independent bar.
811
+ group: Optional[int]
812
+ #: ``bar ... dist``, the gap from the left of one bar to the left of
813
+ #: the next in a group. Absent: GLE's own ``width * 1.4``.
814
+ dist: Optional[float]
815
+ #: Bar width in DATA units (GLE's ``bar dN ... width w``), or absent
816
+ #: (G19). Absent is the historical behaviour and the default: GLE sizes
817
+ #: the set from the data itself -- ``drawBar`` takes
818
+ #: ``getMinXInterval()/(nbars*2)`` whenever ``width`` is 0 (its "not
819
+ #: given" sentinel) -- and gleplot only writes a width down for the
820
+ #: datasets that derivation cannot serve (G16,
821
+ #: :meth:`gleplot.writer.GLEWriter.bar_width_gle_cannot_derive`). A
822
+ #: value here is the caller's own number: it is emitted verbatim and
823
+ #: suppresses G16's derived one. ``0`` is GLE's own "no width given",
824
+ #: so it is read as absent rather than emitted.
825
+ width: Optional[float]
826
+ label: Optional[str]
827
+ data_file: Optional[str]
828
+ column_names: Optional[List[str]]
829
+ #: Where the numbers come from; absent means InlineData (this
830
+ #: series' own array fields). See :mod:`gleplot.sources`.
831
+ data_source: Optional[DataSource]
832
+ _draw_seq: int
833
+ #: See ``_XYSeries._gle_names``.
834
+ _gle_names: Dict[str, str]
835
+ zorder: float
836
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
837
+ visible: bool
838
+ #: Legend swatch colour when a ``keyfill`` is not the bar fill. Absent
839
+ #: means the swatch is the bar fill (``update_key_fill`` already copied it).
840
+ swatch_color: Optional[str]
841
+
842
+ def default_column_names(self) -> Optional[List[str]]:
843
+ if self.get("bottom") is not None:
844
+ # The sidecar is the baseline and the top, not the segment
845
+ # height. The legend label is the ``key``, not the header.
846
+ return ["x", "bottom", "top"]
847
+ return _build_column_names("x", ["height"], self.get("label"))
848
+
849
+
850
+ class HistSeries(Series):
851
+ """A binned sample count -- ``Axes.hist``.
852
+
853
+ The sidecar holds the raw samples (GLE bins them with ``let dK = hist``).
854
+ ``histtype`` selects the drawing: ``step`` is ``dK line hist``;
855
+ ``stepfilled`` is ``bar dK`` on that same result, one bin wide, from zero.
856
+ """
857
+
858
+ ATTR = "hists"
859
+ KIND = "hist"
860
+ ZORDER_DEFAULT = 2.0
861
+ KIND_RANK = 4
862
+ ARRAY_FIELDS = ("samples",)
863
+
864
+ samples: np.ndarray
865
+ #: ``step`` (``line hist``) or ``stepfilled`` (adjoining bars).
866
+ histtype: str
867
+ #: Inclusive start of the bin window. Absent: GLE chooses (axis, else data).
868
+ hist_from: Optional[float]
869
+ #: Exclusive end of the bin window, except the last bin which includes it.
870
+ hist_to: Optional[float]
871
+ #: Equal-width bin count (GLE ``bins``). Absent when ``bin_step`` is set,
872
+ #: and when both were omitted (GLE's own default of 10).
873
+ bins: Optional[int]
874
+ #: Bin width (GLE ``step``). Used only when ``bins`` is absent.
875
+ bin_step: Optional[float]
876
+ #: ``stepfilled`` bar width in data units. Absent: GLE derives one, which
877
+ #: is half the bin and leaves gaps, so the writer sets this for API series.
878
+ bar_width: Optional[float]
879
+ #: ``None`` is a recovered ``dN`` line that set no colour: the writer
880
+ #: writes none, and GLE draws in the current colour.
881
+ color: Optional[str]
882
+ #: Stroke on a ``stepfilled`` bar. Absent: GLE's black edge.
883
+ edgecolor: Optional[str]
884
+ linestyle: str
885
+ #: ``None`` is a recovered ``dN`` line that drew a line but set no
886
+ #: ``lwidth``: the writer writes none (GLE's current line width).
887
+ linewidth: Optional[float]
888
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
889
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
890
+ _lwidth_verbatim: bool
891
+ label: Optional[str]
892
+ yaxis: str
893
+ #: ``'x2'`` binds the histogram to the top scale. Absent means the
894
+ #: primary x axis. A ``stepfilled`` histogram cannot use it: GLE's
895
+ #: ``bar`` command has no ``x2axis``.
896
+ xaxis: str
897
+ data_file: Optional[str]
898
+ column_names: Optional[List[str]]
899
+ data_source: Optional[DataSource]
900
+ _draw_seq: int
901
+ #: See ``_XYSeries._gle_names``.
902
+ _gle_names: Dict[str, str]
903
+ zorder: float
904
+ visible: bool
905
+
906
+ def default_column_names(self) -> Optional[List[str]]:
907
+ # A header would name the *sample* dataset. GLE copies that name into
908
+ # the legend of every used dataset, and ``let hist`` uses it, so the
909
+ # samples would appear as their own key. The histogram's label is the
910
+ # key on the binned dataset instead.
911
+ return None
912
+
913
+
914
+ class FunctionSeries(Series):
915
+ """A curve GLE samples from an expression -- ``Axes.function``.
916
+
917
+ Written as ``let dK = <expression> [from a] [to b] [step h]`` and drawn
918
+ with ``dK line``. There is no sidecar: GLE evaluates the expression.
919
+ """
920
+
921
+ ATTR = "functions"
922
+ KIND = "function"
923
+ ZORDER_DEFAULT = 3.0
924
+ KIND_RANK = 5
925
+
926
+ #: A GLE expression in ``x``, written verbatim into the ``let``.
927
+ expression: str
928
+ #: ``from``, ``to`` and ``step`` of the ``let``. Absent: GLE's default
929
+ #: (the x axis range, sampled at 100 points). On a log x axis GLE reads
930
+ #: ``step`` as a point count.
931
+ let_from: float
932
+ let_to: float
933
+ let_step: float
934
+ #: ``None`` is a recovered ``dN`` line that set no colour: the writer
935
+ #: writes none, and GLE draws in the current colour.
936
+ color: Optional[str]
937
+ linestyle: str
938
+ #: ``None`` is a recovered ``dN`` line that set no ``lwidth``.
939
+ linewidth: Optional[float]
940
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
941
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
942
+ _lwidth_verbatim: bool
943
+ label: Optional[str]
944
+ _draw_seq: int
945
+ #: See ``_XYSeries._gle_names``.
946
+ _gle_names: Dict[str, str]
947
+ zorder: float
948
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
949
+ visible: bool
950
+
951
+
952
+ class FitSeries(Series):
953
+ """A curve GLE fits to data -- ``Axes.fit``.
954
+
955
+ The sidecar holds the data, read as a dataset that is never drawn. It
956
+ has no header: GLE keys every dataset a ``let`` uses, so a header would
957
+ give the data its own legend entry.
958
+ ``let dK = fit dJ with <expression> [from a] [to b] [step h]`` fits the
959
+ coefficients and samples the fitted curve, which ``dK line`` draws. A
960
+ series with a ``model`` instead has no expression, and its ``let`` is
961
+ the closed-form routine for that model: ``let dK = linfit dJ ...``.
962
+ """
963
+
964
+ ATTR = "fits"
965
+ KIND = "fit"
966
+ ZORDER_DEFAULT = 3.0
967
+ KIND_RANK = 6
968
+ ARRAY_FIELDS = ("x", "y")
969
+
970
+ x: np.ndarray
971
+ y: np.ndarray
972
+ #: A GLE expression in ``x``; every other name in it is a coefficient.
973
+ #: Absent on a ``model`` fit.
974
+ expression: str
975
+ #: ``"linear"``, ``"exp"``, ``"exp10"`` or ``"power"``: the key of
976
+ #: :data:`gleplot.parser.tables.FIT_MODEL_TO_ROUTINE`. Absent on an
977
+ #: ``expression`` fit.
978
+ model: str
979
+ #: ``from``, ``to`` and ``step`` of the ``let``, as on
980
+ #: :class:`FunctionSeries`.
981
+ let_from: float
982
+ let_to: float
983
+ let_step: float
984
+ #: ``None`` is a recovered ``dN`` line that set no colour: the writer
985
+ #: writes none, and GLE draws in the current colour.
986
+ color: Optional[str]
987
+ linestyle: str
988
+ #: ``None`` is a recovered ``dN`` line that set no ``lwidth``.
989
+ linewidth: Optional[float]
990
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
991
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
992
+ _lwidth_verbatim: bool
993
+ label: Optional[str]
994
+ data_file: Optional[str]
995
+ _draw_seq: int
996
+ #: See ``_XYSeries._gle_names``.
997
+ _gle_names: Dict[str, str]
998
+ zorder: float
999
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1000
+ visible: bool
1001
+
1002
+
1003
+ #: A dataset name inside a GLE expression, such as ``d1``.
1004
+ _DATASET_NAME_RE = re.compile(r"(?<![A-Za-z0-9_])d[0-9]+(?![A-Za-z0-9_])", re.I)
1005
+
1006
+
1007
+ class DerivedSeries(Series):
1008
+ """A curve GLE computes from other series -- ``Axes.derived``.
1009
+
1010
+ Written as ``let dK = <expression> [from a] [to b] [step h] [nsteps n]
1011
+ [where w] [range dA,dB]`` and drawn with ``dK line``, after every other
1012
+ data series of the axes, so the datasets it reads are already defined.
1013
+ In ``expression`` and ``let_where``, ``d1`` ... ``dn`` stand for
1014
+ ``sources[0]`` ... ``sources[n-1]``; the writer puts in the names it
1015
+ gave those series.
1016
+ """
1017
+
1018
+ ATTR = "derived_series"
1019
+
1020
+ #: A GLE expression over ``x`` and ``d1`` ... ``dn``.
1021
+ expression: str
1022
+ #: ``[attr, index]`` of each operand: the ``Axes`` list and the position
1023
+ #: in it of a line, scatter, file line, function or fit series.
1024
+ sources: List[List[Any]]
1025
+ #: ``from``, ``to`` and ``step`` of the ``let``, as on
1026
+ #: :class:`FunctionSeries`. Absent: GLE's default.
1027
+ let_from: float
1028
+ let_to: float
1029
+ let_step: float
1030
+ #: GLE ``nsteps``: the number of points between ``from`` and ``to``.
1031
+ let_nsteps: int
1032
+ #: GLE ``where``: keep only the points where this expression is true.
1033
+ let_where: str
1034
+ #: GLE ``range``: ``[attr, index]`` of each series whose x values the
1035
+ #: result is computed at, as for ``sources``. Absent: every operand's.
1036
+ let_range: List[List[Any]]
1037
+ #: ``None`` is a recovered ``dN`` line that set no colour.
1038
+ color: Optional[str]
1039
+ linestyle: str
1040
+ #: ``None`` is a recovered ``dN`` line that set no ``lwidth``.
1041
+ linewidth: Optional[float]
1042
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
1043
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
1044
+ _lwidth_verbatim: bool
1045
+ label: Optional[str]
1046
+ _draw_seq: int
1047
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1048
+ visible: bool
1049
+
1050
+
1051
+ class FillSeries(Series):
1052
+ """A filled region -- ``Axes.fill_between`` or ``Axes.fill``.
1053
+
1054
+ Absent ``target`` is the two-curve band ``fill dA,dB``. ``target``
1055
+ ``"x1"`` / ``"x2"`` fills one curve to that axis (``fill x1,dN`` /
1056
+ ``fill dN,x2``). ``"polygon"`` is ``Axes.fill``: ``fill dN`` closes the
1057
+ vertices. ``xmin`` / ``xmax`` / ``ymin`` / ``ymax`` are GLE's clip
1058
+ window; an absent edge is not clipped. On an ``x1`` fill, ``ymin`` is
1059
+ also the line the region closes on (GLE's rule, not a second clip).
1060
+ """
1061
+
1062
+ ATTR = "fills"
1063
+ ARRAY_FIELDS = ("x", "y1", "y2")
1064
+
1065
+ x: np.ndarray
1066
+ y1: np.ndarray
1067
+ y2: np.ndarray
1068
+ color: str
1069
+ alpha: float
1070
+ label: Optional[str]
1071
+ offset: float
1072
+ #: Set by ``open_gle`` when a ``let`` shifts the second curve by another
1073
+ #: amount than the first. Absent: ``offset`` shifts both.
1074
+ _offset2: float
1075
+ data_file: Optional[str]
1076
+ column_names: Optional[List[str]]
1077
+ #: Where the numbers come from; absent means InlineData (this
1078
+ #: series' own array fields). See :mod:`gleplot.sources`.
1079
+ data_source: Optional[DataSource]
1080
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1081
+ visible: bool
1082
+ #: Call order, for the legend. Fills are not z-ordered drawables, so this
1083
+ #: does not change ink. Absent on a series a script did not record it for.
1084
+ _draw_seq: int
1085
+ #: See ``_XYSeries._gle_names``.
1086
+ _gle_names: Dict[str, str]
1087
+ #: Legend swatch colour when it is not the fill colour. Absent means the
1088
+ #: swatch is ``apply_alpha(color, alpha)``.
1089
+ swatch_color: Optional[str]
1090
+ #: ``"x1"``, ``"x2"`` or ``"polygon"``. Absent: two-curve ``fill dA,dB``.
1091
+ target: str
1092
+ #: Clip window in data coordinates. Absent: that edge is open.
1093
+ xmin: float
1094
+ xmax: float
1095
+ ymin: float
1096
+ ymax: float
1097
+
1098
+ def default_column_names(self) -> Optional[List[str]]:
1099
+ if self.get("target") in ("x1", "x2", "polygon"):
1100
+ return _unique_column_names(["x", "y"])
1101
+ return _unique_column_names(["x", "upper", "lower"])
1102
+
1103
+
1104
+ class ErrorbarSeries(Series):
1105
+ """A dataset with x and/or y error bars -- ``Axes.errorbar``."""
1106
+
1107
+ ATTR = "errorbars"
1108
+ KIND = "errorbar"
1109
+ ZORDER_DEFAULT = 5.0
1110
+ KIND_RANK = 3
1111
+ ARRAY_FIELDS = ("x", "y", "yerr_up", "yerr_down", "xerr_left", "xerr_right")
1112
+
1113
+ type: str
1114
+ x: np.ndarray
1115
+ y: np.ndarray
1116
+ yerr_up: Optional[np.ndarray]
1117
+ yerr_down: Optional[np.ndarray]
1118
+ xerr_left: Optional[np.ndarray]
1119
+ xerr_right: Optional[np.ndarray]
1120
+ #: ``None`` is a recovered ``dN`` line that set no colour: the writer
1121
+ #: writes none, and GLE draws in the current colour.
1122
+ color: Optional[str]
1123
+ marker: Optional[str]
1124
+ markersize: float
1125
+ linestyle: str
1126
+ #: ``None`` is a recovered ``dN`` line that drew a line but set no
1127
+ #: ``lwidth``: the writer writes none (GLE's current line width).
1128
+ linewidth: Optional[float]
1129
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
1130
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
1131
+ _lwidth_verbatim: bool
1132
+ label: Optional[str]
1133
+ #: Cap size as the caller gave it (matplotlib points, or cm when set
1134
+ #: through ``capsize_cm``); ``gle_capsize`` is the emitted cm value.
1135
+ capsize: Optional[float]
1136
+ gle_capsize: Optional[float]
1137
+ yaxis: str
1138
+ #: ``'x2'`` binds the series to the top scale. Absent means the
1139
+ #: primary x axis.
1140
+ xaxis: str
1141
+ offset: float
1142
+ data_file: Optional[str]
1143
+ column_names: Optional[List[str]]
1144
+ #: Where the numbers come from; absent means InlineData (this
1145
+ #: series' own array fields). See :mod:`gleplot.sources`.
1146
+ data_source: Optional[DataSource]
1147
+ _draw_seq: int
1148
+ #: See ``_XYSeries._gle_names``.
1149
+ _gle_names: Dict[str, str]
1150
+ zorder: float
1151
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1152
+ visible: bool
1153
+ #: GLE's per-dataset range, as on ``_XYSeries``; the error bars are
1154
+ #: drawn against it too. Absent: that edge is the axis limit.
1155
+ xmin: float
1156
+ xmax: float
1157
+ ymin: float
1158
+ ymax: float
1159
+ #: ``mdist``, ``deresolve`` and ``deresolve_average`` as on
1160
+ #: ``_XYSeries``, read from a file only: :meth:`Axes.errorbar` does not
1161
+ #: take them, since GLE thins the markers but not the error bars.
1162
+ mdist: float
1163
+ deresolve: int
1164
+ deresolve_average: bool
1165
+
1166
+ def default_column_names(self) -> Optional[List[str]]:
1167
+ return _build_errorbar_column_names(
1168
+ self.get("label"),
1169
+ self.get("yerr_up"),
1170
+ self.get("yerr_down"),
1171
+ self.get("xerr_left"),
1172
+ self.get("xerr_right"),
1173
+ )
1174
+
1175
+
1176
+ class FileSeries(Series):
1177
+ """A reference to columns of an existing external data file.
1178
+
1179
+ One class covers every ``series_type`` (``'line'``, ``'errorbar'``,
1180
+ ``'bar'``, ``'fill'``) because the variants are the same *kind* of thing
1181
+ -- a column reference plus style -- and share one list on the axes and
1182
+ one writer dispatch. The union of their fields is declared here and, as
1183
+ everywhere else, only the fields a given call actually supplies are
1184
+ stored, so each variant keeps exactly the shape it had.
1185
+ """
1186
+
1187
+ ATTR = "file_series"
1188
+
1189
+ series_type: str
1190
+ data_file: str
1191
+ x_col: int
1192
+ y_col: int
1193
+ #: ``'fill'`` variant: the two bounding columns.
1194
+ y1_col: int
1195
+ y2_col: int
1196
+ #: ``'errorbar'`` variant.
1197
+ yerr_col: Optional[int]
1198
+ #: ``None`` (``'line'`` and ``'errorbar'`` variants) is a recovered
1199
+ #: ``dN`` line that set no colour: the writer writes none.
1200
+ color: Optional[str]
1201
+ marker: Optional[str]
1202
+ markersize: float
1203
+ linestyle: str
1204
+ #: ``None`` (``'line'`` variant) is a recovered ``dN`` line that set no
1205
+ #: ``lwidth``: the writer writes none.
1206
+ linewidth: Optional[float]
1207
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
1208
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
1209
+ _lwidth_verbatim: bool
1210
+ #: ``'line'`` variant only: GLE's ``nomiss`` qualifier (see
1211
+ #: ``_XYSeries.nomiss``).
1212
+ nomiss: bool
1213
+ #: ``'line'`` variant only: GLE ``dn line`` mode. Absent means a plain
1214
+ #: polyline. See :attr:`LineSeries.line_mode`.
1215
+ line_mode: str
1216
+ label: Optional[str]
1217
+ capsize: Optional[float]
1218
+ yaxis: str
1219
+ #: ``'x2'`` binds the referenced columns to the top scale. Absent
1220
+ #: means the primary x axis.
1221
+ xaxis: str
1222
+ #: Why the recognizer did not load the referenced data, when it did not:
1223
+ #: the file is unreadable, or GLE reads it in a way the loader does not.
1224
+ #: Present only on entries the recognizer degraded to a bare reference.
1225
+ data_error: str
1226
+ _draw_seq: int
1227
+ #: See ``_XYSeries._gle_names``.
1228
+ _gle_names: Dict[str, str]
1229
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1230
+ visible: bool
1231
+ #: Legend swatch colour when a bar or fill ``keyfill`` is not ``color``.
1232
+ swatch_color: Optional[str]
1233
+ #: ``'fill'`` variant: ``"x1"``, ``"x2"`` or ``"polygon"``. Absent means
1234
+ #: the two-curve ``fill dA,dB``.
1235
+ target: str
1236
+ #: The ``fill`` command's clip window on the ``'fill'`` variant (absent:
1237
+ #: not clipped on that edge); the dataset's range (``_XYSeries.xmin``)
1238
+ #: on ``'line'`` and ``'errorbar'``.
1239
+ xmin: float
1240
+ xmax: float
1241
+ ymin: float
1242
+ ymax: float
1243
+ #: ``'line'`` and ``'errorbar'`` variants: see ``_XYSeries.mdist``,
1244
+ #: ``deresolve`` and ``deresolve_average``.
1245
+ mdist: float
1246
+ deresolve: int
1247
+ deresolve_average: bool
1248
+ #: How GLE reads ``data_file``: ``ignore`` (leading lines skipped),
1249
+ #: ``comment`` (the comment marker, replacing GLE's ``!``) and
1250
+ #: ``numrows`` (data rows read). Absent: GLE's default.
1251
+ skiprows: int
1252
+ comment: str
1253
+ max_rows: int
1254
+
1255
+
1256
+ class TextAnnotation(Series):
1257
+ """Free-form text drawn in data coordinates or axes fractions -- ``Axes.text``.
1258
+
1259
+ The one kind with no ``visible`` field: SPEC 7.5's structure tree lists
1260
+ texts as their own branch beside the series, and G11 is per-*series*
1261
+ visibility (see the module docstring).
1262
+ """
1263
+
1264
+ ATTR = "texts"
1265
+
1266
+ x: float
1267
+ y: float
1268
+ text: str
1269
+ color: str
1270
+ fontsize: Optional[float]
1271
+ ha: str
1272
+ va: str
1273
+ box_color: Optional[str]
1274
+ #: Degrees counter-clockwise about the alignment point (GLE ``begin
1275
+ #: rotate``, which rotates about the current point). Absent means 0, so
1276
+ #: a text that does not rotate keeps the historical dict shape.
1277
+ rotation: float
1278
+ #: ``'axes'``: ``x`` and ``y`` are fractions of the frame
1279
+ #: (``Axes.text(transform=ax.transAxes)``). Absent means data coordinates.
1280
+ transform: str
1281
+ #: ``Axes.annotate`` arrow, all absent on a plain text. ``xy`` is the
1282
+ #: arrow tip ``[x, y]`` in data coordinates; ``arrow`` is the GLE
1283
+ #: ``join`` separator (``'->'``, ``'<-'``, ``'<->'`` or ``'-'``);
1284
+ #: ``arrowstyle`` is the GLE tip style (``'simple'``/``'filled'``),
1285
+ #: present exactly when ``arrow`` has a head; ``arrow_linewidth`` is in
1286
+ #: points, absent for GLE's ambient ``lwidth``.
1287
+ xy: List[float]
1288
+ arrow: str
1289
+ arrowstyle: str
1290
+ arrow_color: str
1291
+ arrow_linewidth: float
1292
+
1293
+
1294
+ class _GridSeries(Series):
1295
+ """Base of the two gridded-data kinds (heatmaps and contours).
1296
+
1297
+ Both accept either a regular grid (``source='grid'``, ``z`` plus
1298
+ ``extent``) or scattered samples gridded by GLE's ``fitz``
1299
+ (``source='points'``, ``x``/``y``/``zpts`` plus ``gridsize``), and both
1300
+ hold their bulk data in the same four array fields. A heatmap may also be
1301
+ an expression GLE evaluates itself (``source='function'``), with no
1302
+ arrays at all.
1303
+
1304
+ The shared fields are re-declared in full by each subclass rather than
1305
+ inherited: field order here is serialization order, and the two kinds
1306
+ interleave their common and their own fields differently.
1307
+
1308
+ ``extent`` may be ``None`` on a **reference-backed** grid series (one
1309
+ whose ``data_source`` is a :class:`~gleplot.sources.GridRef`), meaning
1310
+ *auto*: each write computes it from the arrays that write resolved --
1311
+ ``(0, nx, 0, ny)`` in grid mode, the sample bounds in points mode, the
1312
+ same defaults ``Axes.imshow``/``Axes.tripcolor`` bake when handed arrays
1313
+ (SPEC 14.5). A series that owns its arrays always carries a concrete
1314
+ extent, because the creation APIs had the arrays and baked it.
1315
+ See :func:`gleplot.writer.apply_grid_write_time_autos`.
1316
+ """
1317
+
1318
+ ARRAY_FIELDS = ("z", "x", "y", "zpts")
1319
+
1320
+
1321
+ class HeatmapSeries(_GridSeries):
1322
+ """A colormap image -- ``Axes.imshow`` / ``Axes.pcolormesh`` /
1323
+ ``Axes.contourf`` / ``Axes.tripcolor`` / ``Axes.function2d``."""
1324
+
1325
+ ATTR = "heatmaps"
1326
+
1327
+ type: str
1328
+ #: ``'grid'``, ``'points'`` or ``'function'``.
1329
+ source: str
1330
+ #: The GLE expression in ``x`` and ``y`` a ``'function'`` heatmap maps;
1331
+ #: absent on the other sources. Such a heatmap has no arrays and no
1332
+ #: ``data_file``: GLE evaluates the expression at every pixel.
1333
+ expression: str
1334
+ z: Optional[np.ndarray]
1335
+ x: Optional[np.ndarray]
1336
+ y: Optional[np.ndarray]
1337
+ zpts: Optional[np.ndarray]
1338
+ extent: Optional[List[float]]
1339
+ origin: str
1340
+ cmap: str
1341
+ vmin: Optional[float]
1342
+ vmax: Optional[float]
1343
+ interpolation: str
1344
+ #: ``True`` on a ``'grid'`` heatmap from ``Axes.pcolormesh``: ``extent``
1345
+ #: holds the outer cell edges and each value colours one whole cell.
1346
+ #: Absent means ``imshow``'s placement.
1347
+ cells: bool
1348
+ #: The band edges of a ``'grid'`` heatmap from ``Axes.contourf``, which
1349
+ #: colours each value by its band; ``extent`` then holds the grid's first
1350
+ #: and last nodes. Absent on every other heatmap.
1351
+ levels: List[float]
1352
+ #: Which side of a ``contourf``'s levels is filled: ``'neither'``,
1353
+ #: ``'min'``, ``'max'`` or ``'both'``. Present exactly when ``levels`` is.
1354
+ extend: str
1355
+ pixels: Optional[List[int]]
1356
+ invert: bool
1357
+ gridsize: Optional[List[int]]
1358
+ ncontour: Optional[int]
1359
+ label: Optional[str]
1360
+ data_file: str
1361
+ #: Where the numbers come from; absent means InlineData (this
1362
+ #: series' own array fields). See :mod:`gleplot.sources`.
1363
+ data_source: Optional[DataSource]
1364
+ #: Colorbar declaration dict, or ``None`` for no colorbar. Its
1365
+ #: ``zmin``/``zmax``/``zstep`` are concrete numbers, except on a
1366
+ #: reference-backed heatmap that carries ``auto_range = True``, where
1367
+ #: they are ``None`` and each write computes them from the resolved data
1368
+ #: (SPEC 14.5). Its ``orientation`` key is ``'horizontal'`` for a bar
1369
+ #: below the axes; absent means vertical. See
1370
+ #: :meth:`gleplot.Figure.colorbar`.
1371
+ colorbar: Optional[Dict[str, Any]]
1372
+ #: Set by ``open_gle`` on a ``contourf`` with no ``colorbar`` whose band
1373
+ #: sub maps its values back from this ``[zmin, zmax]``: a colorbar kept
1374
+ #: as raw GLE draws through the sub, so the writer keeps the mapping.
1375
+ #: Absent means the values pass through unscaled.
1376
+ _bar_range: List[float]
1377
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1378
+ visible: bool
1379
+
1380
+
1381
+ class ContourSeries(_GridSeries):
1382
+ """Contour lines -- ``Axes.contour`` / ``Axes.tricontour``."""
1383
+
1384
+ ATTR = "contours"
1385
+
1386
+ type: str
1387
+ #: ``'grid'`` or ``'points'``.
1388
+ source: str
1389
+ z: Optional[np.ndarray]
1390
+ x: Optional[np.ndarray]
1391
+ y: Optional[np.ndarray]
1392
+ zpts: Optional[np.ndarray]
1393
+ extent: Optional[List[float]]
1394
+ levels: Optional[List[float]]
1395
+ #: ``None`` is a recovered contour line that set no colour: the writer
1396
+ #: writes none, and GLE draws in the current colour.
1397
+ color: Optional[str]
1398
+ #: ``None`` is a recovered contour line that set no ``lwidth``: the
1399
+ #: writer writes none (GLE's current line width).
1400
+ linewidth: Optional[float]
1401
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
1402
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
1403
+ _lwidth_verbatim: bool
1404
+ linestyle: Optional[int]
1405
+ clabel: bool
1406
+ clabel_fmt: str
1407
+ gridsize: Optional[List[int]]
1408
+ ncontour: Optional[int]
1409
+ label: Optional[str]
1410
+ data_file: str
1411
+ #: Where the numbers come from; absent means InlineData (this
1412
+ #: series' own array fields). See :mod:`gleplot.sources`.
1413
+ data_source: Optional[DataSource]
1414
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1415
+ visible: bool
1416
+
1417
+
1418
+ class RefLine(Series):
1419
+ """A full-width/height guide line -- ``Axes.axvline`` / ``Axes.axhline``.
1420
+
1421
+ Stores the *declaration* only. The concrete two-point dataset is built at
1422
+ write time by ``Axes.materialize_reflines`` so the guide tracks whatever
1423
+ axis limits end up being used.
1424
+ """
1425
+
1426
+ ATTR = "reflines"
1427
+
1428
+ type: str
1429
+ #: ``'v'`` or ``'h'``.
1430
+ orient: str
1431
+ value: float
1432
+ #: Extent along the other axis, as a fraction of the axes box.
1433
+ span_lo: float
1434
+ span_hi: float
1435
+ color: str
1436
+ linestyle: str
1437
+ linewidth: float
1438
+ #: Set by ``open_gle`` on a width of 0 or 1 pt read from a file, which
1439
+ #: is then written as given. Absent, 0 and 1 mean the style's default.
1440
+ _lwidth_verbatim: bool
1441
+ label: Optional[str]
1442
+ data_file: Optional[str]
1443
+ column_names: Optional[List[str]]
1444
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1445
+ visible: bool
1446
+ #: Call order, for the legend. Reference lines are written after the
1447
+ #: fills, so this does not change ink.
1448
+ _draw_seq: int
1449
+
1450
+ def default_column_names(self) -> Optional[List[str]]:
1451
+ return _build_column_names("x", ["y"], self.get("label"))
1452
+
1453
+
1454
+ class Span(Series):
1455
+ """A shaded band -- ``Axes.axvspan`` / ``Axes.axhspan``.
1456
+
1457
+ Like :class:`RefLine`, a declaration materialized into a fill at write
1458
+ time (``Axes.materialize_spans``).
1459
+ """
1460
+
1461
+ ATTR = "spans"
1462
+
1463
+ type: str
1464
+ #: ``'v'`` or ``'h'``.
1465
+ orient: str
1466
+ start: float
1467
+ end: float
1468
+ span_lo: float
1469
+ span_hi: float
1470
+ color: str
1471
+ alpha: float
1472
+ label: Optional[str]
1473
+ data_file: Optional[str]
1474
+ column_names: Optional[List[str]]
1475
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1476
+ visible: bool
1477
+ #: Call order, for the legend. Spans are emitted with the fills, so this
1478
+ #: does not change ink.
1479
+ _draw_seq: int
1480
+ #: Legend swatch colour when it is not the band colour.
1481
+ swatch_color: Optional[str]
1482
+
1483
+ def default_column_names(self) -> Optional[List[str]]:
1484
+ return _unique_column_names(["x", "upper", "lower"])
1485
+
1486
+
1487
+ class PlacedImage(Series):
1488
+ """An external image file stretched over a data extent -- ``Axes.image``.
1489
+
1490
+ Drawn inside the graph block by the ``glp_bitmap`` sub (PNG, JPEG,
1491
+ GIF, TIFF) or the ``glp_postscript`` sub (EPS), in a layer below the
1492
+ grid and the data.
1493
+ """
1494
+
1495
+ ATTR = "images"
1496
+
1497
+ type: str
1498
+ #: The image path exactly as given; GLE reads a relative path from the
1499
+ #: folder the ``.gle`` script is in.
1500
+ file: str
1501
+ #: ``[left, right, bottom, top]`` in data coordinates, each pair
1502
+ #: ascending.
1503
+ extent: List[float]
1504
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1505
+ visible: bool
1506
+
1507
+
1508
+ class Rug(Series):
1509
+ """One rug -- ``Axes.rug`` stores one per call.
1510
+
1511
+ Its values are written to :attr:`data_file` and loaded as a dataset in
1512
+ the graph; ``xrug`` or ``yrug`` from GLE's ``rugs.gle`` draws them after
1513
+ the graph block.
1514
+ """
1515
+
1516
+ ATTR = "rugs"
1517
+
1518
+ type: str
1519
+ #: ``'x'`` (ticks along the x axis, at x values) or ``'y'``.
1520
+ axis: str
1521
+ #: Where the ticks are, in data coordinates along :attr:`axis`.
1522
+ ticks: List[float]
1523
+ #: Tick length in cm, into the axes from the frame; negative points out.
1524
+ length: float
1525
+ #: Frame edge: ``'bottom'``/``'top'`` for x, ``'left'``/``'right'`` for
1526
+ #: y, or ``'both'``.
1527
+ position: str
1528
+ color: str
1529
+ #: Points.
1530
+ linewidth: float
1531
+ #: The sidecar the values are written to, one per line.
1532
+ data_file: str
1533
+ #: Drawn at all; absent (the default) means yes. See :func:`is_visible`.
1534
+ visible: bool
1535
+
1536
+
1537
+ # -- registry -----------------------------------------------------------------
1538
+
1539
+ #: Every series list an axes owns, in the order they are serialized by
1540
+ #: ``Axes.to_dict`` and walked by ``Axes.from_dict``. This single mapping
1541
+ #: replaces the old ``Axes._SERIES_ATTRS`` / ``Axes._ARRAY_KEYS`` /
1542
+ #: ``Axes._default_column_names`` triple: order comes from the mapping,
1543
+ #: array-ness from ``cls.ARRAY_FIELDS``, and the header-row fallback from
1544
+ #: ``cls.default_column_names``.
1545
+ SERIES_CLASSES: Dict[str, Type[Series]] = {
1546
+ cls.ATTR: cls
1547
+ for cls in (
1548
+ LineSeries,
1549
+ ScatterSeries,
1550
+ BarSeries,
1551
+ FillSeries,
1552
+ ErrorbarSeries,
1553
+ FileSeries,
1554
+ TextAnnotation,
1555
+ HeatmapSeries,
1556
+ ContourSeries,
1557
+ RefLine,
1558
+ Span,
1559
+ HistSeries,
1560
+ FunctionSeries,
1561
+ FitSeries,
1562
+ Rug,
1563
+ DerivedSeries,
1564
+ PlacedImage,
1565
+ )
1566
+ }
1567
+
1568
+ #: The registry's keys, i.e. the ``Axes`` series list attribute names.
1569
+ SERIES_ATTRS: Tuple[str, ...] = tuple(SERIES_CLASSES)
1570
+
1571
+ #: The subset that takes part in cross-kind z-ordering, keyed by ``KIND``
1572
+ #: and ordered by ``KIND_RANK`` -- i.e. bars, lines, scatters, errorbars,
1573
+ #: the fixed emission stack that predates ``zorder`` and is still the
1574
+ #: tie-break order in ``sorted_zorder_drawables``.
1575
+ DRAWABLE_CLASSES: Dict[str, Type[Series]] = {}
1576
+ for _cls in sorted(
1577
+ (c for c in SERIES_CLASSES.values() if c.KIND is not None),
1578
+ key=lambda c: c.KIND_RANK or 0,
1579
+ ):
1580
+ DRAWABLE_CLASSES[str(_cls.KIND)] = _cls
1581
+ del _cls
1582
+
1583
+
1584
+ def sorted_zorder_drawables(ax: Any) -> List[Tuple[str, Series]]:
1585
+ """Bars, lines, scatters, and errorbars sorted by ``(zorder, call order)``.
1586
+
1587
+ ``ax`` is anything carrying the series lists under their ``ATTR`` names,
1588
+ in practice a :class:`gleplot.axes.Axes`. It lives here rather than in
1589
+ ``axes`` so the writer can order drawables without importing ``axes``.
1590
+
1591
+ The kind name and both fallbacks come from :data:`DRAWABLE_CLASSES`, so a
1592
+ new drawable kind only has to declare ``KIND``/``ZORDER_DEFAULT``/
1593
+ ``KIND_RANK`` to join the ordering. An explicit ``zorder`` on a series
1594
+ wins; ``_draw_seq`` records the call order and is absent only on
1595
+ pre-zorder projects, where the kind rank reproduces the old fixed
1596
+ emission stack (bars, then lines, scatters, errorbars).
1597
+ """
1598
+ items: List[Tuple[float, float, str, Series]] = []
1599
+ for kind, series_cls in DRAWABLE_CLASSES.items():
1600
+ default_z = float(series_cls.ZORDER_DEFAULT or 0.0)
1601
+ kind_rank = int(series_cls.KIND_RANK or 0)
1602
+ for idx, data in enumerate(getattr(ax, str(series_cls.ATTR))):
1603
+ z = float(data["zorder"]) if "zorder" in data else default_z
1604
+ draw_seq = data.get("_draw_seq")
1605
+ if draw_seq is None:
1606
+ draw_seq = kind_rank * 1_000_000 + idx
1607
+ items.append((z, float(draw_seq), kind, data))
1608
+ items.sort(key=lambda t: (t[0], t[1]))
1609
+ return [(kind, data) for _z, _seq, kind, data in items]