samplekit 1.0.0rc2__cp315-cp315-win_amd64.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.
- samplekit/__init__.py +405 -0
- samplekit/__init__.pyi +2218 -0
- samplekit/_figure.py +173 -0
- samplekit/_figures.py +2066 -0
- samplekit/_native.cp315-win_amd64.pyd +0 -0
- samplekit/_script.py +231 -0
- samplekit/_scripts.py +212 -0
- samplekit/_worker.py +1458 -0
- samplekit/py.typed +0 -0
- samplekit-1.0.0rc2.dist-info/METADATA +196 -0
- samplekit-1.0.0rc2.dist-info/RECORD +15 -0
- samplekit-1.0.0rc2.dist-info/WHEEL +4 -0
- samplekit-1.0.0rc2.dist-info/licenses/LICENSE +21 -0
- samplekit-1.0.0rc2.dist-info/licenses/THIRD-PARTY-LICENSES.md +2496 -0
- samplekit-1.0.0rc2.dist-info/sboms/samplekit.cyclonedx.json +10882 -0
samplekit/_figures.py
ADDED
|
@@ -0,0 +1,2066 @@
|
|
|
1
|
+
"""Figures, drawn by matplotlib.
|
|
2
|
+
|
|
3
|
+
``@figure`` marks a model's method as a figure — an instance method draws one
|
|
4
|
+
sample, a class method a collection — and ``plot`` draws it, or a figure the
|
|
5
|
+
project declares, or two axes given by hand. SampleKit makes the figure and its
|
|
6
|
+
axes; the method only draws, so that the choice between a window and a file,
|
|
7
|
+
and the refusal where no window can be seen, are made here and nowhere else.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import math
|
|
11
|
+
import os
|
|
12
|
+
import pathlib
|
|
13
|
+
import re
|
|
14
|
+
import sys
|
|
15
|
+
import warnings
|
|
16
|
+
|
|
17
|
+
# A KeyError that prints its message on its lines rather than as a quoted key.
|
|
18
|
+
from samplekit._native import _KeyError as LookupFailed
|
|
19
|
+
|
|
20
|
+
__all__ = ["figure", "plot"]
|
|
21
|
+
|
|
22
|
+
KINDS = ("scatter", "line", "step", "bar", "box")
|
|
23
|
+
LEGENDS = ("best", "outside", "none", "upper right", "upper left", "lower left",
|
|
24
|
+
"lower right", "right", "center left", "center right", "lower center",
|
|
25
|
+
"upper center")
|
|
26
|
+
# More groups than this are read as a colour scale when numeric, and refused as
|
|
27
|
+
# text: ten colours repeat, and a legend of more reads as nothing.
|
|
28
|
+
MOST_GROUPS = 10
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class Figure:
|
|
32
|
+
"""A model's method marked ``@sk.figure``. It still behaves as the method
|
|
33
|
+
it marks: ``steel.yield_point(ax)`` draws into ``ax`` as written."""
|
|
34
|
+
|
|
35
|
+
def __init__(self, method, subplots, figsize=None, matplotlib=None):
|
|
36
|
+
if subplots is not None and (
|
|
37
|
+
len(subplots) != 2 or not all(isinstance(n, int) and n > 0 for n in subplots)
|
|
38
|
+
):
|
|
39
|
+
raise ValueError(f"subplots is (rows, columns), two positive integers: {subplots!r}")
|
|
40
|
+
if isinstance(method, staticmethod):
|
|
41
|
+
raise TypeError(
|
|
42
|
+
"a figure draws a sample or a collection: mark an instance method, or a "
|
|
43
|
+
"class method (@sk.figure above @classmethod), not a static method"
|
|
44
|
+
)
|
|
45
|
+
self.method = method
|
|
46
|
+
self.subplots = tuple(subplots) if subplots is not None else None
|
|
47
|
+
self.figsize = _checked_axes({"figsize": figsize}).get("figsize")
|
|
48
|
+
if matplotlib is not None and not isinstance(matplotlib, dict):
|
|
49
|
+
raise TypeError(
|
|
50
|
+
"matplotlib= is a dict of matplotlib's settings, by their names: "
|
|
51
|
+
f"{{'lines.marker': 'None'}}, not {matplotlib!r}"
|
|
52
|
+
)
|
|
53
|
+
self.matplotlib = dict(matplotlib or {})
|
|
54
|
+
self.collection = isinstance(method, classmethod)
|
|
55
|
+
self.name = getattr(method, "__name__", None) or getattr(
|
|
56
|
+
getattr(method, "__func__", None), "__name__", None
|
|
57
|
+
)
|
|
58
|
+
self.__doc__ = getattr(method, "__doc__", None)
|
|
59
|
+
|
|
60
|
+
def __set_name__(self, owner, name):
|
|
61
|
+
self.name = name
|
|
62
|
+
|
|
63
|
+
def __get__(self, instance, owner=None):
|
|
64
|
+
return self.method.__get__(instance, owner)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def figure(method=None, *, subplots=None, figsize=None, matplotlib=None):
|
|
68
|
+
"""Mark a method of a model as a figure.
|
|
69
|
+
|
|
70
|
+
The method draws into the matplotlib axes it receives, and returns
|
|
71
|
+
nothing; ``samplekit.plot`` and ``samplekit plot`` open it in a window or
|
|
72
|
+
write it to a file. A method draws one sample; placed above
|
|
73
|
+
``@classmethod``, it draws a list of them.
|
|
74
|
+
|
|
75
|
+
Args:
|
|
76
|
+
method: The method, when used without arguments: ``@sk.figure``.
|
|
77
|
+
subplots: ``(rows, columns)``: the method receives the array of axes
|
|
78
|
+
``plt.subplots`` makes, instead of one.
|
|
79
|
+
figsize: The figure's width and height, in centimetres.
|
|
80
|
+
matplotlib: matplotlib's settings for this figure alone, by their
|
|
81
|
+
names, over the project's ``[matplotlib]``:
|
|
82
|
+
``{"lines.marker": "None"}``.
|
|
83
|
+
|
|
84
|
+
Returns:
|
|
85
|
+
The method, marked.
|
|
86
|
+
|
|
87
|
+
Raises:
|
|
88
|
+
ValueError: ``subplots`` is not two positive integers.
|
|
89
|
+
|
|
90
|
+
Example:
|
|
91
|
+
>>> class Specimen(sk.Sample):
|
|
92
|
+
... @sk.figure
|
|
93
|
+
... def stress_strain(self, ax):
|
|
94
|
+
... ax.plot(self.curve.values("strain"),
|
|
95
|
+
... self.curve.values("stress"))
|
|
96
|
+
"""
|
|
97
|
+
if method is None:
|
|
98
|
+
return lambda marked: Figure(marked, subplots, figsize, matplotlib)
|
|
99
|
+
return Figure(method, subplots, figsize, matplotlib)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def figures_of(cls):
|
|
103
|
+
"""The figures a model declares, by name, a subclass's over its base's: a
|
|
104
|
+
subclass that redefines the name as something else takes the figure away."""
|
|
105
|
+
found = {}
|
|
106
|
+
for klass in reversed(cls.__mro__):
|
|
107
|
+
for name, value in vars(klass).items():
|
|
108
|
+
if isinstance(value, Figure):
|
|
109
|
+
found[name] = value
|
|
110
|
+
elif isinstance(value, classmethod) and isinstance(value.__func__, Figure):
|
|
111
|
+
raise TypeError(
|
|
112
|
+
f"{klass.__name__}.{name}: @sk.figure goes above @classmethod, "
|
|
113
|
+
"not beneath it"
|
|
114
|
+
)
|
|
115
|
+
elif name in found:
|
|
116
|
+
del found[name]
|
|
117
|
+
return found
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class Declared:
|
|
121
|
+
"""What ``[figure.*]`` holds, or axes given to ``plot`` by hand."""
|
|
122
|
+
|
|
123
|
+
def __init__(self, name, kind, x, y, group=None, query=None, title=None,
|
|
124
|
+
x_label=None, y_label=None, style=None, axes=None, matplotlib=None):
|
|
125
|
+
if kind not in KINDS:
|
|
126
|
+
raise ValueError(f"'{kind}' is not a figure kind: scatter, line, step, bar or box")
|
|
127
|
+
self.name, self.kind, self.x, self.y = name, kind, x, y
|
|
128
|
+
self.group, self.query = _group_text(group), query
|
|
129
|
+
self.title, self.x_label, self.y_label, self.style = title, x_label, y_label, style
|
|
130
|
+
self.axes = _checked_axes(axes or {})
|
|
131
|
+
self.matplotlib = dict(matplotlib or {})
|
|
132
|
+
|
|
133
|
+
def overridden(self, title=None, x_label=None, y_label=None, style=None, group=None,
|
|
134
|
+
kind=None, axes=None):
|
|
135
|
+
"""The same, with what was given here replacing what was declared — an
|
|
136
|
+
empty title or label included, which draws none."""
|
|
137
|
+
merged = dict(self.axes)
|
|
138
|
+
merged.update({key: value for key, value in (axes or {}).items() if value is not None})
|
|
139
|
+
|
|
140
|
+
def given(new, old):
|
|
141
|
+
return old if new is None else new
|
|
142
|
+
|
|
143
|
+
return Declared(self.name, given(kind, self.kind), self.x, self.y,
|
|
144
|
+
given(group, self.group), self.query, given(title, self.title),
|
|
145
|
+
given(x_label, self.x_label), given(y_label, self.y_label),
|
|
146
|
+
given(style, self.style), merged, self.matplotlib)
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _group_text(group):
|
|
150
|
+
"""A group as one text, its fields separated by commas as ``--group
|
|
151
|
+
material,grade`` writes them: a field, several in a list, or ``None``. An
|
|
152
|
+
empty one groups nothing, replacing a figure's own."""
|
|
153
|
+
if group is None or group == "":
|
|
154
|
+
return group
|
|
155
|
+
if isinstance(group, (list, tuple)):
|
|
156
|
+
fields = list(group)
|
|
157
|
+
elif isinstance(group, str):
|
|
158
|
+
fields = group.split(",")
|
|
159
|
+
else:
|
|
160
|
+
raise TypeError(f"group is a field, or several in a list: {group!r}")
|
|
161
|
+
if not all(isinstance(field, str) for field in fields):
|
|
162
|
+
raise TypeError(f"group is a field, or several in a list: {group!r}")
|
|
163
|
+
fields = [field.strip() for field in fields]
|
|
164
|
+
if not fields or not all(fields):
|
|
165
|
+
raise ValueError(f"group names a field, or several separated by commas: {group!r}")
|
|
166
|
+
return ",".join(fields)
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _fields_of(group):
|
|
170
|
+
"""The fields a group names: one, or several whose combinations are the
|
|
171
|
+
groups."""
|
|
172
|
+
return group.split(",") if group else []
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
# Sizes are taken in centimetres and given to matplotlib in inches.
|
|
176
|
+
CM_PER_INCH = 2.54
|
|
177
|
+
|
|
178
|
+
AXIS_KEYS = ("x_limits", "y_limits", "x_scale", "y_scale", "aspect", "legend", "figsize")
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def _checked_axes(axes):
|
|
182
|
+
"""Limits, scales and aspect, checked before anything is drawn."""
|
|
183
|
+
checked = {}
|
|
184
|
+
for key, value in axes.items():
|
|
185
|
+
if value is None:
|
|
186
|
+
continue
|
|
187
|
+
if key in ("x_limits", "y_limits"):
|
|
188
|
+
if not isinstance(value, (list, tuple)) or len(value) != 2:
|
|
189
|
+
raise ValueError(
|
|
190
|
+
f"{key} is two bounds, (low, high), a free one None or \"auto\": {value!r}"
|
|
191
|
+
)
|
|
192
|
+
# "auto" as `.samplekitrc` and the command line write a free end.
|
|
193
|
+
value = tuple(None if bound == "auto" else bound for bound in value)
|
|
194
|
+
for bound in value:
|
|
195
|
+
if bound is not None and (
|
|
196
|
+
isinstance(bound, bool)
|
|
197
|
+
or not isinstance(bound, (int, float))
|
|
198
|
+
or not math.isfinite(bound)
|
|
199
|
+
):
|
|
200
|
+
raise ValueError(
|
|
201
|
+
f"{key} bounds are finite numbers, or None or \"auto\" for a free "
|
|
202
|
+
f"one: {value!r}"
|
|
203
|
+
)
|
|
204
|
+
if value[0] is not None and value[0] == value[1]:
|
|
205
|
+
raise ValueError(f"{key} is a range, and {value[0]:g} to {value[1]:g} is none")
|
|
206
|
+
checked[key] = tuple(value)
|
|
207
|
+
elif key in ("x_scale", "y_scale"):
|
|
208
|
+
if value not in ("linear", "log", "symlog"):
|
|
209
|
+
raise ValueError(f"{key} is linear, log or symlog, not {value!r}")
|
|
210
|
+
checked[key] = value
|
|
211
|
+
elif key == "aspect":
|
|
212
|
+
if value not in ("equal", "auto"):
|
|
213
|
+
raise ValueError(f"aspect is equal or auto, not {value!r}")
|
|
214
|
+
checked[key] = value
|
|
215
|
+
elif key == "legend":
|
|
216
|
+
if value not in LEGENDS:
|
|
217
|
+
raise ValueError(f"legend is one of {', '.join(LEGENDS)}, not {value!r}")
|
|
218
|
+
checked[key] = value
|
|
219
|
+
elif key == "figsize":
|
|
220
|
+
if (
|
|
221
|
+
not isinstance(value, (list, tuple))
|
|
222
|
+
or len(value) != 2
|
|
223
|
+
or not all(isinstance(side, (int, float)) and not isinstance(side, bool)
|
|
224
|
+
and math.isfinite(side) and side > 0 for side in value)
|
|
225
|
+
):
|
|
226
|
+
raise ValueError(
|
|
227
|
+
f"figsize is a width and a height in centimetres, both positive: {value!r}"
|
|
228
|
+
)
|
|
229
|
+
checked[key] = tuple(float(side) for side in value)
|
|
230
|
+
else:
|
|
231
|
+
raise TypeError(f"{key} is not an axis setting: {', '.join(AXIS_KEYS)}")
|
|
232
|
+
return checked
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def plot(target, figure=None, *, x=None, y=None, group=None, kind=None,
|
|
236
|
+
title=None, x_label=None, y_label=None, style=None,
|
|
237
|
+
x_limits=None, y_limits=None, x_scale=None, y_scale=None, aspect=None,
|
|
238
|
+
legend=None, figsize=None, output=None, overwrite=False, project_style=True):
|
|
239
|
+
"""Draw a figure of a sample or a list of samples, with matplotlib.
|
|
240
|
+
|
|
241
|
+
The figure is a model's figure, one declared in ``.samplekitrc``, or
|
|
242
|
+
axes given here: ``x`` and ``y``, drawn as a declared figure would be.
|
|
243
|
+
It opens in a window, or is written to ``output``. The project's
|
|
244
|
+
``[matplotlib]`` settings apply to every figure.
|
|
245
|
+
|
|
246
|
+
Args:
|
|
247
|
+
target: A sample, a ``SampleList``, or an iterable of samples.
|
|
248
|
+
figure: The name of a model's figure or of a declared one.
|
|
249
|
+
x: The field on the x axis, for a figure not declared.
|
|
250
|
+
y: The field on the y axis, for a figure not declared.
|
|
251
|
+
group: A field, or several, whose values split the samples into
|
|
252
|
+
series, each in its own colour.
|
|
253
|
+
kind: ``"scatter"`` (the default), ``"line"``, ``"step"``, ``"bar"``
|
|
254
|
+
or ``"box"``.
|
|
255
|
+
title: The title; ``""`` draws none.
|
|
256
|
+
x_label: The x axis label, instead of the field's symbol and unit.
|
|
257
|
+
y_label: The y axis label, instead of the field's symbol and unit.
|
|
258
|
+
style: The declared style whose symbols and units label the axes;
|
|
259
|
+
``[render] figure_style`` by default.
|
|
260
|
+
x_limits: The x axis bounds, ``(low, high)``; ``None`` or ``"auto"``
|
|
261
|
+
leaves one free.
|
|
262
|
+
y_limits: The y axis bounds, ``(low, high)``; ``None`` or ``"auto"``
|
|
263
|
+
leaves one free.
|
|
264
|
+
x_scale: ``"linear"``, ``"log"`` or ``"symlog"``.
|
|
265
|
+
y_scale: ``"linear"``, ``"log"`` or ``"symlog"``.
|
|
266
|
+
aspect: ``"equal"`` or ``"auto"``.
|
|
267
|
+
legend: Where the legend goes: ``"best"``, ``"outside"``, ``"none"``
|
|
268
|
+
or one of matplotlib's places.
|
|
269
|
+
figsize: The figure's width and height, in centimetres.
|
|
270
|
+
output: The file to write, in the format its extension names:
|
|
271
|
+
``.png``, ``.pdf``, ``.svg``… ``{name}`` in it writes one file per
|
|
272
|
+
sample, for a figure of one sample. A folder it names that does
|
|
273
|
+
not exist is made.
|
|
274
|
+
overwrite: Replace an existing file.
|
|
275
|
+
project_style: Apply the project's ``[matplotlib]`` settings.
|
|
276
|
+
|
|
277
|
+
Returns:
|
|
278
|
+
The matplotlib figures drawn.
|
|
279
|
+
|
|
280
|
+
Raises:
|
|
281
|
+
TypeError: Neither ``figure`` nor ``x`` and ``y`` is given, or both
|
|
282
|
+
are, or axes options are given to a model's figure.
|
|
283
|
+
KeyError: An unknown figure or field; the message names the nearest.
|
|
284
|
+
ValueError: No sample to draw, or an output format matplotlib
|
|
285
|
+
cannot write.
|
|
286
|
+
FileExistsError: ``output`` exists and ``overwrite`` is false.
|
|
287
|
+
RuntimeError: No ``output`` is given and there is no display.
|
|
288
|
+
|
|
289
|
+
Example:
|
|
290
|
+
>>> figures = sk.plot(specimens, "curves", output="paper/curves.pdf")
|
|
291
|
+
>>> figures = sk.plot(specimens, x="yield_strength", y="tensile_strength",
|
|
292
|
+
... group="material", output="strengths.png")
|
|
293
|
+
"""
|
|
294
|
+
samples = _as_list(target)
|
|
295
|
+
if not len(samples):
|
|
296
|
+
# A figure of nothing is refused, as the command line refuses it : an
|
|
297
|
+
# empty file, or a window of empty axes, reads as data.
|
|
298
|
+
raise _in_the_data(ValueError("no sample to draw: the selection is empty"))
|
|
299
|
+
axes = {"x_limits": x_limits, "y_limits": y_limits, "x_scale": x_scale,
|
|
300
|
+
"y_scale": y_scale, "aspect": aspect, "legend": legend, "figsize": figsize}
|
|
301
|
+
if figure is None:
|
|
302
|
+
if x is None or y is None:
|
|
303
|
+
raise TypeError("plot draws a figure by name, or axes x= and y=")
|
|
304
|
+
# A sample's tags are a list, and an axis holds one number or word per
|
|
305
|
+
# sample: said so, where *unknown field* denied a field `group=` takes.
|
|
306
|
+
for axis, field in (("x", x), ("y", y)):
|
|
307
|
+
if field == "tags":
|
|
308
|
+
raise ValueError(
|
|
309
|
+
f"{axis}='tags': a sample's tags are a list, and an axis holds one number "
|
|
310
|
+
"or word per sample — group='tags' draws a series per tag"
|
|
311
|
+
)
|
|
312
|
+
chosen = Declared(None, kind or "scatter", x, y, group, None, title, x_label,
|
|
313
|
+
y_label, style, axes)
|
|
314
|
+
else:
|
|
315
|
+
if x is not None or y is not None:
|
|
316
|
+
raise TypeError(
|
|
317
|
+
"a named figure draws its own axes: pass the name, or x= and y=, not both"
|
|
318
|
+
)
|
|
319
|
+
chosen = _find(samples, figure)
|
|
320
|
+
if isinstance(chosen, Declared):
|
|
321
|
+
chosen = chosen.overridden(title, x_label, y_label, style, group, kind, axes)
|
|
322
|
+
else:
|
|
323
|
+
refused = [name for name, given in (
|
|
324
|
+
("x_label", x_label), ("y_label", y_label), ("style", style),
|
|
325
|
+
("group", group), ("kind", kind), *axes.items())
|
|
326
|
+
if given is not None and name != "figsize"]
|
|
327
|
+
if refused:
|
|
328
|
+
raise TypeError(
|
|
329
|
+
f"'{figure}' is the model's, and draws its own axes: "
|
|
330
|
+
f"{', '.join(refused)} {'changes' if len(refused) == 1 else 'change'} "
|
|
331
|
+
"a declared figure, or axes given with x= and y="
|
|
332
|
+
)
|
|
333
|
+
if isinstance(chosen, Declared) and chosen.style is None:
|
|
334
|
+
chosen.style = _default_style(samples)
|
|
335
|
+
|
|
336
|
+
per_sample = output is not None and "{name}" in str(output)
|
|
337
|
+
if output is not None:
|
|
338
|
+
output = pathlib.Path(output)
|
|
339
|
+
refusal = output_refusal(output)
|
|
340
|
+
if refusal:
|
|
341
|
+
raise ValueError(f"{output}: {refusal}")
|
|
342
|
+
if per_sample and (isinstance(chosen, Declared) or chosen.collection):
|
|
343
|
+
raise ValueError(
|
|
344
|
+
f"{output}: {{name}} writes a file per sample, and this figure draws "
|
|
345
|
+
"every sample in one: name one file"
|
|
346
|
+
)
|
|
347
|
+
if not per_sample and output.exists() and not overwrite:
|
|
348
|
+
raise FileExistsError(
|
|
349
|
+
f"{output} already exists, and nothing was written: overwrite=True replaces it"
|
|
350
|
+
)
|
|
351
|
+
else:
|
|
352
|
+
refusal = window_refusal()
|
|
353
|
+
if refusal:
|
|
354
|
+
raise RuntimeError(refusal)
|
|
355
|
+
|
|
356
|
+
import matplotlib
|
|
357
|
+
|
|
358
|
+
_said_across(samples)
|
|
359
|
+
sheets, fonts, settings = _project_look(samples) if project_style else ([], [], {})
|
|
360
|
+
own = {}
|
|
361
|
+
if project_style and chosen.matplotlib:
|
|
362
|
+
own, problems = matplotlib_settings(chosen.matplotlib,
|
|
363
|
+
f"'{chosen.name or 'figure'}' matplotlib")
|
|
364
|
+
if problems:
|
|
365
|
+
raise ValueError(problems[0])
|
|
366
|
+
import matplotlib.style
|
|
367
|
+
|
|
368
|
+
_learn_fonts(fonts)
|
|
369
|
+
global _DECLARED
|
|
370
|
+
declared, _DECLARED = _DECLARED, _declared_keys(sheets, settings, own)
|
|
371
|
+
try:
|
|
372
|
+
with matplotlib.style.context(sheets), matplotlib.rc_context({**settings, **own}):
|
|
373
|
+
return _draw(samples, chosen, output, title, overwrite, figsize)
|
|
374
|
+
finally:
|
|
375
|
+
_DECLARED = declared
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
def _default_style(samples):
|
|
379
|
+
"""``[render] figure_style``, the style a figure names none reads in."""
|
|
380
|
+
project = _project_of(samples)
|
|
381
|
+
if project is None:
|
|
382
|
+
return None
|
|
383
|
+
return project.render.figure_style
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def output_refusal(output):
|
|
387
|
+
"""Why matplotlib would not write the figure at ``output`` as named, or
|
|
388
|
+
``None``: a path without an extension it would give one of its own, and
|
|
389
|
+
one it does not write it cannot."""
|
|
390
|
+
suffix = output.suffix.lower().lstrip(".")
|
|
391
|
+
if not suffix:
|
|
392
|
+
return (
|
|
393
|
+
"a figure's file says its format by its extension — .pdf, .svg, .png — "
|
|
394
|
+
"and this one has none"
|
|
395
|
+
)
|
|
396
|
+
if suffix not in FORMATS:
|
|
397
|
+
return f"matplotlib writes no '.{suffix}': {', '.join('.' + name for name in FORMATS)}"
|
|
398
|
+
return None
|
|
399
|
+
|
|
400
|
+
|
|
401
|
+
# The formats a figure is written in, the command line's list: a script and
|
|
402
|
+
# `samplekit plot` accept the same files, whatever else the installed
|
|
403
|
+
# matplotlib could write.
|
|
404
|
+
FORMATS = ("eps", "jpeg", "jpg", "pdf", "pgf", "png", "ps", "raw", "rgba", "svg", "svgz",
|
|
405
|
+
"tif", "tiff", "webp")
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
class FigureRaised(Exception):
|
|
409
|
+
"""Marks an exception as the model's figure's own: raised by its code,
|
|
410
|
+
not by SampleKit deciding what to draw."""
|
|
411
|
+
|
|
412
|
+
|
|
413
|
+
def _called(method, *arguments):
|
|
414
|
+
"""Calls a model's figure method, marking what it raises as its own, and
|
|
415
|
+
refusing a figure it drew into with ``plt.*`` instead of the axes it was
|
|
416
|
+
given — a figure SampleKit never writes."""
|
|
417
|
+
pyplot = sys.modules.get("matplotlib.pyplot")
|
|
418
|
+
before = set(pyplot.get_fignums()) if pyplot else set()
|
|
419
|
+
try:
|
|
420
|
+
method(*arguments)
|
|
421
|
+
except Exception as error:
|
|
422
|
+
error._samplekit_figure = True
|
|
423
|
+
raise
|
|
424
|
+
pyplot = sys.modules.get("matplotlib.pyplot")
|
|
425
|
+
stray = set(pyplot.get_fignums()) - before if pyplot else set()
|
|
426
|
+
if stray:
|
|
427
|
+
for number in stray:
|
|
428
|
+
pyplot.close(number)
|
|
429
|
+
error = RuntimeError(
|
|
430
|
+
f"{getattr(method, '__qualname__', method)} drew into a figure of pyplot's "
|
|
431
|
+
"own (plt.plot, plt.xlabel…), not into the axes it was given: draw on "
|
|
432
|
+
"them — ax.plot, ax.set_xlabel"
|
|
433
|
+
)
|
|
434
|
+
error._samplekit_figure = True
|
|
435
|
+
raise error
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
def raised_by_the_figure(error):
|
|
439
|
+
"""Whether ``error`` came out of the model's figure code."""
|
|
440
|
+
return getattr(error, "_samplekit_figure", False)
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
def _in_the_data(error):
|
|
444
|
+
"""Marks a refusal as the samples': their values or their models disagree,
|
|
445
|
+
and the request itself was sound. The command line exits 2 for it, as the
|
|
446
|
+
table does for a column of two units, and 1 for a name or an option."""
|
|
447
|
+
error._samplekit_data = True
|
|
448
|
+
return error
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
def raised_by_the_data(error):
|
|
452
|
+
"""Whether ``error`` says something of the samples rather than of what was
|
|
453
|
+
asked: marked so here, or raised by matplotlib itself over the values it
|
|
454
|
+
was given to draw."""
|
|
455
|
+
if getattr(error, "_samplekit_data", False):
|
|
456
|
+
return True
|
|
457
|
+
trace = error.__traceback__
|
|
458
|
+
while trace is not None and trace.tb_next is not None:
|
|
459
|
+
trace = trace.tb_next
|
|
460
|
+
if trace is None:
|
|
461
|
+
return False
|
|
462
|
+
parts = pathlib.Path(trace.tb_frame.f_code.co_filename).parts
|
|
463
|
+
return "matplotlib" in parts or "numpy" in parts
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
# What the history says wrote a figure's file: the command line when `samplekit
|
|
467
|
+
# plot` draws it, else Python, naming the figure.
|
|
468
|
+
SAID = None
|
|
469
|
+
# Whether `samplekit plot` is drawing: a refusal then names the command's
|
|
470
|
+
# options, `-o`, and a script's otherwise, `output=`.
|
|
471
|
+
COMMAND_LINE = False
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
# Asked from the workbench, where `w` writes a figure to a file.
|
|
475
|
+
WORKBENCH = False
|
|
476
|
+
# Whether the figure drawn read values not current: the command exits 2 for
|
|
477
|
+
# it, as an export does, unless it accepts them.
|
|
478
|
+
STALE_SAID = False
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
def _option(command_line, python):
|
|
482
|
+
"""An option as the one reading the message writes it."""
|
|
483
|
+
if WORKBENCH and command_line.startswith("-o "):
|
|
484
|
+
return "the workbench asks its file next"
|
|
485
|
+
return command_line if COMMAND_LINE else python
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
# The snapshot a figure carries where the command line names it, drawing from
|
|
489
|
+
# the project as it was, with no history written here.
|
|
490
|
+
CARRY = None
|
|
491
|
+
|
|
492
|
+
# What a figure carries in its metadata before its snapshot's id, which
|
|
493
|
+
# version_control reads back.
|
|
494
|
+
CARRIED = "samplekit snapshot "
|
|
495
|
+
|
|
496
|
+
|
|
497
|
+
# The date of writing a format records unless told not to: without it, a
|
|
498
|
+
# figure drawn again from the same data is the same file, as a PNG already is.
|
|
499
|
+
UNDATED = {".pdf": {"CreationDate": None}, ".svg": {"Date": None}}
|
|
500
|
+
|
|
501
|
+
|
|
502
|
+
def _carrying(path, snapshot):
|
|
503
|
+
"""The ``savefig`` keywords that write ``snapshot`` into the file's
|
|
504
|
+
metadata, where its format has a place for it, and leave out the date
|
|
505
|
+
of writing."""
|
|
506
|
+
suffix = pathlib.Path(str(path)).suffix.lower()
|
|
507
|
+
metadata = dict(UNDATED.get(suffix, {}))
|
|
508
|
+
key = {".pdf": "Subject", ".png": "Description", ".svg": "Description"}.get(suffix)
|
|
509
|
+
if snapshot is not None and key:
|
|
510
|
+
metadata[key] = CARRIED + snapshot
|
|
511
|
+
return {"metadata": metadata} if metadata else {}
|
|
512
|
+
|
|
513
|
+
|
|
514
|
+
def _save(figure_, path, carried):
|
|
515
|
+
"""Writes ``figure_`` to ``path``. An SVG's ids are salted at random
|
|
516
|
+
unless a salt is set, so one is, where the project's style set none."""
|
|
517
|
+
import matplotlib
|
|
518
|
+
|
|
519
|
+
salted = {}
|
|
520
|
+
if pathlib.Path(str(path)).suffix.lower() == ".svg" and matplotlib.rcParams["svg.hashsalt"] is None:
|
|
521
|
+
salted = {"svg.hashsalt": "samplekit"}
|
|
522
|
+
with matplotlib.rc_context(salted):
|
|
523
|
+
figure_.savefig(path, **_carrying(path, carried))
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
def _kept(samples, chosen, files, per_sample, drawn):
|
|
527
|
+
"""Writes each figure, tied in the history to the snapshot it was made
|
|
528
|
+
from: a snapshot of each project its samples belong to first, then
|
|
529
|
+
a tag naming the file's hash. A history not kept is a warning."""
|
|
530
|
+
from samplekit import _native
|
|
531
|
+
|
|
532
|
+
paths = [str(sample.path) for sample in samples if getattr(sample, "path", None)]
|
|
533
|
+
# A script writing a figure is a snapshot of its own where it has none
|
|
534
|
+
# yet; the command line's drawing leaves the history to its command.
|
|
535
|
+
written = None if COMMAND_LINE else [str(path) for path in files]
|
|
536
|
+
kept = _native._history_before_output(paths, written) if paths else []
|
|
537
|
+
# What ran, as the script's own snapshot names it, and what was drawn:
|
|
538
|
+
# the figure's name, or its axes as `samplekit plot` says them.
|
|
539
|
+
name = getattr(chosen, "name", None)
|
|
540
|
+
drawn_as = name or f"{chosen.y} against {chosen.x}"
|
|
541
|
+
said = SAID or f"{_native._script_said()} · plot {drawn_as}"
|
|
542
|
+
carried = CARRY or (kept[0][1] if kept else None)
|
|
543
|
+
for at, (figure_, path) in enumerate(zip(drawn, files)):
|
|
544
|
+
# An output's folder is made, as every destination's is.
|
|
545
|
+
pathlib.Path(path).parent.mkdir(parents=True, exist_ok=True)
|
|
546
|
+
_save(figure_, path, carried)
|
|
547
|
+
# A figure of one sample, per file, is made from that sample alone.
|
|
548
|
+
made_from = [paths[at]] if per_sample and at < len(paths) else paths
|
|
549
|
+
for root, snapshot in kept:
|
|
550
|
+
_native._history_tag_output(root, snapshot, str(path), said, made_from)
|
|
551
|
+
|
|
552
|
+
|
|
553
|
+
def _draw(samples, chosen, output, title, overwrite=False, figsize=None):
|
|
554
|
+
drawn = []
|
|
555
|
+
files = []
|
|
556
|
+
try:
|
|
557
|
+
if isinstance(chosen, Declared):
|
|
558
|
+
figure_, axes = _new(output, None, drawn, chosen.axes.get("figsize"))
|
|
559
|
+
_draw_declared(samples, chosen, axes)
|
|
560
|
+
files.append(output)
|
|
561
|
+
elif chosen.collection:
|
|
562
|
+
model = _model_of(samples, chosen)
|
|
563
|
+
figure_, axes = _new(output, chosen.subplots, drawn, figsize or chosen.figsize)
|
|
564
|
+
_called(chosen.method.__get__(None, model), samples, axes)
|
|
565
|
+
if title:
|
|
566
|
+
figure_.suptitle(title)
|
|
567
|
+
files.append(output)
|
|
568
|
+
else:
|
|
569
|
+
methods = [_method_of(sample, chosen) for sample in samples]
|
|
570
|
+
per_sample = output is not None and "{name}" in str(output)
|
|
571
|
+
if output is not None and len(samples) != 1 and not per_sample:
|
|
572
|
+
raise ValueError(
|
|
573
|
+
f"'{chosen.name}' draws one sample, and a file holds one figure: "
|
|
574
|
+
f"name one sample of the {len(samples)}, or write a file per sample "
|
|
575
|
+
"with {name} in the file's name"
|
|
576
|
+
)
|
|
577
|
+
for sample, method in zip(samples, methods):
|
|
578
|
+
figure_, axes = _new(output, method.subplots, drawn,
|
|
579
|
+
figsize or method.figsize)
|
|
580
|
+
_called(method.method.__get__(sample, type(sample)), axes)
|
|
581
|
+
# Its sample named, so that files written one per sample are
|
|
582
|
+
# told apart once printed.
|
|
583
|
+
if title or len(samples) > 1:
|
|
584
|
+
figure_.suptitle(title or sample.name or "")
|
|
585
|
+
files.append(_file_of(output, sample) if per_sample else output)
|
|
586
|
+
if per_sample:
|
|
587
|
+
_check_the_files(files, overwrite)
|
|
588
|
+
# A sample the method drew nothing of — a table without a row —
|
|
589
|
+
# is said, as a declared figure's samples not drawn are: its file
|
|
590
|
+
# was written blank without a word.
|
|
591
|
+
blank = [sample.name or str(sample.path)
|
|
592
|
+
for sample, figure_ in zip(samples, drawn)
|
|
593
|
+
if not _drew_anything(figure_)]
|
|
594
|
+
if blank:
|
|
595
|
+
warnings.warn(
|
|
596
|
+
f"{len(blank)} of {len(samples)} figures drew nothing, and "
|
|
597
|
+
f"{'is' if len(blank) == 1 else 'are'} written blank: {', '.join(blank)}",
|
|
598
|
+
stacklevel=2,
|
|
599
|
+
)
|
|
600
|
+
|
|
601
|
+
if output is not None:
|
|
602
|
+
per_sample = "{name}" in str(output) and len(files) == len(samples) > 1
|
|
603
|
+
_kept(samples, chosen, files, per_sample, drawn)
|
|
604
|
+
else:
|
|
605
|
+
import matplotlib.pyplot as plt
|
|
606
|
+
|
|
607
|
+
plt.show()
|
|
608
|
+
except BaseException:
|
|
609
|
+
# A figure half drawn is closed, so that pyplot does not show it at
|
|
610
|
+
# the script's next plt.show().
|
|
611
|
+
pyplot = sys.modules.get("matplotlib.pyplot")
|
|
612
|
+
if pyplot is not None:
|
|
613
|
+
for figure_ in drawn:
|
|
614
|
+
pyplot.close(figure_)
|
|
615
|
+
raise
|
|
616
|
+
return drawn
|
|
617
|
+
|
|
618
|
+
|
|
619
|
+
def _drew_anything(figure_):
|
|
620
|
+
"""Whether a figure holds a point, a bar or an image: an empty
|
|
621
|
+
`ax.plot([], [])` is a line holding nothing, which `Axes.has_data`
|
|
622
|
+
counts."""
|
|
623
|
+
for ax in figure_.axes:
|
|
624
|
+
if any(len(line.get_xdata()) for line in ax.lines):
|
|
625
|
+
return True
|
|
626
|
+
if any(len(collection.get_offsets()) for collection in ax.collections):
|
|
627
|
+
return True
|
|
628
|
+
if ax.patches or ax.images:
|
|
629
|
+
return True
|
|
630
|
+
return False
|
|
631
|
+
|
|
632
|
+
|
|
633
|
+
def _file_of(output, sample):
|
|
634
|
+
"""``output`` with ``{name}`` replaced by the sample's name, or its file's."""
|
|
635
|
+
name = sample.name or (pathlib.Path(sample.path).stem if sample.path else None)
|
|
636
|
+
if not name:
|
|
637
|
+
raise ValueError(
|
|
638
|
+
f"{output}: {{name}} names a file per sample, and a sample here has neither "
|
|
639
|
+
"a name nor a file"
|
|
640
|
+
)
|
|
641
|
+
return pathlib.Path(str(output).replace("{name}", name))
|
|
642
|
+
|
|
643
|
+
|
|
644
|
+
def _check_the_files(files, overwrite):
|
|
645
|
+
"""A file per sample: two samples of one name would write one file, and an
|
|
646
|
+
existing one is replaced only when asked."""
|
|
647
|
+
seen = set()
|
|
648
|
+
for path in files:
|
|
649
|
+
if path in seen:
|
|
650
|
+
raise ValueError(f"{path}: two samples would write this one file")
|
|
651
|
+
seen.add(path)
|
|
652
|
+
if path.exists() and not overwrite:
|
|
653
|
+
raise FileExistsError(
|
|
654
|
+
f"{path} already exists, and nothing was written: overwrite=True replaces it"
|
|
655
|
+
)
|
|
656
|
+
|
|
657
|
+
|
|
658
|
+
# ----------------------------------------------------------------- choosing
|
|
659
|
+
|
|
660
|
+
|
|
661
|
+
def _project_look(samples):
|
|
662
|
+
"""``[matplotlib]``: its style sheets, its fonts, and its settings checked
|
|
663
|
+
by matplotlib's own validators — a name it does not have or a value it
|
|
664
|
+
refuses is refused here, naming it, where matplotlib alone warns and
|
|
665
|
+
carries on."""
|
|
666
|
+
if not len(samples):
|
|
667
|
+
return [], [], {}
|
|
668
|
+
project = _project_of(samples)
|
|
669
|
+
if project is None:
|
|
670
|
+
return [], [], {}
|
|
671
|
+
written = project.matplotlib
|
|
672
|
+
settings, problems = matplotlib_settings(written)
|
|
673
|
+
if problems:
|
|
674
|
+
raise ValueError(problems[0])
|
|
675
|
+
return list(written.get("style", [])), _font_files(written.get("fonts", [])), settings
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
# The settings the project declares for the figure being drawn, its style
|
|
679
|
+
# sheets' included: where one is declared, SampleKit's own choice gives way.
|
|
680
|
+
_DECLARED = set()
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
def _declared_keys(sheets, settings, own):
|
|
684
|
+
"""The settings a figure's project, its style sheets and the figure itself
|
|
685
|
+
declare, by matplotlib's names."""
|
|
686
|
+
import matplotlib
|
|
687
|
+
import matplotlib.style
|
|
688
|
+
|
|
689
|
+
keys = set(settings) | set(own)
|
|
690
|
+
for sheet in sheets:
|
|
691
|
+
if sheet.lower().endswith(".mplstyle"):
|
|
692
|
+
keys |= set(matplotlib.rc_params_from_file(sheet, use_default_template=False))
|
|
693
|
+
else:
|
|
694
|
+
keys |= set(matplotlib.style.library.get(sheet, {}))
|
|
695
|
+
return keys
|
|
696
|
+
|
|
697
|
+
|
|
698
|
+
def _declares(name):
|
|
699
|
+
"""Whether the project declares ``name``: a marker counts where its
|
|
700
|
+
property cycle carries one."""
|
|
701
|
+
import matplotlib
|
|
702
|
+
|
|
703
|
+
if name in _DECLARED:
|
|
704
|
+
return True
|
|
705
|
+
if name == "lines.marker" and "axes.prop_cycle" in _DECLARED:
|
|
706
|
+
return "marker" in matplotlib.rcParams["axes.prop_cycle"].keys
|
|
707
|
+
return False
|
|
708
|
+
|
|
709
|
+
|
|
710
|
+
def _font_files(patterns):
|
|
711
|
+
"""The font files ``fonts`` names, its patterns found."""
|
|
712
|
+
import glob
|
|
713
|
+
|
|
714
|
+
files = []
|
|
715
|
+
for pattern in patterns:
|
|
716
|
+
files.extend(sorted(glob.glob(pattern)))
|
|
717
|
+
return files
|
|
718
|
+
|
|
719
|
+
|
|
720
|
+
def _learn_fonts(files):
|
|
721
|
+
"""The project's fonts, made known to matplotlib before it draws."""
|
|
722
|
+
if not files:
|
|
723
|
+
return
|
|
724
|
+
from matplotlib import font_manager
|
|
725
|
+
|
|
726
|
+
for file in files:
|
|
727
|
+
font_manager.fontManager.addfont(file)
|
|
728
|
+
|
|
729
|
+
|
|
730
|
+
def matplotlib_problems(written):
|
|
731
|
+
"""What matplotlib refuses of `[matplotlib]`, each said as `plot` says it:
|
|
732
|
+
`validate`'s, which starts this Python only where the section is."""
|
|
733
|
+
return matplotlib_settings(written)[1]
|
|
734
|
+
|
|
735
|
+
|
|
736
|
+
def matplotlib_settings(written, within="[matplotlib]"):
|
|
737
|
+
"""`[matplotlib]` as matplotlib's own validators take it, and what they
|
|
738
|
+
refuse; its style sheets and fonts checked, and left out."""
|
|
739
|
+
import difflib
|
|
740
|
+
import glob
|
|
741
|
+
|
|
742
|
+
import matplotlib
|
|
743
|
+
import matplotlib.style
|
|
744
|
+
|
|
745
|
+
settings = {}
|
|
746
|
+
problems = []
|
|
747
|
+
for sheet in written.get("style", []):
|
|
748
|
+
if sheet.lower().endswith(".mplstyle"):
|
|
749
|
+
if not os.path.isfile(sheet):
|
|
750
|
+
problems.append(f"{within} style: {sheet} is not there")
|
|
751
|
+
elif sheet not in matplotlib.style.available:
|
|
752
|
+
near = difflib.get_close_matches(sheet, matplotlib.style.available, n=1)
|
|
753
|
+
problems.append(
|
|
754
|
+
f"{within} style: matplotlib has no style sheet '{sheet}'"
|
|
755
|
+
+ (f"\n did you mean: {near[0]}?" if near else "")
|
|
756
|
+
)
|
|
757
|
+
for pattern in written.get("fonts", []):
|
|
758
|
+
if not glob.glob(pattern):
|
|
759
|
+
problems.append(f"{within} fonts: {pattern} finds no file")
|
|
760
|
+
for name, value in written.items():
|
|
761
|
+
if name in ("style", "fonts"):
|
|
762
|
+
continue
|
|
763
|
+
if name in ("backend", "interactive"):
|
|
764
|
+
problems.append(
|
|
765
|
+
f"{within} {name} is not a figure's: SampleKit chooses between a "
|
|
766
|
+
"window and a file, and MPLBACKEND chooses the window's backend"
|
|
767
|
+
)
|
|
768
|
+
continue
|
|
769
|
+
if name not in matplotlib.rcParams:
|
|
770
|
+
near = difflib.get_close_matches(name, list(matplotlib.rcParams), n=1)
|
|
771
|
+
problems.append(
|
|
772
|
+
f"{within} {name} is not a matplotlib setting"
|
|
773
|
+
+ (f"\n did you mean: {near[0]}?" if near else "")
|
|
774
|
+
)
|
|
775
|
+
continue
|
|
776
|
+
written_value = value
|
|
777
|
+
# In centimetres, as every size SampleKit takes. Written as text too,
|
|
778
|
+
# "15, 10", which matplotlib reads alike.
|
|
779
|
+
if name == "figure.figsize" and isinstance(value, str):
|
|
780
|
+
try:
|
|
781
|
+
value = [float(side) for side in value.split(",")]
|
|
782
|
+
except ValueError:
|
|
783
|
+
pass
|
|
784
|
+
if name == "figure.figsize" and isinstance(value, (list, tuple)):
|
|
785
|
+
value = [side / CM_PER_INCH if isinstance(side, (int, float)) else side
|
|
786
|
+
for side in value]
|
|
787
|
+
try:
|
|
788
|
+
settings[name] = matplotlib.rcParams.validate[name](value)
|
|
789
|
+
except (ValueError, TypeError) as error:
|
|
790
|
+
# Said as written: the centimetres, not the inches they became.
|
|
791
|
+
said = str(error).replace(repr(value), repr(written_value))
|
|
792
|
+
problems.append(f"{within} {name} = {written_value!r}: {said}")
|
|
793
|
+
return settings, problems
|
|
794
|
+
|
|
795
|
+
|
|
796
|
+
def _as_list(target):
|
|
797
|
+
import samplekit
|
|
798
|
+
|
|
799
|
+
if isinstance(target, samplekit.SampleList):
|
|
800
|
+
return target
|
|
801
|
+
if isinstance(target, samplekit.Sample):
|
|
802
|
+
return samplekit.SampleList([target])
|
|
803
|
+
return samplekit.SampleList(list(target))
|
|
804
|
+
|
|
805
|
+
|
|
806
|
+
def _find(samples, name):
|
|
807
|
+
"""The model's figure of that name, or the project's; both is ambiguous,
|
|
808
|
+
and neither names what exists."""
|
|
809
|
+
ours = {}
|
|
810
|
+
for cls in {type(sample) for sample in samples}:
|
|
811
|
+
ours.update(figures_of(cls))
|
|
812
|
+
declared = {}
|
|
813
|
+
across = None
|
|
814
|
+
try:
|
|
815
|
+
figures = samples.project.figures
|
|
816
|
+
declared = {name: figures[name] for name in figures}
|
|
817
|
+
except ValueError:
|
|
818
|
+
# Several projects: a name each declares alike is one figure; declared
|
|
819
|
+
# differently, or by some only, it is refused naming them.
|
|
820
|
+
projects = [project for project in _projects_of(samples) if project is not None]
|
|
821
|
+
held = [(project, project.figures[name] if name in project.figures else None)
|
|
822
|
+
for project in projects]
|
|
823
|
+
shapes = {repr(_figure_shape(figure)) for _, figure in held if figure is not None}
|
|
824
|
+
if all(figure is not None for _, figure in held) and len(shapes) == 1:
|
|
825
|
+
declared = {name: held[0][1]}
|
|
826
|
+
elif any(figure is not None for _, figure in held):
|
|
827
|
+
across = "; ".join(
|
|
828
|
+
f"{project.root} {'declares it differently' if figure else 'does not declare it'}"
|
|
829
|
+
for project, figure in held[1:]
|
|
830
|
+
if figure is None or repr(_figure_shape(figure)) != repr(_figure_shape(held[0][1]))
|
|
831
|
+
)
|
|
832
|
+
across = f"'{name}' is declared differently across these projects: {across}"
|
|
833
|
+
if name in ours and name in declared:
|
|
834
|
+
raise ValueError(
|
|
835
|
+
f"'{name}' is both a figure of the model and one .samplekitrc declares: "
|
|
836
|
+
"rename one of them"
|
|
837
|
+
)
|
|
838
|
+
if name in ours:
|
|
839
|
+
return ours[name]
|
|
840
|
+
if name in declared:
|
|
841
|
+
held = declared[name]
|
|
842
|
+
return Declared(name, held.kind, held.x, held.y, held.group, held.query,
|
|
843
|
+
held.title, held.x_label, held.y_label, held.style,
|
|
844
|
+
{key: getattr(held, key) for key in AXIS_KEYS},
|
|
845
|
+
getattr(held, "matplotlib", None))
|
|
846
|
+
if across is not None:
|
|
847
|
+
raise _in_the_data(ValueError(
|
|
848
|
+
f"{across}\n declare it alike in each, or draw each project's samples on "
|
|
849
|
+
"their own"
|
|
850
|
+
))
|
|
851
|
+
import difflib
|
|
852
|
+
|
|
853
|
+
# In the order they are declared, the project's then the model's, as the
|
|
854
|
+
# command line lists them.
|
|
855
|
+
known = list(declared) + [figure for figure in ours if figure not in declared]
|
|
856
|
+
near = difflib.get_close_matches(name, known, n=1)
|
|
857
|
+
raise LookupFailed(
|
|
858
|
+
f"no figure named '{name}'"
|
|
859
|
+
+ (f"\n did you mean: {near[0]}?" if near else "")
|
|
860
|
+
+ (f"\n the figures: {', '.join(known)}" if known else ": none is declared")
|
|
861
|
+
)
|
|
862
|
+
|
|
863
|
+
|
|
864
|
+
def _method_of(sample, chosen):
|
|
865
|
+
"""The figure ``chosen`` names, as the sample's own model defines it — a
|
|
866
|
+
subclass's over its base's — refused for a sample whose model has none."""
|
|
867
|
+
found = figures_of(type(sample)).get(chosen.name)
|
|
868
|
+
if found is None:
|
|
869
|
+
raise ValueError(
|
|
870
|
+
f"{sample.name or sample.path}: its model declares no figure '{chosen.name}'"
|
|
871
|
+
)
|
|
872
|
+
return found
|
|
873
|
+
|
|
874
|
+
|
|
875
|
+
def _model_of(samples, chosen):
|
|
876
|
+
"""The class a collection figure is called on: the most derived one every
|
|
877
|
+
sample is an instance of, which must draw the figure as each sample's own
|
|
878
|
+
model does."""
|
|
879
|
+
methods = {id(_method_of(sample, chosen)) for sample in samples}
|
|
880
|
+
if len(methods) > 1:
|
|
881
|
+
raise _in_the_data(ValueError(
|
|
882
|
+
f"these samples' models draw '{chosen.name}' differently: select the "
|
|
883
|
+
"samples of one model"
|
|
884
|
+
))
|
|
885
|
+
first = type(samples[0])
|
|
886
|
+
for cls in first.__mro__:
|
|
887
|
+
if all(isinstance(sample, cls) for sample in samples):
|
|
888
|
+
return cls
|
|
889
|
+
return first
|
|
890
|
+
|
|
891
|
+
|
|
892
|
+
# ----------------------------------------------------------------- the window
|
|
893
|
+
|
|
894
|
+
|
|
895
|
+
def window_refusal():
|
|
896
|
+
"""Why a window cannot be seen here, or ``None``: over SSH without a
|
|
897
|
+
display, or where matplotlib has no interactive backend."""
|
|
898
|
+
over_ssh = os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY")
|
|
899
|
+
display = (
|
|
900
|
+
os.environ.get("DISPLAY")
|
|
901
|
+
or os.environ.get("WAYLAND_DISPLAY")
|
|
902
|
+
or sys.platform in ("darwin", "win32")
|
|
903
|
+
)
|
|
904
|
+
if over_ssh and not display:
|
|
905
|
+
return (
|
|
906
|
+
"a figure opens in a window, and this SSH session has no display to open "
|
|
907
|
+
f"it on: write it to a file instead ({_option('-o figure.pdf', 'output=')})"
|
|
908
|
+
)
|
|
909
|
+
import matplotlib
|
|
910
|
+
import matplotlib.pyplot # noqa: F401 — resolves the automatic backend
|
|
911
|
+
|
|
912
|
+
backend = matplotlib.get_backend().lower()
|
|
913
|
+
if backend.startswith("module://") or "inline" in backend:
|
|
914
|
+
return None
|
|
915
|
+
try:
|
|
916
|
+
from matplotlib.backends.registry import BackendFilter, backend_registry
|
|
917
|
+
|
|
918
|
+
interactive = {
|
|
919
|
+
name.lower() for name in backend_registry.list_builtin(BackendFilter.INTERACTIVE)
|
|
920
|
+
}
|
|
921
|
+
except ImportError: # matplotlib before 3.9
|
|
922
|
+
from matplotlib import rcsetup
|
|
923
|
+
|
|
924
|
+
interactive = {name.lower() for name in getattr(rcsetup, "interactive_bk", [])}
|
|
925
|
+
if backend not in interactive:
|
|
926
|
+
if os.environ.get("MPLBACKEND"):
|
|
927
|
+
return (
|
|
928
|
+
f"MPLBACKEND={os.environ['MPLBACKEND']} chooses a backend that opens no "
|
|
929
|
+
f"window: write the figure to a file ({_option('-o figure.pdf', 'output=')}), "
|
|
930
|
+
"or unset MPLBACKEND"
|
|
931
|
+
)
|
|
932
|
+
return (
|
|
933
|
+
f"matplotlib has no interactive backend here (it chose '{backend}'), so a "
|
|
934
|
+
"window would show nothing: install tkinter or PyQt, or write the figure "
|
|
935
|
+
f"to a file ({_option('-o figure.pdf', 'output=')})"
|
|
936
|
+
)
|
|
937
|
+
return None
|
|
938
|
+
|
|
939
|
+
|
|
940
|
+
def _new(output, subplots, drawn, figsize=None):
|
|
941
|
+
"""A figure and its axes, kept in ``drawn``: pyplot's for a window, a
|
|
942
|
+
figure of its own for a file, so that writing one never changes a script's
|
|
943
|
+
pyplot state. Laid out by matplotlib, so that a long tick label never
|
|
944
|
+
covers an axis's label; ``figsize`` in centimetres, converted here
|
|
945
|
+
for matplotlib, which takes inches; `[matplotlib]`'s otherwise."""
|
|
946
|
+
rows, columns = subplots or (1, 1)
|
|
947
|
+
if figsize is not None:
|
|
948
|
+
# Sizes are centimetres: one written in inches, or a slip, would draw a
|
|
949
|
+
# thumbnail or a picture of a billion pixels without a word.
|
|
950
|
+
if any(side < 2 or side > 150 for side in figsize):
|
|
951
|
+
# At the script's line, as every warning of the package is: a
|
|
952
|
+
# fixed level landed in the package when the call came through it.
|
|
953
|
+
_warn(f"a figure of {figsize[0]:g} by {figsize[1]:g} cm: sizes are in centimetres")
|
|
954
|
+
figsize = tuple(side / CM_PER_INCH for side in figsize)
|
|
955
|
+
if output is None:
|
|
956
|
+
import matplotlib.pyplot as plt
|
|
957
|
+
|
|
958
|
+
figure_, axes = plt.subplots(rows, columns, layout="constrained", figsize=figsize)
|
|
959
|
+
else:
|
|
960
|
+
from matplotlib.figure import Figure as MatplotlibFigure
|
|
961
|
+
|
|
962
|
+
figure_ = MatplotlibFigure(layout="constrained", figsize=figsize)
|
|
963
|
+
axes = figure_.subplots(rows, columns)
|
|
964
|
+
drawn.append(figure_)
|
|
965
|
+
return figure_, axes
|
|
966
|
+
|
|
967
|
+
|
|
968
|
+
# ----------------------------------------------------------------- declared
|
|
969
|
+
|
|
970
|
+
|
|
971
|
+
def _draw_declared(samples, declared, ax):
|
|
972
|
+
"""A declared figure, or axes given, drawn into ``ax``; what it left out,
|
|
973
|
+
and what it read not current, said once it is drawn, one summary each —
|
|
974
|
+
before, a refusal would have followed a warning about a figure never
|
|
975
|
+
drawn."""
|
|
976
|
+
global _HELD
|
|
977
|
+
held = _HELD = _NotCurrent()
|
|
978
|
+
try:
|
|
979
|
+
omitted = _drawn_declared(samples, declared, ax)
|
|
980
|
+
finally:
|
|
981
|
+
_HELD = None
|
|
982
|
+
omitted.say()
|
|
983
|
+
held.say(omitted)
|
|
984
|
+
|
|
985
|
+
|
|
986
|
+
def _drawn_declared(samples, declared, ax):
|
|
987
|
+
if declared.query:
|
|
988
|
+
given = len(samples)
|
|
989
|
+
samples = samples.query(declared.query)
|
|
990
|
+
if not len(samples):
|
|
991
|
+
raise ValueError(
|
|
992
|
+
f"the figure's query '{declared.query}' selects none of the {given} "
|
|
993
|
+
"samples: nothing to draw"
|
|
994
|
+
)
|
|
995
|
+
if declared.group:
|
|
996
|
+
_check_group(samples, declared.group)
|
|
997
|
+
x_table, y_table = _table_of(samples, declared.x), _table_of(samples, declared.y)
|
|
998
|
+
if (x_table is None) != (y_table is None):
|
|
999
|
+
column = declared.x if x_table is not None else declared.y
|
|
1000
|
+
raise ValueError(
|
|
1001
|
+
f"'{column}' is a table's column and the other axis one number per sample: "
|
|
1002
|
+
"draw two columns of one table, or two fields"
|
|
1003
|
+
)
|
|
1004
|
+
project = _project_of(samples)
|
|
1005
|
+
groups = _Groups(samples, declared, project)
|
|
1006
|
+
if x_table is not None:
|
|
1007
|
+
if declared.kind in ("bar", "box"):
|
|
1008
|
+
raise ValueError(
|
|
1009
|
+
f"a {declared.kind} is drawn over one number per sample, and "
|
|
1010
|
+
f"'{declared.x}' and '{declared.y}' are a table's columns: a curve per "
|
|
1011
|
+
"sample is a scatter, a line or a step"
|
|
1012
|
+
)
|
|
1013
|
+
x_read, y_read, omitted = _curves(samples, declared, ax, groups)
|
|
1014
|
+
elif declared.kind == "box":
|
|
1015
|
+
x_read, y_read, omitted = _boxes(samples, declared, ax)
|
|
1016
|
+
else:
|
|
1017
|
+
x_read, y_read, omitted = _points(samples, declared, ax, groups)
|
|
1018
|
+
x_text = (_axis(project, declared.x, x_read, declared.style, _row_of(samples, declared.x))
|
|
1019
|
+
if declared.x_label is None else declared.x_label)
|
|
1020
|
+
y_text = (_axis(project, declared.y, y_read, declared.style, _row_of(samples, declared.y))
|
|
1021
|
+
if declared.y_label is None else declared.y_label)
|
|
1022
|
+
# No title unless one is given: a figure in a report takes its caption
|
|
1023
|
+
# there, and a declaration's name is no sentence.
|
|
1024
|
+
title = declared.title
|
|
1025
|
+
_typeset(x_text, declared.style, "x label", declared.x_label is not None)
|
|
1026
|
+
_typeset(y_text, declared.style, "y label", declared.y_label is not None)
|
|
1027
|
+
_typeset(title, declared.style, "title", True)
|
|
1028
|
+
ax.set_xlabel(x_text)
|
|
1029
|
+
ax.set_ylabel(y_text)
|
|
1030
|
+
_set_axes(ax, declared.axes)
|
|
1031
|
+
if title:
|
|
1032
|
+
ax.set_title(title)
|
|
1033
|
+
groups.finish(ax)
|
|
1034
|
+
_place_legend(ax, declared.axes.get("legend"), groups.title)
|
|
1035
|
+
return omitted
|
|
1036
|
+
|
|
1037
|
+
|
|
1038
|
+
def _place_legend(ax, place, title):
|
|
1039
|
+
"""``best`` by default, beside the axes when more than six series would
|
|
1040
|
+
cover the data, where ``legend`` says otherwise, or none."""
|
|
1041
|
+
handles = ax.get_legend_handles_labels()[0]
|
|
1042
|
+
if not handles or place == "none":
|
|
1043
|
+
return
|
|
1044
|
+
if place is None:
|
|
1045
|
+
place = "outside" if len(handles) > 6 else "best"
|
|
1046
|
+
if place == "outside":
|
|
1047
|
+
small = {} if _declares("legend.fontsize") else {"fontsize": "small"}
|
|
1048
|
+
ax.legend(loc="upper left", bbox_to_anchor=(1.02, 1.0), title=title, **small)
|
|
1049
|
+
else:
|
|
1050
|
+
ax.legend(loc=place, title=title)
|
|
1051
|
+
|
|
1052
|
+
|
|
1053
|
+
class _Groups:
|
|
1054
|
+
"""What ``group`` makes of a figure: its values in the
|
|
1055
|
+
field's declared precision, a legend title in the figure's style, and a
|
|
1056
|
+
colour for each — a colour scale when a numeric group has more values than
|
|
1057
|
+
ten colours tell apart, refused for text. Over several fields, a group is
|
|
1058
|
+
a combination of their values, named field by field: a category, never a
|
|
1059
|
+
scale."""
|
|
1060
|
+
|
|
1061
|
+
def __init__(self, samples, declared, project):
|
|
1062
|
+
self.field = declared.group
|
|
1063
|
+
self.project = project
|
|
1064
|
+
self.style = declared.style
|
|
1065
|
+
self.title = None
|
|
1066
|
+
self.scale = None
|
|
1067
|
+
self.ordered = None
|
|
1068
|
+
self.colours = {}
|
|
1069
|
+
self.parts = None
|
|
1070
|
+
if not self.field:
|
|
1071
|
+
return
|
|
1072
|
+
fields = _fields_of(self.field)
|
|
1073
|
+
keys = {_group_of(sample, self.field) for sample in samples}
|
|
1074
|
+
self.title = ", ".join(self._title_of(samples, field) for field in fields)
|
|
1075
|
+
_typeset(self.title, self.style, "legend title", False)
|
|
1076
|
+
if len(fields) > 1:
|
|
1077
|
+
if len(keys) > MOST_GROUPS:
|
|
1078
|
+
raise _in_the_data(ValueError(
|
|
1079
|
+
f"'{', '.join(fields)}' make {len(keys)} groups together, and more than "
|
|
1080
|
+
f"{MOST_GROUPS} colours repeat: group by fewer fields, or narrow the "
|
|
1081
|
+
"selection"
|
|
1082
|
+
))
|
|
1083
|
+
self.parts = [
|
|
1084
|
+
self._texts(field, list({key[at] for key in keys if _is_number(key[at])}))
|
|
1085
|
+
for at, field in enumerate(fields)
|
|
1086
|
+
]
|
|
1087
|
+
self.texts = {}
|
|
1088
|
+
return
|
|
1089
|
+
values = [key for key in keys if _is_number(key)]
|
|
1090
|
+
# A sample holding no value, or one not applicable, is no value of the
|
|
1091
|
+
# field: a numeric group with them is still numeric, and they are
|
|
1092
|
+
# drawn grey, named in the legend.
|
|
1093
|
+
valued = len(keys - set(NO_VALUE))
|
|
1094
|
+
if len(keys) > MOST_GROUPS:
|
|
1095
|
+
if len(values) < valued or not values:
|
|
1096
|
+
raise _in_the_data(ValueError(
|
|
1097
|
+
f"'{self.field}' makes {len(keys)} groups, and more than "
|
|
1098
|
+
f"{MOST_GROUPS} colours repeat: group by a numeric field for a colour "
|
|
1099
|
+
"scale, or narrow the selection"
|
|
1100
|
+
))
|
|
1101
|
+
import matplotlib
|
|
1102
|
+
|
|
1103
|
+
self.scale = (matplotlib.colors.Normalize(min(values), max(values)),
|
|
1104
|
+
matplotlib.colormaps["viridis"])
|
|
1105
|
+
elif len(values) >= 2 and len(values) == valued:
|
|
1106
|
+
# Numbers keep their order in their colours, each still named in
|
|
1107
|
+
# the legend.
|
|
1108
|
+
import matplotlib
|
|
1109
|
+
|
|
1110
|
+
self.ordered = (matplotlib.colors.Normalize(min(values), max(values)),
|
|
1111
|
+
matplotlib.colormaps["viridis"])
|
|
1112
|
+
self.texts = self._texts(self.field, values) if self.scale is None else {}
|
|
1113
|
+
|
|
1114
|
+
def _title_of(self, samples, field):
|
|
1115
|
+
"""One field's part of the legend's title: its symbol and unit in the
|
|
1116
|
+
figure's style, as an axis is labelled."""
|
|
1117
|
+
if field == "tags":
|
|
1118
|
+
return field
|
|
1119
|
+
units = _Units(field, "group")
|
|
1120
|
+
for sample in samples:
|
|
1121
|
+
try:
|
|
1122
|
+
held = _read(sample, field)
|
|
1123
|
+
except KeyError:
|
|
1124
|
+
continue
|
|
1125
|
+
reading = _reading_of(sample, field) if not hasattr(held, "unit") else (
|
|
1126
|
+
held.unit, held.symbol)
|
|
1127
|
+
units.add(sample, reading)
|
|
1128
|
+
return _axis(self.project, field, units.reading, self.style, _row_of(samples, field))
|
|
1129
|
+
|
|
1130
|
+
def _texts(self, field, values):
|
|
1131
|
+
"""Each numeric value as the legend writes it: at the field's declared
|
|
1132
|
+
precision, unless two values would read alike there — 66 and 66 — and
|
|
1133
|
+
then with the fewest more digits that tell every one apart."""
|
|
1134
|
+
texts = {}
|
|
1135
|
+
for value in values:
|
|
1136
|
+
text = None
|
|
1137
|
+
if self.project is not None:
|
|
1138
|
+
try:
|
|
1139
|
+
text = self.project._value_text(field, value)
|
|
1140
|
+
except (TypeError, ValueError):
|
|
1141
|
+
pass
|
|
1142
|
+
texts[value] = text if text is not None else str(value)
|
|
1143
|
+
if len(set(texts.values())) == len(texts):
|
|
1144
|
+
return texts
|
|
1145
|
+
for digits in range(0, 16):
|
|
1146
|
+
spelled = {value: f"{value:.{digits}f}" for value in values}
|
|
1147
|
+
if len(set(spelled.values())) == len(spelled):
|
|
1148
|
+
return spelled
|
|
1149
|
+
return {value: repr(value) for value in values}
|
|
1150
|
+
|
|
1151
|
+
def label(self, key):
|
|
1152
|
+
"""A group's value as the legend writes it: none for a value a colour
|
|
1153
|
+
bar reads, and the samples without a value named; a combination, each
|
|
1154
|
+
field's value in turn."""
|
|
1155
|
+
if key is None:
|
|
1156
|
+
return None
|
|
1157
|
+
if isinstance(key, tuple):
|
|
1158
|
+
return ", ".join(
|
|
1159
|
+
part if part in NO_VALUE
|
|
1160
|
+
else texts.get(part, str(part)) if _is_number(part)
|
|
1161
|
+
else str(part)
|
|
1162
|
+
for part, texts in zip(key, self.parts)
|
|
1163
|
+
)
|
|
1164
|
+
if key in NO_VALUE:
|
|
1165
|
+
return key
|
|
1166
|
+
if self.scale is not None:
|
|
1167
|
+
return None
|
|
1168
|
+
if _is_number(key):
|
|
1169
|
+
return self.texts.get(key, str(key))
|
|
1170
|
+
return str(key)
|
|
1171
|
+
|
|
1172
|
+
def colour(self, key):
|
|
1173
|
+
if self.scale is not None and _is_number(key):
|
|
1174
|
+
norm, colours = self.scale
|
|
1175
|
+
return colours(norm(key))
|
|
1176
|
+
if self.ordered is not None and _is_number(key):
|
|
1177
|
+
norm, colours = self.ordered
|
|
1178
|
+
# Short of the scale's bronze end, which a white page loses.
|
|
1179
|
+
return colours(0.85 * norm(key))
|
|
1180
|
+
if self.scale is not None or self.ordered is not None:
|
|
1181
|
+
# No value, beside values a scale colours: a colour of the scale
|
|
1182
|
+
# would read as one of them.
|
|
1183
|
+
return "0.6"
|
|
1184
|
+
return None
|
|
1185
|
+
|
|
1186
|
+
def finish(self, ax):
|
|
1187
|
+
"""The colour bar a scale reads by, labelled as the group's axis."""
|
|
1188
|
+
if self.scale is None:
|
|
1189
|
+
return
|
|
1190
|
+
import matplotlib
|
|
1191
|
+
|
|
1192
|
+
norm, colours = self.scale
|
|
1193
|
+
bar = ax.figure.colorbar(matplotlib.cm.ScalarMappable(norm=norm, cmap=colours), ax=ax)
|
|
1194
|
+
bar.set_label(self.title)
|
|
1195
|
+
self.title = None
|
|
1196
|
+
|
|
1197
|
+
|
|
1198
|
+
def _is_number(value):
|
|
1199
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
1200
|
+
|
|
1201
|
+
|
|
1202
|
+
class _Omitted:
|
|
1203
|
+
"""What a figure leaves out, and why, said once it is drawn."""
|
|
1204
|
+
|
|
1205
|
+
def __init__(self, total):
|
|
1206
|
+
self.total = total
|
|
1207
|
+
self.reasons = {}
|
|
1208
|
+
# By the name a read's warning gives them.
|
|
1209
|
+
self.names = set()
|
|
1210
|
+
|
|
1211
|
+
def add(self, sample, reason):
|
|
1212
|
+
self.reasons.setdefault(reason, set()).add(id(sample))
|
|
1213
|
+
path = getattr(sample, "path", None)
|
|
1214
|
+
name = sample.name or (pathlib.Path(path).stem if path else None)
|
|
1215
|
+
if name:
|
|
1216
|
+
self.names.add(name)
|
|
1217
|
+
|
|
1218
|
+
def say(self):
|
|
1219
|
+
for reason, samples in self.reasons.items():
|
|
1220
|
+
_warn(f"{len(samples)} of {self.total} samples not drawn: {reason}")
|
|
1221
|
+
|
|
1222
|
+
|
|
1223
|
+
def _nothing_drawn(samples, omitted, held):
|
|
1224
|
+
"""The refusal of a figure none of whose samples could be drawn: a fact
|
|
1225
|
+
of the samples, not a misspelt name, which a field no sample knows is.
|
|
1226
|
+
``held`` is what a sample would have had to hold."""
|
|
1227
|
+
reasons = list(omitted.reasons)
|
|
1228
|
+
absent = all(reason.startswith("no ") for reason in reasons)
|
|
1229
|
+
if len(samples) == 1:
|
|
1230
|
+
said = ("the one sample selected holds " + " and ".join(reasons) if absent and reasons
|
|
1231
|
+
else "the one sample selected is not drawn: " + "; ".join(reasons))
|
|
1232
|
+
else:
|
|
1233
|
+
said = (f"none of the {len(samples)} samples holds {held}" if absent
|
|
1234
|
+
else f"none of the {len(samples)} samples can be drawn: " + "; ".join(reasons))
|
|
1235
|
+
return _in_the_data(ValueError(f"{said}: nothing to draw"))
|
|
1236
|
+
|
|
1237
|
+
|
|
1238
|
+
def _on_the_axis(value, scale):
|
|
1239
|
+
"""Whether a log axis can show ``value``."""
|
|
1240
|
+
return scale != "log" or value is None or not _is_number(value) or value > 0
|
|
1241
|
+
|
|
1242
|
+
|
|
1243
|
+
def _points(samples, declared, ax, groups):
|
|
1244
|
+
"""A point per sample, a series per value of ``group``."""
|
|
1245
|
+
series = {}
|
|
1246
|
+
units = (_Units(declared.x), _Units(declared.y))
|
|
1247
|
+
missing = []
|
|
1248
|
+
omitted = _Omitted(len(samples))
|
|
1249
|
+
for sample in samples:
|
|
1250
|
+
read_x = _scalar(sample, declared.x, missing, text=declared.kind == "bar")
|
|
1251
|
+
read_y = _scalar(sample, declared.y, missing, text=declared.kind == "bar")
|
|
1252
|
+
if read_x is None or read_y is None:
|
|
1253
|
+
absent = declared.x if read_x is None else declared.y
|
|
1254
|
+
omitted.add(sample, f"no {absent}")
|
|
1255
|
+
continue
|
|
1256
|
+
for axis, value in (("x", read_x[0]), ("y", read_y[0])):
|
|
1257
|
+
if not _on_the_axis(value, declared.axes.get(f"{axis}_scale")):
|
|
1258
|
+
omitted.add(sample, f"{getattr(declared, axis)} at or below zero on a log axis")
|
|
1259
|
+
break
|
|
1260
|
+
else:
|
|
1261
|
+
units[0].add(sample, read_x[2])
|
|
1262
|
+
units[1].add(sample, read_y[2])
|
|
1263
|
+
key = _group_of(sample, declared.group) if declared.group else None
|
|
1264
|
+
entry = series.setdefault(key, ([], [], [], [], []))
|
|
1265
|
+
entry[0].append(read_x[0])
|
|
1266
|
+
entry[1].append(read_y[0])
|
|
1267
|
+
entry[2].append(read_x[1])
|
|
1268
|
+
entry[3].append(read_y[1])
|
|
1269
|
+
entry[4].append(sample)
|
|
1270
|
+
if not series:
|
|
1271
|
+
# A field no sample knows is a misspelling, said with its suggestion;
|
|
1272
|
+
# one some samples lack is an ordinary gap.
|
|
1273
|
+
if missing and len(missing) >= len(samples):
|
|
1274
|
+
raise missing[0]
|
|
1275
|
+
raise _nothing_drawn(samples, omitted, f"both '{declared.x}' and '{declared.y}'")
|
|
1276
|
+
keys = sorted(series, key=_group_order)
|
|
1277
|
+
if declared.kind == "bar":
|
|
1278
|
+
_bars(ax, declared, [(key, series[key]) for key in keys], groups)
|
|
1279
|
+
else:
|
|
1280
|
+
for key in keys:
|
|
1281
|
+
xs, ys, x_errors, y_errors, _ = series[key]
|
|
1282
|
+
if declared.kind in ("line", "step"):
|
|
1283
|
+
order = sorted(range(len(xs)), key=lambda at: xs[at])
|
|
1284
|
+
xs, ys = [xs[at] for at in order], [ys[at] for at in order]
|
|
1285
|
+
x_errors = [x_errors[at] for at in order]
|
|
1286
|
+
y_errors = [y_errors[at] for at in order]
|
|
1287
|
+
_series(ax, declared.kind, xs, ys, x_errors, y_errors, groups.label(key),
|
|
1288
|
+
groups.colour(key))
|
|
1289
|
+
return units[0].reading, units[1].reading, omitted
|
|
1290
|
+
|
|
1291
|
+
|
|
1292
|
+
def _bars(ax, declared, series, groups):
|
|
1293
|
+
"""Bars at each x, a series' beside another's; two of one series at
|
|
1294
|
+
one x would hide one, and are refused. A text x is a category."""
|
|
1295
|
+
for key, (xs, _, _, _, samples) in series:
|
|
1296
|
+
seen = {}
|
|
1297
|
+
for x, sample in zip(xs, samples):
|
|
1298
|
+
if x in seen:
|
|
1299
|
+
raise _in_the_data(ValueError(
|
|
1300
|
+
f"{_named(seen[x])} and {_named(sample)} are two bars at "
|
|
1301
|
+
f"{declared.x} = {x}"
|
|
1302
|
+
+ (f" in the series {groups.label(key) or key}" if key is not None else "")
|
|
1303
|
+
+ ", and one would hide the other: group them apart, or draw their "
|
|
1304
|
+
f"spread with {_option('--kind box', 'kind=box')}"
|
|
1305
|
+
))
|
|
1306
|
+
seen[x] = sample
|
|
1307
|
+
every = [x for _, (xs, *_) in series for x in xs]
|
|
1308
|
+
categorical = any(isinstance(x, str) for x in every)
|
|
1309
|
+
across = [y for _, (_, ys, *_) in series for y in ys]
|
|
1310
|
+
# A text y and a numeric x: a bar per category along y, lying down.
|
|
1311
|
+
if any(isinstance(y, str) for y in across):
|
|
1312
|
+
if categorical:
|
|
1313
|
+
raise ValueError(
|
|
1314
|
+
f"a bar needs a number on one axis: '{declared.x}' and '{declared.y}' both "
|
|
1315
|
+
"hold text"
|
|
1316
|
+
)
|
|
1317
|
+
_lying_bars(ax, declared, series, groups)
|
|
1318
|
+
return
|
|
1319
|
+
# Beside one another, bars at a number left their x, and were read at a
|
|
1320
|
+
# value they did not have.
|
|
1321
|
+
if not categorical and len(series) > 1:
|
|
1322
|
+
raise ValueError(
|
|
1323
|
+
f"bars of {len(series)} groups on a numeric x would each stand off their "
|
|
1324
|
+
f"{declared.x} to be side by side: draw them with "
|
|
1325
|
+
f"{_option('--kind scatter', 'kind=scatter')} or "
|
|
1326
|
+
f"{_option('--kind line', 'kind=line')}, or put a text on x — a material, a grade — "
|
|
1327
|
+
"where side by side means something"
|
|
1328
|
+
)
|
|
1329
|
+
if categorical:
|
|
1330
|
+
order = sorted({str(x) for x in every}, key=_group_order)
|
|
1331
|
+
place = {name: at for at, name in enumerate(order)}
|
|
1332
|
+
position = lambda x: place[str(x)] # noqa: E731
|
|
1333
|
+
else:
|
|
1334
|
+
position = lambda x: x # noqa: E731
|
|
1335
|
+
spots = sorted({position(x) for x in every})
|
|
1336
|
+
spacing = min((b - a for a, b in zip(spots, spots[1:])), default=1.0) or 1.0
|
|
1337
|
+
width = 0.8 * spacing / len(series)
|
|
1338
|
+
for at, (key, (xs, ys, x_errors, y_errors, _)) in enumerate(series):
|
|
1339
|
+
shift = (at - (len(series) - 1) / 2) * width
|
|
1340
|
+
ax.bar([position(x) + shift for x in xs], ys, width=width,
|
|
1341
|
+
xerr=None if categorical else _errors(x_errors), yerr=_errors(y_errors),
|
|
1342
|
+
label=groups.label(key), color=groups.colour(key), **_caps())
|
|
1343
|
+
if categorical:
|
|
1344
|
+
ax.set_xticks(range(len(order)), order)
|
|
1345
|
+
# Many or long names lean, rather than write over each other.
|
|
1346
|
+
if len(order) > 6 or max((len(name) for name in order), default=0) > 8:
|
|
1347
|
+
ax.tick_params(axis="x", labelrotation=40)
|
|
1348
|
+
for label in ax.get_xticklabels():
|
|
1349
|
+
label.set_horizontalalignment("right")
|
|
1350
|
+
|
|
1351
|
+
|
|
1352
|
+
def _lying_bars(ax, declared, series, groups):
|
|
1353
|
+
"""Horizontal bars: a text y, each value a category, and the number x
|
|
1354
|
+
each bar reaches; several groups stand side by side along y."""
|
|
1355
|
+
every = [y for _, (_, ys, *_) in series for y in ys]
|
|
1356
|
+
order = sorted({str(y) for y in every}, key=_group_order)
|
|
1357
|
+
place = {name: at for at, name in enumerate(order)}
|
|
1358
|
+
height = 0.8 / len(series)
|
|
1359
|
+
for at, (key, (xs, ys, x_errors, _, samples)) in enumerate(series):
|
|
1360
|
+
seen = {}
|
|
1361
|
+
for y, sample in zip(ys, samples):
|
|
1362
|
+
if str(y) in seen:
|
|
1363
|
+
raise _in_the_data(ValueError(
|
|
1364
|
+
f"{_named(seen[str(y)])} and {_named(sample)} are two bars at "
|
|
1365
|
+
f"{declared.y} = {y}, and one would hide the other: group them apart"
|
|
1366
|
+
))
|
|
1367
|
+
seen[str(y)] = sample
|
|
1368
|
+
shift = (at - (len(series) - 1) / 2) * height
|
|
1369
|
+
ax.barh([place[str(y)] + shift for y in ys], xs, height=height,
|
|
1370
|
+
xerr=_errors(x_errors), label=groups.label(key),
|
|
1371
|
+
color=groups.colour(key), **_caps())
|
|
1372
|
+
ax.set_yticks(range(len(order)), order)
|
|
1373
|
+
|
|
1374
|
+
|
|
1375
|
+
def _boxes(samples, declared, ax):
|
|
1376
|
+
"""The values of ``y`` over the samples sharing a value of ``x``, a box
|
|
1377
|
+
each: their spread, which a bar would hide. What a box draws is the
|
|
1378
|
+
values; their uncertainties are not a box's to show."""
|
|
1379
|
+
if declared.group:
|
|
1380
|
+
raise ValueError(
|
|
1381
|
+
f"a box plot's boxes are the values of '{declared.x}': "
|
|
1382
|
+
f"{_option('--group', 'group=')} has nothing left to split"
|
|
1383
|
+
)
|
|
1384
|
+
missing = []
|
|
1385
|
+
boxes = {}
|
|
1386
|
+
units = _Units(declared.y)
|
|
1387
|
+
omitted = _Omitted(len(samples))
|
|
1388
|
+
for sample in samples:
|
|
1389
|
+
key = _group_of(sample, declared.x)
|
|
1390
|
+
read_y = _scalar(sample, declared.y, missing)
|
|
1391
|
+
if read_y is None or key in NO_VALUE:
|
|
1392
|
+
omitted.add(sample, f"no {declared.y if read_y is None else declared.x}")
|
|
1393
|
+
continue
|
|
1394
|
+
if not _on_the_axis(read_y[0], declared.axes.get("y_scale")):
|
|
1395
|
+
omitted.add(sample, f"{declared.y} at or below zero on a log axis")
|
|
1396
|
+
continue
|
|
1397
|
+
units.add(sample, read_y[2])
|
|
1398
|
+
boxes.setdefault(key, []).append(read_y[0])
|
|
1399
|
+
if not boxes:
|
|
1400
|
+
if missing and len(missing) >= len(samples):
|
|
1401
|
+
raise missing[0]
|
|
1402
|
+
raise _nothing_drawn(samples, omitted, f"'{declared.y}'")
|
|
1403
|
+
keys = sorted(boxes, key=_group_order)
|
|
1404
|
+
# Each box with its values drawn over it, and how many beneath it: a box
|
|
1405
|
+
# of one sample is a line, which the point and its count explain.
|
|
1406
|
+
ax.boxplot(
|
|
1407
|
+
[boxes[key] for key in keys],
|
|
1408
|
+
tick_labels=[f"{key}\n({len(boxes[key])})" for key in keys],
|
|
1409
|
+
medianprops={"color": "0.2"},
|
|
1410
|
+
)
|
|
1411
|
+
for at, key in enumerate(keys, start=1):
|
|
1412
|
+
size = {} if _declares("lines.markersize") else {"markersize": 3}
|
|
1413
|
+
ax.plot([at] * len(boxes[key]), boxes[key], "o", color="0.35", zorder=3, **size)
|
|
1414
|
+
return (None, None), units.reading, omitted
|
|
1415
|
+
|
|
1416
|
+
|
|
1417
|
+
def _set_axes(ax, axes):
|
|
1418
|
+
"""Scales before limits, so that a log axis is given its bounds as one. A
|
|
1419
|
+
bound a log axis cannot take is refused, where matplotlib ignores it with a
|
|
1420
|
+
warning."""
|
|
1421
|
+
for axis in ("x", "y"):
|
|
1422
|
+
if axes.get(f"{axis}_scale") != "log":
|
|
1423
|
+
continue
|
|
1424
|
+
for bound in axes.get(f"{axis}_limits") or ():
|
|
1425
|
+
if bound is not None and bound <= 0:
|
|
1426
|
+
raise ValueError(
|
|
1427
|
+
f"{axis}_limits has {bound:g}, and a log scale holds no bound at or "
|
|
1428
|
+
"below zero: give a positive one, or auto"
|
|
1429
|
+
)
|
|
1430
|
+
for key, setter in (("x_scale", ax.set_xscale), ("y_scale", ax.set_yscale)):
|
|
1431
|
+
if key in axes:
|
|
1432
|
+
setter(axes[key])
|
|
1433
|
+
for axis in ("x", "y"):
|
|
1434
|
+
bounds = axes.get(f"{axis}_limits")
|
|
1435
|
+
if bounds and None not in bounds and bounds[0] > bounds[1]:
|
|
1436
|
+
_warn(
|
|
1437
|
+
f"{axis}_limits run from {bounds[0]:g} down to {bounds[1]:g}: the {axis} "
|
|
1438
|
+
"axis is drawn reversed"
|
|
1439
|
+
)
|
|
1440
|
+
if "x_limits" in axes:
|
|
1441
|
+
ax.set_xlim(*_free_end(ax, "x", axes["x_limits"], axes.get("x_scale")))
|
|
1442
|
+
if "y_limits" in axes:
|
|
1443
|
+
ax.set_ylim(*_free_end(ax, "y", axes["y_limits"], axes.get("y_scale")))
|
|
1444
|
+
if "aspect" in axes:
|
|
1445
|
+
ax.set_aspect(axes["aspect"], adjustable="box")
|
|
1446
|
+
|
|
1447
|
+
|
|
1448
|
+
def _free_end(ax, axis, bounds, scale):
|
|
1449
|
+
"""Two bounds, a free end placed past the data by matplotlib's margin —
|
|
1450
|
+
measured over the range from the fixed end, as autoscaling measures it —
|
|
1451
|
+
rather than at the last value, where its marker was cut by the frame."""
|
|
1452
|
+
low, high = bounds
|
|
1453
|
+
if (low is None) == (high is None):
|
|
1454
|
+
return bounds
|
|
1455
|
+
interval = ax.dataLim.intervalx if axis == "x" else ax.dataLim.intervaly
|
|
1456
|
+
least, most = (float(end) for end in interval)
|
|
1457
|
+
fixed = low if low is not None else high
|
|
1458
|
+
if not (math.isfinite(least) and math.isfinite(most)):
|
|
1459
|
+
return bounds
|
|
1460
|
+
log = scale == "log"
|
|
1461
|
+
if log and (fixed <= 0 or least <= 0):
|
|
1462
|
+
return bounds
|
|
1463
|
+
|
|
1464
|
+
def along(value):
|
|
1465
|
+
return math.log10(value) if log else value
|
|
1466
|
+
|
|
1467
|
+
def back(value):
|
|
1468
|
+
return 10 ** value if log else value
|
|
1469
|
+
|
|
1470
|
+
margin = ax.margins()[0 if axis == "x" else 1]
|
|
1471
|
+
if low is not None:
|
|
1472
|
+
# The data's far end from the fixed one, whichever side it lies.
|
|
1473
|
+
far = most if along(most) >= along(fixed) else least
|
|
1474
|
+
else:
|
|
1475
|
+
far = least if along(least) <= along(fixed) else most
|
|
1476
|
+
if far == fixed:
|
|
1477
|
+
return bounds
|
|
1478
|
+
free = back(along(far) + margin * (along(far) - along(fixed)))
|
|
1479
|
+
return (fixed, free) if low is not None else (free, fixed)
|
|
1480
|
+
|
|
1481
|
+
|
|
1482
|
+
def _group_order(key):
|
|
1483
|
+
"""Groups in their values' order: numbers as numbers — 80 before 100 —
|
|
1484
|
+
then text, then the samples with none; a combination of several fields
|
|
1485
|
+
by its first field's value, then the next."""
|
|
1486
|
+
if isinstance(key, tuple):
|
|
1487
|
+
return (1, tuple(_group_order(part) for part in key), "")
|
|
1488
|
+
if key is None or key in NO_VALUE:
|
|
1489
|
+
return (2, NO_VALUE.index(key) if key in NO_VALUE else 0, "")
|
|
1490
|
+
if _is_number(key):
|
|
1491
|
+
return (0, key, "")
|
|
1492
|
+
return (1, 0, str(key))
|
|
1493
|
+
|
|
1494
|
+
|
|
1495
|
+
def _curves(samples, declared, ax, groups):
|
|
1496
|
+
"""A curve per sample, for two columns of one table, coloured by group."""
|
|
1497
|
+
units = (_Units(declared.x), _Units(declared.y))
|
|
1498
|
+
drawn = 0
|
|
1499
|
+
colours = {}
|
|
1500
|
+
omitted = _Omitted(len(samples))
|
|
1501
|
+
points = 0
|
|
1502
|
+
if declared.group:
|
|
1503
|
+
# Drawn group by group, so that the legend reads in the groups' order.
|
|
1504
|
+
samples = sorted(samples, key=lambda s: _group_order(_group_of(s, declared.group)))
|
|
1505
|
+
# A curve per sample past ten colours: twenty, then a scale, never a
|
|
1506
|
+
# colour two curves share.
|
|
1507
|
+
palette = _palette(len(samples)) if not declared.group else None
|
|
1508
|
+
for sample in samples:
|
|
1509
|
+
table_x = _table_in(sample, declared.x)
|
|
1510
|
+
table_y = _table_in(sample, declared.y)
|
|
1511
|
+
if table_x is None or table_y is None:
|
|
1512
|
+
omitted.add(sample, f"no {declared.x if table_x is None else declared.y}")
|
|
1513
|
+
continue
|
|
1514
|
+
(name_x, table, column_x), (name_y, _, column_y) = table_x, table_y
|
|
1515
|
+
if name_x != name_y:
|
|
1516
|
+
raise ValueError(
|
|
1517
|
+
f"'{declared.x}' and '{declared.y}' are columns of two tables: a curve "
|
|
1518
|
+
"is read along one table's rows"
|
|
1519
|
+
)
|
|
1520
|
+
xs = [_number(sample, declared.x, v) for v in table.values(column_x)]
|
|
1521
|
+
ys = [_number(sample, declared.y, v) for v in table.values(column_y)]
|
|
1522
|
+
x_errors = table.uncertainties(column_x)
|
|
1523
|
+
y_errors = table.uncertainties(column_y)
|
|
1524
|
+
keep = [at for at in range(len(xs)) if xs[at] is not None and ys[at] is not None]
|
|
1525
|
+
shown = [at for at in keep
|
|
1526
|
+
if _on_the_axis(xs[at], declared.axes.get("x_scale"))
|
|
1527
|
+
and _on_the_axis(ys[at], declared.axes.get("y_scale"))]
|
|
1528
|
+
points += len(keep) - len(shown)
|
|
1529
|
+
units[0].add(sample, _column_reading(table, column_x))
|
|
1530
|
+
units[1].add(sample, _column_reading(table, column_y))
|
|
1531
|
+
# With a group, a curve takes its group's colour and the legend names
|
|
1532
|
+
# each group once; without, each curve is its sample.
|
|
1533
|
+
label, colour = sample.name, (palette[drawn] if palette else None)
|
|
1534
|
+
if declared.group:
|
|
1535
|
+
key = _group_of(sample, declared.group)
|
|
1536
|
+
colour = groups.colour(key)
|
|
1537
|
+
if colour is None:
|
|
1538
|
+
if key not in colours:
|
|
1539
|
+
colours[key] = f"C{len(colours) % 10}"
|
|
1540
|
+
label = groups.label(key)
|
|
1541
|
+
else:
|
|
1542
|
+
label = None
|
|
1543
|
+
colour = colours[key]
|
|
1544
|
+
else:
|
|
1545
|
+
# Named once per group: under a colour bar, only the
|
|
1546
|
+
# samples without a value.
|
|
1547
|
+
label = groups.label(key) if key not in colours else None
|
|
1548
|
+
colours[key] = colour
|
|
1549
|
+
_series(
|
|
1550
|
+
ax,
|
|
1551
|
+
declared.kind,
|
|
1552
|
+
[xs[at] for at in shown],
|
|
1553
|
+
[ys[at] for at in shown],
|
|
1554
|
+
[x_errors[at] for at in shown],
|
|
1555
|
+
[y_errors[at] for at in shown],
|
|
1556
|
+
label,
|
|
1557
|
+
colour,
|
|
1558
|
+
)
|
|
1559
|
+
drawn += 1
|
|
1560
|
+
if not drawn:
|
|
1561
|
+
raise _nothing_drawn(samples, omitted,
|
|
1562
|
+
f"the columns '{declared.x}' and '{declared.y}'")
|
|
1563
|
+
if points:
|
|
1564
|
+
_warn(f"{points} points not drawn: at or below zero on a log axis")
|
|
1565
|
+
return units[0].reading, units[1].reading, omitted
|
|
1566
|
+
|
|
1567
|
+
|
|
1568
|
+
def _palette(count):
|
|
1569
|
+
"""Colours for ``count`` curves, none repeating: matplotlib's ten where
|
|
1570
|
+
they are enough, twenty, then evenly along a scale."""
|
|
1571
|
+
import matplotlib
|
|
1572
|
+
|
|
1573
|
+
if count <= 10:
|
|
1574
|
+
return None
|
|
1575
|
+
if count <= 20:
|
|
1576
|
+
return [matplotlib.colormaps["tab20"](at) for at in range(count)]
|
|
1577
|
+
scale = matplotlib.colormaps["viridis"]
|
|
1578
|
+
return [scale(at / (count - 1)) for at in range(count)]
|
|
1579
|
+
|
|
1580
|
+
|
|
1581
|
+
def _caps():
|
|
1582
|
+
"""The error bars' caps: 3 points, unless the project says."""
|
|
1583
|
+
return {} if _declares("errorbar.capsize") else {"capsize": 3}
|
|
1584
|
+
|
|
1585
|
+
|
|
1586
|
+
def _series(ax, kind, xs, ys, x_errors, y_errors, label, colour=None):
|
|
1587
|
+
"""One series in its kind, with error bars wherever an uncertainty is. A
|
|
1588
|
+
round marker on each point, and a line between them for ``line`` — the
|
|
1589
|
+
marker the project's, where it declares one."""
|
|
1590
|
+
xerr = _errors(x_errors)
|
|
1591
|
+
yerr = _errors(y_errors)
|
|
1592
|
+
if kind == "step":
|
|
1593
|
+
(line,) = ax.step(xs, ys, where="mid", label=label, color=colour)
|
|
1594
|
+
ax.errorbar(xs, ys, xerr=xerr, yerr=yerr, fmt="none", ecolor=line.get_color(),
|
|
1595
|
+
**_caps())
|
|
1596
|
+
return
|
|
1597
|
+
drawn = {} if _declares("lines.marker") else {"marker": "o"}
|
|
1598
|
+
if kind == "scatter":
|
|
1599
|
+
drawn["linestyle"] = "none"
|
|
1600
|
+
ax.errorbar(xs, ys, xerr=xerr, yerr=yerr, fmt="", label=label, color=colour,
|
|
1601
|
+
**drawn, **_caps())
|
|
1602
|
+
|
|
1603
|
+
|
|
1604
|
+
def _errors(uncertainties):
|
|
1605
|
+
"""Error bars, or none where no value has an uncertainty; a missing one in
|
|
1606
|
+
a series that has others is drawn as zero, never invented."""
|
|
1607
|
+
if all(u is None for u in uncertainties):
|
|
1608
|
+
return None
|
|
1609
|
+
return [0.0 if u is None else u for u in uncertainties]
|
|
1610
|
+
|
|
1611
|
+
|
|
1612
|
+
# ------------------------------------------------------------------ reading
|
|
1613
|
+
|
|
1614
|
+
|
|
1615
|
+
def _table_of(samples, field):
|
|
1616
|
+
"""Whether some sample holds ``field`` as a table's column."""
|
|
1617
|
+
for sample in samples:
|
|
1618
|
+
if _table_in(sample, field) is not None:
|
|
1619
|
+
return True
|
|
1620
|
+
return None
|
|
1621
|
+
|
|
1622
|
+
|
|
1623
|
+
def _table_in(sample, field):
|
|
1624
|
+
"""``(table name, table, column)`` when ``field`` is a column of a table
|
|
1625
|
+
this sample holds, else ``None``."""
|
|
1626
|
+
import samplekit
|
|
1627
|
+
|
|
1628
|
+
head, _, column = field.partition(".")
|
|
1629
|
+
if not column or head not in sample:
|
|
1630
|
+
return None
|
|
1631
|
+
held = sample[head]
|
|
1632
|
+
if isinstance(held, samplekit.Table) and column in held.column_names:
|
|
1633
|
+
return head, held, column
|
|
1634
|
+
return None
|
|
1635
|
+
|
|
1636
|
+
|
|
1637
|
+
def _scalar(sample, field, missing, text=False):
|
|
1638
|
+
"""``(value, uncertainty, (unit, symbol))`` of one field of a sample — a
|
|
1639
|
+
number it holds, a table's cell included, or with ``text`` a category, as
|
|
1640
|
+
a bar's x may be — or ``None`` where the sample holds no value of it. A
|
|
1641
|
+
field the sample does not know is kept in ``missing``, to be raised if no
|
|
1642
|
+
sample knows it."""
|
|
1643
|
+
import samplekit
|
|
1644
|
+
|
|
1645
|
+
try:
|
|
1646
|
+
held = _read(sample, field)
|
|
1647
|
+
except KeyError as error:
|
|
1648
|
+
missing.append(error)
|
|
1649
|
+
return None
|
|
1650
|
+
if isinstance(held, samplekit.Property):
|
|
1651
|
+
# Read once each, a warning said at the caller's line.
|
|
1652
|
+
value = _heard(lambda: held.value)
|
|
1653
|
+
# Never entered, or not applicable: no point.
|
|
1654
|
+
if value is None or value is samplekit.NA:
|
|
1655
|
+
return None
|
|
1656
|
+
if text and isinstance(value, str):
|
|
1657
|
+
return value, None, (None, held.symbol)
|
|
1658
|
+
uncertainty = _heard(lambda: held.uncertainty)
|
|
1659
|
+
return _number(sample, field, value), uncertainty, (held.unit, held.symbol)
|
|
1660
|
+
if isinstance(held, samplekit.Table):
|
|
1661
|
+
raise ValueError(f"'{field}' is a table: name one of its columns, {field}.<column>")
|
|
1662
|
+
if held is None or held is samplekit.NA:
|
|
1663
|
+
return None
|
|
1664
|
+
if text and isinstance(held, str):
|
|
1665
|
+
return held, None, (None, None)
|
|
1666
|
+
return (
|
|
1667
|
+
_number(sample, field, held),
|
|
1668
|
+
_channel(sample, field, "u"),
|
|
1669
|
+
_reading_of(sample, field),
|
|
1670
|
+
)
|
|
1671
|
+
|
|
1672
|
+
|
|
1673
|
+
def _reading_of(sample, field):
|
|
1674
|
+
"""``(unit, symbol)`` of a number read by path: a cell's own, or — for a
|
|
1675
|
+
channel, ``diameter.u``, ``diameter.stats.mean`` — its quantity's."""
|
|
1676
|
+
import samplekit
|
|
1677
|
+
|
|
1678
|
+
unit = _channel(sample, field, "unit")
|
|
1679
|
+
if unit is not None:
|
|
1680
|
+
return unit, _channel(sample, field, "symbol")
|
|
1681
|
+
head = field
|
|
1682
|
+
while "." in head:
|
|
1683
|
+
head = head.rsplit(".", 1)[0]
|
|
1684
|
+
try:
|
|
1685
|
+
held = _read(sample, head)
|
|
1686
|
+
except (KeyError, ValueError):
|
|
1687
|
+
continue
|
|
1688
|
+
if isinstance(held, samplekit.Property):
|
|
1689
|
+
return held.unit, held.symbol
|
|
1690
|
+
if not isinstance(held, (list, dict)) and held is not None:
|
|
1691
|
+
return _channel(sample, head, "unit"), _channel(sample, head, "symbol")
|
|
1692
|
+
return None, None
|
|
1693
|
+
|
|
1694
|
+
|
|
1695
|
+
def _channel(sample, field, channel):
|
|
1696
|
+
"""A field's other channel — a cell's uncertainty or unit — or ``None``
|
|
1697
|
+
where it has none, or the field already names a channel."""
|
|
1698
|
+
try:
|
|
1699
|
+
return _read(sample, f"{field}.{channel}")
|
|
1700
|
+
except (KeyError, ValueError):
|
|
1701
|
+
return None
|
|
1702
|
+
|
|
1703
|
+
|
|
1704
|
+
def _number(sample, field, value):
|
|
1705
|
+
from samplekit import NA
|
|
1706
|
+
|
|
1707
|
+
# Not applicable is left out, as a value never entered is.
|
|
1708
|
+
if value is None or value is NA:
|
|
1709
|
+
return None
|
|
1710
|
+
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
|
1711
|
+
if hasattr(value, "isoformat"):
|
|
1712
|
+
return value # a date orders an axis as matplotlib reads it
|
|
1713
|
+
raise TypeError(
|
|
1714
|
+
f"'{field}' of {sample.name or sample.path} is {value!r}, not a number to draw"
|
|
1715
|
+
)
|
|
1716
|
+
return value
|
|
1717
|
+
|
|
1718
|
+
|
|
1719
|
+
def _check_group(samples, group):
|
|
1720
|
+
"""A group no sample knows is a misspelling, refused with the nearest
|
|
1721
|
+
field, as an axis is; a table's column is refused, since it is not one
|
|
1722
|
+
value per sample. Each field of several is checked so."""
|
|
1723
|
+
import samplekit
|
|
1724
|
+
|
|
1725
|
+
for field in _fields_of(group):
|
|
1726
|
+
if field == "tags":
|
|
1727
|
+
continue
|
|
1728
|
+
refused = None
|
|
1729
|
+
for sample in samples:
|
|
1730
|
+
try:
|
|
1731
|
+
held = _read(sample, field)
|
|
1732
|
+
except KeyError as error:
|
|
1733
|
+
refused = refused or error
|
|
1734
|
+
continue
|
|
1735
|
+
# One value per sample or nothing: a table's repr was a legend
|
|
1736
|
+
# entry, and a group per sample of them was refused for its
|
|
1737
|
+
# count. A column is refused by the read itself, naming its cells.
|
|
1738
|
+
if isinstance(held, samplekit.Table):
|
|
1739
|
+
raise ValueError(
|
|
1740
|
+
f"'{field}' is a table: group by one of its cells, "
|
|
1741
|
+
f"{field}.<column>[<index>], or by a field each sample holds one value of"
|
|
1742
|
+
)
|
|
1743
|
+
break
|
|
1744
|
+
else:
|
|
1745
|
+
said = refused.args[0] if refused.args else str(refused)
|
|
1746
|
+
raise LookupFailed(f"{said}\n tags and name group samples too")
|
|
1747
|
+
|
|
1748
|
+
|
|
1749
|
+
def _group_of(sample, group):
|
|
1750
|
+
"""The group a sample falls in: its value of the field, or over several
|
|
1751
|
+
fields the combination of its values, one per field."""
|
|
1752
|
+
fields = _fields_of(group)
|
|
1753
|
+
if len(fields) > 1:
|
|
1754
|
+
return tuple(_group_of(sample, field) for field in fields)
|
|
1755
|
+
if group == "tags":
|
|
1756
|
+
return ", ".join(sample.tags) or "(no tag)"
|
|
1757
|
+
try:
|
|
1758
|
+
held = _read(sample, group)
|
|
1759
|
+
except KeyError:
|
|
1760
|
+
return NONE
|
|
1761
|
+
import samplekit
|
|
1762
|
+
|
|
1763
|
+
if isinstance(held, samplekit.Property):
|
|
1764
|
+
held = _heard(lambda: held.value)
|
|
1765
|
+
if isinstance(held, list):
|
|
1766
|
+
return ", ".join(str(item) for item in held)
|
|
1767
|
+
if held is samplekit.NA:
|
|
1768
|
+
return NOT_APPLICABLE
|
|
1769
|
+
return NONE if held is None else held
|
|
1770
|
+
|
|
1771
|
+
|
|
1772
|
+
# The groups of the samples holding no value — never entered, or not
|
|
1773
|
+
# applicable: neither is a value of the field, so a numeric group stays one.
|
|
1774
|
+
NONE = "(none)"
|
|
1775
|
+
NOT_APPLICABLE = "n/a"
|
|
1776
|
+
NO_VALUE = (NONE, NOT_APPLICABLE)
|
|
1777
|
+
|
|
1778
|
+
|
|
1779
|
+
def _read(sample, field):
|
|
1780
|
+
"""``sample[field]``, its warnings — an outdated value — said at the caller's
|
|
1781
|
+
line, the first outside SampleKit, rather than at this module's."""
|
|
1782
|
+
return _heard(lambda: sample[field])
|
|
1783
|
+
|
|
1784
|
+
|
|
1785
|
+
def _heard(read):
|
|
1786
|
+
"""What ``read`` returns, the warnings it gave said at the caller's line —
|
|
1787
|
+
or, while a figure is drawn, what they say of values not current held to
|
|
1788
|
+
be summed up once it is drawn."""
|
|
1789
|
+
with warnings.catch_warnings(record=True) as caught:
|
|
1790
|
+
warnings.simplefilter("always")
|
|
1791
|
+
held = read()
|
|
1792
|
+
for warning in caught:
|
|
1793
|
+
if _HELD is not None and _HELD.take(warning.message):
|
|
1794
|
+
continue
|
|
1795
|
+
_warn(warning.message, warning.category)
|
|
1796
|
+
return held
|
|
1797
|
+
|
|
1798
|
+
|
|
1799
|
+
# What a declared figure's reads said of values not current, while it is drawn:
|
|
1800
|
+
# one summary once it is, rather than a warning per value.
|
|
1801
|
+
_HELD = None
|
|
1802
|
+
|
|
1803
|
+
|
|
1804
|
+
class _NotCurrent:
|
|
1805
|
+
"""The values not current a figure read, by sample, said as one summary
|
|
1806
|
+
— as an export says what it was written from."""
|
|
1807
|
+
|
|
1808
|
+
READ = re.compile(
|
|
1809
|
+
r"^(?:(?P<who>.*?): )?(?:the uncertainty of )?'(?P<field>[^']+)' (?P<said>.+)$",
|
|
1810
|
+
re.DOTALL,
|
|
1811
|
+
)
|
|
1812
|
+
STATES = (("is outdated", "outdated"), ("failed when last computed", "failed"),
|
|
1813
|
+
("waits for", "waiting"), ("was never computed", "never computed"))
|
|
1814
|
+
|
|
1815
|
+
def __init__(self):
|
|
1816
|
+
self.read = {}
|
|
1817
|
+
|
|
1818
|
+
def take(self, message):
|
|
1819
|
+
"""Whether ``message`` says a value is not current, kept if so."""
|
|
1820
|
+
found = self.READ.match(str(message))
|
|
1821
|
+
if not found:
|
|
1822
|
+
return False
|
|
1823
|
+
for words, state in self.STATES:
|
|
1824
|
+
if found["said"].startswith(words):
|
|
1825
|
+
who = found["who"] or ""
|
|
1826
|
+
fields = self.read.setdefault(who, {})
|
|
1827
|
+
fields.setdefault(found["field"], state)
|
|
1828
|
+
return True
|
|
1829
|
+
return False
|
|
1830
|
+
|
|
1831
|
+
def say(self, omitted):
|
|
1832
|
+
"""One warning: how many values of which states, in how many samples,
|
|
1833
|
+
which, and what answers it. A value waiting, or never computed, of a
|
|
1834
|
+
sample left out is the left-out summary's, and not said twice."""
|
|
1835
|
+
read = {}
|
|
1836
|
+
for who, fields in self.read.items():
|
|
1837
|
+
kept = {field: state for field, state in fields.items()
|
|
1838
|
+
if not (who in omitted.names and state in ("waiting", "never computed"))}
|
|
1839
|
+
if kept:
|
|
1840
|
+
read[who] = kept
|
|
1841
|
+
if not read:
|
|
1842
|
+
return
|
|
1843
|
+
counted = {}
|
|
1844
|
+
for fields in read.values():
|
|
1845
|
+
for state in fields.values():
|
|
1846
|
+
counted[state] = counted.get(state, 0) + 1
|
|
1847
|
+
states = ", ".join(f"{counted[state]} {state}" for _, state in self.STATES
|
|
1848
|
+
if state in counted)
|
|
1849
|
+
listed = [f"{who} {', '.join(fields)}".strip() for who, fields in read.items()]
|
|
1850
|
+
if len(listed) > 5:
|
|
1851
|
+
listed = listed[:5] + [f"and {len(listed) - 5} more"]
|
|
1852
|
+
samples = f"{len(read)} sample" + ("" if len(read) == 1 else "s")
|
|
1853
|
+
global STALE_SAID
|
|
1854
|
+
STALE_SAID = True
|
|
1855
|
+
_warn(
|
|
1856
|
+
f"drawn from values that are not current: {states} in {samples} — "
|
|
1857
|
+
f"{'; '.join(listed)}\n "
|
|
1858
|
+
+ _option("samplekit status says why, and samplekit compute runs them again",
|
|
1859
|
+
"not_current() says why, and compute() runs them again")
|
|
1860
|
+
)
|
|
1861
|
+
|
|
1862
|
+
|
|
1863
|
+
def _warn(message, category=UserWarning):
|
|
1864
|
+
package = os.path.dirname(os.path.abspath(__file__)) + os.sep
|
|
1865
|
+
frame = sys._getframe(1)
|
|
1866
|
+
while frame is not None and os.path.abspath(frame.f_code.co_filename).startswith(package):
|
|
1867
|
+
frame = frame.f_back
|
|
1868
|
+
if frame is None:
|
|
1869
|
+
warnings.warn(message, category, stacklevel=2)
|
|
1870
|
+
return
|
|
1871
|
+
warnings.warn_explicit(
|
|
1872
|
+
message, category, frame.f_code.co_filename, frame.f_lineno,
|
|
1873
|
+
module=frame.f_globals.get("__name__"),
|
|
1874
|
+
registry=frame.f_globals.setdefault("__warningregistry__", {}),
|
|
1875
|
+
)
|
|
1876
|
+
|
|
1877
|
+
|
|
1878
|
+
class _Units:
|
|
1879
|
+
"""The unit and symbol an axis is labelled with: every sample's unit is the
|
|
1880
|
+
same, or the points would share an axis in different units."""
|
|
1881
|
+
|
|
1882
|
+
def __init__(self, field, what="axis"):
|
|
1883
|
+
self.field = field
|
|
1884
|
+
self.what = what
|
|
1885
|
+
self.unit = self.symbol = self.whose = None
|
|
1886
|
+
|
|
1887
|
+
def add(self, sample, reading):
|
|
1888
|
+
unit, symbol = reading or (None, None)
|
|
1889
|
+
if unit is None:
|
|
1890
|
+
# A file that writes no unit is in the one its project declares.
|
|
1891
|
+
unit = _declared_unit(sample, self.field)
|
|
1892
|
+
if unit is not None:
|
|
1893
|
+
if self.unit is None:
|
|
1894
|
+
self.unit, self.whose = unit, sample
|
|
1895
|
+
elif unit != self.unit:
|
|
1896
|
+
raise _in_the_data(ValueError(
|
|
1897
|
+
f"'{self.field}' is in {self.unit} in {_named(self.whose)} and in "
|
|
1898
|
+
f"{unit} in {_named(sample)}: one {self.what} holds one unit"
|
|
1899
|
+
))
|
|
1900
|
+
if self.symbol is None:
|
|
1901
|
+
self.symbol = symbol
|
|
1902
|
+
|
|
1903
|
+
@property
|
|
1904
|
+
def reading(self):
|
|
1905
|
+
return self.unit, self.symbol
|
|
1906
|
+
|
|
1907
|
+
|
|
1908
|
+
def _declared_unit(sample, field):
|
|
1909
|
+
"""The unit ``[property.*]`` declares for a field's quantity in the
|
|
1910
|
+
sample's project, or ``None``."""
|
|
1911
|
+
head = (field or "").split("[", 1)[0]
|
|
1912
|
+
try:
|
|
1913
|
+
properties = sample.project.properties
|
|
1914
|
+
except Exception:
|
|
1915
|
+
return None
|
|
1916
|
+
while head:
|
|
1917
|
+
if head in properties:
|
|
1918
|
+
return properties[head].unit
|
|
1919
|
+
if "." not in head:
|
|
1920
|
+
return None
|
|
1921
|
+
head = head.rsplit(".", 1)[0]
|
|
1922
|
+
return None
|
|
1923
|
+
|
|
1924
|
+
|
|
1925
|
+
def _named(sample):
|
|
1926
|
+
return sample.name or str(sample.path)
|
|
1927
|
+
|
|
1928
|
+
|
|
1929
|
+
def _column_reading(table, column):
|
|
1930
|
+
"""``(unit, symbol)`` of a table's column, read from its first row."""
|
|
1931
|
+
try:
|
|
1932
|
+
cell = table[0][column]
|
|
1933
|
+
return cell.unit, cell.symbol
|
|
1934
|
+
except Exception:
|
|
1935
|
+
return None
|
|
1936
|
+
|
|
1937
|
+
|
|
1938
|
+
def _project_of(samples):
|
|
1939
|
+
"""The project a figure's labels, style and settings are read from: the
|
|
1940
|
+
samples', or over several projects the first sample's."""
|
|
1941
|
+
try:
|
|
1942
|
+
return samples.project
|
|
1943
|
+
except ValueError:
|
|
1944
|
+
return _projects_of(samples)[0]
|
|
1945
|
+
|
|
1946
|
+
|
|
1947
|
+
def _figure_shape(figure):
|
|
1948
|
+
"""What a declared figure draws and how, to tell two declarations apart."""
|
|
1949
|
+
if figure is None:
|
|
1950
|
+
return None
|
|
1951
|
+
return tuple(getattr(figure, key) for key in (
|
|
1952
|
+
"kind", "x", "y", "group", "query", "title", "x_label", "y_label", "style",
|
|
1953
|
+
*AXIS_KEYS))
|
|
1954
|
+
|
|
1955
|
+
|
|
1956
|
+
def _projects_of(samples):
|
|
1957
|
+
"""Each project the samples come from, in the order met, by root."""
|
|
1958
|
+
found = {}
|
|
1959
|
+
for sample in samples:
|
|
1960
|
+
try:
|
|
1961
|
+
project = sample.project
|
|
1962
|
+
except (ValueError, AttributeError):
|
|
1963
|
+
continue
|
|
1964
|
+
if project is not None:
|
|
1965
|
+
found.setdefault(str(project.root), project)
|
|
1966
|
+
return list(found.values()) or [None]
|
|
1967
|
+
|
|
1968
|
+
|
|
1969
|
+
def _said_across(samples):
|
|
1970
|
+
"""Over several projects, a word when the others declare their figures'
|
|
1971
|
+
settings or style differently from the first's, which the figure
|
|
1972
|
+
follows."""
|
|
1973
|
+
projects = [project for project in _projects_of(samples) if project is not None]
|
|
1974
|
+
if len(projects) < 2:
|
|
1975
|
+
return
|
|
1976
|
+
lead = projects[0]
|
|
1977
|
+
differing = [
|
|
1978
|
+
str(project.root) for project in projects[1:]
|
|
1979
|
+
if project.matplotlib != lead.matplotlib
|
|
1980
|
+
or project.render.figure_style != lead.render.figure_style
|
|
1981
|
+
]
|
|
1982
|
+
if differing:
|
|
1983
|
+
_warn(
|
|
1984
|
+
f"these samples come from {len(projects)} projects: the figure follows "
|
|
1985
|
+
f"{lead.root}'s [matplotlib] and figure style, which "
|
|
1986
|
+
f"{', '.join(differing)} declare differently"
|
|
1987
|
+
)
|
|
1988
|
+
|
|
1989
|
+
|
|
1990
|
+
def _axis(project, field, read, style, row=None):
|
|
1991
|
+
"""An axis's label: the field's symbol in the style, else the field, and
|
|
1992
|
+
its unit in the style in brackets. A cell's symbol is its column's, so
|
|
1993
|
+
its row is said after it — ``Specific hardness, day 3`` — where it read
|
|
1994
|
+
as the whole column."""
|
|
1995
|
+
unit, symbol = read if read else (None, None)
|
|
1996
|
+
if project is not None:
|
|
1997
|
+
unit, symbol = project._axis_label(field, unit, symbol, style)
|
|
1998
|
+
elif style not in (None, "plain"):
|
|
1999
|
+
raise ValueError(f"no style '{style}' is declared: no .samplekitrc was found")
|
|
2000
|
+
text = f"{symbol}, {row}" if symbol and row else symbol or field
|
|
2001
|
+
return f"{text} [{unit}]" if unit else text
|
|
2002
|
+
|
|
2003
|
+
|
|
2004
|
+
def _row_of(samples, field):
|
|
2005
|
+
"""The row a cell's field names, in words — ``day 3``, the index column
|
|
2006
|
+
and its value — or ``None`` for a field that is no cell."""
|
|
2007
|
+
import re
|
|
2008
|
+
|
|
2009
|
+
import samplekit
|
|
2010
|
+
|
|
2011
|
+
found = re.match(r"^([A-Za-z_]\w*)\.[A-Za-z_]\w*\[([^\]]*)\]", field or "")
|
|
2012
|
+
if not found:
|
|
2013
|
+
return None
|
|
2014
|
+
table, written = found.groups()
|
|
2015
|
+
for sample in samples:
|
|
2016
|
+
try:
|
|
2017
|
+
held = sample[table] if table in sample else None
|
|
2018
|
+
except (KeyError, ValueError):
|
|
2019
|
+
continue
|
|
2020
|
+
if not isinstance(held, samplekit.Table):
|
|
2021
|
+
continue
|
|
2022
|
+
index = held.index
|
|
2023
|
+
names = [index] if isinstance(index, str) else list(index)
|
|
2024
|
+
values = [value.strip() for value in written.split(",")]
|
|
2025
|
+
if len(names) == len(values):
|
|
2026
|
+
return ", ".join(f"{name} {value}" for name, value in zip(names, values))
|
|
2027
|
+
return f"{', '.join(names)} {written}"
|
|
2028
|
+
return None
|
|
2029
|
+
|
|
2030
|
+
|
|
2031
|
+
def _typeset(text, style, what="label", given=False):
|
|
2032
|
+
"""Refuses a label matplotlib would not typeset — LaTeX outside ``$…$``,
|
|
2033
|
+
which it writes out backslash by backslash, or mathtext it cannot parse —
|
|
2034
|
+
naming it, rather than a figure that shows the source or fails in
|
|
2035
|
+
matplotlib's words when it is drawn. Under ``text.usetex`` LaTeX typesets
|
|
2036
|
+
the label, and none of this applies."""
|
|
2037
|
+
if not text:
|
|
2038
|
+
return
|
|
2039
|
+
import re
|
|
2040
|
+
|
|
2041
|
+
import matplotlib
|
|
2042
|
+
|
|
2043
|
+
if matplotlib.rcParams["text.usetex"]:
|
|
2044
|
+
return
|
|
2045
|
+
where = f" (style '{style}')" if style and not given else ""
|
|
2046
|
+
remedy = "write it in mathtext" if given else "declare a style for figures, or write the label yourself in mathtext"
|
|
2047
|
+
# An escaped dollar is a dollar sign, not the edge of mathtext.
|
|
2048
|
+
plain = re.sub(r"\$[^$]*\$", "", text.replace(r"\$", ""))
|
|
2049
|
+
if "\\" in plain:
|
|
2050
|
+
raise ValueError(
|
|
2051
|
+
f"the {what} '{text}'{where} is LaTeX outside $…$, which matplotlib writes "
|
|
2052
|
+
f"as it is\n a figure's text is matplotlib's mathtext, $\\mathrm{{porosity}}$ and "
|
|
2053
|
+
f"not \\si{{\\litre}}, % and not \\%: {remedy}"
|
|
2054
|
+
)
|
|
2055
|
+
if "$" not in text.replace(r"\$", ""):
|
|
2056
|
+
return
|
|
2057
|
+
from matplotlib.mathtext import MathTextParser
|
|
2058
|
+
|
|
2059
|
+
try:
|
|
2060
|
+
MathTextParser("path").parse(text)
|
|
2061
|
+
except ValueError as error:
|
|
2062
|
+
said = str(error).strip().splitlines()
|
|
2063
|
+
raise ValueError(
|
|
2064
|
+
f"matplotlib cannot typeset the {what} '{text}'{where}: "
|
|
2065
|
+
f"{said[-1] if said else error}"
|
|
2066
|
+
) from None
|