rootfig 0.7.0__tar.gz → 0.7.1__tar.gz

{rootfig-0.7.0 → rootfig-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.7.0
+Version: 0.7.1
 Summary: Publication-quality figures straight from ROOT trees, without ROOT: uproot + Awkward + hist + mplhep with a TTree::Draw-like API.
 Project-URL: Homepage, https://github.com/jbeirer/rootfig
 Project-URL: Documentation, https://jbeirer.github.io/rootfig/

{rootfig-0.7.0 → rootfig-0.7.1}/docs/batch.md

@@ -268,11 +268,17 @@ included; its unused cells stay empty:
 book.save_pdf("overview.pdf", layout=(2, 3))
 ```
 
-A page is as large as the grid of figures the plots would have on their own, so
-a plot in a cell keeps its usual size: every cell of the document is as large as
-the largest figure any plot of the book would draw alone (a ratio panel makes it
-taller, a `Style` with a `figsize` sets its own). `figsize=` on `save_pdf()`
-sets the size of the whole page instead:
+A page is as large as the grid of figures the plots would have on their own,
+plus a narrow gap between neighbouring cells, so a plot in a cell keeps its
+usual size: every cell of the document is as large as the largest figure any
+plot of the book would draw alone (a ratio panel makes it taller, a `Style` with
+a `figsize` sets its own). A cell is laid out exactly as a figure of its size,
+whatever the grid and the style: the gap above a ratio panel, the room for
+labels, the legend and the y limits are the same on a `1 × 1` page as on an
+`8 × 8` one. The plots of a page are finished together, so a dense page takes
+about as long as the same plots on pages of their own. `figsize=` on
+`save_pdf()` sets the size of the whole page instead, the cells sharing what the
+gaps leave; one too small for the grid is refused before anything is drawn:
 
 ```python
 book.save_pdf("overview.pdf", figsize=(16, 10))

{rootfig-0.7.0 → rootfig-0.7.1}/docs/plotting.md

@@ -306,12 +306,22 @@ range avoids range inference.
   `Variable`'s `log` flag (`plot2d`, `efficiency` and `profile` do the same for
   their variables); `True`/`False` override it.
 - `xlabel`, `ylabel`, `unit`, `title`. The title sits above the axes, where
-  the CMS-style label is also drawn; with such a style prefer `text=`.
+  the CMS-style label is also drawn; with such a style prefer `text=`. The x
+  label ends at the right end of the axis, where matplotlib also puts the
+  axis' offset text (`×10⁻⁶` for small values); when both are shown the label
+  moves left of it, or below it where the axis is too short for both side by
+  side, also with `axes.formatter.useoffset` off, which drops an additive offset
+  but still shows the order of magnitude. On a figure rootfig makes the place is
+  chosen each time the figure is drawn, so a resized figure keeps the label clear
+  for its new size; on axes passed with `ax=` the label goes below the offset
+  text, which holds at any size. A `labelpad` or transform set on the label after
+  plotting is kept, and the label is kept clear starting from it.
 - Automatic y limits leave room for the legend, the experiment label, the
   statistics box and `text` lines: a small fixed margin is added above the
   tallest bin, and the upper limit is then raised until none of them covers a
-  histogram (the legend picks a free upper corner). Room is only made for
-  what is actually drawn, so a plot without annotations keeps the margin.
+  histogram (the legend picks a free upper corner of its axes). Room is only
+  made for what is actually drawn, so a plot without annotations keeps the
+  margin. It is measured on the figure as laid out, as it is shown and saved.
   A `ylim` with an explicit upper value switches this off.
 
 ## Legend, labels, text and statistics
@@ -339,6 +349,8 @@ range avoids range inference.
   wide, the luminosity gets a separate line above the label. The luminosity of
   a broken x axis sits above the right end of the right segment. An explicit
   title is placed above these labels, preserving its font, alignment and padding.
+- The experiment name and status share a baseline, including after resizing
+  the figure. `label_loc=2` and `3` explicitly put the status on a separate line.
 - `stats=True` adds entries, mean and standard deviation per sample below the
   legend (a location string moves it).
 

{rootfig-0.7.0 → rootfig-0.7.1}/src/rootfig/__init__.py

@@ -59,7 +59,7 @@ from rootfig.histograms import (
 from rootfig.model import Cut, Group, Sample, Style, Systematic, Variable, log_bins
 from rootfig.plotting import Plot, dark_theme, use_style
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 __all__ = [
     "ALL",

{rootfig-0.7.0 → rootfig-0.7.1}/src/rootfig/api/_pdf.py

@@ -16,11 +16,12 @@ from typing import TYPE_CHECKING, Any, Protocol
 
 from matplotlib.colors import to_hex
 
-from rootfig.plotting import Plot, figure_size, style_context
+from rootfig.plotting import Plot, figure_size, finishing_together, style_context
 from rootfig.plotting.figure import close_figures_since, open_figure_ids
 from rootfig.plotting.pages import (
     Page,
     background_color,
+    cell_room,
     make_page,
     multipage_pdf,
     page_size,
@@ -81,8 +82,15 @@ def page_sizes(
 
     An explicit ``figsize`` is the size of each page, and the styles of the tasks
     are left alone; otherwise a page is its grid of cells of :func:`cell_size`.
+
+    Raises
+    ------
+    ValueError
+        ``figsize`` leaves no room for the cells of a page's grid.
     """
     if figsize is not None:
+        for page in pages:
+            cell_room(figsize, page.grid)
         return [figsize] * len(pages)
     inches = cell_size(tasks)
     return [page_size(page.grid, inches) for page in pages]
@@ -149,13 +157,16 @@ def write_pdf(
     ``prepared`` yields the tasks in the order of ``tasks``, which ``pages`` split
     into consecutive runs; the tasks of a page are drawn in reading order into the
     cells of one figure of the size :func:`page_sizes` gives the page, created
-    under the style of the page's first task. The document is written
+    under the style of the page's first task, and finished together once all are
+    drawn (:func:`~rootfig.plotting.finishing_together`), so a page is laid out a
+    fixed number of times however many plots it holds. The document is written
     through :func:`~rootfig.plotting.pages.multipage_pdf`: an existing ``target``
     is replaced only once every page is written. A ``metadata`` among
     ``savefig_kwargs`` describes the document, not a page, so it goes to the
-    writer; the rest is passed to every :meth:`PdfPages.savefig`. A failing task
-    raises with its note (see :meth:`PlotBook.plots`), a failing write with a note
-    naming the page and the file; the page figure is closed either way.
+    writer; the rest is passed to every :meth:`PdfPages.savefig`. Errors during
+    drawing, deferred finishing or writing carry a note naming the page and file.
+    Preparation and drawing errors also retain their task note (see
+    :meth:`PlotBook.plots`); the page figure is closed either way.
     """
     kwargs = {"facecolor": "auto", "edgecolor": "auto", **savefig_kwargs}
     metadata = kwargs.pop("metadata", None)
@@ -170,8 +181,13 @@ def write_pdf(
             try:
                 with task_note(first, f"opening PDF page {number} for"):
                     fig, cells = make_page(size, page.grid, style=first.kwargs.get("style"))
-                for cell in cells[: page.count]:
-                    next(prepared).draw(cell=cell)
+                try:
+                    with finishing_together(fig):
+                        for cell in cells[: page.count]:
+                            next(prepared).draw(cell=cell)
+                except Exception as exc:
+                    exc.add_note(f"while rendering PlotBook PDF page {number} to {str(target)!r}")
+                    raise
                 try:
                     pdf.savefig(fig, **kwargs)
                 except Exception as exc: