plotnine.composition.inset_element

inset_element(
    obj,
    left,
    bottom,
    right,
    top,
    align_to="panel",
    on_top=True,
    anchor="center"
)

Place a plot as an inset within another plot

By default the inset is rendered on top of the host (on_top=True). With on_top=False it is rendered behind the host’s panel and labels but above the host’s plot_background. Adding an inset_element to a composition attaches it to the most recently added plot in that composition.

Parameters

obj : ggplot | Compose | PILImage | np.ndarray | _InsetImage

The object to render as an inset. One of:

  • ggplot or Compose — full plot pipeline.
  • PIL.Image.Image or numpy.ndarray — raster image. The image is letterboxed inside the user’s bbox so its aspect ratio is preserved.
left : float

Bounding box of the inset as fractional coordinates in the range [0, 1], relative to the host region selected by align_to. The bottom-left corner of that region is (0, 0) and the top-right is (1, 1).

bottom : float

Bounding box of the inset as fractional coordinates in the range [0, 1], relative to the host region selected by align_to. The bottom-left corner of that region is (0, 0) and the top-right is (1, 1).

right : float

Bounding box of the inset as fractional coordinates in the range [0, 1], relative to the host region selected by align_to. The bottom-left corner of that region is (0, 0) and the top-right is (1, 1).

top : float

Bounding box of the inset as fractional coordinates in the range [0, 1], relative to the host region selected by align_to. The bottom-left corner of that region is (0, 0) and the top-right is (1, 1).

align_to : Literal["panel", "plot", "full"] = "panel"

Which region of the host plot the bounding box is relative to:

  • "panel" — the data area only (default).
  • "plot" — the panel plus axes, labels, titles, captions and legends
  • "full" — everything the host plot occupies plus plot margin
on_top : bool = True

When True (default) the inset paints above the host plot. When False, the inset paints between the host’s plot_background and the rest of the host (panel, titles, legends, …), so the host’s panel area covers the inset. Useful for backdrops, decorations, or branding that should look like part of the page rather than an overlay.

anchor : Anchor = "center"

Where to anchor the image inside the user’s bbox when its aspect ratio doesn’t match. One of "center" (default), "top", "top-right", "right", "bottom-right", "bottom", "bottom-left", "left", "top-left", or a (h, v) tuple in [0, 1]² with h = 0 left / h = 1 right and v = 0 bottom / v = 1 top. Only meaningful for image insets; plot / composition insets fill the entire area by resizing without constraining the aspect ratio, so the anchor has no effect.

Notes

figure_size and dpi set on the inset’s theme are ignored. The inset shares the host’s figure, so these values come from the host theme. The canvas size of the inset is determined by the bounding box and the area it is align_to.

For image insets, inset_element(...) + theme(...) draws a sibling rectangle around the image; only plot_background is honored today.

Examples

Composed with a host plot:

>>> p = ggplot(mtcars, aes("wt", "mpg")) + geom_point()
>>> p + inset_element(p, 0.6, 0.6, 1, 1)

Image inset with a black border:

>>> from PIL import Image
>>> p + (
...     inset_element(Image.open("logo.png"), 0.7, 0.7, 1, 1)
...     + theme(plot_background=element_rect(color="black", size=1))
... )

Methods

Name Description
draw Render this inset standalone on an implicit blank host
save Save this inset as an image file
show Display this inset using the matplotlib backend set by the user

draw

draw(*, show=False)

Render this inset standalone on an implicit blank host

Parameters

show : bool = False

Whether to show the plot.

save

save(*args, **kwargs)

Save this inset as an image file

Accepts the same arguments as save.

show

show()

Display this inset using the matplotlib backend set by the user