ExternalAxesContainer

class ExternalAxesContainer(*args, external_axes_class=None, external_axes_kwargs=None, **kwargs)

Bases: CartesianAxes

Container axes that wraps an external axes instance.

This class inherits from ultraplot’s CartesianAxes and creates/manages an external axes as a child. It provides ultraplot’s interface while delegating drawing and interaction to the wrapped external axes.

Parameters:

• *args – Positional arguments passed to Axes.__init__

• external_axes_class (type) – The external axes class to instantiate (e.g., mpltern.TernaryAxes)

• external_axes_kwargs (dict, optional) – Keyword arguments to pass to the external axes constructor

• external_shrink_factor (float, optional, default: rc['external.shrink'] = 0.9) – The factor by which to shrink the external axes within the container to leave room for labels. For ternary plots, labels extend significantly beyond the plot area, so a value of 0.90 (10% padding) helps prevent overlap with adjacent subplots while keeping the axes large.

• external_padding (float, optional, default: 5.0) – Padding in points to add around the external axes tight bbox. This creates space between the external axes and adjacent subplots, preventing overlap with tick labels or other elements. Set to 0 to disable padding.

• **kwargs – Keyword arguments passed to Axes.__init__

Notes

When using external axes containers with multiple subplots, the external axes (e.g., ternary plots) are automatically shrunk to prevent label overlap with adjacent subplots. If you still experience overlap, you can:

1. Increase spacing with wspace or hspace in subplots()

2. Decrease external_shrink_factor (more aggressive shrinking)

3. Use tight_layout or constrained_layout for automatic spacing

Example: uplt.subplots(ncols=2, projection=('ternary', None), wspace=5)

To reduce padding between external axes and adjacent subplots, use: external_padding=2 or external_padding=0 to disable padding entirely.

Initialize the container and create the external axes child.

Methods Summary

clear()	Clear the container and mark external axes as stale.
contour(*args, **kwargs)	Delegate contour to external axes.
contourf(*args, **kwargs)	Delegate contourf to external axes.
draw(renderer)	Override draw to render container (with abc/titles) and external axes.
fill(*args, **kwargs)	Delegate fill to external axes.
format(**kwargs)	Format the container and delegate to external axes where appropriate.
get_external_axes()	Get the wrapped external axes instance.
get_external_child()	Get the external axes child (alias for get_external_axes).
get_tightbbox(renderer, *args, **kwargs)	Override to return the container bbox for consistent layout positioning.
has_external_child()	Check if this container has an external axes child.
hexbin(*args, **kwargs)	Delegate hexbin to external axes.
imshow(*args, **kwargs)	Delegate imshow to external axes.
pcolormesh(*args, **kwargs)	Delegate pcolormesh to external axes.
plot(*args, **kwargs)	Delegate plot to external axes.
scatter(*args, **kwargs)	Delegate scatter to external axes.
set(*[, adjustable, agg_filter, alpha, ...])	Set multiple properties at once.
set_position(pos[, which])	Override to sync position changes to external axes.
stale_callback(*args, **kwargs)	Mark external axes as stale when container is marked stale.
tricontour(*args, **kwargs)	Delegate tricontour to external axes.
tricontourf(*args, **kwargs)	Delegate tricontourf to external axes.
tripcolor(*args, **kwargs)	Delegate tripcolor to external axes.
triplot(*args, **kwargs)	Delegate triplot to external axes.

Methods Documentation

clear()

Clear the container and mark external axes as stale.

contour(*args, **kwargs)

Delegate contour to external axes.

contourf(*args, **kwargs)

Delegate contourf to external axes.

draw(renderer)

Override draw to render container (with abc/titles) and external axes.

fill(*args, **kwargs)

Delegate fill to external axes.

format(**kwargs)

Format the container and delegate to external axes where appropriate.

This method handles ultraplot-specific formatting on the container and attempts to delegate common parameters to the external axes.

Parameters:

**kwargs – Formatting parameters. Common matplotlib parameters (title, xlabel, ylabel, xlim, ylim) are delegated to the external axes if supported.

get_external_axes()

Get the wrapped external axes instance.

Returns:

axes – The external axes instance, or None if not created

get_external_child()

Get the external axes child (alias for get_external_axes).

Returns:

axes – The external axes instance, or None if not created

get_tightbbox(renderer, *args, **kwargs)

Override to return the container bbox for consistent layout positioning.

By returning the container’s bbox, we ensure the layout engine positions the container properly within the subplot grid, and we rely on our iterative shrinking to ensure the external axes fits within the container.

has_external_child()

Check if this container has an external axes child.

Returns:

bool – True if an external axes instance exists, False otherwise

hexbin(*args, **kwargs)

Delegate hexbin to external axes.

imshow(*args, **kwargs)

Delegate imshow to external axes.

pcolormesh(*args, **kwargs)

Delegate pcolormesh to external axes.

plot(*args, **kwargs)

Delegate plot to external axes.

scatter(*args, **kwargs)

Delegate scatter to external axes.

set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, external=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Property	Description
adjustable	{‘box’, ‘datalim’}
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	float or None
anchor	(float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …}
animated	bool
aspect	{‘auto’, ‘equal’} or float
autoscale_on	bool
autoscalex_on	unknown
autoscaley_on	unknown
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	bool or ‘line’
box_aspect	float or None
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
external	unknown
facecolor or fc	:mpltype:`color`
figure	Figure or SubFigure
forward_navigation_events	bool or “auto”
frame_on	bool
gid	str
in_layout	bool
label	object
mouseover	bool
navigate	bool
navigate_mode	unknown
path_effects	list of AbstractPathEffect
picker	None or bool or float or callable
position	unknown
prop_cycle	Cycler
rasterization_zorder	float or None
rasterized	bool
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
subplotspec	unknown
title	str
transform	Transform
url	str
visible	bool
xbound	(lower: float, upper: float)
xlabel	str
xlim	(left: float, right: float)
xmargin	float greater than -0.5
xscale	str or ScaleBase
xticklabels	unknown
xticks	unknown
ybound	(lower: float, upper: float)
ylabel	str
ylim	(bottom: float, top: float)
ymargin	float greater than -0.5
yscale	str or ScaleBase
yticklabels	unknown
yticks	unknown
zorder	float

set_position(pos, which='both')

Override to sync position changes to external axes.

stale_callback(*args, **kwargs)

Mark external axes as stale when container is marked stale.

tricontour(*args, **kwargs)

Delegate tricontour to external axes.

tricontourf(*args, **kwargs)

Delegate tricontourf to external axes.

tripcolor(*args, **kwargs)

Delegate tripcolor to external axes.

triplot(*args, **kwargs)

Delegate triplot to external axes.