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/_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