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/__init__.py +772 -0
- gleplot/_warn.py +45 -0
- gleplot/axes.py +10714 -0
- gleplot/cairo_support.py +232 -0
- gleplot/colors.py +721 -0
- gleplot/compiler.py +863 -0
- gleplot/config.py +491 -0
- gleplot/dataio.py +1403 -0
- gleplot/figure.py +5789 -0
- gleplot/guides.py +172 -0
- gleplot/markers.py +424 -0
- gleplot/mathtext.py +679 -0
- gleplot/palettes.py +243 -0
- gleplot/parser/__init__.py +83 -0
- gleplot/parser/expr.py +196 -0
- gleplot/parser/lexer.py +289 -0
- gleplot/parser/metadata.py +374 -0
- gleplot/parser/recognizer.py +12654 -0
- gleplot/parser/report.py +74 -0
- gleplot/parser/syntax.py +756 -0
- gleplot/parser/tables.py +484 -0
- gleplot/parser/units.py +196 -0
- gleplot/py.typed +0 -0
- gleplot/series.py +1609 -0
- gleplot/sources.py +623 -0
- gleplot/writer.py +7215 -0
- gleplot-6.0.0.dist-info/METADATA +138 -0
- gleplot-6.0.0.dist-info/RECORD +31 -0
- gleplot-6.0.0.dist-info/WHEEL +5 -0
- gleplot-6.0.0.dist-info/licenses/LICENSE +25 -0
- gleplot-6.0.0.dist-info/top_level.txt +1 -0
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]
|