OffsetPlots

class stonerplots.OffsetPlots(offset: float = 1.0, *, factor: float = 10.0, pair: bool | Literal['auto'] = 'auto', lines: bool = True, scatter: bool = True, errorbars: bool = True, include_open: bool = False)

Bases: TrackNewFiguresAndAxes, PreserveFigureMixin

Separate datasets on each new axes by a constant y offset or factor.

Inspection and adjustment happen on successful exit. The first dataset is unchanged; dataset i receives i * offset on linear axes or is multiplied by factor ** i on logarithmic axes. Each axes starts at zero.

Parameters:
  • offset (float) – Additive step in y data units on linear axes. Default 1.

  • factor (float) – Positive multiplicative step on log axes. Default 10. Values below 1 stack downwards; negative offsets do likewise.

  • pair (bool or str) – By default ("auto"), equal nonzero numbers of lines and scatter collections are paired by their order within each type. False offsets every dataset separately in overall creation order. True requires equal numbers of both types, raising ValueError otherwise (except on empty axes).

  • lines (bool) – Include data-coordinate Line2D artists. Default True.

  • scatter (bool) – Include data-coordinate scatter collections. Default True.

  • errorbars (bool) – Include complete errorbar plots as line datasets, including plots with fmt="none". Default True. Requires lines=True.

  • include_open (bool) – Also process existing axes and their existing artists. Default False, processing only axes created within the context.

Only ordinary 2D Cartesian axes with linear or log y scales are handled. Reference lines using axes coordinates, filled regions, images and other artist types are not shifted. Pairing is positional, not inferred from labels or colours. Empty ordinary lines and scatter collections are ignored.

Artist y data are changed, without changing caller-owned arrays. Limits are recalculated, respecting disabled autoscaling and explicit limits. Reusing the manager applies another offset to the selected datasets.

Example:

>>> with OffsetPlots(offset=2):
...     fig, ax = plt.subplots()
...     for y in datasets:
...         ax.plot(x, y)
...         ax.scatter(x, y)